speech-to-speech 详解：HuggingFace 的开源语音 Agent 流水线

speech-to-speech 详解：HuggingFace 的开源语音 Agent 流水线

语音 Agent 的"全开源"路线一直有个尴尬：框架开源了，模型却离不开云端 API。huggingface/speech-to-speech 把这条路走通了：VAD → STT → LLM → TTS 四段低延迟流水线，每个组件都可换成开源模型本地跑——Apple Silicon 一台 Mac 就能撑起全本地下语音对话（约 7.5GB 权重），对外暴露 OpenAI Realtime GA 事件集（WebSocket + WebRTC），官方 OpenAI Agents SDK 可直连。它已在生产中作为数千台 Reachy Mini 机器人的对话后端。约 13.2k Star、Apache 2.0 协议。本文从架构、组件矩阵、三种起步配置到选型，完整拆解。

1、项目概述

speech-to-speech（s2s）定位为低延迟、全模块化的语音 Agent 流水线：用开源模型构建语音 Agent，四组件各自独立线程、队列相连，CLI 旗标切换后端。LLM 槽位说 OpenAI 兼容协议——托管提供商、HF Inference Providers、自建 vLLM / llama.cpp 皆可，完全本地完全开源的栈一条路通到底。仓库约 13.2k Star、1.7k Fork、Apache 2.0 协议，2024 年 8 月创建，HuggingFace 官方维护，Python 3.10+（推荐 3.11），曾登 GitHub Trending 日榜第一。

基本盘：

        - 安装：pip install speech-to-speech 一条命令；默认覆盖标准 Realtime 路径，平台依赖自动按 macOS / Linux 解析

        - 默认组件：Silero VAD v5 + Parakeet TDT（STT）+ OpenAI 兼容 LLM + Qwen3-TTS（语音输出）

        - 协议：OpenAI Realtime GA 核心事件集，WebSocket（ws://…/v1/realtime）与 WebRTC 双传输

        - 生产背书：数千台 Reachy Mini 机器人的对话后端正在跑

        - 三命令模型：serve 起服务、talk 连服务器对话、local 一条命令合成两者

2、流水线架构：四组件级联

架构极简：四个组件、四个线程、三条队列——代码为易改而生。

四段流水线：

        - VAD（语音活动检测）：Silero VAD v5 检测语音边界与轮次切换，是打断与节流的闸门

        - STT（语音转文字）：转写用户轮次，支持实时部分转写（live partial transcripts）

        - LLM（大语言模型）：生成回复，流式输出文本与工具调用

        - TTS（文字转语音）：合成音频流式回传客户端

架构要点：

1. Smart Turn 端点检测是隐藏亮点：v3.2 模型用内容与韵律验证"说完了没"——完整轮次立即处理并 800ms 投机重开窗口，未完成轮次延迟 600ms 再动，抢话与漏听两头平衡

2. VAD 参数即产品手感：min_speech_ms、min_silence_ms、speculative_reopen_ms 等旗标把"何时接话"调成可调参数

3. 工具调用支持：打包客户端可挂本地 Python 工具模块（--tool-module），文档有 Serper 联网搜索示例

4. 日志默认无内容：转写记录只报字符数不存原文——服务管理器与日志聚合器的隐私默认项

3、组件矩阵与三档起步

每个槽位多个可换后端，起步按硬件与隐私三选一。

组件矩阵（README 官方表格归纳）：

        - STT 十选项：Parakeet TDT（默认）、Whisper / Faster Whisper / Lightning Whisper MLX、MLX Audio Whisper、Paraformer（FunASR，中文向）、Qwen3-ASR、OpenAI 兼容转写端点、Realtime 转写、vLLM 转写（实验）

        - LLM 四后端：OpenAI 兼容 API（responses-api / chat-completions）、Transformers（CUDA/CPU）、mlx-lm（Apple Silicon）

        - TTS 八选项：Qwen3-TTS（默认）、Kokoro-82M、Pocket TTS、ChatTTS、OmniVoice（600+ 语言、克隆）、MMS TTS、OpenAI 兼容语音端点

        - 附加：--stt none 可跳过 STT 直连音频输入模型（gpt-audio 类）；LLM Proxy 模式可把远端 LLM 暴露为普通端点跑后台任务

三档起步配置：

        - Apple Silicon 全本地：--mac-optimal-settings + MLX 4bit Qwen3-4B，约 7.5GB 权重，16GB 统一内存起，零 API 零外发

        - NVIDIA 全本地：CUDA + Transformers + float16 Qwen3-4B，LLM 权重约 8GB，规划 24GB 显存

        - 本地语音 + 托管 LLM：语音模型本地（约 5.2GB），文本走 OpenAI / HF / OpenRouter，麦克风音频不出本机

矩阵要点：

1. 中文链路有解：STT 换 Paraformer 或 Whisper（zh）、TTS 换 Qwen3-TTS（多语言 auto）、ChatTTS（中英）——语言覆盖取决于组件选择而非流水线

2. 显存预算官方给足：三档配置的内存数字都是"一档对话的规划估算"，上下文长度与音频长度会影响实际

3. 离线运行支持：先联网缓存模型，之后 HF_HUB_OFFLINE=1 完全断网跑

4. OmniVoice 权重协议警示：代码 Apache-2.0 但预训练权重 CC-BY-NC 禁商用，克隆须授权同意——选型时的硬边界

4、命令与服务形态

三条命令覆盖开发到部署，Realtime 兼容层是集成关键。

# Mac 全本地一条命令起步
speech-to-speech local \
    --mac-optimal-settings \
    --model_name mlx-community/Qwen3-4B-Instruct-2507-4bit

# 起服务（默认绑定 127.0.0.1，对外须显式 --host 0.0.0.0）
export OPENAI_API_KEY=...
speech-to-speech serve
# 等价于: --stt parakeet-tdt --llm_backend responses-api --tts qwen3
#         --model_name gpt-5.6-terra 等

# 另一终端连接对话
speech-to-speech talk --url ws://127.0.0.1:8765/v1/realtime

# Python 客户端：OpenAI SDK 直连 Realtime 会话
# from openai import OpenAI
# client = OpenAI(base_url="http://localhost:8765/v1",
#                 websocket_base_url="ws://localhost:8765/v1",
#                 api_key="not-needed")
# with client.realtime.connect(model="local") as conn: ...

# 中文配置示例（STT 换 Whisper，语言锁定 zh）
speech-to-speech serve \
    --stt whisper-mlx --stt_model_name large-v3 --language zh \
    --llm_backend mlx-lm \
    --model_name mlx-community/Qwen3-4B-Instruct-2507-4bit

使用要点：

1. Realtime 事件集双向清单：入站 input_audio_buffer.append、session.update、conversation.item.create / truncate、response.create / cancel；出站语音起止、流式转写、音频增量、工具调用、response.done——官方诚实标注"核心子集，非全量等效"

2. CI 用官方 @openai/agents RealtimeSession 走原生 WebSocket 与 WebRTC 双传输做回归——兼容性是被测出来的

3. Docker 编排：docker compose up 起 llama.cpp（Gemma 4）+ Realtime 服务，8080 与 8765 双端口

4. Linux 安装注意：Qwen3-TTS GGML 默认轮子面向 CUDA 12.8 / Ubuntu 24.04，旧环境从 HF wheelhouse 装对应版本

5、定位对比：语音 Agent 方案三选一

把 speech-to-speech 与 Pipecat、端到端商业 API 放在一张桌上，三条路线清晰起来。

三者对比：

        - speech-to-speech：HF 官方开源流水线，全本地可行，Realtime 协议兼容，代码为易改而生（13.2k Star，Apache 2.0）

        - Pipecat：Daily 维护的框架，200+ 服务集成、多 Agent、电话/WebRTC 全传输，生产生态更厚（15.5k Star，BSD-2）

        - OpenAI Realtime / Gemini Live 直用：托管端到端，零运维最低延迟，但模型与数据皆锁定

选型建议：

1. 要全开源全本地、研究或自托管隐私场景 → speech-to-speech

2. 要产品级语音 Agent、多提供商混搭、电话落地 → Pipecat

3. 要最快上线、接受厂商锁定 → Realtime API 直调

4. 组合玩法：用 speech-to-speech 当"开源 Realtime 服务器"，客户端沿用 OpenAI SDK 生态，模型按需在本地与托管间切换

6、总结

speech-to-speech 是 HuggingFace 官方维护的开源语音 Agent 流水线（约 13.2k Star、Apache 2.0、Python 3.10+）：VAD → STT → LLM → TTS 四组件独立线程队列级联，全部可换后端——STT 十选项（Parakeet TDT 默认、Whisper 系、Paraformer 中文向）、LLM 四后端（OpenAI 兼容 / Transformers / mlx-lm / 音频直入）、TTS 八选项（Qwen3-TTS 默认、OmniVoice 克隆）；Smart Turn 端点检测用模型判断说完与否，投机重开窗口平衡抢话与漏听；对外暴露 OpenAI Realtime 核心事件集（WebSocket + WebRTC），官方 Agents SDK 双传输回归测试；Apple Silicon 约 7.5GB 权重即可全本地运行，已在数千台 Reachy Mini 机器人量产验证。

适用与边界：它适合追求全开源、全本地、可深度改造的语音 Agent 场景——机器人、隐私敏感部署、模型研究都是对口用途，Realtime 兼容层让 OpenAI 生态客户端无缝迁移；四段级联架构比端到端语音模型的延迟上限高，极致低延迟仍需 Realtime 类 API；组件生态以 HF Hub 模型为中心，电话 / SIP 等传输形态不在范围内（那是 Pipecat 的领地）；OmniVoice 权重 CC-BY-NC 禁商用、LLM Proxy 无鉴权限内网等边界，选型时按官方警示逐条核对。