YuE2 for ComfyUI 模型包安装与使用指南：Text-to-Music 与 Music Cover 工作流实战-平芜编程栈

人工智能
音乐生成
音频
媒体生成
大模型

【免费下载链接】Yue2

项目地址：https://ai.gitcode.com/hf_mirrors/Comfy-Org/Yue2

本指南面向 ComfyUI 用户，系统讲解如何在本地 ComfyUI 中安装并启用 YuE2 音乐生成模型包：从模型文件构成、目录放置规则、变体选择，到官方 Music Cover 与 Text to Music 工作流的加载与使用。读完本文，你将能够独立完成 YuE2 模型包（YuE2-3B 主模型 + SheetSage2 音频编码器）的部署，并在 ComfyUI 中通过工作流模板运行音乐生成与音乐翻唱任务。

YuE2 模型包是什么

根据仓库 README.md 的说明，本仓库的定位是Repackaged model files for ComfyUI——即为 ComfyUI 重新打包整理的模型文件发布仓库，其元数据声明如下：

license:cc-by-nc-4.0（非商业用途许可）
tags:comfyui、diffusion-single-file（面向 ComfyUI 的扩散模型单文件格式）
base_model:m-a-p/YuE2-3B、m-a-p/SheetSage2

模型包由两部分组成：

YuE2-3B：约 30 亿参数级别的主干模型（checkpoint），从模型命名与工作流用途可以推断，它承担音乐生成（文本生成音乐）与音乐翻唱（music cover）的扩散主干任务；
SheetSage2：配套的音频编码器（audio encoder），按 ComfyUI 目录约定放置在models/audio_encoders/下，负责音频信号与模型内部表示之间的编解码。

从仓库提供的工作流模板（Music Cover 与 Text to Music）可以确认，该模型包的核心应用场景是音乐生成与音乐翻唱两条创作管线。

仓库文件清单与模型角色

当前仓库根目录下的模型文件清单如下（实际内容由 Git LFS 托管，括号内为 LFS 指针记录的完整文件大小）：

文件（仓库相对路径）	模型角色	精度/变体	完整文件大小
checkpoints/yue2_3b_bf16.safetensors	YuE2-3B 主干 checkpoint	bf16	约 7.80 GB
checkpoints/yue2_3b_int8_convrot.safetensors	YuE2-3B 主干 checkpoint	int8 量化 + convrot	约 3.96 GB
audio_encoders/sheetsage2_bf16.safetensors	SheetSage2 音频编码器	bf16	约 1.39 GB

其中yue2_3b_bf16.safetensors与yue2_3b_int8_convrot.safetensors是两个可选的主干模型变体：

bf16 变体：以 bfloat16 精度保存的完整版本，文件约 7.80 GB（LFS 记录精确字节数 7,799,983,228），通常提供更高的数值精度；
int8_convrot 变体：从文件名可以推断，这是经过int8 量化、并带有convrot（卷积旋转位置编码）处理的低内存版本，文件约 3.96 GB（精确字节数 3,960,938,800），约为 bf16 变体的一半，适合显存与内存相对受限的运行环境。

需要强调的是，两个变体都属于 YuE2-3B 主干模型，放置时共用同一个models/checkpoints/目录，按需选择其一加载即可。

安装：把文件放到 ComfyUI 的 models 目录

标准目录结构

README 明确给出了文件放置规则——必须与 ComfyUI 默认的模型目录约定完全一致：

📂 ComfyUI/ └── 📂 models/ ├── 📂 audio_encoders/ │ └── sheetsage2_bf16.safetensors └── 📂 checkpoints/ └── yue2_3b_bf16.safetensors

也就是说，SheetSage2 音频编码器必须放在models/audio_encoders/，YuE2-3B 主干 checkpoint 必须放在models/checkpoints/。ComfyUI 会按模型类型从这些约定目录加载文件，路径错位将导致工作流中无法识别模型。

获取模型文件

仓库中的.safetensors文件由 Git LFS 托管（这一点从文件内容可以确认，详见后文"源码级验证"一节），因此拉取文件需要两步：

git clone https://gitcode.com/hf_mirrors/Comfy-Org/Yue2 cd Yue2 git lfs pull

git lfs pull会依据仓库内的 LFS 指针把完整的模型文件下载到本地（若已安装 Git LFS 扩展）。也可以直接从原始模型仓库m-a-p/YuE2-3B与m-a-p/SheetSage2分别获取对应文件，再按上述目录结构放置。

变体选择建议

默认推荐：将yue2_3b_bf16.safetensors放入models/checkpoints/，它与 SheetSage2 音频编码器同为 bf16 精度，组合总大小约9.19 GB；
低内存环境：若显存/内存紧张，可改用yue2_3b_int8_convrot.safetensors（约 3.96 GB），与音频编码器组合约5.35 GB，以较小的模型体积换取更低的资源占用（从文件大小对比可以推断其量化降耗效果）。

安装后自检

模型放入后，可通过文件大小快速自检是否下载完整。LFS 指针中记录的完整大小可作为校验基准：yue2_3b_bf16.safetensors应为 7,799,983,228 字节，yue2_3b_int8_convrot.safetensors应为 3,960,938,800 字节，sheetsage2_bf16.safetensors应为 1,386,868,122 字节。若本地文件远小于上述数值，说明仍停留在 LFS 指针阶段，需要执行git lfs pull。

使用：加载 YuE2 工作流

README 提供了两个与 YuE2 配套的 ComfyUI 官方工作流模板（由 Comfy-Org 的 workflow_templates 仓库维护），文件名与用途如下：

工作流模板文件	用途
`audio_yue2_music_cover.json`	YuE2: Music Cover（音乐翻唱）
`audio_yue2_text2music.json`	YuE2: Text to Music（文本生成音乐）

在 ComfyUI 中，可以通过内置的工作流模板（Workflow Templates）入口检索并加载这两个模板。加载后，工作流会引用位于models/checkpoints/的 YuE2-3B 主干模型与位于models/audio_encoders/的 SheetSage2 编码器——因此务必先完成上一节的目录放置，再加载工作流。

Text to Music（文本生成音乐）：以自然语言文本描述（如风格、情绪、乐器、结构等）为输入，生成对应的音乐片段；
Music Cover（音乐翻唱）：以已有音频为输入，结合文本指令对歌曲进行翻唱/改编创作。

实际运行前，建议先确认 ComfyUI 版本与工作流模板所需节点兼容，首次执行时模型加载与推理耗时会明显偏长（属于正常现象）。

源码级验证：LFS 指针与模型文件事实

仓库内的模型文件在 Git 层面实际上是Git LFS 指针文件（135 字节的纯文本），而不是完整的二进制模型。以 checkpoints/yue2_3b_bf16.safetensors 为例，其内容为：

version https://git-lfs.github.com/spec/v1 oid sha256:33765adbf9813c9a50318218760b2fd819a319862460a04884607581961c6fee size 7799983228

其中：

oid sha256：完整文件的 SHA-256 摘要，用于校验下载内容的完整性；
size：完整文件的字节大小，可用作自检依据。

三个文件（audio_encoders/一个、checkpoints/两个）均为该 LFS 指针格式，这解释了为何仓库目录在磁盘上只占几十 KB——完整的模型本体需通过 Git LFS 拉取后才会出现在本地。

同时，从目录结构可以印证 ComfyUI 的模型分类加载约定：audio_encoders/承载音频编码器类模型，checkpoints/承载扩散主干 checkpoint，两者与 README.md 中规定的放置规则一一对应，工作流节点正是按这些目录约定查找模型文件的。

使用注意与边界

许可协议：模型包采用cc-by-nc-4.0许可，仅限非商业用途，商用前需另行确认授权；
磁盘空间：完整拉取三个文件约需13.15 GB磁盘空间；仅部署 bf16 组合约 9.19 GB，int8 组合约 5.35 GB；
首次运行：第一次加载模型会执行权重载入与初始化，耗时长属正常；int8 变体的量化方式与 convrot 位置编码属于该变体特有的实现细节，具体行为以实际加载与推理输出为准；
本文所述的一切文件路径与模型信息均以当前仓库实际内容为准，模型能力、输出质量与硬件适配请以自身运行结果为准，不宜将仓库外的第三方评测结论当作本项目事实。