HuggingFace Speech-to-Speech：开源语音 Agent 流水线全解析

HuggingFace Speech-to-Speech 项目封面

HuggingFace 的 speech-to-speech 项目把语音 Agent 的四个核心环节——语音活动检测（VAD）、语音转文字（STT）、大语言模型（LLM）、文字转语音（TTS）——拆成了四个独立线程，用队列串联。每个环节都开放替换，LLM 槽位兼容 OpenAI 协议，整套流水线可以全部跑在本地硬件上。

截至本文，该项目在 GitHub 上获得 7189 Star、949 Fork，采用 Apache 2.0 许可证，已在生产环境中为数以千计的 Reachy Mini 机器人提供对话后端。

架构：四段式级联流水线

speech-to-speech 的核心设计是一个级联式（cascaded）管道。从用户说话到 Agent 回复，音频数据依次流经四个处理阶段，每个阶段运行在独立线程中，通过队列传递数据：

text

麦克风音频 → [VAD] → [STT] → [LLM] → [TTS] → 扬声器音频

语音活动检测（VAD）：使用 Silero VAD v5，负责检测说话的起止边界和轮次切换。这一步过滤掉静音和背景噪音，避免下游组件做无用功。
语音转文字（STT）：将用户的话语转录为文本，支持实时部分转录。
大语言模型（LLM）：生成回复内容，流式输出文本和工具调用。
文字转语音（TTS）：将回复文本合成为音频，流式返回客户端。

每个阶段都有多个可互换的后端实现，通过命令行参数选择。这种设计的好处在于：开发者可以根据硬件条件和延迟预算灵活搭配。例如在高端 GPU 服务器上用 Parakeet TDT + 大参数 LLM，在 Apple Silicon Mac 上用 MLX 优化的轻量模型，在嵌入式设备上用更小的 TTS 引擎。

Speech-to-Speech Logo

全组件可替换矩阵

下表是项目支持的全部组件组合：

组件	后端实现	平台	安装方式
VAD	Silero VAD v5	全平台	内置
STT	Parakeet TDT（默认）	CUDA/CPU/Apple Silicon	内置
STT	Whisper（Transformers）	CUDA/CPU	内置
STT	Faster Whisper	CUDA/CPU	pip extra
STT	Lightning Whisper MLX	Apple Silicon	pip extra
STT	Paraformer	CUDA/CPU	pip extra
LLM	OpenAI 兼容 API（默认）	云端/自托管	内置
LLM	Transformers	CUDA/CPU	内置
LLM	mlx-lm	Apple Silicon	内置
TTS	Qwen3-TTS（默认）	GGML/CUDA/Apple Silicon	内置
TTS	Kokoro-82M	CUDA/CPU/Apple Silicon	pip extra
TTS	Pocket TTS（Kyutai Labs）	CPU/CUDA	pip extra
TTS	ChatTTS	CUDA/CPU	pip extra

默认配置组合为：Parakeet TDT 做语音识别 + OpenAI 兼容 API 做语言模型 + Qwen3-TTS 做语音合成。

OpenAI Realtime 兼容协议

这是项目最具竞争力的设计决策。speech-to-speech 暴露了一个 WebSocket 端点 /v1/realtime，完全兼容 OpenAI Realtime API 协议。

这意味着：任何已经对接了 OpenAI Realtime API 的客户端（包括网页应用、移动 App、机器人 SDK），只需把 WebSocket 地址从 OpenAI 换成本地服务器，就能无缝切换到开源方案。

服务器实现了 OpenAI Realtime 的核心事件集：

入站：input_audio_buffer.append、session.update、conversation.item.create、response.create、response.cancel
出站：语音起止事件、流式转录、音频增量、工具调用、response.done

当用户打断 Agent 说话时，VAD 会检测到新的语音活动，通过共享的 CancelScope 机制使 LLM 和 TTS 的过期输出失效，然后清空相关队列。这种中断处理机制让对话感觉更自然。

四种运行模式

项目提供四种部署模式，适配不同场景：

Realtime（默认）：通过 WebSocket 使用 OpenAI Realtime 协议。适合在应用或设备上对接标准语音 API。

Local：直接使用本机麦克风和扬声器。适合在笔记本上直接测试流水线。

WebSocket：传输原始 PCM 音频（16kHz、int16、单声道）。适合构建极简自定义客户端。

TCP Socket：通过 TCP 流式传输原始 PCM。适合模型在远程服务器上运行、客户端在本地处理麦克风输入的场景。

快速上手

安装只需一行命令（需要 Python 3.10+）：

bash

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

这会在 ws://localhost:8765/v1/realtime 启动一个 Realtime 服务器，使用 Parakeet TDT 做本地 STT、OpenAI 兼容 LLM、Qwen3-TTS 做本地语音输出。

如果在 macOS 上运行，一条命令设置 Apple Silicon 全本地优化：

bash

speech-to-speech --local_mac_optimal_settings

这个设置会：对所有模型启用 MPS 设备、使用 Parakeet TDT 做 STT、用 mlx-lm 做 LLM 后端、用 Qwen3-TTS（mlx-audio 引擎，6bit 量化）做 TTS、设为 local 模式。

全本地部署方案

想要完全不依赖任何云端 API？项目提供了完整的本地化路径。以 llama.cpp + Gemma 4 为例：

bash

# 终端 1：llama.cpp 启动 Gemma 4
llama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 65536 -fa on --swa-full

# 终端 2：speech-to-speech 指向本地 LLM
speech-to-speech \
    --mode realtime \
    --stt parakeet-tdt \
    --llm_backend responses-api \
    --tts qwen3 \
    --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_stream \
    --enable_live_transcription

四个阶段全部运行在本地硬件上：VAD 在 CPU 上跑 Silero、STT 用 Parakeet TDT、LLM 走 llama.cpp 的 Gemma 4、TTS 用 Qwen3-TTS。没有一行数据离开你的机器。

LLM 后端的灵活性

LLM 是流水线中计算量最大、延迟最高的环节。项目为此提供了两种 API 后端，共享相同的连接参数：

responses-api（默认）：请求 /v1/responses 端点，兼容 OpenAI 最新协议
chat-completions：请求 /v1/chat/completions 端点，兼容传统格式

两种后端可以指向不同提供方：

提供方	base_url	适用场景
OpenAI	默认	快速体验
HF Inference Providers	router.huggingface.co/v1	开源模型托管
OpenRouter	openrouter.ai/api/v1	多模型路由
vLLM	localhost:8000/v1	本地 GPU 推理
llama.cpp	localhost:8080/v1	本地 CPU/Apple Silicon 推理

当使用 chat-completions 后端时，可以通过 --responses_api_reasoning_effort none 关闭推理过程，减少语音交互的延迟。这对于像 Gemma 4 31B 这样的大模型在 Cerebras 上运行时降低首字节延迟有实际意义。

多语言支持

语言覆盖取决于 STT 和 TTS 后端的选择，管道本身不限制语言。两种使用模式：

单语言模式：通过 --language zh 指定目标语言。STT 和 TTS 会针对该语言优化。

语言自动检测模式：设置 --language auto，STT 会检测每条语音的语言并传递给 LLM。可选添加 --enable_lang_prompt，在转录后追加一条指令要求 LLM 用检测到的语言回复。

bash

# 中文本地全栈
speech-to-speech \
    --stt whisper-mlx \
    --stt_model_name large-v3 \
    --language zh \
    --llm_backend mlx-lm \
    --model_name mlx-community/Qwen3-4B-Instruct-2507-bf16

生产级应用：Reachy Mini

speech-to-speech 不只是一个演示项目。它运行在生产环境中，为数千台 Reachy Mini 机器人提供对话后端。

Reachy Mini 是 Pollen Robotics 的桌面机器人，配备板载麦克风、扬声器、摄像头和九个执行器。它运行在 Linux 上（Raspberry Pi Compute Module 4），通过 HuggingFace Spaces 生态驱动应用。

在 NVIDIA GTC 的现场部署中，HP 的工程师团队使用搭载 NVIDIA GB10 Grace Blackwell 芯片的 ZGX Nano 设备运行 speech-to-speech，为 Reachy Mini 提供医疗分诊助理的语音对话能力。整个语音循环从患者走近到机器人抬头说话，延迟控制在了自然对话的范围内。

延迟优化策略

级联管道的延迟是各阶段延迟的累加。LLM 推理是最大的延迟瓶颈——一次大模型的 forward pass 可能占去端到端响应时间的主体。

项目采取的优化策略包括：

流式输出：LLM 文本和 TTS 音频都采用流式传输，播放可以在完整回复生成之前就开始。
可中断架构：用户打断时，VAD 触发 CancelScope 使 LLM 和 TTS 的过期输出失效，清空队列。
后端选择：根据硬件选择延迟最优的后端（如 Cerebras 加速的 Gemma 4、Groq 加速的 gpt-oss-20b）。
推理抑制：通过 --responses_api_reasoning_effort none 关闭 LLM 的推理过程，牺牲推理深度换取语音交互的低延迟。

Docker 部署

项目提供了 Docker Compose 配置，一键启动 llama.cpp（Gemma 4）+ TCP socket 服务器：

bash

# 需要先安装 NVIDIA Container Toolkit
docker compose up

Compose 文件启动 llama.cpp 服务器和 TCP socket 服务器，暴露端口 8080、12345、12346。

项目定位与生态

speech-to-speech 填补了开源语音 Agent 领域的一个空白。在此之前，构建语音 Agent 通常需要：自己组装 VAD + STT + LLM + TTS 的胶水代码、处理流式音频的队列管理、实现轮次检测和中断逻辑、对接各种模型的不兼容接口。

它把这些工程问题统一封装到一个 pip install 即可使用的包中，同时保留了每个组件的完全可控性。OpenAI Realtime 兼容协议让迁移成本降到最低——已有的客户端代码几乎不需要改动。

来源：GitHub - huggingface/speech-to-speech | HuggingFace Blog - Reachy Mini goes fully local