VibeVoice ComfyUI 节点

微软 VibeVoice 文本转语音模型的全面 ComfyUI 集成，可在您的 ComfyUI 工作流中直接实现高质量的单人及多人语音合成。

✨ 功能

核心功能

• 🎤 单人 TTS：生成自然语音，可选语音克隆
• 👥 多人对话：支持最多 4 位不同说话者
• 🎯 语音克隆：从音频样本中克隆声音
• 🎨 LoRA 支持：使用自定义 LoRA 适配器对声音进行微调（v1.4.0+）
• 🎚️ 语速控制：通过调整参考语音速度来改变语速（v1.5.0+）
• 📝 文本文件加载：从文本文件加载脚本
• 📚 自动文本分块：无缝处理长文本，支持自定义分块大小
• ⏸️ 自定义暂停标签：使用 [pause] 和 [pause:ms] 标签插入静音（封装功能）
• 🔄 节点串联：连接多个 VibeVoice 节点以构建复杂工作流
• ⏹️ 中断支持：在生成前或生成过程中取消操作
• 🔧 灵活配置：可控制温度、采样和引导尺度

性能与优化

• ⚡ 注意力机制：可选择 auto、eager、sdpa、flash_attention_2 或 sage
• 🎛️ 扩散步数：可调节质量与速度之间的平衡（默认：20 步）
• 💾 内存管理：可切换生成后自动清理显存
• 🧹 释放内存节点：手动控制内存，适用于复杂工作流
• 🍎 Apple Silicon 支持：通过 MPS 在 M1/M2/M3 Mac 上实现原生 GPU 加速
• 🔢 8 位量化：在大幅降低显存占用的同时保持完美音质
• 🔢 4 位量化：在几乎不损失音质的情况下实现最大显存节省

兼容性与安装

• 📦 自包含：内置 VibeVoice 代码，无外部依赖
• 🔄 通用兼容性：自适应支持 transformers v4.51.3+
• 🖥️ 跨平台：适用于 Windows、Linux 和 macOS
• 🎮 多后端支持：支持 CUDA、CPU 和 MPS（Apple Silicon）

🎥 视频演示

点击观看演示视频

📦 安装

自动安装（推荐）

1. 将此仓库克隆到您的 ComfyUI 自定义节点文件夹中：

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

2. 重启 ComfyUI - 节点将在首次使用时自动安装所需依赖项

📥 模型安装

需要手动下载

从版本 1.6.0 开始，模型和分词器必须手动下载并放置到正确文件夹中。封装不再自动下载它们。

下载链接

模型

您可以从 HuggingFace 下载 VibeVoice 模型：

模型	大小	下载链接
VibeVoice-1.5B	~5.4GB	microsoft/VibeVoice-1.5B
VibeVoice-Large	~18.7GB	aoi-ot/VibeVoice-Large
VibeVoice-Large-Q8	~11.6GB	FabioSarracino/VibeVoice-Large-Q8
VibeVoice-Large-Q4	~6.6GB	DevParker/VibeVoice7b-low-vram

分词器（必需）

VibeVoice 使用 Qwen2.5-1.5B 分词器：

• 下载地址：Qwen2.5-1.5B 分词器
• 必需文件：tokenizer_config.json、vocab.json、merges.txt、tokenizer.json

安装步骤

1. 如果 models/vibevoice/ 文件夹不存在，请创建它：

   ComfyUI/models/vibevoice/
   

2. 下载并整理文件到 vibevoice 文件夹中：

   ComfyUI/models/vibevoice/
   ├── tokenizer/                 # 将 Qwen 分词器文件放入此处
   │   ├── tokenizer_config.json
   │   ├── vocab.json
   │   ├── merges.txt
   │   └── tokenizer.json
   ├── VibeVoice-1.5B/           # 模型文件夹
   │   ├── config.json
   │   ├── model-00001-of-00003.safetensors
   │   ├── model-00002-of-00003.safetensors
   │   └── ... (其他模型文件)
   ├── VibeVoice-Large/
   │   └── ... (模型文件)
   └── my-custom-vibevoice/      # 支持自定义名称
       └── ... (模型文件)
   

3. 对于使用 git-lfs 或 HF CLI 从 HuggingFace 下载的模型，也可以使用缓存结构：

   ComfyUI/models/vibevoice/
   └── models--microsoft--VibeVoice-1.5B/
       └── snapshots/
           └── [hash]/
               └── ... (模型文件)
   

4. 刷新浏览器 - 模型将出现在下拉菜单中

注意事项

• 下拉菜单将显示从文件夹名称中提取的友好名称
• 同时支持普通文件夹和 HuggingFace 缓存结构
• 每次刷新浏览器时都会重新扫描模型
• 量化模型会根据其配置文件自动检测
• 分词器的搜索优先级如下：
  1. ComfyUI/models/vibevoice/tokenizer/（推荐）
  2. ComfyUI/models/vibevoice/models--Qwen--Qwen2.5-1.5B/（如果之前安装过）
  3. HuggingFace 缓存（如有）

🔧 可用节点

1. VibeVoice 从文件加载文本

从 ComfyUI 的输入/输出/临时目录中加载文本内容。

• 支持格式：.txt
• 输出：用于 TTS 节点的文本字符串

2. VibeVoice 单人声

使用单一声音将文本转换为语音。

• 文本输入：直接输入文本或从“加载文本”节点连接
• 模型：从下拉菜单中选择可用模型
• 声音克隆：可选音频输入，用于声音克隆
• 参数（按顺序）：
  • text：要转换为语音的输入文本
  • model：从 ComfyUI/models/vibevoice/ 中找到的可用模型列表中选择
  • attention_type：auto、eager、sdpa、flash_attention_2 或 sage（默认：auto）
  • quantize_llm：对未量化的模型仅动态量化 LLM 组件。选项：“全精度”（默认）、“4bit”或“8bit”。4bit 可显著节省显存，且质量损失极小。8bit 在质量和内存占用之间提供了良好平衡。需要 CUDA GPU。对于已量化的模型则忽略此参数。
  • free_memory_after_generate：生成后释放显存（默认：True）
  • diffusion_steps：去噪步骤数（5–100，默认：20）
  • seed：随机种子，用于结果可重复性（默认：42）
  • cfg_scale：无分类器指导（1.0–2.0，默认：1.3）
  • use_sampling：启用或禁用确定性生成（默认：False）
• 可选参数：
  • voice_to_clone：用于声音克隆的音频输入
  • lora：来自 VibeVoice LoRA 节点的 LoRA 配置
  • temperature：采样温度（0.1–2.0，默认：0.95）
  • top_p：核采样参数（0.1–1.0，默认：0.95）
  • max_words_per_chunk：长文本每块的最大词数（100–500，默认：250）
  • voice_speed_factor：语速调整（0.8–1.2，默认：1.0，步长：0.01）

3. VibeVoice 多人声

生成具有不同声音的多角色对话。

• 说话人格式：使用 [N]: 标记，其中 N 为 1–4
• 声音分配：可为每个说话人提供可选的声音样本
• 推荐模型：VibeVoice-Large，以获得更好的多人声效果
• 参数（按顺序）：
  • text：包含说话人标签的输入文本
  • model：从 ComfyUI/models/vibevoice/ 中找到的可用模型列表中选择
  • attention_type：auto、eager、sdpa、flash_attention_2 或 sage（默认：auto）
  • quantize_llm：对未量化的模型仅动态量化 LLM 组件。选项：“全精度”（默认）、“4bit”或“8bit”。4bit 可显著节省显存，且质量损失极小。8bit 在质量和内存占用之间提供了良好平衡。需要 CUDA GPU。对于已量化的模型则忽略此参数。
  • free_memory_after_generate：生成后释放显存（默认：True）
  • diffusion_steps：去噪步骤数（5–100，默认：20）
  • seed：随机种子，用于结果可重复性（默认：42）
  • cfg_scale：无分类器指导（1.0–2.0，默认：1.3）
  • use_sampling：启用或禁用确定性生成（默认：False）
• 可选参数：
  • speaker1_voice 至 speaker4_voice：用于声音克隆的音频输入
  • lora：来自 VibeVoice LoRA 节点的 LoRA 配置
  • temperature：采样温度（0.1–2.0，默认：0.95）
  • top_p：核采样参数（0.1–1.0，默认：0.95）
  • voice_speed_factor：所有说话人的语速调整（0.8–1.2，默认：1.0，步长：0.01）

4. VibeVoice 释放内存

手动从内存中释放所有已加载的 VibeVoice 模型。

• 输入：audio — 连接音频输出以触发内存清理
• 输出：audio — 不改变地传递输入音频
• 使用场景：插入到节点之间，以便在工作流的特定点释放显存/内存
• 示例：[VibeVoice 节点] → [释放内存] → [保存音频]

5. VibeVoice LoRA

配置并加载自定义 LoRA 适配器，用于微调 VibeVoice 模型。

• LoRA 选择：包含可用 LoRA 适配器的下拉菜单
• LoRA 位置：将您的 LoRA 文件夹放置在 ComfyUI/models/vibevoice/loras/
• 参数：
  • lora_name：从可用 LoRA 适配器中选择，或选择“None”以禁用
  • llm_strength：语言模型 LoRA 的强度（0.0–2.0，默认：1.0）
  • use_llm：应用语言模型 LoRA 组件（默认：True）
  • use_diffusion_head：应用扩散头替换（默认：True）
  • use_acoustic_connector：应用声学连接器 LoRA（默认：True）
  • use_semantic_connector：应用语义连接器 LoRA（默认：True）
• 输出：lora — LoRA 配置，用于连接到说话人节点
• 用法：[VibeVoice LoRA] → [单人声/多人声节点]

💬 多人声文本格式

对于多人声生成，请使用 [N]: 格式来组织文本：

[1]: 你好，今天过得怎么样？
[2]: 我很好，谢谢你的关心！
[1]: 听到这个真好。
[3]: 大家好，我可以加入你们的对话吗？
[2]: 当然可以，欢迎！

重要提示：

• 使用 [1]:、[2]:、[3]:、[4]: 来标记说话人
• 最多支持 4 个说话人
• 系统会自动从您的文本中检测说话人的数量
• 每个说话人可以选择性地提供声音样本进行克隆

🧠 模型信息

VibeVoice-1.5B

• 大小：约 5.4GB 下载
• 显存：约 6GB
• 速度：推理更快
• 质量：适合单人声
• 使用场景：快速原型设计、单人声音效

VibeVoice-Large

• 大小：约 18.7GB 下载
• 显存：约 20GB
• 速度：推理较慢但经过优化
• 质量：现有最佳质量（全精度）
• 使用场景：最高质量制作、多人声对话
• 备注：微软最新官方发布版本

VibeVoice-Large-Q8

• 大小：约 11.6GB 下载（比完整模型减少 38%）
• 显存：约 12GB（比全精度减少 40%）
• 速度：推理速度均衡
• 质量：与全精度完全相同——完美保留音频质量
• 使用场景：适用于配备 12GB 显存的 GPU（如 RTX 3060、4070 Ti 等），实现制作级音频
• 量化：仅对 LLM 进行 8bit 量化，音频组件保持全精度
• 备注：由 Fabio Sarracino 量化

VibeVoice-Large-Q4

• 大小：约 6.6GB 下载
• 显存：约 8GB
• 速度：推理速度均衡
• 质量：质量良好，损失极小
• 使用场景：为低端 GPU 提供最大显存节省
• 备注：由 DevParker 量化

模型将在首次使用时自动下载，并缓存在 ComfyUI/models/vibevoice/ 中。

⚙️ 生成模式

确定性模式（默认）

• use_sampling = False
• 产生一致、稳定的输出
• 推荐用于生产环境

采样模式

• use_sampling = True
• 输出更具变化性
• 使用 temperature 和 top_p 参数
• 适合创意探索

🎯 语音克隆

要克隆一种声音：

1. 将音频节点连接到 voice_to_clone 输入端（单人说话）
2. 或者连接到 speaker1_voice、speaker2_voice 等（多人说话）
3. 模型会尝试匹配该声音的特征

语音样本要求：

• 清晰的音频，背景噪音尽量少
• 最短3–10秒。建议至少30秒以获得更好的质量
• 自动重采样至24kHz

🎨 LoRA 支持

概述

从1.4.0版本开始，VibeVoice ComfyUI支持自定义的LoRA（低秩适应）适配器，用于微调语音特征。这使您能够在保持基础VibeVoice功能的同时，训练和使用专门的语音模型。

设置LoRA适配器

1. LoRA目录结构： 将您的LoRA适配器文件夹放置在：ComfyUI/models/vibevoice/loras/

   ComfyUI/
   └── models/
       └── vibevoice/
           └── loras/
               ├── my_custom_voice/
               │   ├── adapter_config.json
               │   ├── adapter_model.safetensors
               │   └── diffusion_head/  (可选)
               ├── character_voice/
               └── style_adaptation/
   

2. 所需文件：

   • adapter_config.json：LoRA配置文件
   • adapter_model.safetensors 或 adapter_model.bin：模型权重
   • 可选组件：
     • diffusion_head/：自定义扩散头权重
     • acoustic_connector/：声学连接器适配
     • semantic_connector/：语义连接器适配

在ComfyUI中使用LoRA

1. 添加VibeVoice LoRA节点：

   • 在工作流中创建一个“VibeVoice LoRA”节点
   • 从下拉菜单中选择您的LoRA
   • 配置组件设置和强度

2. 连接到说话人节点：

   • 将LoRA节点的输出连接到说话人节点的 lora 输入端
   • 单人说话和多人说话节点都支持LoRA

3. LoRA参数：

   • llm_strength：控制语言模型LoRA的影响程度（0.0-2.0）
   • 组件开关：启用或禁用特定的LoRA组件
   • 选择“无”以禁用LoRA并使用基础模型

训练您自己的LoRA

要为VibeVoice创建自定义LoRA适配器，请使用官方微调仓库：

• 仓库：VibeVoice微调
• 特性：
  • 参数高效的微调
  • 支持自定义数据集
  • 可调节的LoRA等级和缩放
  • 可选的扩散头适配

最佳实践

• 语音一致性：对于长文本，在所有分块中使用相同的LoRA
• 内存管理：LoRA只会增加少量内存开销（约100-500MB）
• 兼容性：LoRA适配器与所有VibeVoice模型变体兼容
• 强度调整：从默认强度（1.0）开始，根据结果进行调整

兼容性说明

⚠️ Transformers版本：LoRA实现是在 transformers==4.51.3 版本上开发和测试的。虽然我们的封装支持 transformers>=4.51.3，但不能保证在更新版本的transformers中LoRA功能正常工作。如果您遇到LoRA加载问题，建议专门使用 transformers==4.51.3：

pip install transformers==4.51.3

🙏 致谢

LoRA实现由@jpgallegoar完成（PR #127）

🎚️ 语音速度控制

概述

语音速度控制功能允许您通过调整参考语音的速度来影响生成语音的语速。此功能会在处理前对输入的参考语音样本进行时间拉伸，从而使模型学习并重现改变后的语速。

自1.5.0版本起可用

工作原理

系统会对参考语音音频应用时间拉伸：

• 值小于1.0会减慢参考语音，生成较慢的语音
• 值大于1.0会加快参考语音，生成较快的语音
• 模型会从修改后的语音特征中学习，并以相似的速度生成语音

使用方法

• 参数：voice_speed_factor
• 范围：0.8到1.2
• 默认值：1.0（正常速度）
• 步长：0.01（1%增量）

推荐设置

• 最佳范围：0.95至1.05，以获得自然的声音效果
• 较慢的语音：尝试0.95（慢5%）或0.97（慢3%）
• 较快的语音：尝试1.03（快3%）或1.05（快5%）
• 最佳效果：提供至少20秒的参考音频，以便更准确地匹配语速

注意事项

• 效果在较长的参考音频样本上表现更好（建议20秒以上）
• 极端值（小于0.9或大于1.1）可能会产生不自然的语音
• 在多说话人模式下，速度调整会平等地应用于所有说话人
• 合成语音（未提供音频时）不受此参数影响

📖 示例

# 单人说话
voice_speed_factor: 0.95  # 稍微慢一点，语气更沉稳
voice_speed_factor: 1.05  # 稍微快一点，语气更活泼

# 多人说话
voice_speed_factor: 0.98  # 所有说话人语速慢2%
voice_speed_factor: 1.02  # 所有说话人语速快2%

⏸️ 暂停标签支持

概述

VibeVoice封装包含一个自定义的暂停标签功能，允许您在文本段落之间插入静音。这不是微软VibeVoice的标准功能——而是我们封装的原创实现，旨在提供更多对语音节奏的控制。

自1.3.0版本起可用

使用方法

您可以在文本中使用两种类型的暂停标签：

• [pause]：插入1秒的静音（默认）
• [pause:ms]：插入自定义持续时间的静音，单位为毫秒（例如，[pause:2000]表示2秒）

📖 示例

单人说话

欢迎来到我们的演讲。[pause] 今天我们将探讨人工智能。[pause:500] 让我们开始吧！

多人说话

[1]: 大家好 [pause] 今天过得怎么样？
[2]: 我很好！[pause:500] 谢谢你的关心。
[1]: 很高兴听到！

注意事项

⚠️ 上下文限制警告：

注意：暂停会强制将文本分割成多个分块。这可能会降低模型理解上下文的能力。模型的上下文仅限于其当前分块。

这意味着：

• 暂停前后的文本会被分别处理
• 模型在生成语音时无法跨越暂停边界查看上下文
• 这可能会影响韵律和语调的一致性
• 这可能会影响韵律和语调的一致性

工作原理

1. 封装会解析您的文本以查找暂停标签
2. 暂停之间的文本段落会被独立处理
3. 会为每个暂停时长生成静音音频
4. 所有音频片段（语音和静音）会被拼接在一起

最佳实践

• 在自然的断句处使用暂停（如句子或段落结束）
• 避免在需要保持上下文连贯的短语中间使用暂停
• 测试不同的暂停时长，找到最自然的效果

💡 取得最佳效果的提示

1. 文本准备：

   • 使用适当的标点符号以产生自然停顿
   • 将长文本拆分为多个段落
   • 对于多说话人场景，确保清晰的说话人切换标记
   • 适度使用停顿标签，以保持上下文连贯性

2. 模型选择：

   • 对于快速的单说话人任务，使用1.5B参数量的模型（速度最快，约需8GB显存）
   • 若追求极致音质，可选用Large版本（约需20GB显存）
   • 如需在12GB显存下获得优质音频，推荐使用Large-Q8版本（音质完美，模型体积缩小38%）
   • 若要最大限度节省显存，可选择Large-Quant-4Bit版本（约需7GB显存）

3. 种子管理：

   • 默认种子（42）通常适用于大多数情况
   • 建议保存表现良好的种子，以便为同一角色保持一致的音色
   • 若默认种子效果不佳，可尝试随机生成种子

4. 性能优化：

   • 首次运行时会下载模型文件（5–17GB）
   • 后续运行将直接调用缓存中的模型
   • 推荐使用GPU以加快推理速度

💻 系统要求

硬件

• 最低配置：8GB显存，适用于VibeVoice-1.5B
• 推荐配置：17GB及以上显存，适用于VibeVoice-Large
• 内存：16GB及以上系统内存

软件

• Python 3.8+
• PyTorch 2.0+
• CUDA 11.8+（用于GPU加速）
• Transformers 4.51.3+
• ComfyUI（最新版本）

🔧 故障排除

安装问题

• 确保使用ComfyUI提供的Python环境
• 自动安装失败时，可尝试手动安装
• 安装完成后请重启ComfyUI

生成问题

• 若语音不稳定，可尝试启用确定性模式
• 多说话人场景中，请确保文本格式正确，如“[N]:”
• 检查说话人编号是否连续（例如1,2,3，而非1,3,5）

显存问题

• Large模型需要约16GB显存
• 在显存较低的设备上，建议使用1.5B模型
• 模型采用bfloat16精度以提升效率

📖 示例

单说话人

文本: “欢迎来到我们的演示。今天我们将探索令人着迷的人工智能世界。”
模型: [从可用模型中选择]
cfg_scale: 1.3
use_sampling: False

两说话人

[1]: 你看到最新的AI进展了吗？
[2]: 是的，它们非常令人印象深刻！
[1]: 我觉得语音合成已经取得了长足的进步。
[2]: 绝对如此，现在听起来非常自然。

四说话人对话

[1]: 各位，欢迎大家参加我们的会议。
[2]: 感谢邀请！
[3]: 很高兴能来。
[4]: 期待今天的讨论。
[1]: 那么我们开始议程吧。

📊 性能基准

模型	显存占用	上下文长度	最大音频时长
VibeVoice-1.5B	~6GB	64K tokens	~90分钟
VibeVoice-Large	~20GB	32K tokens	~45分钟
VibeVoice-Large-Q8	~12GB	32K tokens	~45分钟
VibeVoice-Large-Q4	~8GB	32K tokens	~45分钟

⚠️ 已知限制

• 多说话人模式最多支持4个说话人
• 最佳效果适用于英文和中文文本
• 部分种子可能导致输出不稳定
• 无法直接控制背景音乐的生成

📄 许可证

本ComfyUI插件基于MIT许可证发布。详细信息请参阅LICENSE文件。

注意：VibeVoice模型本身受微软许可条款约束：

• VibeVoice仅用于研究目的
• 请查阅微软VibeVoice仓库以获取完整的模型许可详情

🔗 链接

• 原始VibeVoice仓库 - 官方微软VibeVoice仓库（目前暂不可用）

🙏 致谢

• VibeVoice模型：微软研究院
• ComfyUI集成：Fabio Sarracino
• 基础模型：基于Qwen2.5架构构建

💬 支持

如遇问题或疑问：

1. 请查看故障排除部分
2. 检查ComfyUI日志以获取错误信息
3. 确保VibeVoice已正确安装
4. 提交包含详细错误信息的问题

🤝 贡献

欢迎贡献代码！请：

1. 全面测试修改内容
2. 遵循现有代码风格
3. 根据需要更新文档
4. 提交带有清晰描述的拉取请求

📝 更改记录

版本1.8.1

• 强制安装bitsandbytes>=0.48.1库，因为0.48.0版本存在严重bug，导致Q8模型无法正常工作。
• Bug修复

版本1.8.0

• 全新官方8位量化模型：VibeVoice-Large-Q8
  • 发布于HuggingFace：FabioSarracino/VibeVoice-Large-Q8
  • 模型大小：11.6GB（相比18.7GB的全精度版本缩小38%）
  • 显存占用：12GB（相比20GB减少40%）
  • 音质完美：与全精度模型无差异，未出现任何质量损失
  • 选择性量化策略：保留扩散头、VAE及连接器等音频关键组件的全精度
  • 专为12GB显存的GPU（如RTX 3060、4070 Ti等）设计
  • 通过精心选择量化组件，有效解决了常见8位量化带来的“噪声”问题
• 新增8位动态LLM量化
  • Single和Multiple Speaker节点新增“8bit”选项
  • 选项包括：“full precision”（默认）、“4bit”、“8bit”
  • 对非量化模型仅动态量化LLM部分
  • 扩散头、声学/语义连接器以及分词器等音频关键组件均保持全精度
  • 在音质与显存节省之间取得良好平衡
  • 需要CUDA GPU和bitsandbytes库支持
  • 对于已量化模型则自动忽略

版本1.7.0

• 新增针对非量化模型的动态LLM-only 4位量化功能
  • Single和Multiple Speaker节点新增“quantize_llm”参数
  • 选项为“full precision”（默认）或“4bit”
  • 仅量化语言模型部分，而扩散头仍保持全精度
  • 生成速度显著提升，同时大幅节省显存
  • 相比全精度，音质损失极小
  • 需要CUDA GPU进行量化
  • 对于已量化模型则自动忽略
  • 使用NF4（4-bit NormalFloat）量化类型，专为神经网络优化

版本1.6.3

• 修复了分词器初始化错误
  • 解决了加载处理器时出现的TypeError: expected str, bytes or os.PathLike object, not NoneType问题
  • 添加了健壮的分词器文件路径解析回退机制
  • 改进了vocab.json和merges.txt文件的加载处理
  • 加强了分词器初始化过程中异常情况的处理能力

版本1.6.2

• 修复了分词器加载问题，该问题源于HuggingFace缓存可能干扰本地文件
• 分词器现直接从指定路径加载，避免缓存冲突
• 增加了明确的文件路径加载方式，以提高可靠性
• 改进了日志记录，以便显示实际使用的分词器文件

版本1.6.1

• 通过移除不必要的HuggingFace设置，改进了集成工作

版本 1.6.0

• 重大变更：移除了从 HuggingFace 自动下载模型的功能
  • 现在必须手动下载模型并放置到 ComfyUI/models/vibevoice/ 目录下
  • 动态模型下拉菜单，每次刷新浏览器时都会扫描可用的模型
  • 支持自定义文件夹名称和 HuggingFace 缓存结构
  • 能够自动从配置文件中检测量化模型
  • 提高了用户对模型管理的控制能力
  • 消除了与私有 HuggingFace 仓库相关的认证问题
• 改进的日志系统：
  • 优化了日志记录，减少了控制台的混乱输出
  • 输出更加清晰，提升了用户体验

版本 1.5.0

• 新增语音速度控制功能，用于调整语速
  • 在单人说话者节点和多人说话者节点中新增 voice_speed_factor 参数
  • 对参考音频进行时间拉伸以影响输出语速
  • 取值范围为 0.8 到 1.2，步长为 0.01
  • 推荐取值范围为 0.95 到 1.05，以获得自然效果
  • 使用 20 秒以上的参考音频效果最佳

版本 1.4.3

• 改进了 LoRA 系统，增强了日志记录和兼容性检查
  • 添加了模型兼容性检测，防止加载不匹配的 LoRA
  • 增强了 LoRA 组件加载过程的调试日志
  • 自动检测不兼容的模型-LoRA 组合，并给出明确的错误信息
  • 防止在使用量化模型时加载标准 LoRA 出现错误
  • 对 LoRA 权重加载过程进行了小幅优化

版本 1.4.2

• 修复了若干 bug

版本 1.4.1

• 修复了加载本地缓存模型时出现的 HuggingFace 认证错误
  • 解决了已下载模型的 401 授权错误问题
  • 节点现在能够正确使用本地模型快照，无需 HuggingFace API 认证
  • 防止在 ComfyUI/models/vibevoice/ 中存在模型时进行不必要的 API 调用

版本 1.4.0

• 新增 LoRA（低秩适应）支持，用于微调模型
  • 新增“VibeVoice LoRA”节点，用于配置自定义语音适配
  • 支持语言模型、扩散头和连接器的适配
  • 下拉菜单可方便地从 ComfyUI/models/vibevoice/loras/ 中选择 LoRA
  • 可调节 LoRA 强度及各组件开关
  • 兼容单人说话者节点和多人说话者节点
  • 内存开销极小（每份 LoRA 约 100-500MB）
  • 致谢：由 @jpgallegoar 实现

版本 1.3.0

• 新增自定义暂停标签支持，用于控制语音节奏
  • 新增 [pause] 标签，表示 1 秒钟的静音（默认）
  • 新增 [pause:ms] 标签，用于指定自定义持续时间（单位为毫秒），例如 [pause:2000] 表示 2 秒钟
  • 适用于单人说话者节点和多人说话者节点
  • 自动在暂停点分割文本，同时保持语音一致性
  • 注意：此功能为封装特性，并非 Microsoft VibeVoice 的一部分

版本 1.2.5

• 修复了若干 bug

版本 1.2.4

• 在单人说话者节点中新增了针对长文本的自动分块功能
  • 单人说话者节点现在会自动将超过 250 字的文本拆分为多个块，以避免音频加速问题
  • 新增可选参数 max_words_per_chunk（取值范围为 100-500 字，默认为 250）
  • 使用相同的种子确保所有分块的语音特征一致
  • 无缝拼接音频分块，生成流畅自然的输出

版本 1.2.3

• 新增 SageAttention 支持，用于加速推理
  • 新增“sage”注意力选项，采用量化注意力（INT8/FP8）以加快生成速度
  • 要求：配备 CUDA 的 NVIDIA 显卡，并安装 sageattention 库

版本 1.2.2

• 新增 4 位量化模型支持
  • 菜单中新增 VibeVoice-Large-Quant-4Bit 模型，仅需约 7GB 显存，而此前需要约 17GB
  • 要求：配备 CUDA 的 NVIDIA 显卡，并安装 bitsandbytes 库

版本 1.2.1

• 修复了若干 bug

版本 1.2.0

• MPS 支持 Apple Silicon：
  • 新增对搭载 Apple Silicon（M1/M2/M3）的 Mac 设备的 GPU 加速支持
  • 自动检测并使用 MPS 后端（如可用），相比 CPU 可显著提升性能

版本 1.1.1

• 通用 Transformer 兼容性：
  • 实现了自适应系统，可自动调整以适应不同版本的 Transformer
  • 保证从 v4.51.3 版本起的兼容性
  • 自动检测并适应不同版本之间的 API 变化

版本 1.1.0

• 更新了下载 VibeVoice-Large 模型的 URL
• 移除了已弃用的 VibeVoice-Large-Preview 模型

版本 1.0.9

• 将 VibeVoice 代码直接嵌入到封装器中
  • 新增 vvembed 文件夹，包含完整的 VibeVoice 代码（MIT 许可证）
  • 不再需要外部安装 VibeVoice
  • 确保所有用户都能继续正常使用

版本 1.0.8

• 修复了 BFloat16 兼容性问题
  • 解决了与音频处理节点相关的张量类型兼容性问题
  • 输入音频张量现在会被转换为 Float32，以实现与 numpy 的兼容性
  • 输出音频张量则被显式转换为 Float32，以确保与下游节点的兼容性
  • 解决了在使用语音克隆或保存音频时出现的“Got unsupported ScalarType BFloat16”错误

版本 1.0.7

• 新增中断处理器，用于检测用户的取消请求
• 修复了若干 bug

版本 1.0.6

• 修复了一个导致 VibeVoice 节点无法直接接收来自其他 VibeVoice 节点音频的 bug

版本 1.0.5

• 新增对 Microsoft 官方 VibeVoice-Large 模型（稳定版）的支持

版本 1.0.4

• 改进了分词器依赖项的处理

版本 1.0.3

• 在单人说话者节点和多人说话者节点中新增了 attention_type 参数，用于优化性能
  • auto（默认）：自动选择最佳实现
  • eager：无优化的标准实现
  • sdpa：PyTorch 优化的缩放点积注意力
  • flash_attention_2：Flash Attention 2，用于获得最高性能（需要兼容的 GPU）
• 新增 diffusion_steps 参数，用于控制生成质量与速度的权衡
  • 默认值为 20（VibeVoice 默认值）
  • 值越高：质量越好，但生成时间越长
  • 值越低：生成速度更快，但可能质量稍差

版本 1.0.2

• 在单人说话者节点和多人说话者节点中新增了 free_memory_after_generate 开关
  • 新增专用“释放内存节点”，用于工作流中的手动内存管理
  • 改进了 VRAM/RAM 使用优化
  • 提升了长时间生成任务的稳定性
  • 用户现在可以选择自动或手动内存管理方式

版本 1.0.1

• 修复了说话者文本中的换行符问题（无论是单人还是多人说话者节点）
  • 现在会在生成前自动移除单个说话者文本中的换行符
  • 改善了所有生成模式下的文本格式处理

版本 1.0.0

• 初始发布
  • 单人说话者节点，具备语音克隆功能
  • 多人说话者节点，具备自动说话者检测功能
  • 支持从 ComfyUI 目录加载文本文件
  • 提供确定性和采样两种生成模式
  • 支持 VibeVoice 1.5B 和 Large 模型

VibeVoice-ComfyUI 快速上手指南

VibeVoice-ComfyUI 是微软 VibeVoice 文本转语音（TTS）模型在 ComfyUI 中的集成节点，支持高质量单人及多人语音合成、声音克隆及 LoRA 微调。

1. 环境准备

系统要求

• 操作系统：Windows, Linux, macOS (包括 Apple Silicon M1/M2/M3)
• 显卡 (GPU)：
  • NVIDIA GPU (推荐 CUDA 后端)
  • Apple Silicon (支持 MPS 加速)
  • 或仅使用 CPU (速度较慢)
• 显存 (VRAM) 建议：
  • VibeVoice-1.5B: 最低 6GB
  • VibeVoice-Large (全精度): 约 20GB
  • VibeVoice-Large-Q8 (8-bit): 约 12GB (推荐 RTX 3060/4070 Ti 等)
  • VibeVoice-Large-Q4 (4-bit): 约 8GB (低显存方案)

前置依赖

• 已安装 ComfyUI 及其管理器 (ComfyUI Manager)。
• Python 环境需兼容 transformers >= 4.51.3 (插件首次运行时会自动安装所需依赖)。

---

2. 安装步骤

第一步：安装插件节点

打开终端，进入 ComfyUI 的自定义节点目录并克隆仓库：

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

重启 ComfyUI。插件会在首次使用时自动安装必要的 Python 依赖包。

第二步：下载模型与分词器 (必需)

注意：从 v1.6.0 开始，模型和分词器不再自动下载，需手动放置到指定目录。

1. 创建目录结构： 在 ComfyUI/models/ 下创建 vibevoice 文件夹：

   ComfyUI/models/vibevoice/
   ├── tokenizer/          # 存放分词器文件
   └── [模型名称文件夹]/    # 存放模型文件
   

2. 下载分词器 (Tokenizer)： VibeVoice 依赖 Qwen2.5-1.5B 的分词器。

   • 来源：HuggingFace - Qwen/Qwen2.5-1.5B
   • 需下载文件：tokenizer_config.json, vocab.json, merges.txt, tokenizer.json
   • 将上述文件放入 ComfyUI/models/vibevoice/tokenizer/ 目录。

3. 下载主模型： 根据显存选择以下任一模型下载，并将文件放入 ComfyUI/models/vibevoice/ 下的独立文件夹中（文件夹名可自定义，如 VibeVoice-1.5B）：

   模型版本	大小	适用场景	下载链接
   VibeVoice-1.5B	~5.4GB	快速测试、单人语音	microsoft/VibeVoice-1.5B
   VibeVoice-Large-Q8	~11.6GB	推荐：高质量且省显存	FabioSarracino/VibeVoice-Large-Q8
   VibeVoice-Large-Q4	~6.6GB	极低显存方案	DevParker/VibeVoice7b-low-vram
   VibeVoice-Large	~18.7GB	最高质量 (需大显存)	aoi-ot/VibeVoice-Large

   国内用户若访问 HuggingFace 困难，可使用镜像站 (如 hf-mirror.com) 或 Git LFS 加速工具下载。

4. 刷新界面： 点击 ComfyUI 界面上的 "Refresh" 按钮，模型将出现在节点的下拉菜单中。

---

3. 基本使用

场景一：单人语音合成 (Single Speaker)

这是最基础的用法，将文本转换为语音，可选声音克隆。

1. 添加节点：

   • 双击搜索并添加 VibeVoice Single Speaker 节点。
   • 添加 Save Audio 节点用于保存结果。

2. 配置参数：

   • text: 输入要合成的文本（例如："你好，欢迎使用 VibeVoice。"）。
   • model: 选择已下载的模型（如 VibeVoice-Large-Q8）。
   • voice_to_clone (可选): 连接一个 Load Audio 节点，上传参考音频以实现声音克隆。
   • diffusion_steps: 去噪步数，默认 20 (越高音质越好但越慢)。
   • quantize_llm: 若使用非量化模型且显存紧张，可设为 8bit 或 4bit。

3. 连接与运行：

   [VibeVoice Single Speaker] (AUDIO 输出) --> [Save Audio] (AUDIO 输入)
   

   点击 "Queue Prompt" 生成音频。

场景二：多人对话合成 (Multi-Speaker)

支持最多 4 人对话，需按特定格式编写脚本。

1. 添加节点：

   • 添加 VibeVoice Multiple Speakers 节点。

2. 编写脚本： 在 text 输入框中使用 [N]: 标记说话人（N 为 1-4）：

   [1]: 你好，今天天气不错！
   [2]: 是啊，适合出去走走。
   [1]: 那我们一起去公园吧？
   

3. 声音克隆 (可选)：

   • 将不同的参考音频分别连接到 speaker1_voice, speaker2_voice 等输入端，为每个角色赋予不同音色。

4. 运行： 连接 Save Audio 节点后执行，系统将自动识别说话人并生成连贯对话。

进阶技巧

• 长文本处理：节点支持自动分块，无需手动切割长文章。
• 插入停顿：在文本中使用 [pause] 或 [pause:1000] (毫秒) 插入静音。
• 显存优化：在工作流中插入 VibeVoice Free Memory 节点，可在生成间隙手动释放显存，防止 OOM。