网页语音 Agent

本示例构建在浏览器中运行的语音 Agent。React 客户端可搭配 Python 或 Node.js 后端，通过后端连接 Grok API 的实时语音服务。切换服务器时无需更改前端。

注意：这些实现用于学习和开发。要用于生产环境，还需进一步加固。

架构

所有示例均采用以下架构：

Browser (Web Client)
    ↓ WebSocket + REST API
    ↓
Backend (Python or Node.js)
    ↓ WebSocket
    ↓
XAI Realtime Voice API

组件

前端

位置：client/

单个 React + TypeScript 网页应用
同时支持 Python 和 Node.js 后端
功能包括：
- 实时音频流
- 调试控制台（显示音频以外的所有 WebSocket 消息）
- 实时对话转录
- 麦克风音量指示器

后端

所有后端均提供相同的 REST 和 WebSocket API，因此可在不更改前端的情况下相互替换。默认均运行在 8000 端口。

XAI 后端

位置：xai/

Python：xai/backend-python/，使用 FastAPI + websockets
Node.js：xai/backend-nodejs/，使用 Express + ws

快速开始

1. 选择并启动后端

所有后端均使用 8000 端口，因此一次只能运行一个。

XAI Python 后端：

cd xai/backend-python
./start.sh

XAI Node.js 后端：

cd xai/backend-nodejs
./start.sh

2. 启动前端

cd client
./start.sh

3. 打开浏览器

访问 http://localhost:5173

功能

所有后端的共有功能

用于会话管理的 REST API
连接语音 API 的 WebSocket 代理
服务端 VAD（语音活动检测）
双向音频流
支持原生采样率的 PCM16 音频格式
健康检查端点

前端功能

通过 Web Audio API 使用麦克风和扬声器
实时音频可视化
调试控制台（不包含音频消息）
实时对话转录
简洁的黑白界面
支持 TypeScript

共用 API 约定

所有后端实现相同的 API：

REST 端点

GET  /                      - Service info
GET  /health                - Health check
POST /sessions              - Create session
GET  /sessions              - List sessions
DELETE /sessions/:id        - Delete session

WebSocket 端点

WS /ws/:session_id          - Audio streaming

WebSocket 消息

客户端 → 服务器：

{"type": "input_audio_buffer.append", "audio": "base64..."}
{"type": "input_audio_buffer.commit"}
{"type": "response.create"}

服务器 → 客户端：

转发全部 XAI API 事件
包括音频、转录、状态更新和错误

配置

后端环境变量

# API key
XAI_API_KEY=your_key

# API endpoint
API_URL=wss://api.x.ai/v1/realtime

# Server configuration (same for all)
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."

前端环境变量

# Backend URL (same for all backends)
VITE_API_BASE_URL=http://localhost:8000

测试不同后端

前端不依赖具体后端实现，可按以下步骤切换测试：

停止当前后端（Ctrl+C）
启动另一个后端
刷新浏览器（无需重启前端）
点击 START 连接新后端

音频格式

所有示例均使用以下配置：

采样率：自动检测浏览器原生采样率，通常为 48 kHz、44.1 kHz 或 24 kHz
格式：PCM16（16 位有符号整数）
声道：单声道
传输：在 JSON 格式的 WebSocket 消息中以 Base64 编码传输
分块时长：约 100 毫秒

注意：XAI 后端支持原生采样率。前端自动检测浏览器的原生音频采样率并据此配置会话，从而避免重采样开销并改善音质。

前置条件

所有示例

XAI API 密钥
支持 Web Audio API 的现代浏览器

Python 后端

Python 3.8 或更高版本
pip 和 venv

Node.js 后端

Node.js 18 或更高版本
npm

前端

Node.js 18 或更高版本
npm

注意：移动浏览器不在官方支持范围内。

从写代码，到创作下一幕

Agent Plan & Coding Plan

Seedance 2.5