LiveKit Voice Agent Demo（中文电话场景）

一个最小可跑的 LiveKit Agents 中文语音对话 demo。跑通后可以用浏览器麦克风跟 AI 实时对话，也可以接入 SIP 真实电话场景。

技术栈

模块	选型	说明
框架	LiveKit Agents	WebRTC 实时音视频 + Agent 编排
VAD	Silero	端点检测 / 静音判断
STT	火山引擎流式 ASR（豆包流式语音识别 2.0）	自写 plugin，WS 流式
LLM	豆包 seed-2.0（火山方舟）	通过 OpenAI 兼容接口接入，关闭 thinking
TTS	豆包语音合成 BV700 灿灿	自写 plugin，HTTP 单次合成

特性

• 流式中文语音识别
• 流式语音合成 + Barge-in 打断
• 自写 STT/TTS plugin（火山引擎 / 豆包），可作为对接国内云服务的范式参考
• 提供 SIP Trunk 入站配置示例，对接电话机器人供应商
• 含 agent_realtime.py 作为对照：OpenAI Realtime API 一站式版本

一、准备工作

1. 注册 LiveKit Cloud（免费）

访问 https://cloud.livekit.io 用 GitHub 登录，创建 project，在 Settings 拿到 3 个值：

• LIVEKIT_URL（形如 wss://xxx.livekit.cloud）
• LIVEKIT_API_KEY
• LIVEKIT_API_SECRET

2. 拿 API Key

服务	用途	注册
火山方舟（豆包 LLM）	LLM	https://www.volcengine.com/product/ark
火山引擎语音合成（豆包 TTS）	TTS	https://console.volcengine.com/speech/service/8
火山引擎大模型 ASR	STT	https://www.volcengine.com/docs/6561/1354869

国内可直连。海外可选 Deepgram 作为 STT 备份。

3. 检查 Python

python3 --version  # 需要 3.10+

二、启动 Demo

# 1. 建虚拟环境 + 装依赖
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 2. 配 .env
cp .env.example .env
# 编辑 .env 填入 key

# 3. 首次启动需要下载 Silero VAD 模型
python agent.py download-files

# 4. 启动 Agent
python agent.py dev

看到类似日志说明跑起来了：

INFO  livekit.agents.cli - starting worker
INFO  livekit.agents - agent worker registered with LiveKit
INFO  livekit.agents - worker ready

三、用浏览器测试

保持 Agent 终端继续跑，新开浏览器访问：

👉 https://agents-playground.livekit.io

• 选 "Manual" 模式，填入 LIVEKIT_URL / API_KEY / API_SECRET
• 点 Connect，允许麦克风
• 听到开场白后说话，AI 会接话

验证清单

• 听到开场白
• 自己的话能被识别（看 Playground 字幕区）
• AI 回答能听到
• 自己开口能立刻打断 AI（barge-in）
• 端到端延迟在 1-2 秒以内

四、接 SIP 真实电话

1. LiveKit Cloud Dashboard → SIP → 创建 Inbound Trunk（可参考 sip-inbound-trunk.json 改 number 后导入）
2. 创建 Dispatch Rule（参考 sip-dispatch-rule.json）
3. 拿 LiveKit 分配的 SIP URI / DID 给电话机器人供应商，由对方把呼叫推过来
4. 详见 https://docs.livekit.io/sip

需要的 SIP 参数清单（问供应商要）：

参数	说明
SIP 服务器地址 / 端口 / 传输协议（UDP/TCP/TLS）	供应商信令地址
Auth Username / Password	鉴权
Caller ID（主叫号码）	E.164 格式
并发路数 / 编解码（PCMU/PCMA/Opus）/ DTMF 方式	语音参数
入站：DID 号码 + 推送 URI + 白名单 IP / 鉴权	入站对接信息

五、目录结构

.
├── agent.py                    # 主 Agent（拼接式：VAD + STT + LLM + TTS）
├── agent_realtime.py           # 对照版：OpenAI Realtime API 一站式
├── system_prompt.txt           # 系统提示词
├── plugins/
│   ├── doubao_tts.py          # 豆包 TTS plugin（HTTP）
│   └── volcengine_stt.py      # 火山引擎 ASR plugin（WS 流式）
├── sip-inbound-trunk.json      # SIP 入站 Trunk 配置示例
├── sip-dispatch-rule.json      # SIP Dispatch Rule 示例
├── requirements.txt
└── .env.example

六、延迟优化要点

agent.py 中已应用：

• thinking: {type: "disabled"} 关闭豆包 Pro 的 thinking 链（砍约 1.5s）
• max_completion_tokens=120 控制输出长度，TTS 也跟着快
• min_endpointing_delay=0.3 候选人停 300ms 即判定讲完
• preemptive_generation=True ASR partial 拿到就先跑 LLM

七、Troubleshooting

现象	排查
pip install 卡住	换源 pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt
ImportError	pip install -U livekit-agents
Playground 连不上	LIVEKIT_URL/KEY/SECRET 填错
听不到开场白	TTS appid / access_token 错或配额不足
说话识别不出	VOLCENGINE_ASR_API_KEY 错
AI 自言自语停不下	barge-in 失效，确认 Silero VAD 已加载

License

MIT