目录

实时语音 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。高频音频流由客户端凭短期令牌直连厂商,而有副作用的工具执行经业务后端完成后,再由客户端回传到实时会话:

flowchart LR Client["Web / Flutter 客户端"] -->|"1. 请求短期令牌"| Backend["业务后端 (TypeScript / Go)"] Backend -->|"2. 签发短期凭据"| Provider["Gemini Live / OpenAI Realtime"] Backend -->|"3. 返回短期凭据"| Client Client -->|"4. 双向音频与控制流"| Provider Provider -->|"5. 下发工具调用请求"| Client Client -->|"6. 鉴权执行业务工具"| Backend Backend -->|"7. 返回工具执行结果"| Client Client -->|"8. 将工具结果回传实时会话"| Provider

第 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 输出。
  • 区分三类超时并管控成本:分别配置「短期令牌建连有效期」「单次会话最长存活时间」与「静音空闲自动断开」,并结合各厂商按音频/文本实际用量的计价规则监控长会话开销;慢工具调用务必配置超时与口头过渡提示,避免长时间静默。

参考资料