WebRTC 语音 Agent
本示例在浏览器中构建低延迟语音 Agent。浏览器通过 WebRTC 连接你的服务器，服务器再通过 WebSocket 连接 Grok API。如果浏览器端语音延迟是首要考虑因素，可以从此示例入手。
注意：这些实现供学习和开发使用。用于生产环境前，还需进一步加固。
概览
这个基于 WebRTC 的语音 Agent 支持：
低延迟的 WebRTC 语音通信
实时双向音频流
连接质量监控（码率、抖动、丢包）
服务端中继，连接浏览器端 WebRTC 和 XAI API 端 WebSocket
架构
Browser (WebRTC Client)
↓ WebRTC (PCM16 via DataChannel)
↓
Node.js Server (Relay)
↓ WebSocket (PCM16 pass-through)
↓
XAI API服务器在两端之间转发数据：
客户端 → 服务器：通过 WebRTC DataChannel 传输 PCM16 音频
服务器 → XAI：通过 WebSocket 传输 PCM16 音频
无需转换音频：全程使用 PCM16
快速开始
前提条件
Node.js 18 或更高版本
XAI API 密钥
支持 WebRTC 的 Chrome 或 Edge 浏览器
1. 启动服务器
cd server
# Create .env file with your XAI_API_KEY
echo "XAI_API_KEY=your_key_here" > .env
./start.sh服务器将监听端口 8000（可通过以下文件配置：.env）。
2. 启动客户端
cd client
./start.sh客户端将在端口 5173 启动。
3. 打开浏览器
访问 http://localhost:5173 并点击 START 开始语音对话。
组件
服务器（/server）
使用 Node.js 和 TypeScript 构建的服务器负责：
接受来自浏览器的 WebRTC 连接
处理信令（SDP offer/answer 和 ICE 候选）
通过 DataChannel 转发 PCM16 音频
通过 WebSocket 连接 XAI API
收集连接质量统计数据
技术栈：Express、werift（纯 JS 的 WebRTC 实现）、WebSocket、TypeScript
参见 server/README.md 了解详情。
客户端（/client）
使用 React 和 TypeScript 构建的网页应用负责：
与服务器建立 WebRTC 连接
通过 WebRTC 采集麦克风音频
显示实时转录文本
显示 WebRTC 连接质量统计数据
提供查看消息的调试控制台
技术栈：React、Vite、WebRTC API、TypeScript
参见 client/README.md 了解详情。
功能
WebRTC 功能
客户端与服务器之间的 WebRTC 连接
通过 DataChannel 传输音频和控制消息
可配置 STUN/TURN 以支持 NAT 穿透
监控连接质量
使用 PCM16 音频格式，无需转换编解码器
语音 Agent 功能
实时语音交互
服务端语音活动检测（VAD）
对话转录
处理打断
用于监控的调试控制台
界面功能
页眉中的 WebRTC 标记
连接质量指示器
统计面板（码率、抖动、丢包和往返时间 RTT）
麦克风电平指示器
实时显示转录文本，跨会话保留
配置
服务端配置
编辑 server/.env：
# Required
XAI_API_KEY=your_xai_api_key_here
# Optional
PORT=8000
VOICE=ara
INSTRUCTIONS="You are a helpful voice assistant. You are speaking to a user in real-time over audio. Keep your responses conversational and concise since they will be spoken aloud."
API_URL=wss://api.x.ai/v1/realtime客户端配置
客户端会自动连接至 http://localhost:8000（如果设置了 VITE_API_BASE_URL，则连接至该地址）。
TURN 服务器配置
客户端和服务端都包含 ENABLE_TURN 开关，可在网络受限时启用 TURN 服务器：
位置：
客户端：
client/src/hooks/useWebRTC.ts（第 13 行）服务端：
server/src/rtc-peer.ts（第 9 行）
默认值：false（仅使用 STUN，适用于大多数网络）
何时启用：
企业防火墙限制严格，阻止 UDP
网络需要 TURN 中继
测试 TURN 服务器功能
注意：如果 TURN 服务器响应缓慢或不可达，启用 TURN 可能会使连接时间增加 10 至 15 秒。大多数连接只使用 STUN 即可正常工作。
建议：使用 Chrome 或 Edge 以获得最佳兼容性。
与 WebSocket 版本比较
| 功能 | WebSocket 版本 | WebRTC 版本 |
|---|---|---|
| 音频传输 | WebSocket | WebRTC DataChannel |
| 控制消息 | WebSocket | WebRTC DataChannel |
| 音频格式 | PCM16 | PCM16 |
| NAT 穿透 | 不适用（直连） | STUN/TURN |
| 连接质量统计 | 无 | 有，提供详细统计 |
| 浏览器支持 | 所有现代浏览器 | 推荐 Chrome 或 Edge |
| 连接时间 | 快（约 1 秒） | 快（约 1 秒，使用 TURN 时可能更慢） |
开发
客户端和服务端均采用 TypeScript，以保证类型安全并改善开发体验。
服务端开发
cd server
npm run dev # Run with ts-node (no build step)
npm run watch # Watch mode for TypeScript客户端开发
cd client
npm run dev # Vite dev server with HMR