七个 pip extras：哪些该装，哪些别碰

speech-to-speech 是 Hugging Face 的语音代理流水线（github.com/huggingface/speech-to-speech，仓库标注 Apache-2.0，star 11893，2026-08-09 快照）。它的结构是 VAD → STT → LLM → TTS 四级级联，每一级都有多个可互换后端。装的时候真正让人犯难的不是主包，而是 README「可选组件」那一串 pip extras——名字都很像，说明只有一行，装错了程序还不一定报错。

这篇只解决一个问题：在你的机器上，这些 extras 里哪些该装，哪些纯属白装。

先搞清楚：一个 extra 都不装，你已经有什么

这一步跳过去的人最后都会多装东西。README 的安装小节写得很明确，要求 Python 3.10+，然后：

pip install speech-to-speech

默认安装就已经覆盖了一条完整的实时路径：

• STT 是 Parakeet TDT（nvidia/parakeet-tdt-0.6b-v3）
• LLM 走 OpenAI 兼容 API
• TTS 是 Qwen3-TTS（Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice），非 macOS 平台默认用 GGML 后端，Apple Silicon 上用 mlx-audio
• 本地音频与实时服务两种模式都在

macOS 与非 macOS 的依赖靠 pyproject.toml 里的平台标记自动解析，你不用手动挑。

换句话说：extras 的存在意义只有一个——你要偏离上面这条默认路径。 不偏离就别装。

八行 extras，七个是换模型的，一个是换传输的

README 的可选组件小节一共列了八行：

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[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 支持
pip install "speech-to-speech[webrtc]"          # WebRTC 传输

其中前七个换的是流水线里某一级的模型实现，最后那个 webrtc 换的是传输层，跟模型无关。本文说的「七个」指前面那七个；webrtc 只影响客户端怎么把音频送进来，不影响你用哪个模型，因此不在本篇的选型问题里，装不装取决于你的客户端要不要走 WebRTC。

extra	换掉哪一级	平台前提	什么时候才需要
kokoro	TTS	CUDA / CPU、Apple Silicon	想用 hexgrad/Kokoro-82M；macOS 上是内置的，不用装
pocket	TTS	CPU / CUDA	想用 Kyutai Labs 的 Pocket TTS
chattts	TTS	CUDA / CPU	想用 ChatTTS（README 标注语言为英文与中文）
faster-whisper	STT	CUDA / CPU	想用 Faster Whisper 而不是默认 Parakeet
whisper-mlx	STT	Apple Silicon	想用 Lightning Whisper MLX
paraformer	STT	CUDA / CPU	想用 FunASR 的 Paraformer
mlx-lm	LLM 侧	macOS	想跑视觉模型（mlx-vlm 支持）

决策路径：问自己三个问题

问题一：你的平台是什么。 这一列决定了一半的 extras 你连看都不用看。whisper-mlx 和 mlx-lm 是 Apple Silicon / macOS 侧的，在 Windows 或 Linux 上装了没有意义；反过来 kokoro 在非 macOS 上才需要 extra，macOS 上它是内置的。这两条方向相反，很容易记反。

问题二：你要不要中文。 这是中文读者必须先看的一条：默认 STT（Parakeet TDT）覆盖的是 25 种欧洲语言。 想做中文语音代理，STT 这一级必须换掉——要么 Whisper 系，要么 Paraformer。Paraformer 的参数文件里 --paraformer_stt_model_name 默认值就是 paraformer-zh，README 的多语言表也标注它默认那个检查点偏中文。TTS 那一级则不一定要动，默认的 Qwen3-TTS 本身是多语言的，--qwen3_tts_language 默认 auto。

问题三：你有没有 GPU。 这一条主要影响装的顺序而不是装什么，见下面 CUDA 那节。

命令块 A：macOS 上做中文

README 给出的中文示例是这一条（原样）：

speech-to-speech serve \
    --stt whisper-mlx \
    --stt_model_name large-v3 \
    --language zh \
    --llm_backend mlx-lm \
    --model_name mlx-community/Qwen3-4B-Instruct-2507-bf16

逐项说明为什么这么写：--stt whisper-mlx 把 STT 从默认的 Parakeet 换成 Lightning Whisper MLX，这一步对应 pip install "speech-to-speech[whisper-mlx]"；--language zh 是必须显式给的，因为 --language 默认值是 en；--llm_backend mlx-lm 是 Apple Silicon 上的进程内本地推理后端，它本身在 macOS 上是内置的，不需要装 mlx-lm extra——那个 extra 是给视觉模型用的 mlx-vlm 支持。这是本篇最容易白装的一个。

命令块 B：把 TTS 挪到 CPU

Pocket TTS 的 extra 是 pocket，README 给的启动命令是（原样）：

speech-to-speech serve \
    --tts pocket \
    --pocket_tts_voice jean \
    --pocket_tts_device cpu

--pocket_tts_device 的默认值本身就是 cpu，这里显式写出来只是让配置自解释。--pocket_tts_voice 默认 jean，README 列出的预设音色是 alba、marius、javert、jean、fantine、cosette、eponine、azelma，也支持本地音频文件路径和 Hugging Face 路径。至于这些音色听起来怎么样，我们一秒钟输出都没有听过，不评价。

命令块 C：Linux + CUDA，装的顺序比装什么更重要

README 专门开了小节讲这个坑：Linux 上 Qwen3-TTS 的 GGML 后端来自 faster-qwen3-tts[ggml]，它在 PyPI 上的默认 qwentts-cpp-python wheel 面向 CUDA 12.8。如果你机器上没有这个 wheel 期望的 CUDA 12 运行时，必须先从 Hugging Face wheelhouse 装匹配的 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 兜底
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

注意这一步跟 extras 无关，它属于主包本身在 CUDA 机器上的前置。想绕开整个 GGML 路径也有一条：传 --qwen3_tts_backend torch，切回之前那套 CUDA-graphs 实现。

三个「别碰」

别碰之一：pocket 和 DeepFilterNet 二选一。 README 写得很直白：DeepFilterNet（VAD 那一级可选的音频增强）需要 numpy<2，而 Pocket TTS 需要 numpy>=2，两者冲突。README 的处置是「只在不使用 Pocket TTS 的环境里手动安装 DeepFilterNet」。对应到 CLI 上就是 --audio_enhancement（默认 False）这个开关——如果你装了 pocket，就当没有这个开关。

别碰之二：平台不对的那几个。 上面表里已经列了，不重复。

别碰之三：为了「多一个选择」而全装。 每多一个 extra 就是多一条依赖链，而 numpy 那条冲突已经证明这些依赖链之间并不互相兼容。

另外提醒一句：已弃用的实现（含 MeloTTS）放在仓库的 archive/ 目录里，不再接入 CLI。网上老教程里出现的那些后端名，先确认它还在不在 CLI 里。

验收：装完怎么确认它真的生效了

这是本篇最该记住的一条。README 明确写了 CLI 的一个行为：只为选中的后端构造配置；未激活后端的已知选项仍然被接受，但会带警告地忽略。 JSON 配置同理，多余的非激活后端键也是被忽略。

翻译成后果就是：你写错了后端专属参数，程序不会报错停下，只会警告一声然后照跑默认路径。 你以为自己换了 STT，实际上还在跑 Parakeet，而且没有任何硬失败提示你。

所以验收动作是这两条：

# 看当前默认组合的参数
speech-to-speech serve -h

# 看另一种组合的参数——选择器必须放在 -h 前面
speech-to-speech serve --stt mlx-audio-whisper -h

第二条的写法是 README 特意强调的：想看某个后端的专属参数，得先用选择器把那个组合选出来，-h 放最后。装完 extra 之后，去 -h 的输出里找该后端专属的那组参数在不在，这比看 pip list 靠谱。

还有一处特别值得先查再跑：--stt / --tts 的取值字符串不一定等于 extra 的名字。 我们手上有依据的取值只有 README 命令里出现过的那几个（比如 parakeet-tdt、whisper-mlx、mlx-audio-whisper、none，TTS 侧的 qwen3、pocket、kokoro）。其余几个后端的确切选择器字符串，请以 -h 的实际输出为准，别照着 extra 名字猜着写——猜错了正好撞上「只警告不报错」这个行为。

顺带一个真会咬人的默认值：faster-whisper 那一组共 8 个参数，其中 --faster_whisper_stt_model_name 默认是 tiny.en，--faster_whisper_stt_gen_language 默认是 en。也就是说装完 faster-whisper extra 什么都不改，你拿到的是一个英文专用的小模型。相比之下 Paraformer 那组只有 2 个参数，默认模型名直接是 paraformer-zh。这两个默认值的差别，比 extra 名字本身重要得多。

什么情况下这篇不适用

只跑默认路径的，全篇跳过。 一个 extra 都不装是完全正常的用法，README 给的最短路径就是 pip install speech-to-speech 加一个 API key 就 serve。

Windows 用户注意：README 的后端矩阵是按 CUDA / CPU / Apple Silicon 三档划分的，我们手上的资料里没有针对 Windows 的单独说明，这里就不替它编。仓库另外提供了 Docker 路线：装好 NVIDIA Container Toolkit 后 docker compose up，compose 会起一个跑 Gemma 4 的 llama.cpp 服务和实时服务，暴露端口 8080 与 8765；仓库里还有 Dockerfile 与 Dockerfile.arm64。

打算给多人用的，extras 不是你的瓶颈。 --num_pipelines 默认值是 1，意味着默认只承载一个并发会话，这跟你装了几个 extra 没关系。

打算把服务暴露出去的，先看清官方口径。 serve 默认绑定 127.0.0.1，--host 的帮助原文里写的是：显式传 0.0.0.0 才会把未认证的（unauthenticated）API 暴露到网络上。服务端自身不做认证也不做限流，只应在受信网络内或放在网关后面启用；--enable_llm_proxy（默认 False）同理。这里不给「这样配就安全了」的结论。

最后一句关于许可：仓库标注 Apache-2.0，但上面提到的每个模型权重（Silero、Qwen3-TTS、Kokoro、ChatTTS、Parakeet、Paraformer 等）各有各的许可，我们一份都没读过，以各自模型页面与 LICENSE 原文为准。

延伸阅读

• 从 pip install 到第一次 serve：默认装了些什么
• docker compose up 起来的是两个服务，不是一个
• 参数写错了不报错：非激活后端的选项只会带个警告被忽略

---

本文依据 speech-to-speech 官方仓库（github.com/huggingface/speech-to-speech）的 README、 src/speech_to_speech/arguments_classes/ 下的参数定义与 Realtime Engine 架构文档整理，核对日 2026-08-09。 本文内容为仓库源码与文档口径，我们没有安装、部署或调用过该服务，文中毫秒值均为参数默认值而非实测延迟。 参数与默认值随版本变动，请以 speech-to-speech serve -h 的实际输出为准。

许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。安全相关做法请结合自身环境评估，本文不构成安全方案建议。