语音到语音：使用开源模型构建本地语音助手

📖 快速索引

• 方法
  • 结构
  • 模块化
• 设置
• 使用
  • Docker 服务器方式
  • 服务器/客户端方式
  • 本地方式
• 命令行使用
  • 模型参数
  • 生成参数
  • 重要参数

方法

结构

本仓库实现了一个由以下部分组成的级联式语音到语音流水线：

1. 语音活动检测 (VAD)
2. 语音转文本 (STT)
3. 语言模型 (LM)
4. 文本转语音 (TTS)

模块化

该流水线提供了一种完全开放且模块化的方案，重点利用 Hugging Face 中心库中 Transformers 库提供的模型。代码设计易于修改，并且我们已经支持特定设备和外部库的实现：

VAD

• Silero VAD v5

STT

• Hugging Face 中心库中通过 Transformers 🤗 提供的任何 Whisper 模型检查点，包括 whisper-large-v3 和 distil-large-v3
• Lightning Whisper MLX
• MLX Audio Whisper - 在 Apple Silicon 上实现快速 Whisper 推理
• Parakeet TDT - 在 Apple Silicon 上实现亚百毫秒延迟的实时流式 STT（通过 nano-parakeet 使用 CUDA/CPU，无需 NeMo）
• Paraformer - FunASR

LLM

• Hugging Face 中心库中任何遵循指令的语言模型（可通过 Transformers 🤗 获取），链接为：Hugging Face Hub
• mlx-lm
• OpenAI API

TTS

• MeloTTS
• ChatTTS
• Pocket TTS - 来自 Kyutai Labs 的流式语音克隆 TTS
• Kokoro-82M - 针对 Apple Silicon 优化的快速高质量 TTS

设置

克隆仓库：

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

使用 uv 安装依赖项：

uv sync

该项目现在使用单个带有平台标记的 pyproject.toml 文件，因此 macOS 和非 macOS 平台的依赖项会自动从一个文件中解析。

如果您使用 Melo TTS（macOS 上的默认选项），请在安装后运行一次：

uv run python -m unidic download

Apple Silicon 上的 MeloTTS 注意事项：

• 如果 MeloTTS 在 MPS 上因“输出通道数超过 65536 不受 MPS 设备支持”而失败，请先更新 macOS。
• 我们曾在较旧版本的 macOS 上复现过此问题，并确认在同一环境下升级到 macOS 26.3.1 后问题得以解决。

关于 DeepFilterNet 的说明： DeepFilterNet（用于 VAD 中可选的音频增强）目前由于 numpy 版本限制，与 Pocket TTS 不兼容。DeepFilterNet 需要 numpy<2，而 Pocket TTS 则需要 numpy>=2。

如果您希望以 DeepFilterNet 为中心进行设置并使用 pyproject.toml：

1. 编辑 pyproject.toml：移除 pocket-tts 依赖行。
2. 将 deepfilternet>=0.5.6 和 numpy<2 添加到 project.dependencies。
3. 重新同步环境：

   uv sync --refresh
   

要切换回 Pocket TTS，只需恢复 pyproject.toml 中的更改，并再次运行 uv sync --refresh。

使用

该流水线可以通过三种方式运行：

• 服务器/客户端方式：模型在服务器上运行，音频输入输出通过 TCP 套接字从客户端传输。
• WebSocket 方式：模型在服务器上运行，音频输入输出通过 WebSocket 从客户端传输。
• 本地方式：在本地运行。

推荐设置

服务器/客户端方式

1. 在服务器上运行流水线：

   python s2s_pipeline.py --recv_host 0.0.0.0 --send_host 0.0.0.0
   

2. 在本地运行客户端以处理麦克风输入并接收生成的音频：

   python listen_and_play.py --host <您的服务器 IP 地址>
   

WebSocket 方式

1. 以 WebSocket 模式运行流水线：

   python s2s_pipeline.py --mode websocket --ws_host 0.0.0.0 --ws_port 8765
   

2. 在您的客户端应用中连接到 WebSocket 服务器，地址为 ws://<服务器 IP>:8765。服务器将处理双向音频流：

   • 向服务器发送原始音频字节（16kHz，int16，单声道）
   • 从服务器接收生成的音频字节

本地方式（Mac）

1. 为了在 Mac 上获得最佳设置：

   python s2s_pipeline.py --local_mac_optimal_settings
   

   您也可以指定特定的语言模型：

   python s2s_pipeline.py \
       --local_mac_optimal_settings \
       --lm_model_name mlx-community/Qwen3-4B-Instruct-2507-bf16
   

此设置：

• 添加 --device mps 以在所有模型上使用 MPS。
• 设置 Parakeet TDT 作为 STT（在 Apple Silicon 上实现快速流式 ASR）。
• 设置 MLX LM 作为语言模型（使用 --lm_model_name 指定模型）。
• 设置 MeloTTS 作为 TTS。
• 需要为 MeloTTS 进行一次性 UniDic 设置：

  uv run python -m unidic download
  

• --tts pocket 和 --tts kokoro 也是 macOS 上有效的 TTS 选项。

Docker 服务器

安装 NVIDIA Container Toolkit

https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html

启动 docker 容器

docker compose up

使用 Cuda 的推荐用法

借助 Torch Compile 和 Pocket TTS，结合 Whisper 实现简单低延迟的设置：

python s2s_pipeline.py \
	--lm_model_name microsoft/Phi-3-mini-4k-instruct \
	--stt_compile_mode reduce-overhead \
  --tts pocket \
  --recv_host 0.0.0.0 \
	--send_host 0.0.0.0 

多语言支持

该流水线目前支持英语、法语、西班牙语、中文、日语和韩语。考虑了两种使用场景：

• 单语言对话：通过 --language 标志强制设置语言，指定目标语言代码（默认为 'en'）。
• 语言切换：将 --language 设置为 'auto'。在这种情况下，Whisper 会检测每个语音提示的语言，并向 LLM 提示 "请用 ... 回答我的消息"，以确保响应使用检测到的语言。

请注意，您必须使用与目标语言兼容的 STT 和 LLM 检查点。对于多语言 TTS，请使用 Melo（英语、法语、西班牙语、中文、日语和韩语）或 Chat-TTS。

使用服务器版本：

对于自动语言检测：

python s2s_pipeline.py \
    --stt whisper-mlx \
    --stt_model_name large-v3 \
    --language auto \
    --llm mlx-lm \
    --lm_model_name mlx-community/Qwen3-4B-Instruct-2507-bf16

或者针对特定语言，例如中文：

python s2s_pipeline.py \
    --stt whisper-mlx \
    --stt_model_name large-v3 \
    --language zh \
    --llm mlx-lm \
    --lm_model_name mlx-community/Qwen3-4B-Instruct-2507-bf16

本地 Mac 设置

对于自动语言检测（注意：--stt whisper-mlx 会覆盖最佳设置中的默认 parakeet-tdt，因为 Whisper large-v3 具有更广泛的语言覆盖范围）：

python s2s_pipeline.py \
    --local_mac_optimal_settings \
    --stt whisper-mlx \
    --stt_model_name large-v3 \
    --language auto \
    --lm_model_name mlx-community/Qwen3-4B-Instruct-2507-bf16

或者针对特定语言，例如中文：

python s2s_pipeline.py \
    --local_mac_optimal_settings \
    --stt whisper-mlx \
    --stt_model_name large-v3 \
    --language zh \
    --lm_model_name mlx-community/Qwen3-4B-Instruct-2507-bf16

使用 Pocket TTS

Kyutai Labs 的 Pocket TTS 提供具有语音克隆功能的流式 TTS。要使用它：

python s2s_pipeline.py \
    --tts pocket \
    --pocket_tts_voice jean \
    --pocket_tts_device cpu

可用的语音预设包括：alba、marius、javert、jean、fantine、cosette、eponine、azelma。您也可以使用自定义语音文件或 HuggingFace 路径。

命令行使用

注意: 所有 CLI 参数的参考可以直接在 参数类 中找到，或者通过运行 python s2s_pipeline.py -h 获取。

模块级参数

参见 ModuleArguments 类。允许设置：

• 一个通用的 --device（如果希望各部分在同一设备上运行）
• --mode 为 local 或 server
• 选择的 STT 实现
• 选择的 LM 实现
• 选择的 TTS 实现
• 日志级别

VAD 参数

参见 VADHandlerArguments 类。值得注意的是：

• --thresh：触发语音活动检测的阈值。
• --min_speech_ms：被检测到的语音活动的最小持续时间，才被视为语音。
• --min_silence_ms：用于分割语音的静音间隔的最小长度，以平衡句子切割和延迟降低。

STT、LM 和 TTS 参数

model_name、torch_dtype 和 device 针对语音转文本、语言模型和文本转语音的每种实现都公开了。使用相应的前缀指定目标流水线部分（例如 stt、lm 或 tts，更多细节请查看各实现的 参数类）。

例如：

--lm_model_name google/gemma-2b-it

生成参数

模型生成方法的其他生成参数可以使用部分前缀加 _gen_ 来设置，例如 --stt_gen_max_new_tokens 128。如果尚未公开，这些参数可以添加到流水线部分的参数类中。

引用

Silero VAD

@misc{Silero VAD,
  author = {Silero Team},
  title = {Silero VAD: 预训练的企业级语音活动检测器 (VAD)、数字检测器和语言分类器},
  year = {2021},
  publisher = {GitHub},
  journal = {GitHub 仓库},
  howpublished = {\url{https://github.com/snakers4/silero-vad}},
  commit = {insert_some_commit_here},
  email = {hello@silero.ai}
}

Distil-Whisper

@misc{gandhi2023distilwhisper,
      title={Distil-Whisper：通过大规模伪标签进行稳健的知识蒸馏},
      author={Sanchit Gandhi 和 Patrick von Platen 和 Alexander M. Rush},
      year={2023},
      eprint={2311.00430},
      archivePrefix={arXiv},
      primaryClass={cs.CL}
}

Parler-TTS

@misc{lacombe-etal-2024-parler-tts,
  author = {Yoach Lacombe 和 Vaibhav Srivastav 和 Sanchit Gandhi},
  title = {Parler-TTS},
  year = {2024},
  publisher = {GitHub},
  journal = {GitHub 仓库},
  howpublished = {\url{https://github.com/huggingface/parler-tts}}
}

Speech-to-Speech 快速上手指南

Speech-to-Speech 是一个基于开源模型构建本地语音智能体（Voice Agents）的级联管道工具。它支持语音活动检测 (VAD)、语音转文本 (STT)、大语言模型 (LLM) 和文本转语音 (TTS) 的全流程处理，具有高度模块化特性。

环境准备

系统要求

• 操作系统: macOS (推荐 Apple Silicon) 或 Linux (支持 NVIDIA CUDA)。
• Python 版本: 建议使用 Python 3.10+。
• 硬件加速:
  • macOS: 利用 MPS (Metal Performance Shaders) 加速。
  • Linux: 需安装 NVIDIA Container Toolkit 以支持 GPU 加速。

前置依赖

• 包管理器: 项目推荐使用 uv 进行依赖管理，安装速度更快且能自动处理平台差异。

  # 安装 uv (如果尚未安装)
  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• 网络环境: 由于模型主要从 Hugging Face Hub 下载，国内用户建议配置镜像源或使用代理以确保下载顺利。

安装步骤

1. 克隆仓库

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

2. 同步依赖 使用 uv 自动解析并安装适用于当前平台（macOS 或 Linux）的依赖：

   uv sync
   

3. 额外配置 (仅 macOS 用户) 如果使用的是默认的 MeloTTS (macOS 默认)，需要下载 UniDic 词典：

   uv run python -m unidic download
   

   注意: 如果在 Apple Silicon 上遇到 MPS 错误 (Output channels > 65536 not supported)，请尝试更新 macOS 系统至最新版本。

4. 可选配置 (DeepFilterNet) 如果需要音频增强功能且不使用 Pocket TTS，需手动修改 pyproject.toml 移除 pocket-tts 并添加 deepfilternet>=0.5.6 和 numpy<2，然后运行 uv sync --refresh。

基本使用

该工具支持三种运行模式：本地模式 (Local)、服务端/客户端模式 (Server/Client) 和 WebSocket 模式。以下提供最常用的两种场景示例。

场景一：macOS 本地快速体验 (推荐)

此模式利用 Apple Silicon 优化设置，自动选择 Parakeet TDT (STT)、MLX LM (LLM) 和 MeloTTS (TTS)，适合单机调试。

python s2s_pipeline.py --local_mac_optimal_settings

指定特定大模型运行：

python s2s_pipeline.py \
    --local_mac_optimal_settings \
    --lm_model_name mlx-community/Qwen3-4B-Instruct-2507-bf16

场景二：服务器部署 (CUDA/Linux)

适用于在服务器上运行模型，通过 TCP sockets 流式传输音频。

1. 启动服务端 (监听所有接口):

   python s2s_pipeline.py \
       --lm_model_name microsoft/Phi-3-mini-4k-instruct \
       --stt_compile_mode reduce-overhead \
       --tts pocket \
       --recv_host 0.0.0.0 \
       --send_host 0.0.0.0
   

2. 启动客户端 (在另一台机器或同一机器的不同终端运行，替换 <IP address> 为服务器 IP):

   python listen_and_play.py --host <IP address of your server>
   

多语言支持

默认支持英语、法语、西班牙语、中文、日语和韩语。

• 自动语言检测:

  python s2s_pipeline.py --language auto ...
  

• 指定语言 (例如中文):

  python s2s_pipeline.py --language zh ...
  

  注意：确保所选的 STT 和 LLM 模型支持目标语言。对于多语言 TTS，推荐使用 Melo 或 ChatTTS。

命令行参数提示

所有可用参数可通过以下命令查看详细说明：

python s2s_pipeline.py -h

关键参数前缀说明：

• --stt_...: 语音转文本相关参数
• --lm_...: 大语言模型相关参数
• --tts_...: 文本转语音相关参数
• --vad_...: 语音活动检测相关参数