🎙️ speech-to-speech：Hugging Face 开源语音智能体pipeline

speech-to-speech 是 Hugging Face 开源的模块化语音智能体 pipeline，完整串联 VAD→STT→LLM→TTS 全链路，通过 OpenAI Realtime 兼容 WebSocket 对外提供服务。全部组件均可自由替换，彻底摆脱云端 API 的隐私焦虑与成本压力。

⭐ 核心亮点

speech-to-speech 是 Hugging Face 出品的模块化语音智能体开发框架，6.8k Stars。不是什么玩具项目——它已经在数千台 Reachy Mini 机器人的生产环境里跑了很久，作为这些机器人的对话大脑。

整个 pipeline 走的是四步链：VAD 检测语音边界 → STT 把声音转文字 → LLM 生成回复 → TTS 把文字转回语音。每个环节都有多个后端可选，OpenAI 的、llama.cpp 的、本地模型的，统统能换。

最骚的是：只要你的客户端支持 OpenAI Realtime API，就可以直接连上来。意味着市面上所有支持这个协议的 AI 应用、浏览器插件、手机 App，都能直接用这个开源 pipeline 搭建自己的语音助手，而不用交一分钱给云厂商。

一条命令启动：

pip install speech-to-speech
export OPENAI_API_KEY=***
speech-to-speech

默认走 Parakeet TDT 做语音识别，OpenAI 的 LLM，然后 Qwen3-TTS 输出语音。监听在 ws://localhost:8765/v1/realtime，随便找个 WebSocket 客户端就能开聊。

📥 安装使用

Python 环境要求：3.10+

最简安装：

pip install speech-to-speech

然后设置 API Key（用 OpenAI 或者兼容 OpenAI 协议的其他 LLM 提供商）：

export OPENAI_API_KEY=***
speech-to-speech

想要全本地跑？一条命令切到 llama.cpp：

# 后台起一个本地 Gemma4 模型
llama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 65536 -fa on --swa-full

# 把 speech-to-speech 的 LLM 指过去
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 ""

4 种运行模式：

模式	传输方式	适用场景
`realtime`（默认）	WebSocket / OpenAI Realtime 协议	对接标准语音 App / 设备
`local`	直接用本机麦克风和扬声器	本地直接开聊
`websocket`	原始 PCM over WebSocket	轻量自定义客户端
`socket`	原始 PCM over TCP	模型跑在远程服务器

支持的可替换后端一览：

组件	后端选项
VAD	Silero VAD v5（内置）
STT	Parakeet TDT / Whisper / Faster Whisper / Lightning Whisper MLX / Paraformer
LLM	OpenAI 兼容 API / Transformers / mlx-lm（Apple Silicon）
TTS	Qwen3-TTS（默认）/ Kokoro-82M / Pocket TTS / ChatTTS / MMS TTS

TTS 额外安装：

pip install "speech-to-speech[kokoro]"     # Kokoro-82M TTS
pip install "speech-to-speech[pocket]"     # Pocket TTS
pip install "speech-to-speech[chattts]"    # ChatTTS
pip install "speech-to-speech[facebook-mms]" # MMS TTS
pip install "speech-to-speech[faster-whisper]" # Faster Whisper

NVIDIA GPU 用户注意：Linux 下 Qwen3-TTS 的 GGML 后端默认 wheel 绑的是 CUDA 12.8，如果你的机器是其他 CUDA 版本，先装对应 wheel 再装 speech-to-speech：

# CUDA 13.x
pip install "qwentts-cpp-python==0.3.1+cu130" \
  -f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cu130

# CUDA 12.4
pip install "qwentts-cpp-python==0.3.1+cu124" \
  -f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cu124

# CPU only
pip install "qwentts-cpp-python==0.3.1+cpu" \
  -f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cpu

pip install speech-to-speech

从源码安装：

git clone https://github.com/huggingface/speech-to-speech.git
cd speech-to-speech
uv sync

🎯 适用场景

🤖 机器人集成
已经在数千台 Reachy Mini 机器人里跑着了，这个 pipeline 就是它们的语音大脑。如果你也在做具身智能项目，这是目前最省心的开源方案。

🏠 隐私敏感场景
不想把语音数据发给任何云厂商？全本地跑，麦克风进、声音出，中间没有任何数据离开你的机器。llama.cpp + Kokoro/TTS 的组合，完全不依赖任何网络。

🧪 AI 应用语音化
你的 App 或者浏览器插件接了 OpenAI Realtime API？无缝替换成这个开源 pipeline，零成本获得同等能力。各种智能客服、语音助手、语音笔记工具都可以基于这个改。

🍎 Apple Silicon 用户
macOS 上有原生的 MLX 加速支持，MLX Whisper 做 STT，mlx-lm 跑 LLM，mlx-audio 做 TTS，一套全苹果自研芯片跑到底，效率高还不费电。

🔍 对比/替代方案

vs ChatGPT Voice / Realtime API
省去每月 $200 的 Plus 订阅费，不用受限于 OpenAI 的模型和语音选项。自己的机器跑，Token 成本趋近于零。缺点是你得自己维护服务。

vs RealtimeTTA / 其他语音智能体框架
speech-to-speech 的最大优势是 Hugging Face 背书，生态完整，文档清晰，每个组件都有多个生产级后端可选。模块化程度高，想换哪个环节就换哪个，不用被迫接受整套方案。

vs 纯本地 TTS 方案（如 fish-speech, GPT-SoVITS）
那些是单点 TTS 工具，这个是完整 pipeline。如果你的场景只需要语音合成，用 fish-speech 就够了；但要做完整的语音对话智能体，这个才是完整解。

⚠️ 注意事项

CUDA 版本匹配问题
Linux 用户安装时最常踩的坑就是 Qwen3-TTS GGML 后端的 CUDA 版本。如果跑起来报 CUDA 相关错误，大概率是 wheel 版本和你的驱动不匹配。先装对 qwentts-cpp-python 版本再装主包。

numpy 版本冲突
DeepFilterNet（可选音频增强）和 Pocket TTS 存在 numpy 版本冲突：前者要求 numpy<2，后者要求 numpy>=2。如果你两个功能都要，得手动处理依赖隔离。

macOS Apple Silicon 限制
部分 TTS 后端（如 Kokoro）需要通过 Rosetta 2 跑 x86 版本，或者用替代方案（Qwen3-TTS 通过 mlx-audio 可以原生支持）。

中文支持看模型
默认的 Parakeet TDT 和 Qwen3-TTS 对中文支持较好，但如果你换成其他 STT/TTS 模型，需要确认该模型是否针对你的目标语言优化过。

Realtime API 客户端需要支持 WebSocket
realtime 模式需要客户端实现 WebSocket 连接和 OpenAI Realtime 协议。如果你的客户端只支持普通 HTTP API，得用 local 模式直接对着麦克风聊。

✅ 总结

一句话：Hugging Face 出品的模块化语音智能体 pipeline，VAD→STT→LLM→TTS 四个环节全部可替换，用 OpenAI Realtime 协议暴露服务，6.8k Stars，已经在数千台机器人生产验证过。

优点：

全链路模块化，每个组件都能换掉
OpenAI Realtime 兼容，现有生态零成本接入
生产级验证，机器人里真跑了
支持 llama.cpp/vLLM/GGML，全本地无云依赖
Apple Silicon MLX 加速支持

缺点：

依赖 Python 3.10+
全开源方案配置起来比直接用 API 复杂一些
CUDA 版本 wheel 匹配需要手动处理
文档主要是英文

推荐指数：⭐⭐⭐⭐（4/5）

适合有语音智能体需求、想要本地部署、或者在做具身智能项目的开发者。目前同类开源方案里，Hugging Face 这套的模块化和生产成熟度都是靠前的。

GitHub | PyPI