YuE2歌曲生成模型Windows本地部署完整教程

本教程系统讲解如何在 Windows 系统上本地部署 YuE2-3B 音乐生成模型，并完成从环境搭建、冒烟测试到完整成歌的全流程。YuE2-3B 是 m-a-p 团队开源的歌曲生成模型，输入一段风格描述和歌词，即可输出带人声与伴奏的完整歌曲（48kHz 立体声），音质对标 Suno v5/v6。官方仅提供 Linux 环境的部署指引，本教程借助 ComfyUI 便携整合包的嵌入式 Python 环境在 Windows 上完成部署，并覆盖 YuE2 最具特色的 ABC 乐谱编辑与旋律复用玩法，实战案例为原创歌曲《今夜不眠》。

前置教程

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

• ComfyUI本地部署MiniMax H3消费级显卡文生视频、图生视频教程，讲解 ComfyUI 便携整合包的下载与安装方法，本教程复用其嵌入式 Python 环境来运行 YuE2。
• PyTorch安装与版本选择问题详解，理解 CUDA 版 PyTorch 与显卡驱动的对应关系，便于排查部署中的环境问题。
• TTS模型服务调用与本地部署教程，同为音频生成类模型的部署实践，可对照理解语音合成与歌曲生成的差异。

资源下载

• YuE2 模型整合包网盘地址，包含 YuE2-3B 主模型（约 6.8GB）与 YuE2-Vae 解码器（约 507MB）两个完整文件夹。
• yue2-song 示例代码网盘地址，本教程配套的生成脚本与两份提示词示例。
• 《今夜不眠》成歌试听网盘地址，本教程实战案例的输出成果，可先试听再决定是否部署。

1. YuE2 模型与生成原理

1.1 什么是 YuE2-3B

YuE2-3B 是开源团队 m-a-p（multimodal-art-projection）发布的开源音乐生成模型，任务是「歌词 + 风格提示词 → 完整歌曲」。它直接输出48kHz 采样率的立体声音频，包含人声演唱与器乐伴奏，支持中文与英文歌词，官方基准显示其歌曲质量可与 Suno v5/v6 对标。模型权重采用 CC BY-NC 4.0 协议发布，允许学习和研究使用，商用需要另行授权。

与上一代 YuE 相比，YuE2 最突出的变化是引入了可编辑乐谱（ABC 记谱）：模型在生成音频之前，会先规划出一份包含旋律与和弦的乐谱文件 score.abc。这份乐谱既可以由模型自动生成，也可以由人工或 AI 编辑后回填，让「改旋律、换和弦、保留副歌」这类精细化控制成为可能，具体玩法见本教程第 4 章。

部署 YuE2 需要两个模型组件，均放在模型仓库中发布：

YuE2-3B 仓库内还附带 yue2_infer 推理包的安装轮子（yue2_infer-0.1.5-py3-none-any.whl），以及官方示例提示词 examples/tonight-awake.json，本教程都会直接使用。

1.2 三阶段生成流水线

YuE2 的单次生成由四个环节串联完成，理解这条流水线有助于后续排查生成慢、显存占用高等问题：

• 符号规划（ABC 阶段）：模型先把「风格 + 歌词」翻译成一份 ABC 记谱乐谱，确定旋律走向、和弦进行与段落结构（如 [Verse]、[Chorus] 的排布）。这一步的产物就是后续可编辑的 score.abc。
• 语义 token 生成（AR 阶段）：以乐谱为条件，自回归地逐 token 生成歌曲的语义表示。这是整条流水线中最耗时的一环，本教程实测约占全程一半以上时间。
• 声学生成（NAR 阶段）：把语义表示并行地扩展为精细的音频潜变量，属于非自回归生成，速度与音频长度相关。
• VAE 解码：YuE2-Vae 把音频潜变量一次性解码为 48kHz 立体声波形，写入 audio.flac。

YuE2 提供三种 CoT（思维链）模式控制符号规划的行为：

1.3 官方环境要求与本教程方案

YuE2 官方给出的运行环境是 Linux、Python 3.10 以上、24GB 显存且支持 BF16 的 NVIDIA 显卡。多数 Windows 用户的条件与该要求存在差距，本教程的部署方案正是为弥合这一差距设计的，思路概括为一句话：借用 ComfyUI 便携整合包的嵌入式 Python 环境来运行 YuE2 推理包。

ComfyUI 便携整合包自带一套完整可用的 CUDA 版 PyTorch 环境（python_embeded 目录，本教程实测版本为 Python 3.13.14 + torch 2.13.0+cu130），无需安装 Python 或 Conda 即可直接运行推理脚本。YuE2 的依赖则安装到独立的 YuE2env 目录中，与 ComfyUI 本体的依赖完全隔离，互不污染。

关于显卡，有两点实测结论值得说明：

• Turing 架构显卡（RTX 20 系）可以运行。yue2_infer 推理包会自动检测显卡架构：计算能力 8.0 以上（RTX 30/40 系）使用 BF16，7.x（RTX 20 系及更早）自动回退到 FP16，本教程即在 22GB 显存的 RTX 2080 Ti 上完整跑通。
• 显存预算可调。推理包提供 memory_budget_gib 参数控制显存预算（默认 24），预算不超过 12GB 时会自动切换更小的 VAE 分块尺寸。本教程在 22GB 显存上验证，更低显存的显卡可以尝试调低该参数，但本文未对低显存配置做验证。

ComfyUI 本体在本方案中只承担「提供 Python 运行环境」的角色，生成过程不经过 ComfyUI 的节点画布，ComfyUI 自身的功能与依赖不受任何影响。如果你已经在用 ComfyUI 部署其他模型，本方案可以直接叠加；如果你尚未安装 ComfyUI 便携包，请先完成前置教程中的安装章节。

2. 环境准备

2.1 硬件与软件清单

ComfyUI 便携包的下载与安装方法见前置教程，下载后解压即可使用，本教程后续所有命令都在便携包根目录（即 python_embeded 文件夹所在目录）执行。

2.2 下载模型并放置到固定目录

推荐使用资源下载区的模型整合包网盘地址：下载 YuE2-3B.zip（约 6.3GB），解压后得到 YuE2-3B 与 YuE2-Vae 两个文件夹，把它们整体移动到 C:\models 目录下（压缩包文件名虽只写了 YuE2-3B，实际内含两个模型文件夹）。

不方便使用网盘时，也可以从官方仓库命令行下载到相同位置：

pip install -U huggingface-hub
hf download m-a-p/YuE2-3B --local-dir C:\models\YuE2-3B
hf download m-a-p/YuE2-Vae --local-dir C:\models\YuE2-Vae

无论哪种方式，放置完成后核对目录结构，关键文件如下：

C:\models\YuE2-3B
├── model.safetensors          主模型权重（约 6.8GB）
├── config.json                模型结构配置
├── modeling_yue2.py           模型结构定义代码
├── qwen.tiktoken              分词器词表
├── generation_config.json     生成默认参数
├── yue2_infer-0.1.5-py3-none-any.whl    推理包安装轮子
└── examples\tonight-awake.json          官方示例提示词

C:\models\YuE2-Vae
├── model.safetensors          VAE 权重（约 507MB）
├── config.json
└── modeling_vae.py

模型整合包约 7.3GB，解压前留意磁盘剩余空间。yue2_infer 推理包安装轮子随 YuE2-3B 文件夹一并附带，无需单独下载。

2.3 安装 yue2-infer 推理包到隔离目录

YuE2 的推理依赖与 ComfyUI 本体的依赖存在版本差异，直接装进 ComfyUI 的 site-packages 可能破坏 ComfyUI 本身。正确做法是把推理包装进独立的 YuE2env 文件夹，运行脚本时再临时把这个文件夹放到模块搜索路径的最前面。

打开命令提示符（按 Win+R 输入 cmd），切换到 ComfyUI 便携包根目录，依次执行：

cd /d D:\ComfyUI_windows_portable

# 安装 YuE2 推理包本体（不解析依赖，避免拉入与嵌入环境冲突的 torch 版本）
python_embeded\python.exe -m pip install --target=YuE2env --no-deps C:\models\YuE2-3B\yue2_infer-0.1.5-py3-none-any.whl

# 补齐三个嵌入环境缺失的纯 Python 依赖
python_embeded\python.exe -m pip install --target=YuE2env --no-deps "transformers==4.57.6" soundfile accelerate

三条命令都执行完后，YuE2env 文件夹内应有如下内容（dist-info 结尾的是包元数据目录）：

YuE2env
├── yue2                       推理包主体
├── yue2_infer-0.1.5.dist-info
├── transformers               4.57.6
├── transformers-4.57.6.dist-info
├── soundfile                  音频读写库
├── soundfile-0.14.0.dist-info
├── accelerate                 模型加载加速
└── accelerate-1.15.0.dist-info

其余依赖（torch、numpy、tiktoken、safetensors、huggingface-hub）全部复用 python_embeded 自带的版本，无需额外安装。执行以下命令验证推理包可用：

python_embeded\python.exe -c "import sys; sys.path.insert(0, 'YuE2env'); from yue2 import YuE2Pipeline; import importlib.metadata as m; print('yue2-infer', m.version('yue2-infer'))"

输出 yue2-infer 0.1.5 即安装成功。

安装命令中的 --no-deps 参数是本步骤的关键。yue2_infer 轮子声明的依赖锁定 torch==2.10.0，若让 pip 自动解析依赖，它会把另一套 torch 装进 YuE2env，既浪费数 GB 磁盘又可能与嵌入环境的 CUDA 版本不匹配。跳过依赖解析、由嵌入环境提供 torch，是便携包场景下最干净的组合方式。

2.4 验证 GPU 与 PyTorch 环境

继续在便携包根目录执行：

python_embeded\python.exe -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0))"

正常输出类似 2.13.0+cu130 True NVIDIA GeForce RTX 2080 Ti，三项分别代表 torch 版本、CUDA 可用、显卡型号。若 cuda 项为 False，通常是显卡驱动过旧，先更新驱动再继续。

3. 生成第一首歌

3.1 部署示例脚本

从资源下载区获取 yue2-song.zip，解压后把 yue2-song 文件夹整体放到 ComfyUI 便携包根目录（与 python_embeded 同级）。此时根目录结构如下：

ComfyUI_windows_portable
├── python_embeded             嵌入式 Python 环境
├── YuE2env                    YuE2 隔离依赖
├── yue2-song                  示例项目（本步放入）
│   ├── yue2_run.py            生成主脚本
│   ├── YuE2生成歌曲.bat       双击运行的批处理入口
│   ├── tonight-awake.json     官方示例《今晚不眠》提示词
│   ├── jinye-bumian.json      实战案例《今夜不眠》提示词
│   └── README.md              使用说明
└── ComfyUI                    ComfyUI 本体（保持原样）

yue2_run.py 是整个示例的核心，它完成「前置隔离路径、加载双模型、按模式生成、保存全部产物」四件事。节选其主干逻辑：

import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parent
ENV = ROOT / "YuE2env"
if not ENV.is_dir():
    ENV = ROOT.parent / "YuE2env"  # 项目放在便携包子目录时，回上一级找隔离依赖
sys.path.insert(0, str(ENV))       # 把隔离依赖目录放到模块搜索路径最前面

import torch
from yue2 import YuE2Pipeline
from yue2.protocol import GenerationConfig, Sampling

MODEL_DIR = Path(r"C:\models\YuE2-3B")
VAE_DIR = Path(r"C:\models\YuE2-Vae")

# 同时加载主模型与 VAE，显存预算按显卡实际容量设置
pipe = YuE2Pipeline.from_pretrained(
    str(MODEL_DIR), vae=str(VAE_DIR), device="cuda",
    memory_budget_gib=22, local_files_only=True, generation_config=gen,
)

# 一次调用完成三阶段生成，song.save_artifacts 保存乐谱、潜变量与音频
song = pipe(style=style, lyrics=lyrics, cot=cot, seed=seed)
result = song.save_artifacts(str(ROOT / "YuE2-output" / out_name))
pipe.close()

完整代码请查看 yue2-song/yue2_run.py。脚本支持的主要参数如下：

3.2 冒烟测试

第一次部署建议先跑冒烟测试：它把各阶段的 token 预算压到很短，用约一分半钟验证「模型加载、显卡推理、音频写出」整条链路是否通畅，避免直接跑完整歌曲时在十几分钟后才发现问题。在便携包根目录执行（也可以用批处理入口 yue2-song\YuE2生成歌曲.bat smoke，效果相同）：

python_embeded\python.exe yue2-song\yue2_run.py --mode smoke --out smoke-test

运行后先看到显卡信息与精度回退提示：

GPU: NVIDIA GeForce RTX 2080 Ti  capability: (7, 5)
AR dtype for this GPU: float16

capability: (7, 5) 表示 Turing 架构，推理包自动选择了 FP16 精度；RTX 30/40 系显卡这里会显示更高的计算能力并使用 BF16。中间是各阶段的英文进度输出（当前阶段、已耗时、token 吞吐），结尾三行是关键结果：

done in 90.2s
audio: 32.0s  -> YuE2-output\smoke-test\audio.flac
timing: {"abc": {...}, "semantic": {...}, ...}

用播放器打开 YuE2-output\smoke-test\audio.flac，能听到一段三十秒左右的短曲即冒烟测试通过。这段音频因为预算被压缩，乐句会在中途截断，属于预期行为，正式生成的歌曲不存在该问题。

3.3 完整生成官方示例《今晚不眠》

冒烟通过后，运行完整模式生成官方示例歌曲。tonight-awake.json 是 YuE2 官方提供的提示词案例，风格为 City Pop，结构完整（前奏、主歌、预副歌、副歌、桥段、尾奏）：

python_embeded\python.exe yue2-song\yue2_run.py --mode full --out jinwan-bumian

不指定 --prompt-json 时脚本默认读取 C:\models\YuE2-3B\examples\tonight-awake.json。也可以直接双击 yue2-song\YuE2生成歌曲.bat，它无参数运行时等价于上面这条命令。以下是本教程在 RTX 2080 Ti（22GB 显存）上的完整耗时实测，可作为对你自己机器的预期参照：

完整生成的产物保存在 YuE2-output\jinwan-bumian\，每个文件都有明确用途：

request.json 与 result.json 是排查与复现的好帮手：想复现某次生成，把 request.json 中的 style、lyrics、seed 原样回填即可得到一致结果；想对比两次生成的差异，diff 这两个文件比回忆参数可靠得多。

3.4 生成自己的歌曲：编写提示词 JSON

生成自己的歌曲只需要一份提示词 JSON。以本教程实战案例《今夜不眠》（暗色 R&B 抒情曲，见资源下载区试听链接）为例，文件格式如下：

{
  "title": "今夜不眠",
  "style": "Dark atmospheric R&B ballad, slow 66 BPM, B minor, deep sub bass, sparse trap-influenced hi-hats, hazy analog synth pads, moody electric piano, raw natural unprocessed male vocal, intimate close-mic performance, melancholic introspective late-night mood, spacious reverb",
  "lyrics": "[Intro]\n\n[Verse]\n凌晨三点的天花板 数着裂缝发呆\n手机屏幕忽明忽暗 像退潮的对白\n...\n[Outro]\n天快亮了\n就到这吧\n晚安",
  "cot": "full",
  "seed": 60966
}

style 与 lyrics 的写法直接决定成歌质量，两条实战经验：

• 风格描述用英文短语堆叠，覆盖五个维度：曲种与情绪（Dark atmospheric R&B ballad）、速度与调性（slow 66 BPM, B minor）、配器（deep sub bass, electric piano）、人声质感（raw natural unprocessed male vocal, intimate close-mic）、空间氛围（spacious reverb）。维度写得越具体，模型发挥越稳定。
• 歌词用结构标签分段，[Intro]、[Verse]、[Pre-Chorus]、[Chorus]、[Bridge]、[Outro] 标记段落，标签之间的换行用 \n 表示。重复的副歌把歌词块原样再写一遍，模型会按重复段处理。纯器乐段落（前奏、间奏）保留标签、内容留空即可。

写好 JSON 后执行（把 --out 换成你的输出名）：

python_embeded\python.exe yue2-song\yue2_run.py --mode full --prompt-json yue2-song\jinye-bumian.json --out jinye-bumian

也可以不写 JSON，用 --style 与 --lyrics-file 直接传入：

python_embeded\python.exe yue2-song\yue2_run.py --mode full --style "City Pop, upbeat, danceable" --lyrics-file my-lyrics.txt --seed 831001 --out my-song

3.5 试听与验收

生成完成后，用任意支持 FLAC 的播放器（如 foobar2000、PotPlayer）打开 YuE2-output\jinye-bumian\audio.flac 验收，检查三点：人声咬字是否清晰、副歌是否有记忆点、伴奏与人声是否协调。对效果不满意时，优先调整的顺序是换种子（--seed）重跑、微调风格描述、最后才是改歌词——同提示词换种子重跑的成本远低于改提示词，效果变化却往往最明显。

本教程实战案例《今夜不眠》的完整成歌已放入资源下载区的网盘，可直接试听对照自己机器的生成效果。

4. 进阶：ABC 乐谱编辑与旋律复用

4.1 认识 score.abc

score.abc 是 YuE2 符号规划阶段的产物，采用通用的 ABC 记谱法描述旋律与和弦。打开《今夜不眠》的乐谱，头部声明拍号、速度与调性，主体按段落分块，双引号内是和弦标记：

X:1
T:
M:4/4
L:1/16
Q:1/4=65
V: Vocal clef=treble name="Vocal Melody" snm="Vocal"
V: Ins clef=treble name="Ins Melody" snm="Inst."
K:Bbm
% verse
V: Vocal
"Bbm"fBBBdBBf3BBdeed|"Ab6"e2cBcBcBA2zAABdB|...
V: Ins
Z4|

头部字段含义：M:4/4 拍号，Q:1/4=65 速度（每分钟 65 拍），K:Bbm 调性（降 B 小调）；V: Vocal 与 V: Ins 分别定义人声轨与器乐轨，% 开头的行是注释（段落标记）。score.abc 既是生成结果，也是可以再创作的输入——这正是 YuE2 区别于一般「黑盒」歌曲生成模型的地方。

4.2 复用乐谱生成新版本

拿到一份满意的乐谱后，可以在保持旋律与和弦不变的前提下更换风格或歌词，生成同一首歌的不同版本。操作方法是给脚本传入 --abc-file 指向已有乐谱，并把 --cot 设为 melody：

python_embeded\python.exe yue2-song\yue2_run.py --mode full ^
  --prompt-json yue2-song\jinye-bumian.json ^
  --abc-file YuE2-output\jinwan-bumian\score.abc ^
  --cot melody ^
  --out jinye-bumian-v2

传入外部乐谱后，符号规划阶段被整段跳过（乐谱直接作为前缀进入语义生成），既省下约两三分钟的规划时间，又锁定了旋律。本教程实测《今夜不眠》两次生成的对比：

二次生成省时约三分之一，且两次歌曲的旋律骨架一致。你也可以手动编辑 score.abc 后再传入（例如把某段和弦从 "Gm7" 改成 "Bbmaj7"），实现改和弦、调旋律这类精细控制；编辑时保持每小节音符时值总和不变是基本要求，调性（K:）与速度（Q:）改动属于进阶操作，建议小步修改、逐次试听。

4.3 生成参数速查

5. 总结

5.1 核心内容回顾

• YuE2-3B 是 m-a-p 开源的歌曲生成模型，输入风格提示词与结构化歌词，输出 48kHz 立体声完整歌曲，权重为 CC BY-NC 4.0 协议。
• 官方环境为 Linux + 24GB BF16 显卡；Windows 上可借助 ComfyUI 便携包的嵌入式 Python 环境部署，Turing 架构显卡自动回退 FP16 精度运行。
• 部署三步：模型放 C:\models、推理包装入隔离目录 YuE2env、示例脚本放便携包根目录；依赖隔离是整套方案不破坏 ComfyUI 的关键。
• 生成流水线为「符号规划 → 语义 token 生成 → 声学生成 → VAE 解码」四阶段，实测 RTX 2080 Ti 生成三分钟歌曲约 17 分钟。
• score.abc 乐谱可编辑、可复用，配合 --cot melody 与 --abc-file 能在锁定旋律的前提下换风格换歌词，二次生成提速约三分之一。

5.2 常见问题与解答

问：显存不足（OOM）报错怎么办？

答：先关闭其他占用显存的程序（浏览器硬件加速、游戏、其他本地大模型）；再把 yue2_run.py 中的 memory_budget_gib 调低到接近你的显存容量（如 12GB 显存设 11）；最后确认用冒烟模式先验证链路。低于 22GB 显存的配置本教程未完整验证，生成超长歌曲时可能仍需进一步降低预算。

问：为什么不用 ComfyUI 的节点工作流来生成歌曲？

答：本教程发布时 yue2_infer 推理包以 Python API 与命令行为主要使用方式，ComfyUI 侧暂无成熟的 YuE2 节点。便携包的价值在于它提供了一套开箱即用的 CUDA 版 Python 环境，直接运行推理脚本即可，后续若出现社区 YuE2 节点，环境可直接复用。

问：RTX 30 系、40 系显卡会更快吗？

答：会。计算能力 8.0 以上的显卡使用 BF16 精度且通常搭配更高的显存带宽，语义生成阶段的吞吐会明显提高；本教程 2080 Ti 实测语义阶段约 8 至 11 token/秒，可将其作为相对基准估算自己机器的耗时。

问：模型可以商用吗？

答：YuE2-3B 与 YuE2-Vae 均采用 CC BY-NC 4.0 协议，明确限制商业用途。学习、研究、个人创作不受限，商用需联系版权方获得授权。

问：提示词报错找不到模型目录？

答：脚本默认从 C:\models\YuE2-3B 与 C:\models\YuE2-Vae 加载模型。模型放在其他位置时，修改 yue2_run.py 顶部的 MODEL_DIR 与 VAE_DIR 两个路径常量即可。

问：生成中断后能续跑吗？

答：目前不支持断点续跑，中断后需重新执行。可先用冒烟模式确认环境稳定，再跑完整生成；生成期间避免休眠、关机与高负载任务抢占显卡。