huggingface speech-to-speech

以下是翻译后的中文内容，已按照要求保留原文结构、代码块、技术术语，并忽略无关文本：

Speech To Speech：使用开源模型构建语音代理

一个低延迟、完全模块化的语音代理流水线：VAD -> STT -> LLM -> TTS，通过兼容 OpenAI Realtime 的 WebSocket API 暴露。每个组件都可替换。LLM 插槽支持 OpenAI 兼容协议，因此你可以将其指向托管提供商、HF Inference Providers，或指向你自己硬件上的 vLLM 或 llama.cpp 服务器，以实现完全本地、完全开放的堆栈。该流水线已在生产环境中运行，作为数千台 Reachy Mini 机器人的对话后端。

快速开始

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

这将启动一个 OpenAI Realtime 兼容服务器，地址为 ws://localhost:8765/v1/realtime，使用 Parakeet TDT 进行本地 STT，使用 OpenAI 兼容的 LLM，以及 Qwen3-TTS 进行本地语音输出。从源代码检出后，你可以在第二个终端中与其对话：

python scripts/listen_and_play_realtime.py --host 127.0.0.1 --port 8765

更倾向于将 LLM 保留在自己的机器上？使用 llama.cpp 提供 Gemma 4 服务：

llama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 65536 -fa on --swa-full

然后将 OpenAI 兼容的 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 " "

任何兼容 OpenAI Realtime 的客户端都可以连接。有关协议和 LLM 后端选项，请参见 Realtime API 和 LLM backends。

索引

• 工作原理
• 安装
• 支持的组件
• 运行模式
• Realtime API
• LLM 后端
• 多语言支持
• Pocket TTS
• CLI 参考
• 贡献
• Star 历史
• 引用

工作原理

该流水线由四个组件级联而成，每个组件在自己的线程中运行，并通过队列连接：

• 语音活动检测 (VAD)：Silero VAD v5 检测语音边界和话轮转换。
• 语音转文本 (STT)：转录用户的话轮，可选实时部分转录。
• 语言模型 (LLM)：生成响应，流式传输文本和工具调用。
• 文本转语音 (TTS)：合成音频并流式传输回客户端。

每个阶段都有多个可互换的后端，通过 CLI 标志选择。代码设计易于修改，重点关注通过 Transformers 和 Hugging Face Hub 可用的模型。

安装

需要 Python 3.10+。

pip install speech-to-speech

默认安装涵盖标准实时路径：

• Parakeet TDT 用于 STT
• OpenAI 兼容 API 用于语言模型
• Qwen3-TTS 用于语音输出，在非 macOS 平台上默认使用 GGML 后端，在 Apple Silicon 上使用 mlx-audio

本地音频和实时服务器模式下的 macOS 和非 macOS 依赖项通过 pyproject.toml 中的平台标记自动解析。

Qwen3-TTS 的 CUDA 注意事项

在 Linux 上，Qwen3-TTS 的 GGML 后端来自 faster-qwen3-tts[ggml]。其在 PyPI 上的默认 qwentts-cpp-python wheel 针对 CUDA 12.8。如果你的机器没有该 wheel 所需的 CUDA 12 运行时，请在安装 speech-to-speech 之前从 Hugging Face wheelhouse 安装匹配的 wheel：

# 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 fallback
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

要使用之前的 CUDA-graphs 实现而不是 GGML，请传递 --qwen3_tts_backend torch。

可选后端

额外的后端通过 pip extras 安装：

pip install "speech-to-speech[kokoro]"          # Kokoro-82M TTS on non-macOS
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 STT
pip install "speech-to-speech[whisper-mlx]"     # Lightning Whisper MLX STT on macOS
pip install "speech-to-speech[paraformer]"      # Paraformer STT through FunASR
pip install "speech-to-speech[mlx-lm]"          # mlx-vlm support for vision models on macOS

已弃用的实现（包括 MeloTTS）位于 archive/ 中，不再连接到 CLI。

关于 DeepFilterNet 的说明：DeepFilterNet 用于 VAD 中的可选音频增强，需要 numpy<2，与需要 numpy>=2 的 Pocket TTS 冲突。请仅在不使用 Pocket TTS 的环境中手动安装它。

从源代码安装

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

这将以可编辑模式安装包，并使 speech-to-speech CLI 可用。

支持的组件

| 组件 | 后端 | 平台 | 安装方式 | |------|------|------|----------| | VAD | Silero VAD v5 | 全部 | 内置 | | STT | Parakeet TDT (默认) | CUDA / CPU 通过 nano-parakeet，Apple Silicon 通过 MLX | 内置 | | STT | Whisper 通过 Transformers | CUDA / CPU | 内置 | | STT | Faster Whisper | CUDA / CPU | faster-whisper | | STT | Lightning Whisper MLX | Apple Silicon | whisper-mlx | | STT | MLX Audio Whisper | Apple Silicon | macOS 内置 | | STT | Paraformer | CUDA / CPU | paraformer | | LLM | OpenAI 兼容 API (responses-api, chat-completions) | 托管提供商或自托管服务器 | 内置 | | LLM | Transformers | CUDA / CPU | 内置 | | LLM | mlx-lm | Apple Silicon | macOS 内置 | | TTS | Qwen3-TTS (默认) | Linux 上 GGML / CUDA，macOS 上 mlx-audio | 内置 | | TTS | Kokoro-82M | CUDA / CPU，Apple Silicon | 非 macOS 上 kokoro；macOS 上内置 | | TTS | Pocket TTS | CPU / CUDA | pocket | | TTS | ChatTTS | CUDA / CPU | chattts | | TTS | MMS TTS | CUDA / CPU | facebook-mms |

使用 --stt、--llm_backend 和 --tts 选择实现。运行 speech-to-speech -h 查看确切值和后端特定标志。

运行模式

| 模式 | 传输方式 | 使用场景 | |------|----------|----------| | realtime (默认) | WebSocket，OpenAI Realtime 协议，路径 /v1/realtime | 你正在针对标准语音 API 构建应用或设备 | | local | 你机器的麦克风和扬声器 | 你想与流水线对话 |