HuggingFace 出品的 speech-to-speech 是本周 GitHub 周榜第 15（周增长 3823 star）。截至 2026-08-06，11350 颗星、1402 fork、132 open issues、107 watchers，Apache-2.0 协议，纯 Python，仓库 2024-08-07 创建，最近一次 push 就在今天（2026-08-06），项目还在快速迭代。一句话定位：用开源模型搭本地语音 agent，一条 VAD→STT→LLM→TTS 流式 pipeline，对外暴露 OpenAI Realtime 兼容的 WebSocket API，每个组件都能换。背靠 HuggingFace 意味着它默认接的是自家生态的模型（Parakeet TDT、Qwen3-TTS 都托管在 HF Hub 上），但协议层留足了口子，OpenAI、vLLM、llama.cpp 都能接，不绑死任何一家。它已经在生产环境跑——是数千台 Reachy Mini 机器人的对话后端，不是个 demo 项目。
一、它是什么
一条低延迟、全模块化的语音 agent pipeline：VAD → STT → LLM → TTS，通过 OpenAI Realtime 兼容的 WebSocket API 暴露在 ws://localhost:8765/v1/realtime。每个组件都可换。默认配置：本地 Parakeet TDT 做 STT、OpenAI 兼容 API 当 LLM（默认模型 gpt-5.4-mini）、本地 Qwen3-TTS 做语音输出。LLM 这个槽位说 OpenAI 兼容协议，所以可以指向托管厂商（OpenAI、HF Inference Providers、OpenRouter）、自托管服务（vLLM、llama.cpp），或本地 transformers / mlx-lm——凑齐「全本地、全开源」的一套。任何 OpenAI Realtime 兼容客户端都能连，把 base_url 换一下就行。
二、解决什么痛点
云端语音 agent（OpenAI Realtime 这类）有三个绕不开的痛点。一是贵：按音频分钟计费，一个客服中心一天几千小时通话，云 API 账单能到几万美元，重度使用烧钱烧得肉疼。二是延迟：音频上云、模型推理、音频回传这一圈 round trip，很难压到 300ms 以内，用户说完话要干等半秒才听到回应，对话节奏发飘，体验远不如人与人对话。三是隐私：用户语音数据出本机，医疗问诊、金融电话、客服录音这些场景直接踩合规红线，GDPR、HIPAA、国内个保法都过不去。再加上厂商锁定——云厂商改 API、改定价、下线模型，你只能跟着。speech-to-speech 的解法是把四个组件全做成可换、可全本地：VAD 用 Silero VAD v5，STT 默认 Parakeet TDT，TTS 默认 Qwen3-TTS，LLM 槽位既可以调云厂商也可以指向 llama.cpp 本地服务。要全本地就把 LLM 指向本地，要省事就调 OpenAI API，要数据不出本机就四个组件全开本地开源模型。协议层用 OpenAI Realtime 兼容，意味着你原来写好的 Realtime 客户端不用改代码，换端点即可。
三、核心能力：开源模型搭本地语音 agent（ASR+LLM+TTS 流式）
四个阶段各自跑在独立线程里，靠 queue 串起来：
- VAD（语音活动检测）：Silero VAD v5 检测语音边界和 turn-taking。
- STT（语音转文字，即 ASR）：转写用户这一轮话，可选实时 partial transcript。
- LLM：生成回复，流式输出文本和 tool call。
- TTS：合成音频流式回传客户端。
「全模块化」在实战中意味着什么？意味着你可以按硬件预算和延迟要求逐个组件调。比如延迟敏感场景把 LLM 换成小模型量化版，TTS 换成更轻的 Kokoro-82M；中文场景把 STT 换成 Paraformer，TTS 换成 ChatTTS；Mac 用户一条 --local_mac_optimal_settings 全切到 MLX 生态。组件之间靠 queue 解耦，换一个不影响其他三个，这是它和「一坨打包好的黑盒语音 SDK」最根本的区别。
支持的组件清单（README 原表）：
| Component | Backend | Platforms |
|---|---|---|
| VAD | Silero VAD v5 | all |
| STT | Parakeet TDT（默认） | CUDA/CPU via nano-parakeet，Apple Silicon via MLX |
| STT | Whisper（Transformers） | CUDA/CPU |
| STT | Faster Whisper | CUDA/CPU |
| STT | Lightning Whisper MLX | Apple Silicon |
| STT | MLX Audio Whisper | Apple Silicon |
| STT | Paraformer | CUDA/CPU |
| LLM | OpenAI 兼容 API（responses-api / chat-completions） | 托管或自托管 |
| LLM | Transformers | CUDA/CPU |
| LLM | mlx-lm | Apple Silicon |
| TTS | Qwen3-TTS（默认） | Linux 走 GGML/CUDA，macOS 走 mlx-audio |
| TTS | Kokoro-82M | CUDA/CPU，Apple Silicon |
| TTS | Pocket TTS | CPU/CUDA |
| TTS | ChatTTS | CUDA/CPU |
| TTS | MMS TTS | CUDA/CPU |
四种运行模式：
| Mode | Transport | 何时用 |
|---|---|---|
realtime（默认） | OpenAI Realtime 协议 over WebSocket 或 WebRTC | 给 app 或设备对接标准语音 API |
local | 本机麦克风和扬声器 | 直接和 pipeline 说话，不需要客户端 |
raw-websocket | 裸 PCM over WebSocket | 极简自定义客户端，不用 Realtime 协议 |
socket | 裸 PCM over TCP | 模型跑在远程服务器，配简单的麦克风/播放客户端 |
其他能力：Smart Turn v3.2 端点检测（用 huggingface.co/pipecat-ai/smart-turn-v3 模型，靠内容和韵律验证 Silero 的 end-of-speech 判定，减少用户说话中途停顿被误判成说完的「误切」情况，仅 --mode realtime 支持，默认开启，首次用时自动从 HF Hub 下载量化版 CPU 模型）；LLM Proxy（--enable_llm_proxy 把远端 LLM 同步暴露成普通 OpenAI 兼容端点，让客户端能并发跑摘要/起标题/后台 agent，不被语音对话打断，适合在对话进行中同时做会议纪要、意图分类等副任务）；多语言（取决于 STT/TTS backend，Parakeet TDT 覆盖 25 种欧洲语言，Whisper 广覆盖多语言，Paraformer 默认偏中文，Qwen3-TTS 多语言默认 --qwen3_tts_language auto，ChatTTS 英文+中文，--language auto 让 STT 检测每段语音语种转发给 LLM；可选 --enable_lang_prompt 追加一句「请用某种语言回复」的指令，大模型通常能从上下文推断语种，但小模型加这句显式指令更稳）；Pocket TTS（Kyutai Labs 出品，流式 TTS 带声音克隆，8 个预设音色 alba/marius/javert/jean/fantine/cosette/eponine/azelma，也支持自定义声音文件和 HF Hub 路径，适合给品牌或角色定制专属音色）。
四、三分钟上手
# 1. 装（Python 3.10+）
pip install speech-to-speech
# 2. 跑（默认 LLM 走 OpenAI Responses API，需要 OPENAI_API_KEY）
export OPENAI_API_KEY=sk-xxx
speech-to-speech
# 启动 OpenAI Realtime 兼容服务 ws://localhost:8765/v1/realtime
# 默认：本地 Parakeet TDT STT + OpenAI 兼容 LLM + 本地 Qwen3-TTS
# 3. 另开一个终端，直接和它说话
python scripts/listen_and_play_realtime.py --host 127.0.0.1 --port 8765上面这三行命令是最快体验路径：本地 STT 和 TTS 已经能跑，只有 LLM 走 OpenAI 云端。你对着麦克风说话，Parakeet TDT 转文字，OpenAI 生成回复，Qwen3-TTS 合成语音播回来，一条完整语音对话就跑通了。要 LLM 也留在本机（不调 OpenAI，不需要 key），用 llama.cpp 起 Gemma 4：
# Terminal 1: llama.cpp 起 Gemma 4
llama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 65536 -fa on --swa-full
# Terminal 2: 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 ""Mac 一键本地最优配置：
speech-to-speech --local_mac_optimal_settings
# 等价于 --device mps + Parakeet TDT + MLX LM + Qwen3-TTS（mlx-audio 6bit）+ --mode localDocker（需先装 NVIDIA Container Toolkit）：
docker compose up
# 起 llama.cpp + Gemma 4 + TCP socket server，暴露 8080/12345/12346五、适合谁 + 踩坑
适合：要给硬件设备（机器人、智能音箱、kiosk）搭对话后端的团队——已是数千台 Reachy Mini 机器人的生产后端；数据不能出本机的场景（医疗、金融、客服录音）；想避开云端语音 API 按分钟计费的开发者；想用 OpenAI Realtime 协议但不愿绑死 OpenAI 的团队；要在内网或离线环境跑语音 agent 的开发者（工厂车间、船舶、偏远地区，没网也能用）；做语音 agent 原型验证的研究者--一条命令起服务，OpenAI SDK 直连，省去搭基础设施的工夫。
下面七条踩坑都来自 README 明确警告或安装注意事项，提前知道能省不少排查时间。踩坑七条。一是 Qwen3-TTS 在 Linux 走 GGML backend，PyPI 默认 wheel 要 CUDA 12.8 runtime，机器没装 CUDA 12 runtime 就得先装匹配版本：pip install "qwentts-cpp-python==0.3.1+cu130" -f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cu130（CUDA 13.x）或 +cu124（CUDA 12.4）或 +cpu（纯 CPU fallback），Mac 用户走 mlx-audio 不踩这个坑。二是 LLM 是延迟大头，README 原话「The LLM is the most compute-intensive and highest-latency component」，一次大模型 forward pass 可能 dominate 端到端响应时间，要低延迟选小模型（gpt-5.4-mini、Gemma 4 E4B、Qwen3-4B）或用 Cerebras/Groq 这类低延迟推理提供商，要本地则 llama.cpp 跑量化模型。三是 macOS 与 Linux 默认 backend 不同（Qwen3-TTS 非 macOS 走 GGML，macOS 走 mlx-audio），两条路径有不同 bug，跨平台部署要两边都测。四是 DeepFilterNet 与 Pocket TTS 冲突（DeepFilterNet 要 numpy<2，Pocket TTS 要 numpy>=2，不能同装），只在不用 Pocket TTS 的环境手动装 DeepFilterNet。五是 LLM Proxy 默认关闭且无鉴权无限流，--enable_llm_proxy 暴露的 /v1/chat/completions 或 /v1/responses 只能在可信网络启用，或部署在自带访问控制的网关后面，README 明确警告。六是 Smart Turn v3.2 仅 --mode realtime 支持，选其他模式要 --no_smart_turn。七是 Direct Audio Input（绕过 STT 把 VAD 切出来的音频段直接发给 audio-input 模型）只支持 --llm_backend chat-completions，不支持 responses-api，且默认 gpt-5.4-mini 不收音频，得显式 --model_name 指定支持音频的模型。
六、和竞品比
只陈述 README 能核实的事实。和 OpenAI Realtime API 比：speech-to-speech 实现的是 OpenAI Realtime 兼容协议的核心事件集（inbound：input_audio_buffer.append、session.update、conversation.item.create、response.create、response.cancel；outbound：speech start/stop、流式转录、audio deltas、tool calls、response.done）。差异在于四组件全可换、可全本地、可全开源，OpenAI Realtime 是云服务只能调 OpenAI 模型；任何 OpenAI Realtime 客户端把 base_url 一换就能连，原来调 OpenAI Realtime 的代码几乎零改动，迁移成本低，这层协议兼容是它最大的工程杠杆。和 pipecat 比：Smart Turn v3.2 端点检测模型来自 huggingface.co/pipecat-ai/smart-turn-v3，speech-to-speech 复用了 pipecat 生态的这个模型，但 README 没把它定位为 pipecat 替代也没做对比，这里只陈述可核实部分。和单一 STT/TTS 工具（Whisper.cpp、ChatTTS、Faster Whisper、Whisper MLX 等）比：speech-to-speech 是端到端 pipeline 把 VAD+STT+LLM+TTS 串起来并暴露标准 Realtime API，单一工具只解决一环，实际上 ChatTTS、Faster Whisper、Whisper MLX 都是 speech-to-speech 的可选 backend，关系是包含而非竞争。要补充的是，speech-to-speech 不提供云端托管版本，你要自己部署和运维，这是它和 OpenAI Realtime 这类纯云服务的本质分工差异--一个卖服务，一个卖方案。一句话：要 OpenAI Realtime 兼容协议、要全本地全开源、要四组件可换、要给硬件设备搭对话后端，选 speech-to-speech。
参考来源
- HuggingFace speech-to-speech GitHub 仓库（11350 star，Apache-2.0，Python）：https://github.com/huggingface/speech-to-speech
- speech-to-speech README（取材于 2026-08-06）：https://github.com/huggingface/speech-to-speech/blob/main/README.md
- Reachy Mini 机器人介绍（README 提及的生产场景）：https://huggingface.co/blog/reachy-mini
- Smart Turn v3.2 模型（端点检测）：https://huggingface.co/pipecat-ai/smart-turn-v3
- Parakeet TDT STT 模型：https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3
- Qwen3-TTS 模型：https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice