1. 从 STTTTS 到 Realtime语音助理为什么值得重做一遍如果你做过语音助手大概率踩过同一条流水线先录音调 STT 把语音转成文字再把文字丢给大模型生成回复最后用 TTS 把回复念出来。这条链路能跑通但体验很割裂——用户说完话要等两三秒才有回应中间任何一环识别错了后面全跟着错语气、停顿、情绪这些信息在转文字那一步就丢干净了。Azure OpenAI Realtime 系列模型把这条链路压成了一步音频进、音频出模型自己处理打断、轮次和上下文。它对外提供两种通信方式WebRTC 和 WebSocket。WebRTC 适合浏览器端做低延迟双向音频WebSocket 适合服务端或桌面端做可控的事件流。这篇就围绕这两种链路讲清楚怎么用 TaoToken 的统一 Key 和 API 通道把语音助理原型跑起来包括 settings.json、config.toml 骨架、环境变量、端点配置以及会话建立、音频往返、错误码排查这些能直接复制的动作。适合谁看已经了解大模型 API 调用、想快速验证 Realtime 语音交互的开发者手里有 Azure OpenAI 部署但被多套 Key 和端点管理搞烦的人以及想给现有应用加一个能对话、能调工具的语音入口的团队。先说清楚一个前提Realtime 模型和普通 Chat 模型最大的区别是会话是有状态的。普通对话每次请求都要把历史消息重新发一遍Realtime 则是建立一个长连接会话之后所有音频帧、事件、工具调用都在这条连接里流动。所以配置的重点不是发一条请求而是把会话建起来并维持住。2. TaoToken 前置统一 Key 与 API 通道怎么摆TaoToken 在这里扮演的角色是统一入口。你不需要在代码里散落一堆 Azure 资源名、部署名、区域端点而是把鉴权和路由收敛到一处客户端只认一个 Key 和一个 Base URL。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个不加 UTM。动手前先做三件事第一拿到统一 Key。登录后进控制台在 API Keys 页面创建一个新 Key复制出来存到环境变量里别写进代码。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。第二确认你要用的模型标识。Realtime 类模型在请求里通常需要一个 deployment 或 model 字段这个值以你实际开通的为准。想先在网页里确认模型能不能正常对话可以用模型对话页试一下 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。第三想清楚链路选型。浏览器里做实时语音优先 WebRTC因为它自带回声消除、抖动缓冲和音频轨道管理服务端做音频流处理、或者需要精确控制每个事件顺序选 WebSocket。两条链路的鉴权和端点配置思路一致差别在传输层。注意Realtime 会话涉及音频权限和长连接本地调试建议用 https 或 localhost否则浏览器会拦麦克风。3. 可复制配置settings.json 与 config.toml 骨架配置分两层一层是给编辑器/客户端插件用的 settings.json一层是给服务端或 CLI 工具用的 config.toml。两者都通过环境变量注入敏感信息避免硬编码。3.1 settings.json 骨架这个文件适合放在项目根目录或编辑器配置目录核心是把 Base URL、Key 来源、模型标识、传输方式写清楚。{ taotoken: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, realtime: { model: your-realtime-deployment, transport: webrtc, voice: sage, turnDetection: { type: server_vad, threshold: 0.5, prefixPaddingMs: 300, silenceDurationMs: 200, createResponse: true } }, websocket: { endpointEnv: TAOTOKEN_REALTIME_WS, reconnect: { maxRetries: 5, backoffMs: 800 } } } }几个字段说明apiKeyEnv指向环境变量名而不是 Key 本身transport决定走 WebRTC 还是 WebSocketturnDetection里的server_vad是服务端语音活动检测silenceDurationMs控制多久没声音算一轮说完调太小会频繁打断调太大响应迟钝。3.2 config.toml 骨架服务端或 CLI 场景用 TOML 更顺手尤其是需要多环境切换时。[taotoken] base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} [taotoken.realtime] model your-realtime-deployment transport websocket voice sage [taotoken.realtime.turn_detection] type server_vad threshold 0.5 prefix_padding_ms 300 silence_duration_ms 200 create_response true [taotoken.realtime.tools] enabled true tool_choice auto3.3 环境变量与端点把敏感值和端点从配置里抽出来写进.env或 shell profileexport TAOTOKEN_API_KEYsk-你的统一Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_REALTIME_WSwss://taotoken.net/api/realtimeWebRTC 链路还需要一个会话创建端点用来换取临时凭证避免把长期 Key 暴露到浏览器export TAOTOKEN_SESSIONS_URLhttps://taotoken.net/api/realtime/sessions提示WebRTC 的正确姿势是后端用长期 Key 调 sessions 接口拿临时 key前端只拿临时 key 去建 PeerConnection。前端直接塞长期 Key 等于把钥匙挂在门上。4. 验证请求会话建立、音频往返与工具调用配置写完接下来是能跑起来的验证动作。分 WebRTC 和 WebSocket 两条链路。4.1 WebRTC 链路建立会话前端流程是四步请求临时凭证、创建 RTCPeerConnection、通过 DataChannel 发事件、用 SDP offer/answer 完成握手。async function startSession() { const resp await fetch(/api/realtime/session, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ model: your-realtime-deployment, voice: sage }) }); if (!resp.ok) throw new Error(session failed: ${resp.status}); const data await resp.json(); const ephemeralKey data.client_secret?.value; await initPeerConnection(ephemeralKey); }拿到临时 key 后建连接async function initPeerConnection(ephemeralKey) { const pc new RTCPeerConnection(); const audioEl document.createElement(audio); audioEl.autoplay true; document.body.appendChild(audioEl); pc.ontrack (e) { audioEl.srcObject e.streams[0]; }; const media await navigator.mediaDevices.getUserMedia({ audio: true }); pc.addTrack(media.getAudioTracks()[0]); const dc pc.createDataChannel(realtime-channel); dc.addEventListener(open, () { sendSessionUpdate(dc); dc.send(JSON.stringify({ type: response.create })); }); dc.addEventListener(message, (e) handleServerEvent(JSON.parse(e.data))); const offer await pc.createOffer(); await pc.setLocalDescription(offer); const sdpResp await fetch(${WEBRTC_URL}?modelyour-realtime-deployment, { method: POST, body: offer.sdp, headers: { Authorization: Bearer ${ephemeralKey}, Content-Type: application/sdp } }); await pc.setRemoteDescription({ type: answer, sdp: await sdpResp.text() }); }4.2 session.update指令与工具会话建立后第一件事是发session.update把系统指令、轮次检测、工具定义一次性配好。工具目前支持 function 类型MCP 服务在 Realtime 里还不支持这点要注意。function sendSessionUpdate(dc) { const event { type: session.update, session: { instructions: 你是一名会议助理用亲切语气服务。开场语我是您的会议助理小爱。只能提供创建会议服务需要客户提供开始时间、持续时长、会议名称。, turn_detection: { type: server_vad, threshold: 0.5, prefix_padding_ms: 300, silence_duration_ms: 200, create_response: true }, tools: [ { type: function, name: createMeeting, description: 创建指定开始时间、时长和名称的会议, parameters: { type: object, properties: { start_time: { type: string, description: 格式 2025-09-09 15:33:00 }, duration: { type: integer, description: 分钟数 }, title: { type: string, description: 会议名称 } }, required: [start_time, duration, title] } } ], tool_choice: auto } }; dc.send(JSON.stringify(event)); }4.3 处理工具调用模型决定调工具时服务端会推response.output_item.done里面item.type是function_call。你解析参数、执行本地逻辑再把结果作为一条 user 消息塞回会话然后触发一次新的 response。function handleServerEvent(evt) { if (evt.type response.output_item.done evt.item?.type function_call) { const args JSON.parse(evt.item.arguments); if (evt.item.name createMeeting) { const ok createMeeting(args); if (ok) { dc.send(JSON.stringify({ type: conversation.item.create, item: { type: message, role: user, content: [{ type: input_text, text: 会议已创建成功请回复用户 }] } })); dc.send(JSON.stringify({ type: response.create })); } } } if (evt.type session.error) { console.error(session error:, evt.error?.message); } }4.4 WebSocket 链路事件流验证WebSocket 链路没有 SDP 握手直接连上后发 JSON 事件。适合服务端做音频转发或做自动化测试。const ws new WebSocket(${TAOTOKEN_REALTIME_WS}?modelyour-realtime-deployment, [ realtime, openai-insecure-api-key.${process.env.TAOTOKEN_API_KEY} ]); ws.onopen () { ws.send(JSON.stringify({ type: session.update, session: { instructions: 你是语音助理, voice: sage } })); }; ws.onmessage (e) { const evt JSON.parse(e.data); if (evt.type response.audio.delta) { // 收到 base64 音频分片解码后送播放器 } if (evt.type error) { console.error(ws error:, evt.error); } };音频往返验证对着麦克风说一句话观察是否收到response.audio.delta事件以及播放器里有没有声音。如果只收到文本 delta 没有音频多半是 voice 或输出模态没配对。5. 本篇常见错排查麦克风没声音 / 浏览器不弹权限检查页面是否在 https 或 localhost 下getUserMedia在非安全上下文会被直接拒绝。另外确认pc.addTrack用的是音频轨道而不是视频轨道。会话建立返回 401 或 403临时 key 过期或没拿到。WebRTC 的临时 key 有效期很短拿到后要立刻用。如果后端换 key 的接口本身报错先单独用 curl 验证 sessions 端点。curl -X POST $TAOTOKEN_SESSIONS_URL \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:your-realtime-deployment,voice:sage}DataChannel 打开了但模型不回应多半是没发response.create或者turn_detection配成了none导致模型不自动响应。检查session.update是否真的发出去了可以在 message 回调里打印所有事件类型。工具调用不触发tools数组格式不对或者tool_choice设成了none。另外 description 写得太模糊模型不知道什么时候该调。把 description 写具体参数 required 列全。音频断续、延迟高silence_duration_ms太小会让 VAD 频繁切轮次太大则响应慢。一般 200 到 500 之间调。网络侧检查是否走了不稳定的链路WebRTC 对丢包敏感。WebSocket 连上就断鉴权头格式不对或者子协议没带。不同客户端对openai-insecure-api-key这种子协议写法支持不一致服务端场景建议用标准 Authorization 头。收到 session.error 但信息很少把完整 error 对象打出来通常包含 code 和 message。常见 code 有invalid_request_error参数问题和rate_limit_exceeded配额问题。6. 接下来怎么走原型跑通后下一步通常是把它接到真实业务里。如果你要做的是长期编码助手或 Agent 类应用需要稳定的额度和更长的会话支持可以看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入细节和端点说明都在文档里 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你用的是 Claude Code 这类工具做开发Anthropic 兼容接入的说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 。我自己的习惯是先把 WebSocket 链路跑通做自动化测试确认事件流和工具调用没问题再切到 WebRTC 做前端体验。这样出问题时能快速判断是模型侧还是传输侧。另外临时 key 的换取一定要放后端前端只拿短时效凭证这条线别省。