ComfyUI-Qwen-TTS

英语 | 中文版

基于阿里巴巴通义实验室团队开源的 Qwen3-TTS 项目，为 ComfyUI 提供的语音合成、语音克隆和语音设计自定义节点。

📋 更改日志

• 2026-02-04: 功能更新：新增全局暂停控制（QwenTTSConfigNode）及对 extra_model_paths.yaml 的支持（update.md）
• 2026-01-29: 功能更新：支持加载自定义微调模型与说话人（update.md）
  • 注：目前微调功能仍处于实验阶段；为获得最佳效果，建议使用零样本克隆。
• 2026-01-27: UI 优化：简洁的 LoadSpeaker 界面；修复了与 PyTorch 2.6+ 的兼容性问题（update.md）
• 2026-01-26: 功能更新：新增语音持久化系统（SaveVoice / LoadSpeaker）（update.md）
• 2026-01-24: 增加注意力机制选择及模型内存管理功能（update.md）
• 2026-01-24: 在所有 TTS 节点中添加生成参数（top_p、top_k、温度、重复惩罚）（update.md）
• 2026-01-23: 依赖兼容性与 Mac (MPS) 支持，新增节点：VoiceClonePromptNode、DialogueInferenceNode（update.md）

在线工作流

• Qwen3-TTS 多角色多轮对话生成工作流：
  • 工作流
• Qwen3-TTS 三合一（克隆、设计、自定义）工作流：
  • 工作流

核心特性

• 🎵 语音合成：高质量文本转语音转换。
• 🎭 语音克隆：从短参考音频实现零样本语音克隆。
• 🎨 语音设计：根据自然语言描述创建自定义语音特征。
• 🚀 高效推理：同时支持 12Hz 和 25Hz 语音分词器架构。
• 🎯 多语言支持：原生支持 10 种语言（中文、英文、日语、韩语、德语、法语、俄语、葡萄牙语、西班牙语和意大利语）。
• ⚡ 集成加载：无需单独的加载节点；模型加载采用按需管理并结合全局缓存。
• ⏱️ 超低延迟：支持高保真语音重建与低延迟流式传输。
• 🧠 注意力机制选择：可从多种注意力实现（sage_attn、flash_attn、sdpa、eager）中选择，并具备自动检测与优雅回退功能。
• 💾 内存管理：生成完成后可选择卸载模型，以释放显存，适用于显存有限的用户。

节点列表

1. Qwen3-TTS 语音设计（VoiceDesignNode）

根据文本描述生成独特语音。

• 输入：
  • text：待合成的目标文本。
  • instruct：语音描述（例如：“温柔的女声，音调较高”）。
  • model_choice：目前语音设计功能仅支持 1.7B 模型。
  • attention：注意力机制（auto、sage_attn、flash_attn、sdpa、eager）。
  • unload_model_after_generate：生成完成后将模型从内存中卸载，以释放显存。
• 适用场景：最适合用于创建“想象中的”语音或特定角色原型。

2. Qwen3-TTS 语音克隆（VoiceCloneNode）

从参考音频片段克隆语音。

• 输入：
  • ref_audio：用于克隆的短音频片段（5–15秒）。
  • ref_text：参考音频中所包含的文本（有助于提升质量）。
  • target_text：希望克隆后的语音说出的新文本。
  • model_choice：可选择 0.6B（速度快）或 1.7B（质量高）。
  • attention：注意力机制（auto、sage_attn、flash_attn、sdpa、eager）。
  • unload_model_after_generate：生成完成后将模型从内存中卸载，以释放显存。
• 适用场景：从参考音频中提取语音特征并进行克隆。

3. Qwen3-TTS 自定义语音（CustomVoiceNode）

使用预设说话人进行标准 TTS 合成。

• 输入：
  • text：目标文本。
  • speaker：从预设语音中选择（Aiden、Eric、Serena 等）。
  • instruct：可选的风格指令。
  • attention：注意力机制（auto、sage_attn、flash_attn、sdpa、eager）。
  • unload_model_after_generate：生成完成后将模型从内存中卸载，以释放显存。
• 适用场景：使用预设语音进行常规语音合成。

4. Qwen3-TTS 角色库（RoleBankNode）[新]

收集并管理多个语音提示，用于对话生成。

• 输入：
  • 最多 8 个角色，每个角色包含：
    • role_name_N：角色名称（如“Alice”、“Bob”、“旁白”）。
    • prompt_N：来自 VoiceClonePromptNode 的语音克隆提示。
• 适用场景：为 DialogueInferenceNode 创建命名语音注册表。每个角色库最多支持 8 种不同语音。

5. Qwen3-TTS 语音克隆提示（VoiceClonePromptNode）[新]

从参考音频中提取并复用语音特征。

• 输入：
  • ref_audio：用于提取特征的短音频片段（5–15秒）。
  • ref_text：参考音频中所包含的文本（强烈推荐以提高质量）。
  • model_choice：可选择 0.6B（速度快）或 1.7B（质量高）。
  • attention：注意力机制（auto、sage_attn、flash_attn、sdpa、eager）。
  • unload_model_after_generate：生成完成后将模型从内存中卸载，以释放显存。
• 适用场景：一次性提取“提示项”，并在不同的 VoiceCloneNode 实例中多次使用，从而实现更快、更一致的生成效果。

6. Qwen3-TTS 多角色对话（DialogueInferenceNode）[新]

合成包含多名说话人的复杂对话。

• 输入：
  • script：对话脚本，格式为“角色名：文本”。
  • role_bank：来自 RoleBankNode 的包含语音提示的角色库。
  • model_choice：可选择 0.6B（速度快）或 1.7B（质量高）。
  • attention：注意力机制（auto、sage_attn、flash_attn、sdpa、eager）。
  • unload_model_after_generate：生成完成后将模型从内存中卸载，以释放显存。
  • pause_seconds：句子之间的静默时长。
  • merge_outputs：将所有对话片段合并为一段长音频。
  • batch_size：可并行处理的行数（数值越大速度越快，但显存消耗也越多）。
• 适用场景：在一个节点中完成多角色语音合成，非常适合有声书配音或角色扮演场景。

7. Qwen3-TTS 加载说话人（LoadSpeakerNode）[新]

无需任何配置即可加载已保存的语音特征和元数据。

• 适用场景：通过自动加载预先计算好的特征和元数据，实现“选择即播放”的体验。

8. Qwen3-TTS 保存语音（SaveVoiceNode）[新]

将提取的语音特征和元数据持久化到磁盘，以供未来使用。

• 适用场景：构建永久性的语音库，以便后续通过 LoadSpeakerNode 重复使用。

9. Qwen3-TTS 配置（QwenTTSConfigNode）[新功能]

定义标点符号的全局停顿时长，以控制语音节奏。

• 输入：
  • pause_linebreak：换行符后的静音时长。
  • period_pause：句号（.）后的静音时长。
  • comma_pause：逗号（,）后的静音时长。
  • question_pause：问号（?）后的静音时长。
  • hyphen_pause：连字符（-）后的静音时长。
• 用法：将输出连接到其他 TTS 节点的 config 输入端。

注意力机制

所有节点都支持多种注意力实现方式，并具备自动检测和优雅降级功能：

机制	描述	速度	安装方法
sage_attn	SAGE 注意力实现	⚡⚡⚡ 最快	pip install sage_attn
flash_attn	Flash Attention 2	⚡⚡ 快速	pip install flash_attn
sdpa	缩放点积注意力（PyTorch 内置）	⚡ 中速	内置（无需安装）
eager	标准注意力（回退选项）	🐢 最慢	内置（无需安装）
auto	自动选择最佳可用选项	变化	不适用

自动检测优先级

当选择 attention: "auto" 时，系统会按以下顺序检查：

1. sage_attn → 如果已安装，则使用 SAGE 注意力（最快）
2. flash_attn → 如果已安装，则使用 Flash Attention 2
3. sdpa → 始终可用（PyTorch 内置）
4. eager → 始终可用（回退选项，最慢）

所选机制会记录在控制台中，以确保透明性。

优雅降级

如果您选择的注意力机制不可用：

• 系统会回退到 sdpa（如果可用）
• 如果仍不可用，则回退到 eager（最后手段）
• 并会记录降级决策及警告信息。

模型缓存

• 模型会按注意力机制特定的键进行缓存。
• 更改注意力机制时，会自动清除缓存并重新加载模型。
• 使用不同注意力机制的同一模型可在缓存中共存。

内存管理

生成后卸载模型

所有节点均提供 unload_model_after_generate 切换开关：

• 启用：生成完成后清除模型缓存、GPU 内存并执行垃圾回收。
• 禁用：模型保留在缓存中，以便后续更快地生成（默认设置）。

适用场景：

• ✅ 如果显存有限（< 8GB），建议启用。
• ✅ 如果需要依次运行多个不同的模型，建议启用。
• ✅ 如果已完成生成并希望释放内存，建议启用。
• ❌ 如果使用同一模型生成多个片段，则建议禁用（速度更快）。

控制台输出：

🗑️ [Qwen3-TTS] 正在卸载 1 个缓存模型...
✅ [Qwen3-TTS] 模型缓存和 GPU 内存已清空

安装

请确保已安装所需依赖项：

pip install torch torchaudio transformers librosa accelerate

模型目录结构

ComfyUI-Qwen-TTS 会按照以下优先级自动搜索模型：

ComfyUI/
├── models/
│   └── qwen-tts/
│       ├── Qwen/Qwen3-TTS-12Hz-1.7B-Base/
│       ├── Qwen/Qwen3-TTS-12Hz-0.6B-Base/
│       ├── Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign/
│       ├── Qwen/Qwen3-TTS-Tokenizer-12Hz/
│       └── voices/（保存的预设 .wav/.qvp 文件）

注意：您也可以使用 extra_model_paths.yaml 来定义自定义模型路径：

qwen-tts: D:\MyModels\Qwen

最佳实践提示

音质

• 克隆：使用干净、无噪声的参考音频（5–15 秒）。
• 参考文本：提供参考音频中所说的文本可显著提升质量。
• 语言：选择正确的语言以获得最佳发音和韵律。

性能与内存

• 显存：使用 bf16 精度可在几乎不损失质量的情况下大幅节省显存。
• 注意力机制：使用 attention: "auto" 可自动选择最快的可用机制。
• 卸载模型：如果显存有限（< 8GB）或需要运行多个不同模型，建议启用 unload_model_after_generate。
• 本地模型：将权重预先下载到 models/qwen-tts/ 目录下，以优先从本地加载，避免 HuggingFace 超时。

注意力机制

• 最佳性能：安装 sage_attn 或 flash_attn 可使速度比 sdpa 提升 2–3 倍。
• 兼容性：使用 sdpa（默认）可获得最大兼容性，且无需安装。
• 低显存：对于其他机制可能导致 OOM 错误的小模型（0.6B），可使用 eager。

对话生成

• 批量大小：增加 batch_size 可加快生成速度（但会占用更多显存）。
• 停顿：调整 pause_seconds 可控制对话片段之间的时长。
• 合并：启用 merge_outputs 可生成连续对话；禁用则生成独立片段。

致谢

• Qwen3-TTS：阿里巴巴 Qwen 团队的官方开源仓库。

许可证

• 本项目采用 Apache License 2.0 许可证。
• 模型权重受 Qwen3-TTS 许可协议约束。

作者

• 哔哩哔哩：空间
• YouTube：频道

ComfyUI-Qwen-TTS 快速上手指南

ComfyUI-Qwen-TTS 是基于阿里通义千问团队开源的 Qwen3-TTS 项目开发的自定义节点，支持高质量语音合成、零样本声音克隆及基于自然语言描述的音色设计。

1. 环境准备

系统要求

• 操作系统: Windows, Linux, macOS (支持 MPS)
• Python: 建议 3.10+
• 显存 (VRAM):
  • 基础使用：≥ 6GB
  • 推荐配置：≥ 8GB (若显存小于 8GB，建议在节点中开启 unload_model_after_generate)
• 模型: 需下载 Qwen3-TTS 系列模型权重。

前置依赖

确保已安装基础 PyTorch 环境。在 ComfyUI 的虚拟环境中执行以下命令安装核心依赖：

pip install torch torchaudio transformers librosa accelerate

💡 国内加速建议： 如遇下载缓慢，推荐使用清华或阿里镜像源安装：

pip install torch torchaudio transformers librosa accelerate -i https://pypi.tuna.tsinghua.edu.cn/simple

可选依赖（性能加速）

为了获得更快的推理速度，建议安装以下注意力机制库（二选一即可，非必须）：

• SAGE Attention (最快): pip install sage_attn
• Flash Attention 2: pip install flash_attn

若未安装，系统将自动回退至 PyTorch 内置的 sdpa 模式，兼容性最好但速度稍慢。

---

2. 安装步骤

步骤一：安装自定义节点

在 ComfyUI 的 custom_nodes 目录下克隆本仓库：

cd ComfyUI/custom_nodes
git clone https://github.com/你的仓库地址/ComfyUI-Qwen-TTS.git

(注：请替换为实际的 GitHub 仓库地址，或通过 ComfyUI Manager 搜索 "ComfyUI-Qwen-TTS" 直接安装)

步骤二：部署模型权重

节点会自动在以下目录查找模型，请确保结构一致：

ComfyUI/models/qwen-tts/
├── Qwen/Qwen3-TTS-12Hz-1.7B-Base/       # 基础模型 (高质量)
├── Qwen/Qwen3-TTS-12Hz-0.6B-Base/       # 基础模型 (快速)
├── Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign/# 音色设计专用模型
└── Qwen/Qwen3-TTS-Tokenizer-12Hz/       # 分词器

💡 模型下载提示： 模型文件较大，建议通过 HuggingFace 镜像站或国内模型社区（如 ModelScope/魔搭）下载后放入上述目录，避免超时。 也可在 extra_model_paths.yaml 中配置自定义路径：

qwen-tts: D:\MyModels\Qwen

步骤三：重启 ComfyUI

安装完成后，重启 ComfyUI 以加载新节点。

---

3. 基本使用

以下是最简单的声音克隆工作流示例，只需 5-15 秒参考音频即可复刻音色。

工作流构建

1. 添加节点：Qwen3-TTS Voice Clone (VoiceCloneNode)
2. 连接输入：
   • ref_audio: 上传一段清晰的参考人声录音（wav/mp3，5-15 秒）。
   • ref_text: 输入参考音频中说的文字（强烈建议填写，可显著提升克隆质量）。
   • target_text: 输入你想要生成的新文本内容。
3. 参数设置：
   • model_choice: 选择 0.6B (速度快) 或 1.7B (音质好)。
   • attention: 保持 auto (自动选择最快可用方案)。
   • unload_model_after_generate: 显存紧张时勾选此项。
4. 连接输出：将节点的音频输出连接到 Save Audio 或直接预览。

进阶功能速览

• 音色设计: 使用 VoiceDesignNode，输入描述（如“温柔的女声，音调较高”）即可创造虚拟角色声音。
• 多角色对话: 组合使用 RoleBankNode + DialogueInferenceNode，可一次性生成长篇多人对话广播剧。
• 音色保存: 使用 SaveVoiceNode 提取特征并保存，后续通过 LoadSpeakerNode 一键加载，无需重复处理参考音频。

运行示例

点击 "Queue Prompt" 开始生成。首次运行时会下载/加载模型，后续生成将利用缓存大幅提速。