基于 OpenAI Realtime API 的语音聊天模式，与文本模式共享 RAG 流水线

方案简介

这是 santifer.io 聊天机器人的语音模式配方：在文本聊天之外，用 OpenAI Realtime API 实现 audio-to-audio 的实时语音对话，并与文本模式共享同一条 RAG 流水线，单次会话成本约 $0.25。

前端由 React hook useVoiceMode.ts 负责 WebSocket 管理、音频采集与转写文本持久化；token 由 api/voice-token.js 签发（OpenAI Realtime ephemeral token + 限流）；语音过程中的检索请求通过 function calling 调用 api/rag-search.js 复用 RAG；整个语音会话由 api/voice-trace.js 做带成本估算的 Langfuse 追踪。

亮点与能力

• audio-to-audio 实时语音对话（OpenAI Realtime API）
• 与文本模式共享 RAG 检索管线（function calling 触发）
• ephemeral token 下发 + 服务端限流
• 语音会话 Langfuse 追踪与成本估算
• 音频采集、转写文本持久化（useVoiceMode.ts）
• /ops 面板展示语音会话数、文本/语音占比、延迟 P50/P95、每分钟成本

组成与分工

• useVoiceMode.ts：React hook，WebSocket 管理、音频采集、transcript 持久化
• api/voice-token.js：签发 OpenAI Realtime ephemeral token 并做限流
• OpenAI Realtime WebSocket：audio-to-audio 实时语音推理通道
• api/rag-search.js：供语音模式 function calling 调用的 RAG 搜索端点
• api/voice-trace.js：语音会话追踪与成本估算
• Langfuse：语音 tags 支撑 /ops 面板的语音统计

实施步骤

1. 部署 token 端点

部署 api/voice-token.js（Vercel Edge），为浏览器签发 OpenAI Realtime ephemeral token 并实施限流。

2. 前端接入语音 hook

在 React 中使用 src/useVoiceMode.ts，由它建立与 OpenAI Realtime 的 WebSocket 连接、采集麦克风音频并持久化转写文本。

3. 打通语音 RAG

部署 api/rag-search.js，语音模式通过 function calling 调用它，与文本模式共享混合检索管线。

4. 接入会话追踪

部署 api/voice-trace.js，为每个语音会话写入 Langfuse trace 并估算成本。

5. 运行语音质量评测

纳入 71 条自动评测中的 voice_quality 类别（6 条，Mixed 类型）：

npm run evals

使用与配置要点

• 每次开启语音会话前先经 api/voice-token.js 获取 ephemeral token，服务端限流防止滥用
• 语音与文本共用 RAG，回答质量口径一致
• 验证方式：查看 /ops 面板 Voice 标签页，确认 sessions、text/voice split、latency P50/P95、cost per minute 均有真实数据（来自 Langfuse tags）
• 成本参考：~$0.25/session

注意事项与常见问题

• 语音模式有明确会话成本（约 $0.25/session），需结合 /ops 成本页监控
• 语音质量评测（6 条）为 Mixed 类型，含 LLM-as-Judge（Haiku）成分，CI 门禁每次 push 都会执行

优缺点

• ✓ 语音文本共享同一 RAG 管线
• ✓ 临时令牌+限流保障安全
• ✕ 语音会话有成本约 $0.25/次
• ✕ 仅覆盖语音，弱网体验受限

出处

本方案挖掘自开源项目 santifer/cv-santiago，方案内容与实施命令均来自其 README 原文。