OpenAI Realtime API 怎么配置语音轮次检测

OpenAI Realtime API 的语音轮次检测配置位于 session.audio.input.turn_detection。支持 VAD 的实时语音会话通常默认使用 server_vad；希望减少对自然停顿的误切分，可以选择 semantic_vad；按键说话或完全由客户端决定边界时，把它设为 null。

官方地址：https://developers.openai.com/api/docs/guides/realtime-vad

模式命名：把轮次边界当成独立架构决策

我做语音交互时最容易踩的坑，是把“用户没声音了”直接等同于“用户说完了”。短暂停顿、思考、吸气和环境噪声都会让音量边界偏离语义边界。Realtime API 把这个取舍拆成两类 VAD，再允许彻底关闭检测，正好对应三种架构模式。

如果业务是客服问答、设备控制等短句场景，我通常先用 server_vad；访谈、辅导、陪练等允许较长停顿的场景，更值得试 semantic_vad；录音按钮、对讲机和严格审核链路则适合关闭 VAD。

适用压力：server_vad 怎样平衡噪声和延迟

server_vad 通过静音区间自动切分音频。三个最常用参数分别控制“多大声才算开始”“起点前保留多少声音”和“安静多久算结束”。

const event = {
  type: "session.update",
  session: {
    type: "realtime",
    audio: {
      input: {
        turn_detection: {
          type: "server_vad",
          threshold: 0.5,          // 提高后需要更响的声音才触发，嘈杂环境可逐步上调。
          prefix_padding_ms: 300,  // 把检测起点前的音频带入本轮，减少吞掉首字。
          silence_duration_ms: 500,// 静音达到该时长后判断本轮结束。
          create_response: true,   // 检测到结束后自动创建模型响应。
          interrupt_response: true// 用户开口时允许打断正在生成的响应。
        }
      }
    }
  }
};

// WebSocket 和 WebRTC 数据通道都可以发送同一类 session.update 事件。
channel.send(JSON.stringify(event));

threshold 范围是 0 到 1，更高意味着需要更响的输入；silence_duration_ms 越短，轮次结束越快，但也更容易把思考停顿误判成结束。prefix_padding_ms 则用于保留检测到说话前的一小段音频。

典型实现：semantic_vad 用语义完整度决定等待

semantic_vad 不只看静音，还根据用户已经说出的内容判断是否可能表达完毕。它的核心调节项是 eagerness：

const event = {
  type: "session.update",
  session: {
    type: "realtime",
    audio: {
      input: {
        turn_detection: {
          type: "semantic_vad",
          eagerness: "low",        // 让用户有更多时间停顿和组织语言。
          create_response: true,   // 对话模式下，轮次结束后自动回复。
          interrupt_response: true// 用户再次开口时允许打断模型语音。
        }
      }
    }
  }
};

// 会话更新后，服务端会返回 session.updated 供客户端同步状态。
channel.send(JSON.stringify(event));

eagerness 可设为 low、medium、high 或 auto，其中 auto 等价于 medium。需要更快切分时选 high，希望减少打断时选 low。

反例：不要把检测、打断和自动响应绑死

很多应用确实需要自动检测轮次，但不希望立刻回复。例如先做审核、检索增强或输入校验，再决定是否让模型响应。这时保留 VAD，同时把 create_response 和 interrupt_response 设为 false，客户端在检查通过后再发送 response.create。

另一个反例是把转录会话和语音对话会话完全等同。create_response 与 interrupt_response 只用于语音对话模式；在转录会话里，VAD 主要控制音频怎样分块。

后果：关闭 VAD 后客户端接管轮次

按键说话时，可以通过 session.update 把 turn_detection 设为 null。客户端随后负责提交输入缓冲区并触发模型响应：

// 关闭服务端 VAD，让应用自己决定用户何时说完。
channel.send(JSON.stringify({
  type: "session.update",
  session: {
    type: "realtime",
    audio: { input: { turn_detection: null } }
  }
}));

// 松开说话按钮后提交这一轮音频。
channel.send(JSON.stringify({ type: "input_audio_buffer.commit" }));

// 显式请求模型生成下一条响应。
channel.send(JSON.stringify({ type: "response.create" }));

关闭 VAD 后，应用还应在新一轮开始前按传输方式处理缓冲区，并在用户打断时取消未完成响应。需要特别注意：gpt-live-transcribe 和 gpt-realtime-whisper 要求省略轮次检测配置或设为 null，并通过 input_audio_buffer.commit 完成每个音频轮次。

判断清单：怎样选择第一版参数

• 短句、命令、低延迟：从 server_vad 开始，逐步调整阈值和静音时长。
• 长句、自然停顿、避免抢话：使用 semantic_vad，先试 auto 或 low。
• 按键说话或严格审核：关闭 VAD，客户端显式 commit 和 create response。
• 要检测但不要自动回答：保留 VAD，将自动响应相关开关设为 false。
• 排查切分问题：监听 input_audio_buffer.speech_started 与 input_audio_buffer.speech_stopped，把参数、音频环境和事件时间放在同一条观测链路里。

常见问题

问：Realtime API 默认是哪种轮次检测？
对于支持 VAD 的会话和模型，默认是 server_vad。

问：只想让服务端切分音频，但由业务决定何时回答，可以吗？
可以。保留 VAD，把 create_response 与 interrupt_response 设为 false，再由客户端发送 response.create。

问：静音时长是不是越短越好？
不是。更短会降低等待延迟，也会增加把自然停顿切成两轮的概率，需要用真实噪声与说话节奏调参。