Hugging Face Speech-to-Speech 部署教程

Speech-to-Speech 是一个由 Hugging Face 开发的开源语音对话系统，它构建了一个 VAD (语音活动检测) -> STT (语音转文本) -> LLM (大语言模型) -> TTS (文本转语音) 的模块化流水线，并通过 WebSocket/WebRTC 协议实现低延迟的实时语音交互。本教程将指导你在本地环境中部署并运行这个系统。

核心概念与架构

在开始部署前，先了解其核心架构有助于后续配置。

  • 流水线设计：系统将语音对话拆分为四个独立组件，每个组件运行在独立线程中，通过队列连接，实现流式处理。
  • 高度模块化：每个组件都是可插拔、可替换的。你可以根据硬件和需求选择不同的后端（Backend），例如使用 transformers、mlx-lm 进行本地推理，或调用 OpenAI、Hugging Face Inference Providers 等云端 API。
  • 通信协议：服务器端实现了 OpenAI Realtime API 的核心事件集，支持 WebSocket 和 WebRTC，这意味着任何兼容该协议的客户端（如 OpenAI Agents SDK）都可以连接。

准备工作：硬件与软件要求

根据你的运行模式，硬件需求差异很大。请根据以下三种典型场景进行规划：

  1. Apple Silicon (Mac) 完全本地运行：需要一台 Apple Silicon Mac，建议 16GB 或更高 的统一内存。核心模型权重总计约 7.5 GB。
  2. NVIDIA GPU (Linux) 完全本地运行：需要一台 Linux 主机，配备 至少 24GB 显存 的 NVIDIA GPU（如 RTX 3090 或更高），用于运行未量化的 LLM 权重（约 8 GB）及其他模型。
  3. 本地语音 + 云端 LLM：预算约 8 GB 可用内存（Apple Silicon 建议总内存 16GB，NVIDIA 需约 8GB 显存）。麦克风音频留在本地，仅发送文本和对话历史到云端。

通用软件要求：

  • 操作系统：macOS (Apple Silicon) 或 Linux (Ubuntu 20.04+ 推荐)。

  • Python 版本：Python 3.10 或更高版本（推荐 3.11）。

  • 音频库 (Linux)：Ubuntu/Debian 系统需安装 libportaudio2 和 libsndfile1：

    1
    sudo apt-get install libportaudio2 libsndfile1

第一步：安装 Speech-to-Speech

强烈建议 在 Python 虚拟环境中进行安装，以避免包冲突。

1
2
3
4
5
6
7
# 1. 创建并激活虚拟环境
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# 2. 从 PyPI 安装核心包
pip install speech-to-speech

  • 关于 Qwen3-TTS 的 CUDA 兼容性 (Linux 用户)：在 Linux 上，默认的 Qwen3-TTS GGML 后端 (faster-qwen3-tts[ggml]) 针对 CUDA 12.8 和 glibc 2.39 (Ubuntu 24.04) 编译。如果你的 CUDA 或 glibc 版本较旧，需要先安装匹配的 wheel。例如，对于 CUDA 12.4：

    1
    2
    pip install "qwentts-cpp-python==0.3.1+cu124" -f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cu124
    pip install speech-to-speech

  • 安装可选 TTS 后端：如需使用 Kokoro、Pocket TTS、OmniVoice 等，需安装对应的 extras：

    1
    2
    3
    pip install "speech-to-speech[kokoro]"
    pip install "speech-to-speech[pocket]"
    # 其他 extras: [chattts], [omnivoice], [faster-whisper], [paraformer] 等

第二步：选择并运行你的配置

根据你的硬件，选择以下三种命令之一。首次运行会自动下载并预热模型，请确保网络通畅，并佩戴耳机以避免回声啸叫。

配置一：Apple Silicon 完全本地运行 (无需 API Key)

此配置在 Apple Silicon Mac 上使用 MLX 加速，运行量化后的 STT、LLM 和 TTS 模型。

1
2
3
speech-to-speech local \
    --mac-optimal-settings \
    --model_name mlx-community/Qwen3-4B-Instruct-2507-4bit
  • --mac-optimal-settings: 自动为 Apple Silicon 选择最优的 MLX 后端和量化参数。
  • 首次运行会下载约 7.5 GB 的模型文件。

配置二：NVIDIA GPU (Linux) 完全本地运行

此配置在 NVIDIA GPU 上使用 Transformers 运行未量化的 LLM，需要至少 24GB 显存。

1
2
3
4
5
6
7
8
speech-to-speech local \
    --device cuda \
    --stt parakeet-tdt \
    --llm_backend transformers \
    --model_name Qwen/Qwen3-4B-Instruct-2507 \
    --llm_torch_dtype float16 \
    --tts qwen3 \
    --qwen3_tts_backend ggml
  • --device cuda: 指定使用 CUDA。
  • --llm_backend transformers: 使用 Hugging Face Transformers 库加载模型。
  • --llm_torch_dtype float16: 使用半精度以节省显存。

配置三：本地语音 + 托管 LLM (如 OpenAI)

此配置在本地运行 STT 和 TTS，将文本对话发送给云端 LLM，适用于资源有限的场景。需要设置 API Key。

1
2
3
4
5
6
export OPENAI_API_KEY="你的API密钥"
speech-to-speech local \
    --stt parakeet-tdt \
    --llm_backend responses-api \
    --model_name "gpt-4o-mini" \
    --tts qwen3
  • 你也可以通过 --responses_api_base_url 指向其他兼容 OpenAI 协议的本地服务器（如 vLLM、llama.cpp）或 Hugging Face Inference Providers。

第三步：以服务器模式运行 (供客户端连接)

如果你不想使用内置的麦克风/扬声器客户端，而是希望从浏览器或其他程序连接，可以使用 serve 模式启动服务端。

1
2
3
4
# 以完全本地 Mac 配置为例，启动服务器
speech-to-speech serve \
    --mac-optimal-settings \
    --model_name mlx-community/Qwen3-4B-Instruct-2507-4bit

服务器默认监听 ws://127.0.0.1:8765/v1/realtime。

在另一个终端（激活相同虚拟环境）中，运行客户端连接：

1
speech-to-speech talk --url ws://127.0.0.1:8765/v1/realtime

第四步：离线运行 (可选)

如果需要在内网或无网络环境中运行，请先在线环境下，使用你最终要用的命令完整运行一次，让所有模型和依赖缓存到本地。之后，设置环境变量 HF_HUB_OFFLINE=1 来禁止联网请求：

1
2
3
HF_HUB_OFFLINE=1 speech-to-speech serve \
    --mac-optimal-settings \
    --model_name mlx-community/Qwen3-4B-Instruct-2507-4bit

故障排查与常见问题

  • 麦克风没有声音或扬声器啸叫
    • 检查系统麦克风权限是否授予终端应用。
    • 必须佩戴耳机，防止麦克风拾取扬声器声音产生反馈。
    • 如果反馈严重，可在命令中添加 --local_audio_block_mic_during_playback 参数，这会阻止在扬声器播放时录音（代价是无法打断助手说话）。
  • 显存不足 (CUDA Out of Memory)
    • 对于 NVIDIA 完全本地模式，尝试使用更小的 LLM，或在配置中添加 --offload True 将部分模型权重卸载到 CPU。
    • 确保没有其他程序占用显存。
  • Qwen3-TTS 相关错误 (Linux)
    • 最常见的错误是 CUDA 版本不匹配。请参考“第一步”中关于 CUDA 兼容性的说明，安装正确的 qwentts-cpp-python wheel。
  • 依赖冲突
    • DeepFilterNet (音频增强) 与 Pocket TTS 存在 numpy 版本冲突。如果使用 Pocket TTS，请勿安装 DeepFilterNet。
    • 建议始终在干净的虚拟环境中安装。

至此，你已经成功部署并运行了 Hugging Face 的语音对话系统。你可以根据自己的硬件和需求，自由组合不同的 STT、LLM 和 TTS 后端，构建一个完全本地化、保护隐私的语音助手。这个项目非常适合作为进一步开发语音 Agent 或机器人对话系统的基础。