🎙️ VoiceAgent

实时 AI 语音外呼 Agent Real-time AI voice agent for outbound phone calls.

一条全流式语音管线：FreeSWITCH → VAD → ASR → EOU → LLM → TTS， 通过投机生成（preemptive）和帧级流式播放，把端到端延迟从 5–8s 压到 ~500ms。

---

✨ 核心特性

• 🎙️ 全流式管线 — 火山流式 ASR + Silero VAD + 语义 EOU（turn-detector），实时吐 partial 喂给投机生成。
• ⚡ 投机生成 (Preemptive) — 用户还在说话时就提前跑 LLM + TTS；说完若文本匹配则直接秒回，把 LLM 延迟藏进用户说话期间。
• 🔊 帧级流式播放 — 火山双向流式 TTS → FIFO → FreeSWITCH，无段间空隙、无落盘等待。
• 🧩 双传输模式 — 同一份管线既能接 FreeSWITCH 打真实电话，也能浏览器直连调试（绕开电话网）。
• 🧠 语义判停 (EOU) — LiveKit turn-detector 多语种模型判断用户是否真说完，规则后端可降级（EOU_BACKEND）。
• 🛡️ 打断 (Barge-in) — 软/硬打断区分：附和（"嗯/对"）暂停后续播，实质打断切断 AI；VAD 一次榨干音频队列即时响应。
• 📊 ASR 评测台 — asr_eval/ 内置合成 + 真实音频的识别准确率评测脚本。

🏗️ 端到端数据流

   ☎️ 电话                                                    🔊 回声
   FreeSWITCH ──PCM──▶ VAD ──▶ ASR ──partial──▶ EOU ──▶ LLM ──▶ TTS
   (mod_audio_stream)  Silero   火山流式      turn-detector       火山流式
        ▲                │         │                      │        │
        │                │     投机生成：USER_SPEAKING 阶段提前启动 LLM+TTS
        └────────────────┴──── FIFO 帧级回灌 ◀──────────────────────┘

控制核心是 services/controller，按状态机（USER_SPEAKING / WAITING / PROCESSING / AI_SPEAKING）调度各 worker。

📦 项目结构

VoiceAgent/
├── main.py                  进程入口：装配 transport + 三大事件循环
├── app/                     传输层
│   ├── freeswitch_client.py FreeSWITCH ESL + mod_audio_stream
│   ├── audio_ws_server.py   mic 音频 WebSocket 反连
│   └── debug_server.py      浏览器调试传输
├── services/                管线各 worker
│   ├── vad/                 Silero VAD
│   ├── asr/                 火山流式 ASR（ASRRouter 适配层）
│   ├── eou/                 End-of-Utterance 判定
│   ├── llm/                 LLM worker（含 warmup 长连接）
│   ├── tts/                 火山流式 TTS + FIFO 播放
│   ├── controller/          状态机调度
│   └── logger/              通话记录
├── web/                     Next.js 调试控制台
├── docs/                    VitePress 文档（架构 / 管线 / 延迟优化实录）
├── asr_eval/                ASR 准确率评测台
└── start_voice_agent.sh     一键启动（含 FreeSWITCH 检查）

🚀 快速开始

平台：macOS (Apple Silicon)。需要 uv、FreeSWITCH，以及火山引擎 ASR/TTS 的密钥。

# 1. 配置环境变量（火山引擎 ASR/TTS 密钥、LLM key 等）
cp .env.example .env   # 按需填写

# 2. 安装依赖
uv sync

# 3a. 电话模式（默认，需 FreeSWITCH 在跑）
./start_voice_agent.sh

# 3b. 浏览器调试模式（绕开电话网）
TRANSPORT=browser uv run python -u main.py
#   然后启动调试控制台：
cd web && npm install && npm run dev

常用环境变量：

变量	作用	默认
TRANSPORT	freeswitch（电话）/ browser（调试）	freeswitch
EOU_BACKEND	model（turn-detector 语义判停）/ rule（词尾规则）	model
BARGE_SOFT_DUR	软/硬打断时长阈值（秒），短于此视作附和续播	0.8

📚 文档

docs/ 是一个 VitePress 站点，记录了完整的架构、管线拆解、以及把延迟从 5–8s 压到 ~500ms 的优化实录：

cd docs && npm install && npm run dev

🧪 ASR 评测

cd asr_eval
uv run python eval.py        # 跑准确率评测

🛠️ 技术栈

Python · uv · PyTorch · Silero VAD · LiveKit turn-detector · 火山引擎 ASR/TTS · FreeSWITCH · Next.js · VitePress

📄 License

MIT © Casper