YuE2：用符号规划生成可编辑歌曲
YuE2 给音乐生成和 agent 开发者用，先编辑 melody/chords 再生成歌曲，区别于直接从歌词出音频。
GitHub multimodal-art-projection/YuE 更新 2026-09-13 分支 main 星标 7.3K 分叉 824
Python 音乐生成 YuE2-3B Linux/NVIDIA GPU

🧭 决策指南

为什么现在热： 材料显示它在 2026-09-13 登上 GitHub Trending，当日新增 210 星；README 同时公布了 2026-09-12 的 WildSongBench 结果、6.9632 SongBench Avg，以及可编辑 symbolic planning、zero-shot covers 和 agentic editing，这些发布信息与功能亮点能解释当前关注度。

适合，如果你

  • 你有 Linux、Python 3.12 和支持 BF16 的 NVIDIA GPU，显存至少 24 GB。
    README「Quick start」明确列出 Linux · Python 3.12 · NVIDIA GPU with BF16 support and 24 GB VRAM。
  • 你需要在生成完整歌曲前检查或修改 melody、chords 和 ABC score。
    README「White-box music generation through symbolic planning」说明 melody and chords 可由人或 agent inspect and edit。
  • 你要用同一 YuE2-3B checkpoint 做 zero-shot cover 或 agentic editing。
    README「Zero-shot covers and agentic editing」说明同一 generation checkpoint 支持两类任务。
  • 你要复现 WildSongBench 的 192 prompts 评测流程。
    README「Reproduce the benchmarks」要求按照 WildSongBench 的 reproduce standard YuE2 说明执行。

不适合，如果你

  • 你的运行环境不是 README 指定的 Linux、Python 3.12 和 NVIDIA BF16 GPU。
    README「Quick start」只列出上述运行环境，没有提供 Windows、macOS 或其他后端步骤。
  • 你的设备显存低于 24 GB，且不能满足 YuE2 Quick start 的硬件条件。
    README「Quick start」明确要求 24 GB VRAM。
  • 你只需要直接从 lyrics 和 style 生成音频，不需要 score、melody 或 chords 的可编辑中间结果。
    README 将 YuE22 的核心区别描述为 editable composition，并提供 cot="off" 作为直接生成设置。
  • 你要求以单一综合指标证明模型显著优于所有竞品。
    README「Benchmarks」明确说 rankings vary by metric，且 small gap between the highest means does not establish statistical significance。

前置条件

  • Linux · Python 3.12 · NVIDIA GPU with BF16 support and 24 GB VRAM
  • Model files download from Hugging Face on first use.
  • YuE2 produces 48 kHz stereo audio without quantization.
  • Python runtime is installed separately with `pip install .`.

第一步命令（README 原文）

git clone https://github.com/multimodal-art-projection/YuE.git

要注意

  • 首次执行会从 Hugging Face 下载模型，网络和本地存储要求未在 README 量化。
    README「Quick start」写明 Model files download from Hugging Face on first use。
  • benchmark 使用 YuE2-Vae-legacy，不等同于默认 YuE2-Vae 解码器。
    README「Benchmarks」说明两种 YuE2 设置使用 benchmark decoder YuE2-Vae-legacy。
  • best-of-8 与标准 YuE2 的候选数量不同，前者从八个候选中选择。
    README「Benchmarks」说明 Standard YuE2 selects from two candidates；best-of-8 selects from eight。
  • 生成目录不仅有 audio.flac，还会保留 score、semantic tokens、acoustic latents 和设置。
    README「Quick start」说明 outputs/first-song 目录保留这些 artifacts。
  • MERT2 不是生成必需模型，但 SheetSage2 的 encoder 使用 MERT-v2-FullSong。
    README「Models and resources」说明 MERT2 feature extraction optional，且列出 SheetSage2's encoder。

替代方案

  • Suno v5：如果更看重 WildSongBench 的 MuLan 0.5428 或 PER 8.10%，而不是 YuE2 的 SongBench Avg 6.7316。
    README「Benchmarks」
  • Suno v4.5：如果在 README 的 WildSongBench 表中优先看 PER，Suno v4.5 的 5.80% 低于 YuE2 的 8.44%。
    README「Benchmarks」
  • LeVo 2：如果优先看 AudioBox PQ，LeVo 2 的 8.3966 高于 YuE2 best-of-8 的 8.2714。
    README「Benchmarks」

材料未说明

  • README 未说明 YuE2-3B、YuE2-Vae 和 SheetSage2 的下载体积。
  • README 未说明单首歌曲的生成延迟、显存峰值或 best-of-8 的额外成本。
  • README 未说明 Windows、macOS、AMD GPU 或 CPU 是否受支持。
  • README 未说明生成歌曲的版权、训练数据来源和商业使用边界。
  • README 未说明长歌词、超长歌曲和多语言输入的长度限制。
  • README 未提供 YuE2-Vae 默认解码器与 YuE2-Vae-legacy 的音质差异。
  • 仓库只有 1 个版本和 10 个最近提交，README 未说明后续 API 稳定性或兼容承诺。

💡 深度解析

6
不适合 我需要把 YuE2 与 Suno v5、Suno v6 的 WildSongBench 结果做可复现实验比较；README 中的 6.9632 和 6.7316 能否直接当作单次生成质量？
适合读者： 需要复现 WildSongBench 结果、比较 YuE2 与 Suno v5/v6，并要求实验保留模型和解码器身份的音乐生成研究人员

不适合直接这样解读，因为两个分数对应不同候选选择协议，且 README 明确说排名差异不代表统计显著性。

  • YuE2 best-of-8 的 SongBench Avg 为 6.9632，表示从八个候选中选择；普通 YuE2 为 6.7316，使用 two candidates，不能把前者当作单次生成结果。
  • 对比表中的 YuE2 设置都使用 YuE2-Vae-legacy 基准解码器；如果改用默认 VAE，不能声称复现该表。
  • README 要求依照 WildSongBench 的 standard-yue2 说明复现，并指出不同指标排名会变化；YuE2 的 MuLan、PER 并非全部领先。
  • 结果目录保留生成设置和模型身份，有助于记录实验配置，但不替代评测协议本身。

README 没有给出候选筛选器的完整实现细节、置信区间或显著性检验结果，无法由这两个均值判断普遍领先。

  • Benchmarks：YuE2 (best-of-8) SongBench Avg 6.9632；YuE2 6.7316
  • Benchmarks：Standard YuE2 selects from two candidates; best-of-8 selects from eight
  • Benchmarks：Both YuE2 settings use symbolic planning and the benchmark decoder YuE2-Vae-legacy
  • Benchmarks：Rankings vary by metric; the small gap between the highest means does not establish statistical significance
材料未说明：README 未提供候选选择器的完整实现细节；README 未提供这些均值的置信区间或统计显著性检验结果
适合 我在 Linux 上使用 Python 3.12，手头有支持 BF16 的 NVIDIA GPU 和 24 GB 显存；YuE2 是否适合我在本地运行开放模型并生成 48 kHz 立体声歌曲？
适合读者： 具备 Python 基础、使用 Linux，并拥有支持 BF16 的 NVIDIA GPU 和 24 GB 显存的本地模型研究人员

适合，因为你的运行环境正好满足 README 给出的 Quick start 前提。

  • 项目明确要求 Linux、Python 3.12、支持 BF16 的 NVIDIA GPU 和至少 24 GB 显存；这与你的约束一致。
  • YuE2 不依赖量化，输出为 48 kHz 立体声音频；本地 Python 接口可加载 m-a-p/YuE2-3B 并指定 device="cuda"。
  • 首次运行会从 Hugging Face 下载模型文件，因此网络、缓存空间和访问权限仍可能影响启动。
  • 输出目录会保留曲谱、语义 token、声学 latent、生成设置和模型身份，适合研究实验与复现。

README 没有说明在 24 GB 显存下不同歌曲长度、候选数量或并发数的显存余量，也未提供 CPU、AMD GPU 或移动端的标准部署路径。

  • Quick start：Linux · Python 3.12 · NVIDIA GPU with BF16 support and 24 GB VRAM
  • Quick start：YuE2 produces 48 kHz stereo audio without quantization
  • Quick start：Model files download from Hugging Face on first use
  • Quick start：输出目录保留 score、semantic tokens、acoustic latents、generation settings 和 model identities
python examples/generate.py --output outputs/first-song
材料未说明：README 未说明 24 GB 显存下的最大歌曲长度、候选数量和并发限制；README 未说明首次下载所需的具体磁盘空间
适合 我想让代理先保留原始音频和曲谱，再把同一首英文歌曲改成爵士和声，并输出两个版本比较；YuE2 是否适合作为这个多轮编辑工作流的后端？
适合读者： 正在开发基于 Python 的智能代理，希望围绕 ABC 曲谱、歌词和编曲进行多轮音乐编辑的代理开发者

适合，因为 README 已提供面向代理的 skill，并把曲谱、歌词和版本比较作为明确操作对象。

  • yue2-music skill 教代理生成歌曲、转录和翻唱录音、编辑 ABC 曲谱、检查音乐不变量并组织试听比较。
  • 示例请求直接覆盖你的流程：创建 English piano-pop song，保留 original audio and score，再生成 jazz harmony 版本并比较。
  • Python API 将流程拆成 plan()、generate_semantic()、synthesize() 和 decode()，代理可以在规划与渲染之间插入曲谱或歌词修改。
  • save_artifacts() 会保存音频、曲谱、语义 token、声学 latent、生成设置和模型身份，便于保留原版并追踪版本。

但 README 没有说明 skill 是否支持你使用的具体代理框架，也没有给出并发任务、错误恢复、权限隔离或长对话状态管理方案；这些仍需自行接入。

  • Agent skill：yue2-music 支持生成歌曲、转录和翻唱录音、编辑 ABC scores、检查 musical invariants 和 listening comparisons
  • Agent skill：示例请求包含 English piano-pop、保留 original audio and score、jazz harmony 和比较两个版本
  • How it works：`plan()` → `generate_semantic()` → `synthesize()` → `decode()`
  • Quick start：`song.save_artifacts("outputs/my-song")` 及输出工件说明
材料未说明：README 未说明支持哪些具体的代理框架或工具调用协议；README 未说明长对话状态、并发执行和失败重试的实现方式
不适合 我没有 ABC 曲谱经验，只想输入歌词和风格提示立即试听；在还要安装 Python 3.12、Linux 和 24 GB 显存环境的前提下，YuE2 是否比直接提示词生成更适合我？
适合读者： 只想用歌词和风格提示快速试听、没有 ABC 或和弦编辑经验，并在评估本地工具是否比直接提示词生成更省事的歌曲创作者

不适合把 YuE2 当作最省事的即时试听工具，因为它的价值依赖曲谱规划和本地运行环境，而你的目标是不接触这些环节。

  • README 的默认新歌流程是 cot="full"，会先生成可编辑的旋律与和弦计划；这比只输入提示词多了一层需要理解和检查的中间产物。
  • 项目要求 Linux、Python 3.12、支持 BF16 的 NVIDIA GPU 和至少 24 GB 显存，首次运行还要从 Hugging Face 下载模型。
  • README 的用户体验分析指出，使用者需要理解 ABC 曲谱、规划模式、转谱和分阶段生成；对只想立即试听的普通用户学习成本较高。
  • cot="off" 可以直接从歌词和风格生成，但会放弃显式曲谱控制，因此只是降低了控制能力，不会消除本地安装和硬件要求。

README 未提供托管网页、CPU 推理、移动端运行或无需安装的标准路径。

  • Quick start：`cot="full"` 是 new songs 的默认模式
  • Quick start：Linux · Python 3.12 · NVIDIA GPU with BF16 support and 24 GB VRAM
  • User experience：普通用户需要理解 ABC 曲谱、规划模式、转谱和分阶段生成
  • Quick start：`cot="off"` — Generate directly from lyrics and style
材料未说明：README 未提供无需本地安装的托管服务或网页入口；README 未说明 CPU、AMD GPU 或移动设备上的可用性能
视情况 我需要保留原录音的演唱旋律和歌词顺序，但把伴奏改成爵士风格；在 YuE2 的 `full`、`melody` 和 `off` 模式中，哪种更符合我的翻唱约束？
适合读者： 想保留原曲旋律、改变伴奏风格，并使用 SheetSage2 做音频转谱的翻唱创作者

视情况：如果旋律保持比和声保持更重要，melody 更合适；如果还要尽量保留原曲和弦与整体结构，应使用 full。

  • README 将 cot="melody" 标为“Use a melody plan with free accompaniment”，并明确推荐用于 covers，适合改变伴奏风格。
  • cot="full" 会生成可编辑的旋律与和弦计划，完整曲谱翻唱在 948 首作品评测中达到 0.647 CLEWS mAP，而无曲谱只有 0.006。
  • cot="off" 直接从歌词和风格生成，放弃显式曲谱控制，不符合“保留旋律”的强约束。
  • SheetSage2 的转谱结果是后续控制基础；复杂节奏、多声部或噪声录音造成的转谱错误，可能继续传递到翻唱结果。

README 没有保证每次生成都能同时保持原唱身份、歌词发音、旋律和目标风格，也未说明 SheetSage2 在你的具体录音上的转谱准确率。

  • Quick start：`cot="melody"` — Use a melody plan with free accompaniment; recommended for covers
  • Quick start：`cot="full"` — Generate an editable melody-and-chord plan
  • Benchmarks：948 works，full-score CLEWS mAP 为 0.647，without a score 为 0.006
  • Benchmarks / usage limitations：melody-only covers offer more freedom to change the arrangement
材料未说明：README 未说明 SheetSage2 对具体录音的转谱准确率；README 未说明目标风格变化对原唱身份和歌词发音保持的稳定性
适合 我已经有一份 ABC 曲谱，想在不重新规划旋律的情况下尝试不同风格和解码器；YuE2 是否支持把这份曲谱作为可复用的中间产物？
适合读者： 熟悉 ABC 记谱、希望把自有旋律与和弦计划作为显式控制输入，并需要复用同一曲谱进行多次音频渲染的 Python 开发者

适合，因为 YuE2 把 ABC 曲谱作为 full 或 melody 模式下的显式输入，并提供分阶段 API 进行复用。

  • Quick start 明确支持 abc=...，可在 full 或 melody 模式提供自有曲谱。
  • cot="full" 控制可编辑的旋律与和弦计划，cot="melody" 则保留旋律并允许自由伴奏；这分别对应完整结构复用和风格改编。
  • generation guide 被指定用于 exact-plan reuse 和 decoder selection，说明曲谱不必随每次音频渲染重新规划。
  • 流程拆分为 plan()、generate_semantic()、synthesize()、decode()，并保存 score、tokens、latents 和模型身份，便于比较版本。

不过 README 没有说明自有 ABC 的语法覆盖范围、无效曲谱的报错行为，也没有保证更换解码器后音频的节奏、音色或演唱表达完全一致。

  • Quick start：`abc=...` — Supply your own score in `full` or `melody` mode
  • Quick start：`cot="full"` 和 `cot="melody"` 的行为说明
  • How it works：generation guide 支持 exact-plan reuse and decoder selection
  • Quick start / How it works：分阶段 API 与持久化 score、tokens、latents、model identities
材料未说明：README 未说明支持的 ABC 语法子集和复杂多声部曲谱限制；README 未说明无效或不完整 ABC 曲谱的错误处理行为

✨ 核心亮点

  • YuE2 best-of-8 达到 6.9632 SongBench Avg
  • melody 和 chords 可在渲染前检查编辑
  • 同一 checkpoint 支持 zero-shot covers 与 agentic editing
  • 运行要求 Python 3.12、BF16 与 24 GB VRAM

🔧 工程化

  • YuE2-3B 从 lyrics 和 style 生成 melody-and-chord plan 与完整歌曲
  • Python API 按 plan、generate_semantic、synthesize、decode 分阶段执行
  • SheetSage2 转录录音为 score，支持 zero-shot cover 与编辑

⚠️ 风险

  • Quick start 仅写 Linux、Python 3.12、NVIDIA BF16、24 GB VRAM
  • 模型首次使用从 Hugging Face 下载，README 未给出下载体积
  • SongBench 排名按指标变化，最高均值差距不代表统计显著
  • best-of-8 使用八个候选，README 未说明额外耗时或显存

👥 适合谁？

  • 拥有 Linux 与 24 GB NVIDIA GPU 的 Python 音乐生成开发者
  • 需要检查 ABC score、旋律和和弦的 agent 开发者
  • 需要从录音生成新编曲的 zero-shot covers 工具开发者