装 VibeVoice 依赖时对不上：先看 pyproject.toml 写了什么

2026-08-18

装这个仓库最常见的挫败感不是报错本身，而是「我照文档做了啊」。问题在于 VibeVoice 是一个模型家族，docs/ 下几篇文档各写各的安装步骤，而它们最终都落在同一个 pyproject.toml 上。你按 A 文档装完再去跑 B 文档的脚本，冲突就是这么来的。

排查这类问题的顺序应该反过来：先打开仓库根目录的 pyproject.toml，看清楚它到底声明了什么，再回头看文档让你敲的那条命令要求了什么。

现象长什么样

几种典型情况：

按 docs/vibevoice-asr.md 装完，再去跑 docs/vibevoice-realtime-0.5b.md 里的 demo，或者反过来，transformers 的版本被来回改写；
在 docs/vibevoice-tts.md 里翻不到任何安装步骤，怀疑自己看漏了页；
跟着 vLLM 那条线走，发现命令里写的 extra 名字在 pyproject.toml 里根本查不到；
装完包，跑到某一步才抛 ImportError，提示还要再装一个包。

这四种表现的成因不一样，处置也不一样，别混着治。

判定动作：先把 `pyproject.toml` 读一遍

这是可执行的第一步，不需要跑任何东西，打开文件就行。[project] 段里写着：

requires-python = ">=3.10"

这是 Python 版本的下限。如果你的环境低于这个版本，安装期就会被挡下来，不用往下查了。

dependencies 是一个直接列出的清单，torch、transformers、accelerate、llvmlite、numba、diffusers、tqdm、numpy、scipy、librosa、ml-collections、absl-py 之外，还有 gradio、av、aiortc、uvicorn[standard]、fastapi、pydub、requests 这一串偏 Web 与音视频传输的包。也就是说，pip install -e . 一次性把 demo 服务端那套东西也一起拉进来了，这不是你装错了 extra。

真正值得盯的是约束的疏密：整个 dependencies 里带版本约束的只有三项——transformers 给的是一个有上界的区间，llvmlite 与 numba 各自只写了下限，其余全是裸包名，具体数值以仓库当前的 pyproject.toml 为准。torch 就在裸包名那一堆里。仓库文档在安装一节自述「推荐用 NVIDIA 的深度学习容器来管理 CUDA 环境」，给出的第一步是 sudo docker run 起 nvcr.io/nvidia/pytorch 镜像；如果你不走容器而在裸机上装，torch 具体装到哪个版本、配的是哪套 CUDA，pyproject.toml 这边没有给任何约束，答案不在这个文件里。

可选依赖组只有一个

[project.optional-dependencies] 段落里只有一组：

[project.optional-dependencies]
streamingtts = [
  "transformers==4.51.3",
]

只有一个组，组里也只有一项。它做的事情是把 transformers 从基础清单里那个区间收紧成一个精确版本。

这就解释了第一种现象。docs/vibevoice-asr.md 的 Installation 节写的是 pip install -e .；docs/vibevoice-realtime-0.5b.md 写的是 pip install -e .[streamingtts]。两条命令对 transformers 的要求宽窄不同，如果它们落在同一个虚拟环境里，transformers 最终停在哪个版本由后执行的那条命令与你那版 pip 的解析结果决定，仓库文档没有对这种叠装场景给出说明。如果你既要跑 ASR 又要跑 Realtime，把它们放进两个互不干扰的环境，比在一个环境里来回切要省事得多。

顺带把另一个坑说清楚：streamingtts 这个组名对应的是 VibeVoice-Realtime-0.5B 这条流式 TTS 线，不是 VibeVoice-TTS-1.5B。名字相近，指向的模型不是一个。

命令里的 extra 与配置对不上

vllm_plugin/scripts/start_server.py 里有一段安装逻辑，执行的是：

[sys.executable, "-m", "pip", "install", "-e", "/app[vllm]"],

而上面刚看过，[project.optional-dependencies] 里并没有 vllm 这一组。这两处白纸黑字对不上，我们只把它指出来：脚本请求的 extra 在当前 pyproject.toml 里查不到定义，所以别指望这条命令会额外拉进任何 vLLM 相关的包，实际行为以你那版 pip 的输出为准。

这也是为什么 docs/vibevoice-vllm-asr.md 的安装步骤只有两步：git clone 仓库，然后用官方 vLLM 的 Docker 镜像启动容器，把仓库目录挂进去、以 bash 为入口执行 vllm_plugin/scripts/start_server.py。vLLM 本身来自镜像，不来自这个包的依赖声明。所以「装了 vibevoice 却没有 vLLM」不是故障。

包与 vLLM 的连接点是 pyproject.toml 里的 entry point：

[project.entry-points."vllm.general_plugins"]
vibevoice = "vllm_plugin:register_vibevoice"

docs/vibevoice-vllm-asr.md 的排查一节给出的两条命令正好对着它：pip show vibevoice 确认包装上了，pip show -f vibevoice | grep entry 确认 entry point 落盘了。这是仓库自己给的验证动作，直接用。

pip 装不到的那几样

有几类依赖不在 dependencies 里，得单独处理，漏了就是「装完还是不行」：

ffmpeg：系统级依赖。docs/vibevoice-asr.md 在跑 demo 前写了 apt update && apt install ffmpeg -y；vllm_plugin/scripts/start_server.py 里的 install_system_deps() 装的是 ffmpeg 与 libsndfile1；vLLM 文档的排查项里也有一条「Ensure FFmpeg is installed: ffmpeg -version」。
flash-attn：不在依赖里。两篇安装文档都用注释形式给了 # pip install flash-attn --no-build-isolation，并把安装说明指向 flash-attention 自己的仓库。
peft：finetuning-asr/README.md 的 Requirements 是 pip install -e . 之后再 pip install peft，LoRA 微调这条线才需要。
soundfile：vibevoice/processor/vibevoice_tokenizer_processor.py 里保存音频的分支是 try: import soundfile as sf，失败时抛出的 ImportError 直接提示 Install it with: pip install soundfile。这是运行期才暴露的，不是安装期。

还有一个不需要装的：vibevoice/modular/modular_vibevoice_tokenizer.py 顶部尝试导入 APEX 的 fused_rms_norm_affine，导入失败会把 APEX_AVAILABLE 置为 False 走原生实现；即便导入成功，代码里还有一道环境变量开关 OPTIMIZE_FOR_SPEED，取值为 0 时同样置回 False——这是仓库当前代码里的默认值，随版本可能变动。没有 APEX 不算缺依赖。

Windows 与 Linux 分开说

仓库里的安装说明是一条 Linux 路线：sudo docker run 起 NVIDIA 的 PyTorch 容器，或者用官方 vLLM 镜像，系统依赖走 apt。我们在仓库里没有找到 Windows 原生安装的说明，也没有 Windows 下的等价步骤文档。

所以 Windows 用户不必反复怀疑自己哪一步敲错了。仓库里给出的、不依赖本机环境的路径是 README 与 docs/vibevoice-realtime-0.5b.md 里链出的 Colab notebook（对应 demo/ 目录下的 notebook 文件）。若要在本机装，WSL2 或 Docker Desktop 下按 Linux 那套走会离文档更近；这属于通用做法，不是该项目的官方内容。

装完怎么验证

按仓库给的动作来，不要自己发明：pip show vibevoice 看包是否装上；pip show -f vibevoice | grep entry 看 entry point；ffmpeg -version 看系统依赖。还有一处容易忽略的：[tool.setuptools.packages.find] 的 include 只写了 ["vibevoice*", "vllm_plugin*"]，demo/ 与 finetuning-asr/ 不在打包范围内。这就是为什么文档里用的是可编辑安装 -e，也是为什么示例命令都写成 python demo/... 的相对路径——你得站在仓库目录里跑。

什么情况说明不是依赖装错了

最后这一步比前面都重要：

你在找 TTS 的安装步骤却找不到：docs/vibevoice-tts.md 的「Installation and Usage」一节正文只有一句 Disabled due to widespread misuse.，README 的新闻条目也记载 2025-09-05 微软因发现有与既定意图不符的使用方式、基于负责任 AI 原则从该仓库移除了 VibeVoice-TTS 代码。这不是你的环境问题，是那条路本来就没有步骤可跟。
你在跑 vLLM 那条线，报的是 GPU 显存或模型路径的错：docs/vibevoice-vllm-asr.md 的排查一节把这几类单列了，处置方向是启动参数与模型目录，跟依赖声明无关。
报错发生在推理中途而不是导入阶段：像上面 soundfile 那种由 try/except ImportError 兜住的分支，是走到那一步才触发的，环境本身可能是好的。
你在裸机上装，卡在 torch 或 CUDA：pyproject.toml 对 torch 没有任何版本约束，这条链路的取舍在文档推荐的容器方案里，不在依赖声明里，去 pyproject.toml 里翻是翻不出答案的。

这个项目持续更新，上面引用的依赖清单、可选依赖组、Python 版本下限与脚本里的命令都随版本变动，以仓库最新内容为准。

本文依据 github.com/microsoft/VibeVoice 仓库与 Hugging Face 模型卡于 2026-08-18 的公开内容整理，事实来自仓库内的文档与源码。我们没有下载权重、没有跑过推理、也没有做过训练，因此不涉及显存占用、推理速度、识别准确率与音质的任何描述，也不与其它模型做比较或排名。该项目持续更新，文中涉及的模块路径、配置字段与接口写法随版本变动，请以仓库最新内容为准。

需要说明的是：仓库 README 记载，2025-09-05 微软因发现有与既定意图不符的使用方式，基于负责任 AI 原则从该仓库移除了 VibeVoice-TTS 代码；当前 vibevoice/modular/modeling_vibevoice.py 首行注释标明其来自社区 fork，且该模块未被 vibevoice/modular/__init__.py 的 __all__ 导出。本文只讲代码与架构，不构成 TTS 推理的可用性保证。

仓库 README 的风险与限制一节写明：该模型仅供研究与开发用途，未经进一步测试与开发不建议用于商业或真实场景，并特别提示了合成语音被用于伪造与虚假信息的风险。使用合成语音时应遵守所在司法辖区的法律法规，并在分享 AI 生成内容时主动披露。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。