Hugging Face speech-to-speech：本地全链路实时语音对话开源智能体｜部署与使用全指南

Hugging Face speech-to-speech —— 本地全链路实时语音对话（语音进、语音出）开源语音智能体

适用场景说明：面向博主个人电脑本地部署，基线环境 Windows 10/11 + WSL2（Ubuntu 24.04）、RTX 3070 8GB / RTX 4090 24GB，另含 Linux 云服务器视角。本节严格以官方仓库 README、docs/configuration.md、demo/README.md 与 src/speech_to_speech/ 下 STT / LLM / TTS 组件指南原文为事实来源；README 未提供的 Colab / T4 方案、官方未给出的显存数值均如实标注，不做推测补充。

项目定位与基本信息

官方图片

• 下图为官方 README 顶部 logo（README 第 3 行 <img src="https://raw.githubusercontent.com/huggingface/speech-to-speech/main/logo.png" width="600"/>）：

• 补充素材（非 PNG/JPEG，按本节图片规则不嵌入正文，仅登记来源）：README 「How it works」上方的端点切换演示动图 docs/assets/endpoint-swap-light.gif（暗色模式 endpoint-swap-dark.gif），来源 https://raw.githubusercontent.com/huggingface/speech-to-speech/main/docs/assets/endpoint-swap-light.gif ，curl 200 已验证可访问。

环境要求

另含 Silero VAD、Smart Turn v3.2 ONNX 检查点等小型资源；首次在线启动缓存完成后可离线运行（README「Offline Operation」节）。

最详细部署步骤（Windows 与 WSL2 双视角）

1. 依赖安装

WSL2（Ubuntu 24.04，官方文档描述最完整的 Linux 路径）：

# README Quickstart 原文：先装音频系统库
sudo apt-get install libportaudio2 libsndfile1

# Python 3.11–3.14（推荐 3.11），创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate

Windows 原生：README 仅给出环境激活命令 .venv\Scripts\Activate.ps1，并明确 Windows 不在 CI 兼容性矩阵内；默认 Qwen3-TTS GGML wheel 面向 Linux 编译，原生 Windows 预期存在兼容性风险。建议 NVIDIA 显卡用户优先走 WSL2 路径；原生 Windows 步骤如下，问题需自行排查：

python -m venv .venv
.\.venv\Scripts\Activate.ps1

源码开发方式（README「From Source」节，Linux/macOS）：

git clone https://github.com/huggingface/speech-to-speech.git
cd speech-to-speech
uv sync --python 3.11
source .venv/bin/activate

2. 项目下载 / 安装（README「Installation」节，PyPI 官方方式）

pip install speech-to-speech

可选后端 extras（README「Optional Components」节原文命令）：

pip install "speech-to-speech[kokoro]"          # Kokoro-82M TTS（macOS 需 Python 3.11–3.12）
pip install "speech-to-speech[kitten]"          # KittenTTS
pip install "speech-to-speech[pocket]"         # Pocket TTS
pip install "speech-to-speech[phonon]"         # Phonon TTS（检查点另行提供）
pip install "speech-to-speech[chattts]"        # ChatTTS
pip install "speech-to-speech[omnivoice]"      # OmniVoice TTS（CUDA / Intel XPU / Apple Silicon）
pip install "speech-to-speech[faster-whisper]" # Faster Whisper STT
pip install "speech-to-speech[whisper-mlx]"   # Lightning Whisper MLX STT（macOS）
pip install "speech-to-speech[paraformer]"     # Paraformer STT（FunASR）
pip install "speech-to-speech[fireredvad]"     # FireRed streaming VAD
pip install "speech-to-speech[nemo]"           # Parakeet Unified / Nemotron / Orukeet STT（NeMo）
pip install "speech-to-speech[mlx-lm]"        # macOS mlx-vlm 视觉模型支持

3. 模型 / 权重下载（官方来源 + 国内加速 + 显存现实说明）

官方来源：首次 speech-to-speech local 启动时自动从 Hugging Face Hub 下载默认流水线模型（README Quickstart："The first run downloads the models, so give it a few minutes"）；README「Offline Operation」节要求先在线跑通一次、缓存齐 STT / LLM / TTS / Silero VAD / NLTK / Smart Turn 资源后，再用 HF_HUB_OFFLINE=1 离线运行。

国内加速：沿用 huggingface_hub 标准环境变量 HF_ENDPOINT（机制说明：https://huggingface.co/docs/huggingface_hub/guides/environment-variables ）：

export HF_ENDPOINT=https://hf-mirror.com

CUDA wheel 适配（README「CUDA Note for Qwen3-TTS」节原文）：Linux 下 Qwen3-TTS GGML 后端来自 faster-qwen3-tts[ggml]，PyPI 默认 qwentts-cpp-python wheel 面向 CUDA 12.8 与 manylinux_2_39（即 Ubuntu 24.04）；CUDA 运行时或 glibc 更旧时，先从 HF wheelhouse 安装匹配 wheel，再装 speech-to-speech：

# 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

备选：README 注明可传 --qwen3_tts_backend torch 使用旧版 CUDA-graphs 实现替代 GGML。

RTX 3070 8GB 现实说明（严格按 README 边界，不做外推）：

关于 Colab / T4：官方 README、docs/ 与 demo/README.md 全文未提供 Colab 笔记本或 T4 免费运行方案，本节不编造 Colab 路径；如需云端体验，请以官方仓库后续更新为准。

4. 关键配置（凭据与开关表）

凭据要求（README 各节原文，默认本地流水线不需要任何 key）：

模块级与流水线开关（README「CLI Reference」节 + 组件指南）：

VAD 参数（README「VAD Parameters」节，Silero VAD v5）：

Qwen3-TTS 参数（TTS README「6) Qwen3-TTS」节）：

5. 启动（README「Commands」节三条官方命令）

# README Quickstart 原文命令（WSL2 / Linux）
python3 -m venv .venv
source .venv/bin/activate
pip install speech-to-speech
speech-to-speech local

停止：Ctrl+C。README 提示：佩戴耳机避免助手听到自己；或加 --local_audio_block_mic_during_playback 在播放期间屏蔽麦克风。

使用方法

启动方式与界面

• 终端本地对话（local）：启动后终端显示 Loading models…，音频设备就绪、会话配置完成后出现 Ready — start speaking.；用户消息黄色、助手回复绿色（支持颜色的终端）；默认只显示最终用户转写与流式助手回复，隐藏后端转写副本、常规日志、工具细节与协议事件（README Quickstart 节）。
• 浏览器 Demo（serve + demo/，demo README「Quick start (local)」节）：需要仓库检出、uv、Node.js / npm。

```bash # 1) 启动语音服务端（首次启动下载模型，等待监听 ws://127.0.0.1:8765/v1/realtime） uv sync --python 3.11 uv run speech-to-speech serve

# 2) 安装浏览器 SDK 依赖并启动 Demo 应用 npm ci --prefix demo uv pip install -r demo/requirements.txt export SPEECH_TO_SPEECH_URL=ws://localhost:8765/v1/realtime uv run uvicorn --app-dir demo server:app --reload --port 7860 ```

打开 http://localhost:7860/ ，点击光球、允许麦克风权限后开始对话。Docker 方式（demo README 原文）：

bash docker build -t s2s-demo demo/ docker run -p 7860:7860 -e SPEECH_TO_SPEECH_URL=ws://host.docker.internal:8765/v1/realtime s2s-demo

浏览器麦克风要求 HTTPS 或 localhost：127.0.0.1 与 localhost 可用，纯 http://192.168.x.y 局域网地址无法调用 getUserMedia()（demo README 原文）。 - OpenAI Realtime SDK 直连（README「Realtime API」节官方示例）：

```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)

```

README 注明：服务端实现的是 OpenAI Realtime 核心事件子集（入站 input_audio_buffer.append、session.update、conversation.item.create、conversation.item.truncate、response.create、response.cancel；出站语音起止、流式转写、音频增量、工具调用、response.done），并非完整 API 等价。

中文对话配置（README「Multi-Language Support」节 + STT README 语种表）

默认 Parakeet TDT 仅支持 25 种欧洲语言（en, de, fr, es, it, pt, nl, pl, ru, uk, cs, sk, hu, ro, bg, hr, sl, sr, da, no, sv, fi, et, lv, lt），不含中文；中文对话必须切换 STT 后端：

端到端示例：WSL2 本地中文语音对话（4090 24GB 推荐配置；3070 8GB 见 08.4 现实说明）

# 1) 系统音频库（README Quickstart Ubuntu 节）
sudo apt-get install libportaudio2 libsndfile1

# 2) 环境
python3 -m venv .venv
source .venv/bin/activate
pip install speech-to-speech

# 3) 中文对话启动：Whisper 识别中文 + 按助手回复语言检测 + Qwen3-TTS 自动语种
speech-to-speech local \
  --stt whisper \
  --language zh \
  --enable_lang_prompt \
  --detect_llm_output_language \
  --qwen3_tts_language auto

交互流程（README Quickstart 原文描述）：开口说话 → 停顿 → 助手通过扬声器回答；Ctrl+C 停止；首次运行需等待模型下载；佩戴耳机或加 --local_audio_block_mic_during_playback 防止自激回声。

换音色示例（TTS README + demo README 音色表）：

speech-to-speech local \
  --tts qwen3 \
  --qwen3_tts_speaker Ryan \
  --qwen3_tts_device cuda

外接 llama.cpp LLM 示例（README「Combining with llama.cpp」节原文命令，终端 1 起 LLM、终端 2 连流水线）：

# 终端 1：llama-server 常驻
llama-server \
  -hf ggml-org/gemma-4-E4B-it-GGUF:Q4_0 \
  --alias local-gemma \
  --host 127.0.0.1 --port 8080 \
  -ngl all -np 1 -c 8192 -fa on \
  --no-mmproj \
  --reasoning off

# 终端 2：语音流水线接入本地 LLM
speech-to-speech local \
  --llm_backend responses-api \
  --model_name local-gemma \
  --responses_api_base_url http://127.0.0.1:8080/v1 \
  --responses_api_api_key ""

托管 LLM 示例（语音留本地，文本上云，README「Local speech with a hosted LLM」节）：

export OPENAI_API_KEY=...
speech-to-speech local --llm_backend responses-api

常见坑

本节来源清单

说明：正文中 ws://127.0.0.1:8765/v1/realtime、http://localhost:7860/、http://127.0.0.1:8080/v1 等为本机回环示例地址，非外部引用，不列入来源清单。

待复核 / 边界说明：① 官方 README 未提供 Colab 或 T4 免费方案，本节未予编写；② 8GB 显存显卡的官方可行配置 README 未给出，08.4 已逐条标注边界；③ Pocket TTS 模型卡在本环境返回 401，安装该 extra 前需先在 HF 确认模型可见性与许可；④ 第三方可选后端（OmniVoice、Phonon 等）权重许可独立于项目 Apache-2.0，商用前须核对对应模型卡条款。