实时语音 Agent 的打断与建连
用户一开口,模型已经停止生成,扬声器却还在播上一句话。排查这个问题,要分别看服务端响应、本地播放队列和对话里保留的音频状态。
随着 OpenAI Realtime API(2025 年 8 月 28 日 GA)与 Google Gemini 3.8 Live(2026 年 9 月 15 日 GA)成熟,原生端到端语音接口已经取代了「ASR → LLM → TTS」串联管线。本文基于截至 2026 年 11 月的 Gemini Live API 文档 与 OpenAI Realtime API 文档,聚焦实际落地中最容易出错的四个环节:音频格式与传输差异、短期令牌建连与工具闭环,以及 WebSocket 场景下防竞态的打断截断控制器。
协议、音频格式与打断机制对照
两套接口在采样率、传输协议与打断责任划分上差异明显,写客户端前务必逐项对齐:
| 维度 | Gemini Live API(BidiGenerateContent) |
OpenAI Realtime API(GA) |
|---|---|---|
| 原生传输 | 双向有状态 WebSocket(WSS) | 浏览器/移动端优先 WebRTC(或 SIP);服务端桥接优先 WebSocket |
| PCM 音频格式 | 输入原生 16 kHz(服务端也可按声明采样率重采样);输出 24 kHz 16-bit 小端单声道 PCM(Capabilities) | 在 session.audio.input.format 与 session.audio.output.format 下配置 { type: "audio/pcm", rate: 24000 }(Client Events) |
| 端侧鉴权 | 后端调用 POST /v1beta/auth_tokens 签发 Ephemeral Token |
后端调用 Client Secrets 签发短期客户端凭据 |
| 打断与截断责任 | 默认 START_OF_ACTIVITY_INTERRUPTS;客户端消费 serverContent.interrupted 并清空本地播放队列 |
WebRTC / SIP:服务端管理输出缓冲并在打断时截断,手动清缓冲发 output_audio_buffer.clear;WebSocket:客户端停播清队列,并按实播进度发 conversation.item.truncate |
| 配置更新与迁移 | 建连首帧 setup 声明模型、音频与工具 |
session.update → session.updated;迁移至 GA 需移除旧版 OpenAI-Beta: realtime=v1 头并改用 GA 字段路径 |
在 OpenAI Realtime WebSocket 场景下有一个高频坑:input_audio_buffer.speech_started.item_id 指向的是即将生成的用户消息,绝对不能拿来传给 conversation.item.truncate。截断必须传入正在播放的 assistant 音频对应的 item_id、content_index 以及实际已播放的 audio_end_ms(见 Realtime Conversations)。
短期令牌建连与工具调用闭环
生产环境严禁把长期主密钥打包进 Web 或移动端 App。高频音频流由客户端凭短期令牌直连厂商,而有副作用的工具执行经业务后端完成后,再由客户端回传到实时会话:
第 5 步到第 8 步在两套协议里的具体字段不同:
- Gemini Live(见 Live API Reference):服务端发送原始 JSON 事件
toolCall(含函数调用 ID),客户端执行后回传toolResponse关联同一 ID;若用户中途打断导致工具不再需要,需消费服务端发出的toolCallCancellation取消本地未完成任务。 - OpenAI Realtime(见 Realtime Conversations):客户端以
conversation.item.create回传类型为function_call_output的 Item 并携带相同call_id,随后按需发送response.create让模型继续语音回复。
OpenAI Realtime WebSocket 防竞态打断控制器
如果服务端连续产生新旧响应,而客户端在收到旧响应的 response.done 时无条件清空当前活跃 ID,就会丢失对新响应的取消;同时,被打断响应在网络中延迟到达的音频块也必须丢弃。
下面以 OpenAI Realtime WebSocket 传输为例,给出一个分别追踪「生成中响应」与「当前播放音频」的 TypeScript 控制器:
export interface WsRealtimeHooks {
sendEvent: (payload: Record<string, unknown>) => void;
stopAndFlushAudio: () => number; // 停止播放清空队列,返回当前 assistant 音频实播毫秒数
enqueuePcmChunk: (base64Pcm: string) => void;
}
interface PlayingAudioRef {
responseId: string;
itemId: string;
contentIndex: number;
}
export class WsVoiceTurnController {
private activeResponseId: string | null = null;
private playingAudio: PlayingAudioRef | null = null;
private readonly cancelledResponseIds = new Set<string>();
private readonly hooks: WsRealtimeHooks;
constructor(hooks: WsRealtimeHooks) {
this.hooks = hooks;
}
onServerEvent(event: {
type: string;
response?: { id?: string };
response_id?: string;
item_id?: string;
content_index?: number;
delta?: string;
}): void {
if (event.type === "response.created" && event.response?.id) {
this.activeResponseId = event.response.id;
return;
}
if (event.type === "response.output_audio.delta" && event.delta && event.response_id) {
// 丢弃已被打断响应的迟到音频帧
if (this.cancelledResponseIds.has(event.response_id)) return;
if (event.item_id && typeof event.content_index === "number") {
this.playingAudio = {
responseId: event.response_id,
itemId: event.item_id,
contentIndex: event.content_index,
};
}
this.hooks.enqueuePcmChunk(event.delta);
return;
}
if (event.type === "response.done" && event.response?.id) {
// 仅当结束事件匹配当前活跃 ID 时才清空,避免旧响应 done 覆盖新响应
if (this.activeResponseId === event.response.id) {
this.activeResponseId = null;
}
this.cancelledResponseIds.delete(event.response.id);
return;
}
if (event.type === "input_audio_buffer.speech_started") {
this.interruptActivePlayback();
}
}
interruptActivePlayback(): void {
const playedMs = this.hooks.stopAndFlushAudio();
if (this.activeResponseId) {
const targetId = this.activeResponseId;
this.cancelledResponseIds.add(targetId);
this.hooks.sendEvent({ type: "response.cancel", response_id: targetId });
this.activeResponseId = null;
}
if (this.playingAudio) {
this.hooks.sendEvent({
type: "conversation.item.truncate",
item_id: this.playingAudio.itemId,
content_index: this.playingAudio.contentIndex,
audio_end_ms: Math.max(0, Math.floor(playedMs)),
});
this.playingAudio = null;
}
}
}需要留意:本地追踪 activeResponseId 只能减少多余的取消请求,无法彻底消除网络往返时差——如果取消发出时服务端恰好已结束该响应,服务端会返回无活跃响应的错误回包(实测中常见为 response_cancel_not_active),客户端应将其视为可忽略的状态同步回包,而不是当成致命连接故障。
传输、采样与生命周期边界
- 传输选型别混用:弱网移动蜂窝环境下,OpenAI Realtime 客户端优先走 WebRTC 避免 TCP 队头阻塞;Gemini Live 的原生客户端路径是 WSS,若需 WebRTC 接入则通过自建媒体桥接服务转接。
- 采样率端到端核对:浏览器麦克风常见采集率为 44.1 kHz 或 48 kHz;接入 OpenAI GA PCM 时对齐 24 kHz,接入 Gemini Live 时优先在
AudioWorklet中重采样为 16 kHz(或在协议中显式声明采样率交由服务端重采样),播放端统一对齐 24 kHz 输出。 - 区分三类超时并管控成本:分别配置「短期令牌建连有效期」「单次会话最长存活时间」与「静音空闲自动断开」,并结合各厂商按音频/文本实际用量的计价规则监控长会话开销;慢工具调用务必配置超时与口头过渡提示,避免长时间静默。
参考资料
- Google AI Studio: Gemini Live API Overview
- Google AI Studio: Gemini Live Capabilities
- Google AI Studio: Ephemeral Tokens
- Google AI Studio: Live API Reference
- OpenAI: Realtime API Guide
- OpenAI: Realtime Conversations
- OpenAI: Realtime Client Events
- OpenAI: Realtime Server Events
- OpenAI: Realtime Client Secrets