huggingface/speech-to-speech 来源: https://github.com/huggingface/speech-to-speech # 语音对语音：使用开源模型构建语音代理 PyPI (https://pypi.org/project/speech-to-speech/) Python (https://pypi.org/project/speech-to-speech/) 许可证 一个低延迟、完全模块化的语音代理流水线：VAD -> STT -> LLM -> TTS，通过OpenAI Realtime 兼容的 WebSocket API 暴露。每个组件都可替换。LLM 插槽支持 OpenAI 兼容协议，因此您可以将其指向托管提供商、HF Inference Providers (https://huggingface.co/inference-providers)，或指向自己硬件上的 vLLM 或 llama.cpp 服务器，实现完全本地、完全开源的堆栈。该流水线已在生产环境中作为数千台 Reachy Mini (https://huggingface.co/blog/reachy-mini) 机器人的对话后端运行。 ## 快速开始 bash 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 进行本地语音输出。从源代码检出后，可从第二个终端与其对话： bash python scripts/listen_and_play_realtime.py --host 127.0.0.1 --port 8765 更希望将 LLM 保留在您自己的机器上？使用 llama.cpp 提供 Gemma 4： bash llama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 65536 -fa on --swa-full 然后将 OpenAI 兼容的 LLM 后端指向它： bash 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 兼容的客户端都可以连接。有关协议，请参见 Realtime API；有关提供商和本地服务器选项，请参见 LLM backends。 ## 目录 * 工作原理 * 安装 * 支持的组件 * 运行模式 * Realtime API * LLM 后端 * 多语言支持 * Pocket TTS * CLI 参考 * 贡献指南 * Star 历史 * 引用 ## 工作原理 该流水线由四个组件级联而成，每个组件运行在自己的线程中，并由队列连接： 1. 语音活动检测（VAD）：Silero VAD v5 (https://github.com/snakers4/silero-vad) 检测语音边界和轮流发言。 2. 语音转文字（STT）：转录用户的话语，可选的实时部分转录。 3. 语言模型（LLM）：生成响应，流式传输文本和工具调用。 4. 文字转语音（TTS）：合成音频并流式传输回客户端。 每个阶段都有多个可互换的后端，通过 CLI 标志选择。代码设计易于修改，重点关注通过 Transformers 和 Hugging Face Hub 可用的模型。 ## 安装 需要 Python 3.10+。 bash 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： bash # 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 回退 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 extra 安装： bash pip install "speech-to-speech[kokoro]" # 非 macOS 上的 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 STT pip install "speech-to-speech[whisper-mlx]" # 在 macOS 上 Lightning Whisper MLX STT pip install "speech-to-speech[paraformer]" # 通过 FunASR 的 Paraformer STT pip install "speech-to-speech[mlx-lm]" # macOS 上视觉模型的 mlx-vlm 支持 已弃用的实现（包括 MeloTTS）位于 archive/，不再连接到 CLI。 关于 DeepFilterNet 的说明： DeepFilterNet 用于 VAD 中的可选音频增强，需要 numpy<2，与需要 numpy>=2 的 Pocket TTS 冲突。仅在未使用 Pocket TTS 的环境中手动安装。 ### 从源码安装 bash git clone https://github.com/huggingface/speech-to-speech.git cd speech-to-speech uv sync 这将以可编辑模式安装包，并使 speech-to-speech CLI 可用。 ## 支持的组件 | 组件 | 后端 | 平台 | 安装方式 | |—|—|—|—| | VAD | Silero VAD v5 (https://github.com/snakers4/silero-vad) | 全部 | 内置 | | STT | Parakeet TDT (https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3)（默认） | CUDA / CPU 通过 nano-parakeet，Apple Silicon 通过 MLX | 内置 | | STT | 通过 Transformers 的 Whisper (https://huggingface.co/docs/transformers/en/model_doc/whisper) | CUDA / CPU | 内置 | | STT | Faster Whisper (https://github.com/SYSTRAN/faster-whisper) | CUDA / CPU | faster-whisper | | STT | Lightning Whisper MLX (https://github.com/mustafaaljadery/lightning-whisper-mlx) | Apple Silicon | whisper-mlx | | STT | MLX Audio Whisper (https://github.com/huggingface/mlx-audio) | Apple Silicon | macOS 内置 | | STT | Paraformer (https://github.com/modelscope/FunASR) | CUDA / CPU | paraformer | | LLM | OpenAI 兼容 API（responses-api，chat-completions） | 托管提供商或自托管服务器 | 内置 | | LLM | Transformers (https://huggingface.co/models?pipeline_tag=text-generation&sort=trending) | CUDA / CPU | 内置 | | LLM | mlx-lm (https://github.com/ml-explore/mlx-lm) | Apple Silicon | macOS 内置 | | TTS | Qwen3-TTS (https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice)（默认） | 在 Linux 上 GGML / CUDA，在 macOS 上 mlx-audio | 内置 | | TTS | Kokoro-82M (https://huggingface.co/hexgrad/Kokoro-82M) | CUDA / CPU，Apple Silicon | 非 macOS 上 kokoro；macOS 内置 | | TTS | Pocket TTS (https://github.com/kyutai-labs/pocket-tts) | CPU / CUDA | pocket | | TTS | ChatTTS (https://github.com/2noise/ChatTTS) | CUDA / CPU | chattts | | TTS | MMS TTS (https://huggingface.co/docs/transformers/model_doc/mms) | CUDA / CPU | facebook-mms | 选择实现时使用 --stt、--llm_backend 和 --tts。运行 speech-to-speech -h 查看精确值和后端特定标志。 ## 运行模式 | 模式 | 传输方式 | 何时使用 | |—|—|—| | realtime（默认） | WebSocket，OpenAI Realtime 协议位于 /v1/realtime | 您正在针对标准语音 API 构建应用或设备。 | | local | 您机器的麦克风和扬声器 | 您想直接与流水线对话，无需客户端。 | | websocket | 通过 WebSocket 的原始 PCM | 您需要一个最小的自定义客户端，而不需要 Realtime 协议。 | | socket | 通过 TCP 的原始 PCM | 模型在远程服务器上运行，带有简单的麦克风/播放客户端。 | ### Realtime 服务器 bash export OPENAI_API_KEY=... speech-to-speech 这相当于： bash speech-to-speech \ --thresh 0.6 \ --stt parakeet-tdt \ --llm_backend responses-api \ --tts qwen3 \ --qwen3_tts_model_name Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice \ --qwen3_tts_speaker Aiden \ --qwen3_tts_language auto \ --qwen3_tts_backend ggml \ --qwen3_tts_non_streaming_mode True \ --qwen3_tts_mlx_quantization 6bit \ --model_name gpt-5.4-mini \ --chat_size 30 \ --responses_api_stream \ --enable_live_transcription \ --mode realtime 默认模型是通过 OpenAI Responses API 提供的 gpt-5.4-mini。使用 --model_name 覆盖，并设置 --responses_api_base_url 指向另一个兼容 OpenAI 的提供商或服务器。 ### 本地 Mac bash speech-to-speech --local_mac_optimal_settings 可选地使用特定的 LLM： bash speech-to-speech \ --local_mac_optimal_settings \ --model_name mlx-community/Qwen3-4B-Instruct-2507-bf16 此设置： - 添加 --device mps 以对所有模型使用 MPS。 - 设置 Parakeet TDT 用于 STT。 - 设置 MLX LM 作为 LLM 后端。 - 设置 Qwen3-TTS 用于 TTS，默认使用 mlx-audio 和 6bit MLX 变体。 - 设置 --mode local。 --tts pocket 和 --tts kokoro 在 macOS 上也有效。 要本地比较 MLX 量化变体： bash python scripts/benchmark_tts.py \ --handlers qwen3 \ --iterations 3 \ --qwen3_mlx_quantizations bf16 4bit 6bit 8bit ### WebSocket 1. 以 WebSocket 模式运行流水线： bash speech-to-speech --mode websocket --ws_host 0.0.0.0 --ws_port 8765 2. 从您的客户端连接到 ws://:8765。发送 16 kHz、int16、单声道 PCM 原始音频字节，并接收生成的音频字节。 ### TCP Socket TCP socket 模式故意保持最小化。它流式传输原始 PCM 音频，但不提供完整的 Realtime API 功能集，包括中断处理、实时转录事件或工具调用事件。 1. 在服务器上运行流水线： bash speech-to-speech --mode socket --recv_host 0.0.0.0 --send_host 0.0.0.0 2. 在本地运行客户端以处理麦克风输入和播放： bash python scripts/listen_and_play.py --host ### Docker 安装 NVIDIA Container Toolkit (https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)，然后： bash docker compose up compose 文件启动一个带有 Gemma 4 的 llama.cpp 服务器，启动 TCP socket 服务器，并暴露端口 8080、12345 和 12346。 ## Realtime API Realtime 模式通过 WebSocket 使用 OpenAI Realtime 协议流式传输音频，具有实时转录和低延迟轮流发言。服务器暴露 /v1/realtime，任何 OpenAI Realtime 兼容的客户端都可以连接： python from openai import OpenAI client = OpenAI( base_url="http://localhost:8765/v1", websocket_base_url="ws://localhost:8765/v1", api_key="not-needed", ) with client.realtime.connect(model="local") as conn: conn.send( { "type": "session.update", "session": { "type": "realtime", "instructions": "You are a helpful assistant.", "audio": { "input": { "turn_detection": { "type": "server_vad", "interrupt_response": True, } } }, }, } ) for event in conn: print(event.type) 服务器实现了核心的 Realtime 事件集：入站事件 input_audio_buffer.append、session.update、conversation.item.create、response.create 和 response.cancel；出站事件包括语音开始/停止、流式转录、音频增量、工具调用和 response.done。完整的事件参考、架构和设计细节位于 Realtime Engine README。 ## LLM 后端 LLM 是流水线中计算最密集、延迟最高的组件。大型模型的单次前向传递可能主导端到端响应时间，因此为您的硬件和延迟预算选择合适的后端至关重要。流水线支持： - 本地推理：在 CUDA / CPU 上使用 transformers，在 Apple Silicon 上使用 mlx-lm。 - 自托管服务器：responses-api 和 chat-completions 可以指向本地 vLLM (https://github.com/vllm-project/vllm) 或 llama.cpp (https://github.com/ggerganov/llama.cpp) 服务器。 - 提供商 API：相同的后端适用于 OpenAI、HF Inference Providers (https://huggingface.co/inference-providers)、OpenRouter (https://openrouter.ai) 以及其他兼容 OpenAI 的提供商。 有两个 API 后端可用，它们共享相同的 --responses_api_* 连接标志： - --llm_backend responses-api（默认）目标为 /v1/responses。 - --llm_backend chat-completions 目标为 /v1/chat/completions。 以下示例将 Parakeet TDT 用于本地 STT 和 Qwen3-TTS 用于本地 TTS，与不同的 LLM 后端配对。 ### Responses API 后端 适用于任何实现 OpenAI Responses API 的提供商或服务器。将 --responses_api_base_url 指向端点，并相应地设置 --model_name： | 提供商 / 服务器 | --responses_api_base_url | --responses_api_api_key | |—|—|—| | OpenAI | 省略，使用 OpenAI 默认值 | $OPENAI_API_KEY | | HF Inference Providers | https://router.huggingface.co/v1 | $HF_TOKEN | | OpenRouter | https://openrouter.ai/api/v1 | $OPENROUTER_API_KEY | | vLLM | http://localhost:8000/v1 | 省略或任意字符串 | | llama.cpp | http://127.0.0.1:8080/v1 | 空字符串 | bash # OpenAI speech-to-speech \ --mode local \ --stt parakeet-tdt \ --llm_backend responses-api \ --tts qwen3 \ --qwen3_tts_mlx_quantization 6bit \ --model_name "gpt-4o-mini" \ --responses_api_api_key "$OPENAI_API_KEY" \ --responses_api_stream \ --enable_live_transcription bash # HF Inference Providers: Qwen3.5-9B via Together speech-to-speech \ --mode local \ --stt parakeet-tdt \ --llm_backend responses-api \ --tts qwen3 \ --qwen3_tts_mlx_quantization 6bit \ --model_name "Qwen/Qwen3.5-9B:together" \ --responses_api_base_url "https://router.huggingface.co/v1" \ --responses_api_api_key "$HF_TOKEN" \ --responses_api_stream \ --enable_live_transcription bash # HF Inference Providers: GPT-oss-20B via Groq speech-to-speech \ --stt parakeet-tdt \ --llm_backend responses-api \ --tts qwen3 \ --qwen3_tts_mlx_quantization 6bit \ --model_name "openai/gpt-oss-20b:groq" \ --responses_api_base_url "https://router.huggingface.co/v1" \ --responses_api_api_key "$HF_TOKEN" \ --responses_api_stream \ --enable_live_transcription ### Chat Completions 后端 与 responses-api 相同的配置，重用相同的 --responses_api_* 连接标志，但连接到 /v1/chat/completions 而不是 /v1/responses。在以下情况下优先使用： - 提供商在 Responses 路径上忽略 chat_template_kwargs.enable_thinking，并且需要 reasoning_effort 旋钮来抑制推理，或者 - 服务器的 Responses 流式工具调用路径不可靠，而其 Chat Completions 工具调用流式传输稳定。 这对于某些 vLLM 构建很有用；请参见 #312 (https://github.com/huggingface/speech-to-speech/issues/312)。 添加 --responses_api_reasoning_effort none 以在 chat-template 标志无效的提供商上禁用推理： bash # vLLM 提供具有工具调用的 Qwen 模型 speech-to-speech \ --mode realtime \ --stt parakeet-tdt \ --llm_backend chat-completions \ --tts qwen3 \ --model_name "Qwen/Qwen3-4B-Instruct-2507" \ --responses_api_base_url "http://localhost:8000/v1" \ --responses_api_stream bash # 通过 HF 路由器的 Cerebras 上的 Gemma 4 31B，禁用推理以实现低语音延迟 speech-to-speech \ --mode realtime \ --stt parakeet-tdt \ --llm_backend chat-completions \ --tts qwen3 \ --model_name "google/gemma-4-31B-it:cerebras" \ --responses_api_base_url "https://router.huggingface.co/v1" \ --responses_api_api_key "$HF_TOKEN" \ --responses_api_reasoning_effort none \ --responses_api_stream ### 完全本地 在单独的 llama.cpp 进程中运行 LLM，以实现最低摩擦的完全本地设置，如 Reachy Mini 本地对话指南 (https://huggingface.co/blog/local-reachy-mini-conversation) 所示： ``bash # 终端 1：提供 Gemma 4 的 llama.cpp llama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 6553