huggingface speech-to-speech

以下是您要求的英文文章的中文翻译，已按照保留原文结构、技术术语不翻译、代码块保持原样等要求处理。

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 以及提供商和本地服务器选项。

索引

工作原理
安装
支持的组件
运行模式
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 wheel 仓库安装匹配的 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-compatible API (responses-api, chat-completions) | 托管提供商或自托管服务器 | 内置 | | LLM | Transformers | CUDA / CPU | 内置 | | LLM | mlx-lm | Apple Silicon | 内置 (macOS) | | TTS | Qwen3-TTS (默认) | GGML / CUDA (Linux), mlx-audio (macOS) | 内置 | | TTS | Kokoro-82M | CUDA / CPU, Apple Silicon | kokoro (非 macOS); 内置 (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 获取确切的值和后端特定标志。

运行模式