实时语音对话 Demo

源文件：chapter9/live-audio/README.md

实时语音对话 Demo

一个实时语音对话 Demo，具备语音转文本、AI 对话和文本转语音能力。该应用支持多家 AI 服务提供商，并以极低的延迟提供流畅的对话体验。

这是《深入理解 AI Agent》第 9 章实验 9-1「构建传统语音 Agent」的配套代码。它实现了书中讨论的级联式语音流水线（VAD → ASR → LLM → TTS）：前端采集麦克风并通过 WebSocket 流式传输音频；后端运行 Silero VAD 检测说话结束（约 500 ms 静音），再把该段话语送入可插拔的 ASR、LLM、TTS 提供商，并将合成的音频流式回传以供播放。

功能特性

• 🎤 带语音活动检测（VAD）的实时语音输入
• 🤖 由 AI 驱动的对话，支持多家提供商
• 🔊 文本转语音合成
• ⚡ 低延迟音频流
• 📊 实时延迟监控与日志
• 🎯 基于 WebSocket 的通信
• 🔧 ASR、LLM、TTS 服务灵活的提供商选择

支持的 AI 提供商

ASR（自动语音识别）

• OpenAI Whisper：高准确率，语言支持出色
• SenseVoice（经 Siliconflow）：低延迟、性价比高、自动语言检测

LLM（大语言模型）

• OpenAI GPT-4o：推理能力出色，性能均衡
• OpenRouter GPT-4o：无地域限制，接口统一
• OpenRouter Gemini：响应快，针对实时对话优化
• ARK Doubao：国内低延迟，针对中文优化

TTS（文本转语音）

• CosyVoice2（经 Siliconflow）：自然语音合成，多种系统音色

架构概览

系统采用前后端架构，具备实时音频处理与可插拔的提供商架构：

前端（Next.js）

• 音频采集：使用 Web Audio API 采集麦克风输入
• 音频处理：客户端音频处理并流式传给后端
• WebSocket 通信：把音频流发给后端并接收响应
• 音频播放：播放后端返回的 TTS 音频响应

后端（Node.js）

• WebSocket 服务器：处理实时音频流与客户端连接
• 语音活动检测：服务端 Silero VAD 处理，高准确率地检测语音边界
• 多提供商支持：灵活集成 ASR、LLM、TTS 提供商
• 提供商工厂：支持动态创建与切换提供商

数据流

User Speech → WebSocket → Backend VAD → Multi-Provider STT → Multi-Provider LLM → TTS → Audio Response
​

端口

前端从 WEBSOCKET_PORT 环境变量读取后端端口（见 frontend/.env.example）。它必须与后端的 LISTEN_PORT 一致。

前置条件

• Node.js（v16 或更高）
• npm 或 yarn
• FFmpeg —— 音频处理与格式转换所必需
• Google Chrome（推荐）—— 实时音频性能与兼容性最佳
  • 不推荐：Safari、Edge 或其他浏览器，受限于 WebAudio API
• 来自受支持提供商的 API key（见"配置"一节）

安装 FFmpeg

macOS（使用 Homebrew）

brew install ffmpeg
​

Ubuntu/Debian

sudo apt update
sudo apt install ffmpeg
​

Windows

• 从 https://ffmpeg.org/download.html 下载
• 或使用 Chocolatey：choco install ffmpeg
• 确保 ffmpeg 在你的 PATH 中

项目结构

/backend
- server.js: Main WebSocket server with provider integration
- config.js: Multi-provider configuration settings
- utils/
  - providers/
    - asrProviders.js: ASR provider implementations (OpenAI, Siliconflow)
    - llmProviders.js: LLM provider implementations (OpenAI, OpenRouter, ARK)
  - vad.js: Voice Activity Detection implementation
  - speechToText.js: Provider-aware STT service
  - textProcessor.js: Text preprocessing utilities
- tests/
  - provider-tests.js: Comprehensive provider testing
- run-tests.js: Test runner with environment validation
- utils/providers/: Provider configuration (ASR / LLM / TTS)
- package.json: Backend dependencies and scripts
​

/frontend
- pages/: Next.js pages
  - index.tsx: Main application interface
- components/: Reusable UI components
- public/: Static assets
  - audioWorklet.js: Audio processing and VAD implementation
- next.config.js: Next.js configuration
- tailwind.config.js: Tailwind CSS settings
- package.json: Frontend dependencies and scripts
​

安装

1. 克隆仓库
2. 安装后端依赖：

   cd backend && npm install
   ​

3. 安装前端依赖：

   cd frontend && npm install
   ​

4. 下载 Silero VAD 模型（本仓库已在 backend/models/silero_vad.onnx 内附带；仅在缺失时才需要下载）：

   cd backend/models
   wget https://huggingface.co/deepghs/silero-vad-onnx/resolve/main/silero_vad.onnx
   ​

5. 配置前端的 WebSocket 端口（如不设置，默认为 8848）：

   cd frontend && cp .env.example .env   # sets WEBSOCKET_PORT=8848 to match the backend
   ​

安装完成后，可在无需麦克风或浏览器的情况下校验环境（Node 版本、FFmpeg、VAD 模型、各提供商 key）：

cd backend && npm run check    # or: node check-setup.js
​

它会打印出哪些前置条件已满足、所选提供商是否已配置 API key。仅当某个硬性前置条件缺失（Node < 16、缺少 FFmpeg 或缺少 VAD 模型）时才会以非零状态退出。

配置

基于提供商的配置

系统现支持多家 AI 服务提供商，以获得最大灵活性。你可以为 ASR、LLM、TTS 服务自由组合不同提供商。

1. 环境变量设置

把你的 API key 设为环境变量：

# Required for OpenAI services
export OPENAI_API_KEY="your-openai-api-key"

# Required for OpenRouter services  
export OPENROUTER_API_KEY="your-openrouter-api-key"

# Required for ARK (Doubao) services
export ARK_API_KEY="your-ark-api-key"

# Required for Siliconflow services (ASR and TTS)
export SILICONFLOW_API_KEY="your-siliconflow-api-key"

# For future use
export ANTHROPIC_API_KEY="your-anthropic-api-key"
​

2. 选择提供商

1. 本仓库已附带可直接编辑的 backend/config.js。若缺失（例如全新检出且被忽略），先复制示例：

   cp backend/config.js.example backend/config.js
   ​

2. 编辑 backend/config.js 选择你偏好的提供商：

   const config = {
     // Provider Selection - Choose your preferred providers
     ASR_PROVIDER: 'siliconflow',      // 'openai' (whisper-1) or 'siliconflow' (SenseVoice)
     LLM_PROVIDER: 'openrouter',       // 'openrouter' (gpt-5.6-luna, default), 'openai', 'openrouter-gemini', 'ark'
     TTS_PROVIDER: 'siliconflow',      // 'siliconflow' (CosyVoice2)
   
     // API Keys (loaded from environment variables)
     OPENAI_API_KEY: process.env.OPENAI_API_KEY,
     OPENROUTER_API_KEY: process.env.OPENROUTER_API_KEY,
     ARK_API_KEY: process.env.ARK_API_KEY,
     SILICONFLOW_API_KEY: process.env.SILICONFLOW_API_KEY,
   
     // ... other configuration options
   };
   ​

3. 推荐的提供商组合

默认 / 推荐（只要有 OpenRouter key，任何地方都能用）

ASR_PROVIDER: 'siliconflow',      // SenseVoice
LLM_PROVIDER: 'openrouter',       // openai/gpt-5.6-luna via OpenRouter (avoids gpt-5.6* org verification)
TTS_PROVIDER: 'siliconflow',      // CosyVoice2
​

追求实时性能（国内低延迟）

ASR_PROVIDER: 'siliconflow',      // SenseVoice
LLM_PROVIDER: 'ark',              // Doubao (fast in China); or 'openrouter' for gpt-5.6-luna
TTS_PROVIDER: 'siliconflow',      // CosyVoice2
​

追求最高准确率

ASR_PROVIDER: 'openai',           // Accurate Whisper
LLM_PROVIDER: 'openrouter',       // openai/gpt-5.6-luna via OpenRouter
TTS_PROVIDER: 'siliconflow'       // CosyVoice2
​

4. API key 要求

你只需准备打算使用的那些提供商的 API key：

5. 配置校验

系统内置了完善的校验与测试工具：

# Test all configured providers
npm run test:providers

# Run the full test suite with environment validation
node run-tests.js
​

兼容旧版配置

系统保持了对早期硬编码配置格式的向后兼容，但强烈建议使用新的提供商选择方式以获得更好的灵活性。

用法

1. 设置你的 API key（见"配置"一节）

2. 在 backend/config.js 中配置你偏好的提供商

3. （可选）校验你的设置：cd backend && npm run check

4. 启动后端服务器（8848 端口的 WebSocket 服务器）：

   cd backend && npm start
   ​

   你应看到 Server is running on 0.0.0.0:8848。

5. 启动前端开发服务器（3000 端口）：

   cd frontend && npm run dev
   ​

6. 在浏览器（推荐 Chrome）中打开 http://localhost:3000

7. 点击"Start Recording"并授予麦克风权限，即可开始对话

预期行为：你说完后，后端会检测到约 500 ms 的静音（VAD），转写你的语音（ASR），流式输出 LLM 回复，并将其合成为音频（TTS）自动播放。屏幕上的日志面板会显示各阶段延迟（WebSocket RTT、转写、LLM、TTS）。若在助手说话时你再次开口，播放会被打断。

测试

提供商测试

测试单个提供商及所有组合：

cd backend

# Test all providers with your API keys
node run-tests.js

# Test specific providers only
npm run test:providers

# Install test dependencies if needed
npm install
​

测试套件会自动跳过未配置 API key 的提供商。

测试覆盖

• ✅ ASR 提供商功能（OpenAI Whisper、SenseVoice）
• ✅ LLM 提供商功能（OpenAI、OpenRouter GPT-4o、OpenRouter Gemini、ARK Doubao）
• ✅ TTS 提供商功能（经 Siliconflow 的 CosyVoice2）
• ✅ 所有提供商组合（8 种 ASR+LLM 组合）
• ✅ 动态切换提供商
• ✅ 错误处理与回退机制

故障排查

常见问题

1. 缺少 API key：确保所需的环境变量已设置
2. 找不到 FFmpeg：确保已安装 FFmpeg 并在系统 PATH 中可用
   • 用以下命令测试：ffmpeg -version
   • 若未找到，请参考上文的 FFmpeg 安装说明
3. 网络问题：检查到 API 端点的连通性
4. 限流：考虑切换提供商或实现重试逻辑
5. 地域限制：使用 OpenRouter 以获得全球访问
6. ONNX Runtime 问题：后端使用 ONNX Runtime 做语音活动检测
   • 通常由 onnxruntime-node 包自动解决
   • 某些系统可能需要额外的系统库

性能优化

• 低延迟：使用 Siliconflow ASR + OpenRouter Gemini
• 高准确率：使用 OpenAI ASR + OpenAI LLM
• 国内部署：使用 Siliconflow ASR + ARK LLM

提供商配置请参见 backend/config.js.example 以及 backend/utils/providers/ 下的提供商实现。

许可证

MIT