📌 项目地址：huggingface/speech-to-speech | ⭐ 7,033 颗星 | 🔧 Python | 📜 未标注
一句话概括
speech-to-speech 是 Hugging Face 推出的模块化语音代理框架，将 VAD（语音活动检测）→ STT（语音转文字）→ LLM（大语言模型）→ TTS（文字转语音） 四个阶段串成一条低延迟管道，并通过 OpenAI Realtime 兼容的 WebSocket API 暴露出来。你可以用纯本地模型跑通全流程，也可以混合云端 LLM，所有组件都能自由替换。
为什么要关注这个项目
市面上不少语音助手方案要么依赖云服务（延迟高、数据外传），要么组件绑定紧密（换个模型就得改代码）。speech-to-speech 的设计目标很明确：每个阶段都独立，每个阶段都支持热插拔。VAD 默认用 Silero V5，STT 用 Parakeet TDT，LLM 只要兼容 OpenAI API 格式（包括本地 llama.cpp、vLLM），TTS 用 Qwen3-TTS。这意味着你可以在完全离线的环境中得到一个实时语音对话机器人，而且延迟低到可以作为生产环境使用（已用于数千台 Reachy Mini 机器人）。
上手：最快 3 分钟跑起来
前提：Python 3.10+，以及一个 OpenAI API Key（即使你后续想切成本地 LLM，首次启动也需要这个 key 来获取默认模型配置）。
pip install speech-to-speech
export OPENAI_API_KEY=sk-xxxx
speech-to-speech
默认会在 ws://localhost:8765/v1/realtime 启动一个 WebSocket 服务。然后用仓库里的客户端脚本测试：
# 需要先从 GitHub 克隆仓库
git clone https://github.com/huggingface/speech-to-speech.git
cd speech-to-speech
python scripts/listen_and_play_realtime.py --host 127.0.0.1 --port 8765
对着麦克风说话，几秒内就能听到回复。
完全本地化：把 LLM 换成本地模型
如果希望整个管线都不联网，可以把 LLM 指向本地的 llama.cpp 服务。以 Gemma 4 为例：
# 启动 llama.cpp 服务
llama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 65536 -fa on --swa-full
然后重新启动 speech-to-speech，指向本地地址：
speech-to-speech
--model_name "ggml-org/gemma-4-E4B-it-GGUF"
--responses_api_base_url "http://127.0.0.1:8080/v1"
--responses_api_api_key ""
注意 --responses_api_api_key 留空即可，因为本地服务不需要认证。VAD 和 TTS 默认都使用本地 Transformers 模型，因此整个栈不再依赖外网。
与 OpenAI Realtime 的兼容性
这个项目不仅内部使用 OpenAI 协议，它本身也是一个 OpenAI Realtime API 的兼容服务器。任何现有的 Realtime 客户端（比如网页、移动端、智能音箱框架）都可以直接连接 ws://.../v1/realtime，并用标准消息格式发送音频流、接收文本/音频流。这让你可以在不改变已有上层架构的前提下，把后端从 OpenAI 替换成你的本地语音代理。
多语言支持
TTS 默认使用 Qwen3-TTS，支持多种语言（中文、英文、日文、法文、德文等）。你可以通过 --tts_model 或环境变量切换其他 Hub 上的 TTS 模型。多语言场景下，LLM 的响应语言取决于你选的模型，speech-to-speech 本身不做语言检测或翻译，只负责透传。
需要注意的点
- 依赖较大：首次启动会下载 VAD、STT、TTS 模型（几 GB），请预留网络带宽和磁盘空间。
- 性能调优：默认配置在普通 GPU（如 RTX 3090/4090）上可以达到可交互的延迟（<2s）。如果在 CPU 上运行，STT 和 TTS 的延迟会显著增加。README 没有讨论具体优化方法，建议参考各组件文档。
- 许可证：项目本身采用 MIT license（见仓库 LICENSE 文件），但请留意内部调用的模型（如 Gemma、Qwen3）各自的许可证。
- 不支持会话管理：目前每个连接对应一次对话，没有内置的持久化记忆或上下文管理，你需要自己在上层实现。
适合谁用
- 想快速搭建一个本地语音助手的开发者，不希望数据离开自己机器。
- 需要低延迟实时交互的场景，比如机器人对话、语音控制界面。
- 希望更换任意组件（比如换个更好的 STT 或 TTS）的实验者。
- 已有 OpenAI Realtime 客户端代码，想切换到开源方案降低成本或增加隐私性。