YuE2歌曲生成模型ComfyUI节点工作流与INT8量化教程

本教程是《YuE2歌曲生成模型Windows本地部署完整教程》的续篇。前一篇教程用 ComfyUI 便携包的嵌入式 Python 环境运行官方 yue2_infer 推理管线，实测需要 22GB 显存才能舒服跑通。本教程给出另一条路线：直接用 ComfyUI 官方 YuE2 节点 + INT8 量化模型，把显存门槛降到 8GB（RTX 30 系主流显卡），生成过程全程在 ComfyUI 节点画布内完成，可与其他 ComfyUI 工作流任意组合。实战案例为原创歌曲《盼静无风》，本教程的所有结论都来自 RTX 2080 Ti（22GB）上的实测，并在文末给出 8GB 显卡的迁移要点。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

• YuE2歌曲生成模型Windows本地部署完整教程，YuE2 的模型原理、三阶段生成流水线、ABC 乐谱玩法都在那篇讲透，本教程不再重复，直接进入 ComfyUI 路线。
• ComfyUI本地部署MiniMax H3消费级显卡文生视频、图生视频教程，ComfyUI 便携整合包的下载与安装方法。

资源下载

• YuE2 INT8 量化模型网盘地址，ComfyUI 官方重打包的 YuE2-3B INT8 量化单文件模型（约 3.7GB），下载后放入模型目录即可使用，放置方法见 2.3 节。
• ComfyUI 官方 YuE2 工作流模板 audio_yue2_text2music.json，ComfyUI 0.37 以上版本已内置该模板，此链接仅供需要单独获取模板文件的读者备选。

1. 方案概览

1.1 两条路线怎么选

同一个 YuE2-3B 模型，前教程与本教程是两条独立的部署路线，按你的显存与使用场景对号入座：

一句话结论：显存够、追求速度与全套产物，用前教程的 Python 管线；显存 8~12GB、想在 ComfyUI 里一键成歌，用本教程。

1.2 ComfyUI 官方 YuE2 支持

ComfyUI 从 0.37.0 版本起内置了三个 YuE2 原生节点（comfy_extras/nodes_yue2.py），与 Comfy-Org 发布的单文件重打包模型配套：

注意与前教程的差异：ComfyUI 把「LLM 出乐谱和条件」与「FLOW 模型采样音频 latent」拆成了节点 + 通用 KSampler 的组合，VAE 解码用通用的 VAE Decode Audio 节点。这个架构差异正是本教程第 5 章几个大坑的来源。

1.3 模型文件与显存账本

Comfy-Org/YuE2 仓库提供三种单文件格式，选型依据如下：

INT8 单文件在 ComfyUI 里的显存开销（2080 Ti 实测日志）：AR 模型（LLM 侧）约 2.1GB、FLOW 模型约 1.4GB、VAE 约 1.4GB，三者合计约 3.4GB 全显存驻留，加上采样激活与 KV 缓存，8GB 显卡有约 4GB 余量，ComfyUI 自带的显存管理（不够时自动分阶段搬运）是兜底保险。

INT8 文件的元数据里写着 source: m-a-p/YuE2-3B, vae_source: YuE2-Vae, license: CC-BY-NC-4.0——权重与官方仓库同源，只是按 ComfyUI 的单文件格式重打包并做了 convrot INT8 量化。非商业许可与前教程一致。

2. 环境准备

2.1 硬件与软件清单

2.2 升级 ComfyUI 到 0.37 以上

YuE2 节点是 0.37.0 才内置的，老版本便携包先升级。双击便携包根目录的 update\update_comfyui.bat，完成后确认版本：

type ComfyUI\comfyui_version.py

输出 __version__ = "0.37.0"（或更高）即可。升级不会影响已装的模型与自定义节点。

2.3 下载 INT8 模型

从本教程资源下载区的网盘地址下载 yue2_3b_int8_convrot.safetensors（约 3.7GB）。模型按前教程的惯例集中放在 C:\models 下，下载完成后放入 checkpoints 子目录，目录结构如下：

C:\models\YuE2
└── checkpoints
    └── yue2_3b_int8_convrot.safetensors    3.7GB，本教程唯一需要的模型文件

下载完成后核对文件体积应为 3,960,938,800 字节（约 3.7GB）。网盘或浏览器下载中断时，续传或重新下载后同样以该体积核对完整性。

2.4 把模型目录接入 ComfyUI

ComfyUI 通过 extra_model_paths.yaml 认识 C:\models 下的模型。打开便携包根目录 ComfyUI\extra_model_paths.yaml（没有就新建），追加一节：

yue2_models:
    base_path: C:\models\YuE2
    checkpoints: checkpoints

含义是：把 C:\models\YuE2\checkpoints 注册为 ComfyUI 的 checkpoints 模型目录。如果你在用前教程的 Qwen-Image 等其他条目，直接在文件末尾另起一节即可，互不影响。改完必须重启 ComfyUI（yaml 只在启动时加载一次）。

2.5 验证模型可见

启动 ComfyUI（便携包根目录的 run_nvidia_gpu.bat），浏览器打开 http://127.0.0.1:8188，双击画布搜索 CheckpointLoaderSimple（Load Checkpoint）节点，点开 ckpt_name 下拉框，能看到 yue2_3b_int8_convrot.safetensors 即接入成功。

3. 生成第一首歌

3.1 用官方工作流模板（推荐路线）

ComfyUI 0.37+ 内置了官方 YuE2 模板：菜单 Workflow → Browse Templates → Audio 分类下的 YuE2: Text to Music。打开后是一个名为 Text to Music (YuE2) 的子图，双击进入可以看到完整节点链。模板默认加载的就是 INT8 文件，改三个地方就能出歌：

1. YuE2 Generate ABC 节点：填入 style（英文风格描述）与 lyrics（带 [Verse] [Chorus] 等结构标签的歌词），写法与前教程 3.4 节完全一致；
2. YuE2 Generate Music 节点：max_duration 设为目标时长上限（单位秒）；
3. Seed：换种子重跑是调整效果的第一手段。

点击 Queue 运行。以下是在 2080 Ti 上的实测耗时，供预估你自己机器：

3.2 节点链路解析（手搭工作流必读）

模板虽好，但想把链路拆开自定义（比如用 API 提交、把乐谱换成外部编辑过的 ABC），必须理解六个节点的标准接线。注意与官方模板子图严格一致，尤其不能漏掉 KSampler：

三个最容易踩错的接点：

• KSampler 是必选节点。YuE2GenerateMusic 只产出 conditioning（乐谱 + 语义条件），把音频 latent 真正「画」出来的是 KSampler 调用 FLOW 模型。漏接 KSampler、让空 latent 直通 VAE，输出的是一段恒定的低频嗡嗡声（实测主峰 77Hz + 154Hz），听起来像电流声——这是本教程实测踩过的最大坑，详见 5.1 节。
• KSampler 参数照抄官方模板：steps=32、cfg=1.0、sampler=dpm_2、scheduler=sgm_uniform、denoise=1.0；负条件用 ConditioningZeroOut 接 YuE2GenerateMusic 的输出（cfg=1 时负条件不参与计算，但节点要求必须接）。
• 解码必须用 VAE Decode Audio（VAEDecodeAudio）。通用的 VAE Decode 输出的是 IMAGE 类型，接到 Save Audio 上会在提交时直接报 Return type mismatch 校验错误。

3.3 关键参数说明

启动参数方面，本教程实测 --use-ck-attention（comfy kitchen 加速）与 --fp16-unet、--disable-dynamic-vram 等常用开关对 YuE2 输出没有任何影响（开/关两次 ABC 生成逐字节一致），可按你其他工作流的需要自由保留。

3.4 试听与格式转换

产物在 ComfyUI\output\audio\ 下，浏览器直接访问 http://127.0.0.1:8188/view?filename=文件名&type=output&subfolder=audio 可在线试听。发朋友圈/网盘建议转 MP3（FLAC 4 分半约 27MB，320kbps MP3 约 9MB），装了 ffmpeg 的话一条命令：

ffmpeg -y -i audio.flac -codec:a libmp3lame -b:a 320k audio.mp3

3.5 对生成质量的正确预期

本教程实测有一个重要的经验：不要用几十秒的短样本评判质量。max_duration 压到 5~30 秒时，语义生成会在顶满预算后被硬截断（日志出现 reached its token budget 警告属正常），产出的是一段安静稀疏的「半截前奏」，两套引擎都一样难听。完整的歌（3~5 分钟）才能体现真实水平：本教程在 22GB 卡上用同一份歌词、风格、种子分别跑了 INT8 全曲与 BF16 全曲，修正统计口径后两者与官方管线的历史成歌在频谱结构上互相接近（质心 409~597Hz、谐波帧占比 57~59%），没有可测的系统性差距。

4. 进阶：API 提交与配方复用

4.1 为什么用 API

节点画布适合手动调整，批量生产或程序化调用更适合走 ComfyUI 的 HTTP API（POST /prompt）。把 3.2 节的六节点链写成 JSON 提交，即可脱离画布自动生成。完整可用的工作流 JSON 如下（可直接保存为 submit_yue2.py 运行，依赖仅标准库）：

import json
import sys
import urllib.request

BASE = 'http://127.0.0.1:8188'

# 换成你的 style 与歌词（同前教程 request.json 的写法）
style = "Mandarin folk pop ballad, mid-tempo 84 BPM, B-flat major, acoustic guitar arpeggios, warm piano, soft orchestral strings, breathy emotive male vocal"
lyrics = "[Intro]\n\n[Verse]\n你的主歌歌词\n\n[Chorus]\n你的副歌歌词"
seed = 60966

prompt = {
    "1": {"class_type": "CheckpointLoaderSimple", "inputs": {"ckpt_name": "yue2_3b_int8_convrot.safetensors"}},
    "2": {"class_type": "YuE2GenerateABC", "inputs": {
        "clip": ["1", 1], "style": style, "lyrics": lyrics,
        "seed": seed, "mode": "full", "max_abc_tokens": 8192,
        "temperature": 0.7, "top_p": 0.9, "top_k": 30,
        "repetition_penalty": 1.005, "penalty_window": 100}},
    "3": {"class_type": "YuE2GenerateMusic", "inputs": {
        "clip": ["1", 1], "style": style, "lyrics": lyrics, "abc": ["2", 0],
        "seed": seed, "mode": "full", "max_duration": 270.0,
        "temperature": 1.0, "top_p": 0.95, "top_k": 100, "repetition_penalty": 1.2}},
    "18": {"class_type": "ConditioningZeroOut", "inputs": {"conditioning": ["3", 0]}},
    "4": {"class_type": "EmptyYuE2LatentAudio", "inputs": {"seconds": ["3", 1], "batch_size": 1}},
    "8": {"class_type": "KSampler", "inputs": {
        "model": ["1", 0], "positive": ["3", 0], "negative": ["18", 0],
        "latent_image": ["4", 0],
        "seed": seed, "steps": 32, "cfg": 1.0, "sampler_name": "dpm_2",
        "scheduler": "sgm_uniform", "denoise": 1.0}},
    "5": {"class_type": "VAEDecodeAudio", "inputs": {"samples": ["8", 0], "vae": ["1", 2]}},
    "6": {"class_type": "SaveAudioAdvanced", "inputs": {
        "audio": ["5", 0], "filename_prefix": "audio/YuE2-song", "format": "flac"}},
}

data = json.dumps({"prompt": prompt, "client_id": "tutorial"}).encode('utf-8')
r = urllib.request.urlopen(urllib.request.Request(BASE + '/prompt', data=data,
                       headers={'Content-Type': 'application/json'}), timeout=60)
print(r.read().decode())   # 返回 prompt_id，用于后续查进度

4.2 查询进度与取回产物

提交返回的 prompt_id 用于查询状态，完成后从 history 里拿文件名：

# 查询是否完成
curl http://127.0.0.1:8188/history/<prompt_id>

# 产物固定在 ComfyUI\output\audio\ 下，文件名形如 YuE2-song_00001.flac

4.3 复用前教程的 request.json 配方

前教程的每次生成都会落盘 request.json（风格、歌词、种子、乐谱的权威来源）。把它回填到 4.1 的脚本里，就能在 ComfyUI 里复现同一首歌的「同配方新演唱」；若把其中的 abc 字段（外部乐谱）填进 YuE2GenerateMusic 的 abc 输入、并把 ABC 节点断开，还能实现前教程 4.2 节的「锁定旋律换演绎」玩法。

5. 排坑实录

本章是本教程最值钱的部分，全部来自 2026 年 10 月实测踩坑过程，按坑的严重程度排序。

5.1 输出是持续电流声/低频嗡嗡声：工作流漏了 KSampler

现象：生成顺利完成、文件时长正常，但播放全是恒定的低频电流声，且与种子、参数无关。

原因：YuE2GenerateMusic 输出的是 conditioning，不是音频；空 latent（全零张量）没有经过 KSampler 的 FLOW 采样就直通 VAE。VAE 解码全零 latent 的输出就是一段确定性低频嗡嗡声（实测主峰 77Hz + 154Hz、恒定包络）。

验证方法：对输出做频谱分析，若主峰恒为 77/154Hz、逐段 RMS 完全一致（本教程实测每 10 秒块 RMS 均为 0.126），即可确认。解法：按 3.2 节补上 KSampler 与 ConditioningZeroOut 的标准接线。

5.2 提交报 Return type mismatch：用错了解码节点

现象：API 提交返回 prompt_outputs_failed_validation，细节为 audio, received_type(IMAGE) mismatch input_type(AUDIO)。

原因：接了通用 VAEDecode（图像解码器）。YuE2 的音频 latent 要用 VAEDecodeAudio。

5.3 短样本难听：截断探针的形态问题

现象：max_duration 设 5~30 秒时，输出是安静、稀疏、没有演唱的片段。

原因：语义生成顶满预算被硬截断（正常现象），短音频只够模型铺前奏。解法：完整时长（3 分钟以上）再评判质量；服务器日志里 YuE2 semantic reached its token budget 是预期警告，不是错误。

5.4 INT8 音质与速度的实测结论

• 音质：同配方对比 INT8 全曲、BF16 全曲与官方管线历史成歌，频谱质心、谐波结构占比互相接近，没有可测的系统性劣化。听感上的个别不满意先换种子重跑，再考虑换精度。
• 速度：INT8 convrot 算子在 Turing（RTX 20 系）上反而比 fp16 直接推理慢（实测音乐采样 4.4 token/s vs 12.35 token/s）。但 8GB 显卡装不下 BF16 全量权重（7.8GB），INT8 仍是 8G 卡的现实选择；RTX 30 系（Ampere）以上的 INT8 吞吐表现会好于 Turing，本教程的 4.4 token/s 可作为保守下限。
• 收尾：INT8 实测语义顶满 max_duration 预算才停（4:30 上限出 4:30 的歌），BF16 实测会自然吐结束符提前收尾（4:03）。对收尾干净度敏感时，把 max_duration 设得比预期成歌长度短 10~20 秒。

5.5 显存与加载

• 8GB 显卡建议保持 ComfyUI 默认的显存管理模式，不要加 --disable-dynamic-vram；若极端场景 OOM，追加 --lowvram 启动。
• 模型目录改了 extra_model_paths.yaml 后必须重启 ComfyUI 才生效。
• 检查 INT8 文件完整性：体积应为 3,960,938,800 字节；下载中断时续传或重新下载，完成后同样以该体积核对。

6. 总结

6.1 核心内容回顾

• ComfyUI 0.37+ 内置 YuE2 官方节点，配合 Comfy-Org 的 INT8 单文件（3.7GB），把 YuE2 的显存门槛从 22GB 降到 8GB，全程无需安装任何额外依赖。
• 标准链路六节点：CheckpointLoaderSimple → YuE2GenerateABC → YuE2GenerateMusic → ConditioningZeroOut → KSampler（steps=32/cfg=1/dpm_2/sgm_uniform）→ VAEDecodeAudio → SaveAudioAdvanced；KSampler 是最容易漏掉、漏掉必出电流声的一环。
• max_duration 是生成时长的硬上限，短样本是截断前奏，不能用于质量评判。
• 实测（2080 Ti，INT8）：4 分半歌曲约 33 分钟；修正统计口径后音质与官方管线无系统性差异。
• API 路线（POST /prompt + 六节点 JSON）适合批量生产与前教程 request.json 配方复用。

6.2 常见问题与解答

问：8GB 显卡实际没验证过，靠谱吗？

答：本教程的显存账本来自 2080 Ti 的加载日志：INT8 三块权重共约 3.4GB 全显存驻留 + 激活，8GB 卡理论余量约 4GB，且 ComfyUI 有自动 offload 兜底。30 系显卡的 INT8 吞吐也会好于本教程 Turing 的保守值。如果你在 8G 卡上跑出了实测数据，欢迎在评论区补充。

问：BF16 单文件和前教程的官方原版模型是同一个东西吗？

答：权重同源（元数据标注 source: m-a-p/YuE2-3B），但按 ComfyUI 单文件格式重打包：键名按 LLM/FLOW 角色拆进 text_encoders.* 与 model.diffusion_model.* 两个命名空间、tokenizer 内嵌、VAE 打包进同文件。官方原版散装文件不能直接放进 ComfyUI 使用，本教程的转换成本远高于直接下重打包版。

问：为什么生成的歌和官方管线同配方结果不一样？

答：同种子同配方只保证「同一份创作方案」，不同引擎的实现差异（ABC 预算、采样器实现）会带来不同的演绎版本，属于预期行为，不是故障。想要逐比特复刻只能用同一套引擎重跑。

问：能出 MP3 吗？

答：Save Audio Advanced 节点的 format 可选 mp3 直接输出；已有 FLAC 用 ffmpeg 转（见 3.4 节）。

问：商用许可有变化吗？

答：没有。INT8/BF16 重打包文件的元数据均标注 license: CC-BY-NC-4.0，与前教程的结论一致：学习研究个人创作可用，商用需授权。

问：参考音频翻唱功能怎么用？

答：需要额外下载 audio_encoders/sheetsage2_bf16.safetensors（1.3GB）放入 models/audio_encoders 目录，并使用官方的 Music Cover 模板（Browse Templates → Audio → YuE2: Music Cover），其内部会把参考音频编码为条件注入。本教程的文生歌链路用不到它。