huggingface/speech-to-speech —— 用开源模型构建本地语音代理

这是什么

huggingface/speech-to-speech 是一个基于 Python 的低延迟、全模块化语音代理管道，以 VAD → STT → LLM → TTS 四级级联方式实现端到端语音对话。整个管道通过一个与 OpenAI Realtime API 兼容的 WebSocket 接口暴露，允许任何 OpenAI Realtime 客户端直接连接。每个组件都可独立替换：STT 可以用 Parakeet TDT、Faster Whisper、Whisper MLX 等；LLM 槽位支持所有兼容 OpenAI 协议的推理端点，包括托管服务、Hugging Face Inference Providers 以及本地运行的 vLLM 或 llama.cpp 服务器；TTS 则原生支持 Qwen3-TTS（含 GGML 与 MLX 后端）、Kokoro-82M、ChatTTS、Pocket TTS 等。该管道已经在生产环境中作为数千台 Reachy Mini 机器人（桌面交互机器人）的对话后端运行，证明了其稳定性和实用性。

解决的问题

构建一个可投入生产的语音助手通常需要集成多个独立子系统：语音活动检测（VAD）、语音识别（STT）、语言模型推理、语音合成（TTS），并处理它们之间的时序、并发、流式传输与中断逻辑。同时，不同应用场景对延迟、模型能力、隐私合规性（端侧部署）的要求差异巨大。speech-to-speech 通过四个点解决了这些困扰：

• 消除集成成本：提供一个开箱即用的级联管道，所有组件预先对接好，开发者只需安装并配置环境变量即可运行。
• 组件可置换：用户可根据硬件（GPU/CPU/macOS Silicon）、模型需求（实时性 vs 质量 vs 成本）自由切换 STT、LLM、TTS 组件，而无需重写管道逻辑。
• 兼容现有生态：LLM 和后端 API 采用 OpenAI 兼容协议，意味着开发者可以让管道指向任何兼容提供商（如 OpenAI、Anthropic、本地推理服务器），并且已有的大量 OpenAI Realtime 客户端工具可以直接连接，无需定制接口。
• 生产级稳定：在数千个机器人上验证过的低延迟、高可用性，支持实时打断、流式转录、工具调用等业务关键特性。

核心功能

1. 四级级联管道：VAD（Silero VAD v5）负责检测语音边界和切换轮次，STT 将用户音频转为文本（可选实时部分转录），LLM 生成响应文本与工具调用，TTS 合成音频并流式回传。每个阶段运行在独立线程中，通过队列连接。

2. 多种运行模式：

   • realtime 模式（默认）：通过 OpenAI Realtime 协议的 WebSocket 服务器暴露（ws://localhost:8765/v1/realtime），支持双向流式音频、实时转录、服务器端 VAD 判断说话结束、中断响应、工具调用事件。
   • WebSocket 模式：更简洁的二进制 WebSocket 端点，客户端发送 16 kHz int16 PCM 原始音频，接收生成音频。
   • TCP socket 模式：最小化的原始 PCM 数据流传输，适合嵌入式或低带宽场景，但不包含 Realtime API 的辅助事件。
   • local 模式：在 macOS 上通过 --local_mac_optimal_settings 一键启用 MPS 加速、MLX LM 后端、mlx-audio 的 Qwen3-TTS 等优化配置，实现完全本地运行。

3. 组件后端多样性：

   • STT：Parakeet TDT（默认）、Faster Whisper、Whisper MLX（macOS）、Paraformer（FunASR）。
   • LLM：任意 OpenAI 兼容 API（通过 --responses_api_base_url 配置），包括 llama.cpp、vLLM、mlx-lm 等本地模型。
   • TTS：Qwen3-TTS（GGML/MLX/torch 后端）、Kokoro-82M、ChatTTS、Pocket TTS、Facebook MMS。
   • VAD 可选使用 DeepFilterNet 进行音频增强（与 Pocket TTS 有 numpy 版本冲突，需手动处理）。

4. 本地全开源栈：通过 llama.cpp 在本地运行 Gemma 4，然后将 speech-to-speech 指向本地 llama-server，即可实现完全不依赖云端的全开源语音对话系统。

5. Docker 快速部署：提供 docker compose up 一键启动 llama.cpp 服务器 + TCP socket 服务器，暴露端口供客户端连接。

6. 多语言支持：Qwen3-TTS 支持自动语言检测，多语言 TTS 后端（如 Kokoro、ChatTTS）提供额外选择。

亮点 / 与同类相比

• 低延迟优先设计：每个组件独立线程 + 队列驱动，支持流式输出与实时打断。在 realtime 模式下，服务器端 VAD 判断用户说完整句话后立即开始处理，中间几乎无额外缓冲。普通人机对话延迟可控制在亚秒级。
• 完全模块化：与许多“一体式”语音框架（如 Coqui TTS 全栈）不同，speech-to-speech 的每个阶段都可独立替换，并通过 CLI 标志选择，无需修改代码。这为实验不同模型组合（比如对比 Parakeet TDT vs Faster Whisper 的识别延迟/准确率）提供了极大便利。
• OpenAI Realtime 兼容：直接暴露符合官方协议的 WebSocket 端点，这意味着开发者可以使用 OpenAI 的 Python SDK、TypeScript SDK 或任何第三方 Realtime 客户端直接连接。这大大降低了接入门槛，也让利用现有对话管理、流式处理、中断逻辑成为可能，而无需重新发明协议。
• 全本地运行能力：通过 llama.cpp + Qwen3-TTS GGML 后端，可以完全脱离云端在消费级 GPU（甚至 CPU）上运行。macOS Silicon 用户还能通过 mlx 获得极佳的本地推理性能。相比之下，许多同类项目（如 LiveKit Agents、Asterisk-based 方案）要么依赖云端 API，要么在本地部署上缺乏对 Apple Silicon 和 GGML 的优化。
• 生产验证：已在数千台 Reachy Mini 机器人上作为对话后端长期运行，证明了其稳定性和可扩展性。这意味着它可以安全地用于真实产品，而不仅仅是实验玩具。
• 丰富的安装与配置文档：CLI 参数覆盖全面（speech-to-speech -h 可查看所有后端特定参数），并有详细的 Realtime API 事件参考、架构说明和贡献指南。

适合谁用 / 上手

适合人群：

• 开发语音交互应用（如智能客服、语音助手、机器人对话）的工程师。
• 需要快速原型验证不同 STT/LLM/TTS 组合效果的研究者或产品经理。
• 希望部署全本地（隐私敏感、离线场景）语音对话系统的开发者。
• 对 OpenAI Realtime API 感兴趣、希望用自定义模型替代闭源服务的开发者。

上手方式：

1. 安装：pip install speech-to-speech（Python 3.10+）。
2. 配置 OpenAI API Key（如果使用 OpenAI LLM）或指定本地 LLM 端点。
3. 直接运行 speech-to-speech，启动默认服务器（默认使用 Parakeet TDT STT + OpenAI Responses API + Qwen3-TTS GGML 后端）。
4. 在与服务器同一机器或网络上运行客户端脚本 python scripts/listen_and_play_realtime.py 即可直接用麦克风说话和收听回复。
5. 若需完全本地运行，可以先用 llama.cpp 启动 Gemma 4 服务器，然后运行 speech-to-speech --model_name "ggml-org/gemma-4-E4B-it-GGUF" --responses_api_base_url "http://127.0.0.1:8080/v1" 等命令。
6. Docker 一键部署：docker compose up 启动全栈服务。

更多细节（如更换 TTS 后端、启用流式转录、macOS 优化设置、CLI 参考）均已涵盖在项目文档中。