Microsoft VibeVoice + ComfyUI 本地部署避坑指南#

微软开源的 VibeVoice 效果惊人，但官方代码偏学术，部署门槛高。目前体验最好的方式是使用 ComfyUI 插件。本文记录了从环境报错到模型下载、再到 7B 大模型优化的全过程，实测 12G 显存可流畅运行。

🛠️ 核心工具准备#

环境: ComfyUI (官方整合包或独立环境)
插件: Enemyx-net/VibeVoice-ComfyUI

🚀 第一步：安装插件与依赖#

进入 ComfyUI/custom_nodes 目录：

Bash

1
git clone https://github.com/Enemyx-net/VibeVoice-ComfyUI

关键坑点：依赖版本

VibeVoice 极其依赖新版 transformers (>=4.51.3)。如果你的 ComfyUI 很久没更新，启动时百分百报错。

解决方法（在 ComfyUI 根目录进入终端）：

DOS
```
1
REM 如果是官方整合包，使用内置python全路径
2
python_embeded\python.exe -m pip install -U transformers accelerate
3

4
REM 如果使用虚拟环境 (.venv)
5
.venv\Scripts\python.exe -m pip install -U transformers accelerate
```
验证：安装后运行 pip show transformers，版本需 >= 4.51.3。

📥 第二步：下载模型 (使用 huggingface-cli)#

ComfyUI 版的 VibeVoice 目录结构很特殊，千万不要直接克隆整个仓库，否则会产生大量无用文件。推荐使用 huggingface-cli 精准下载。

进入模型目录：

cd ComfyUI/models/vibevoice (如果没有 vibevoice 文件夹请手动创建)

1. 下载分词器 (Tokenizer) - 必须#

VibeVoice 借用了 Qwen 的分词器，我们只下这几个小文件，不要下 Qwen 的大模型！

DOS

1
huggingface-cli download Qwen/Qwen2.5-1.5B tokenizer_config.json vocab.json merges.txt tokenizer.json --local-dir tokenizer --local-dir-use-symlinks False

2. 下载模型本体 (二选一)#

**方案 A：**轻量版 (1.5B) - 显存 < 8G 推荐

虽然快，但逻辑能力弱，容易丢字。

DOS

1
huggingface-cli download microsoft/VibeVoice-1.5B --local-dir VibeVoice-1.5B --local-dir-use-symlinks False

**方案 B：**大模型量化版 (7B Q4) - 显存 8G-12G 强烈推荐 🔥

这是 DevParker 提供的 4-bit 量化版，音质磁性，不容易吞字，12G 显存必选。

DOS

1
huggingface-cli download DevParker/VibeVoice7b-low-vram --local-dir VibeVoice-Large-Q4 --local-dir-use-symlinks False

📂 第三步：目录结构修正 (重中之重)#

ComfyUI 插件无法识别嵌套文件夹。如果你下载的是 7B Q4 版本，默认文件会藏在 4bit 子文件夹里。

你需要手动调整文件位置，确保最终结构如下：

Plaintext

1
ComfyUI/models/vibevoice/
2
├── tokenizer/               <-- 存放 vocab.json 等4个文件
3
│
4
└── VibeVoice-Large-Q4/      <-- 存放模型本体
5
    ├── config.json
6
    ├── model-00001-of-00002.safetensors
7
    ├── model-00002-of-00002.safetensors
8
    └── ... (直接放在这里，不要套在 4bit 文件夹里！)

🎛️ 第四步：ComfyUI 节点设置#

重启 ComfyUI，加载 VibeVoice Single Speaker 或 Multiple Speakers 节点。

针对 7B Q4 模型的关键设置：#

Model: 选择 VibeVoice-Large-Q4
Quantize LLM: 必须选 None ❌
- 注意：因为模型文件本身已经是量化过的，这里如果再选 4bit/8bit 会报错！
Diffusion Steps: 建议 15 - 20
- 默认 50 步太慢（需 3 分钟），改成 20 步只需 50 秒，音质几乎无损。
Text: 如果句子太长容易丢字，建议用逗号或句号切分长句。

⚡ 常见报错速查#

Model loading failed: VibeVoice embedded module import failed
- 原因: transformers 版本太低。
- 解法: 参照第一步强制升级库。
Out of Memory (OOM)
- 解法: 如果用 1.5B 模型，在节点里开启 4bit 量化；如果用 7B 模型，确保下载的是 DevParker 的 Q4 版本。
ConnectionResetError [WinError 10054]
- 原因: ComfyUI Manager 检查更新网络超时。
- 解法: 忽略即可，不影响音频生成。