YuE2 音乐生成的可复现评测：从可听交付到证据分离的完整实践指南

YuE2 音乐生成的可复现评测：从可听交付到证据分离的完整实践指南

【免费下载链接】YuEYuE2: frontier music generation with symbolic planning, zero-shot covers, and agentic music editing.项目地址: https://gitcode.com/GitHub_Trending/yue/YuE

导读

本文基于 YuE2 技能套件中的评测交付规范文档，系统讲解如何把一个音乐生成结果"变成用户能播放的音频"以及"能被严格复现的评测记录"。你将掌握：如何用YuE2-Vae与YuE2-Vae-legacy分别完成听感预览与基准协议解码、如何复用缓存 latent 进行纯解码、如何用scripts/listen.py构建本地 HTML 听感对比页，以及如何区分符号检查、ASR、对齐与质量分数这几类不同性质的证据。文中所有结论均与 skills/yue2-music/references/listening-and-evaluation.md 及其配套脚本、源码实现相互印证。

核心原则：交付音频，而不是分数

YuE2 的评测与交付规范开宗明义：一个乐谱（score）、一个指标（metric）或一次成功退出的进程，都不是可听的交付结果。任务只有在交付了用户可以播放的音频，并同时说明"产生这段音频的确切条件"时才真正完成。这条原则贯穿整个技能的工作流（见 SKILL.md 中 "Deliver an audible result" 一节）：return playable audio, full prompt/lyrics, before/after ABC, invariant checks and requested evaluations——可播放音频是第一位的，模型/解码器身份与失败记录必须保持可见。

在此基础上，文档进一步给出了三条交付纪律：

1. 听感与评分版本分离：听感预览与基准评分必须使用不同的解码器，且不能凭 "legacy" 一词推断其角色；
2. 证据类型分离：符号检查、ASR、对齐、质量分数与人工听感是五种不同性质的证据，各有支持范围与盲区；
3. 评测与生成分离：公共 YuE2 运行时不附带完整评分代码与评测权重，分数只能在独立评测包中复现。

下文逐条展开，并给出可直接运行的命令。

保持听感与评分版本分离

两个解码器的分工

两个模型的分工在 models-and-setup.md 的模型表中亦有明确记录。规范强调：在记录中必须保留完整的模型名、revision 与哈希，因为"legacy"一词本身并不能说明某条乐谱是用哪个解码器生成的——它只是一个代号，必须靠记录中的精确标识来锚定。

一次生成、多次解码：复用缓存 latent

音乐或歌词的任何编辑都要求重新生成；而仅更换解码器则不需要。正确做法是：对给定歌曲只生成一次声学 latent，然后对同一份latent.npy用每个请求的解码器分别解码。

scripts/run_yue2.py的decode子命令正是为此设计的（见 run_yue2.py）：

python scripts/run_yue2.py decode --source outputs/jazz \ --output outputs/jazz-evaluation \ --model "$YUE2_MODEL_DIR" --vae "$YUE2_EVAL_VAE_DIR" --offline

使用要点（与源码行为一一对应）：

• --source必须是已验证的原生SongResult目录：decode()首先调用verify_result(source)（实现在 storage.py），该函数要求result.json状态为complete，且audio.flac、prefix.npy、semantic.npy、latent.npy、request.json、config.json等必需工件全部在清单内且 SHA-256 与字节数逐一吻合。
• 模型必须与源生成完全一致：解码时会比较pipe.weights["mot"]与源result.json中记录的weights["mot"]，不一致直接抛错——这防止用错误主干模型"复用"latent 得出误导结果。
• latent 不允许改变：解码结束后会再次校验输出目录的latent.npy与源的哈希一致，任何变更都会失败。
• Hub 模型须传已核验的 revision：即--revision与--vae-revision，本地模型目录则配合--offline使用。

新目录会通过SongResult.save_artifacts（见 pipeline.py）保留原始请求、精确的 plan/semantic token 与 latent，同时用cached_decode字段记录本次解码器身份、配置与音频哈希，并用source_generation.json记录源结果、源 latent、源 semantic 的 SHA-256（见 run_yue2.py）。解码时间被记录为operation: "decode_cached_latents"下的vae_seconds，与源生成的source_generation计时明确分开——不要把解码器运行时间报告为完整生成速度。

完整工件目录 vs 裸 FLAC

裸 FLAC 加一份自写的解码器 manifest 对"试听"够用，但不足以作为完整技能包中冻结评测器的输入。评测适配器要求的是完整的原生SongResult.save_artifacts目录，包含：

• result.json（状态、身份、权重、时序、工件清单）；
• 请求与配置（request.json、config.json）；
• token 数组与 latents（semantic.npy、latent.npy）；
• 音频及其哈希（audio.flac）。

同时注意两条禁令：不要把旧 manifest 复制到新音频上，也不要把试听解码器的身份保留在评测音频上。

构建听感对比页

一键生成本地 HTML 播放页

python scripts/listen.py outputs/pop outputs/jazz --output outputs/comparison

该脚本（listen.py）从每个输入的原生歌曲目录中按白名单复制音频与元数据，生成一个本地自包含的 HTML 播放页。关键行为与源码对应：

• 只复制白名单内容：METADATA仅包含request.json、config.json、result.json、invocation.json、input.json、failure.json、run.json、abc_check.json等元数据，另有score.abc与audio.flac/audio.wav。模型权重与 latent 一律不复制——manifest.json中明确记录"weights_or_latents_copied": False。
• 不上传、不发布：页面是纯本地的，无任何网络访问（"network_access": False）。
• 强制全新目录：输出目录已存在则直接报错（Output already exists; choose a fresh comparison directory），且禁止把对比目录建在源歌曲目录内部。
• 完整性校验决定播放器：每个复制文件的 SHA-256/字节数与result.json中的artifacts清单比对；若不匹配则标记native_artifact_checks: FAILED并扣留播放器（测试用例见 test_skill_listen.py）。
• 退出码语义：全部 case 完成返回 0；页面生成但有待审 case 返回 1；命令错误返回 2。

对比页应随带直接音频下载链接一并交付，尤其是在浏览器不支持原生格式时（页面已内置 download 链接与audio.flac/audio.wav两种来源）。

节选（excerpt）的选取规范

• 长编辑必须同时包含完整歌曲与有用节选；节选应从编辑段落之前开始，并包含段落的退出——孤立的几个音符无法暴露转接问题。
• 人声重写：节选应覆盖足够的 verse 与 chorus，以便评估咬字与 phrasing。
• 主题/独奏编辑：应包含完整的主题陈述及其延续，而不仅是开头动机。

每条听感条目必须标注的身份信息

即便生成 MP3 预览，也必须保留无损生成音频；刷新听感链接时不得替换或归一化记录分数所依据的音频。听感页转换是交付产物，而冻结评测适配器会应用自己记录的预处理。

听什么

文档列出的专项听感检查清单：旋律实现、持续音上的和弦冲突、乐器选择、歌词缺失/重复、节奏推进（pacing）、段落转接与结尾。诚实原则同样重要：如果本次没有可用的音频试听能力，就如实说明实际执行了哪些检查，而不要声称"听过了这首歌"。

分离证据：什么检查能证明什么

规范给出了一张关键表格，用于把不同检查的证据价值讲清楚：

其中几类检查在本仓库有直接实现：ABC 结构性检查由 abc_tools.py 的inspect（parse/report）完成，严格限定在 YuE2/SheetSage2 的双声部 ABC 方言内，所有时间均为四分音符的精确分数；发声音符对比由compare实现，逐音符比较音高、起始与时长（compare返回match与差异列表，见 abc_tools.py）。生成目录中的abc_check.json正是运行这类检查后的落盘结果，run_yue2.py 会在每次生成/plan 后自动写出。

另一个重要约束：设计的歌词–音素–音符 sidecar 必须与实测的音频对齐数据分开存放。要声称"发音同步"，就必须保留对齐器的输出，并人工复核难词、花腔（melisma）与器乐段落——仅凭更低的 PER 并不能证明音符时值正确。

评测：使用独立完整的基准包

公共 YuE2 运行时与本技能不附带完整评分代码、评测权重或基准输入，也不暴露yue2 eval、bench或verify命令。这与本仓库的实际结构一致：公共侧提供的是 pipeline.py 的生成/解码能力与 storage.py 的存储验证，而非打分系统。

当独立评测包可用时，必须遵循其文档化入口与冻结的资产清单（frozen asset manifest）。复现某个已发布结果前，要求满足：

• 包内精确的dataset/split 定义与预处理；
• 解码器身份、评分器 revision 与哈希；
• 使用来自SongResult.save_artifacts的benchmark-decoded 原生结果目录；
• 在输入记录中保留参考歌词语言与所有尝试过的模式。

规范同时给出硬性边界：仅做 prepare 的验证不是已测得的分数；若评分资产不可用，就交付听感与符号检查并如实报告"评测不可用"，不得用名称近似的指标顶替或凭空捏造分数。评测器的 GPU 需求与 YuE2 生成的 24 GB 显存基线是两回事，需分开说明。

公开交付前，刻意处理听感产物

scripts/listen.py构建的是本地 bundle：它会剔除凭据类元数据（SECRET_KEYS与SECRET_TEXT正则覆盖 token、password、API key、Bearer、hf_、sk-等，命中即整文件扣留，见 listen.py 与对应测试 test_skill_listen.py），并排除权重与 latent。但精确请求、本地模型路径与失败消息仍可能出现在复制出的文件中——因此公开分享前必须人工复核整个 bundle：

• 只分享预期的音频、乐谱、提示词、歌词与公开模型标识；
• 省略私有路径、账户标识、原始日志与无关 sidecar；
• 原生结果目录保持原样不动；若要准备脱敏的公开元数据导出，应为其建立独立的 manifest 与哈希，不得把修改过的元数据冒充原始生成收据；
• 更新听感预览时，不得改动或替换已保存的基准音频。

另外值得注意：听感页的元数据加载上限为 8 MiB（超限文件被标记 "unreadable or invalid JSON; file withheld"），HTML 输出经过完整转义（html.escape(..., quote=True)），恶意注入的脚本/iframe 会被中和（测试见 test_skill_listen.py），这些都保障了 bundle 的本地安全展示。

报告真实结果并保留失败尝试

评测报告要求"先留预期、再跑实验"：

• 运行前保留预期请求列表；对每个请求的模式/版本记录成功或失败、失败原因、两个截断标志（ABC 截断与语义截断）、解码器身份及每个已完成的指标；
• 报告样本数与分母；部分/缺失的分数保持可见，不得静默丢弃失败模式，也不得在看到分数后挑选有利 seed；
• complete:true只表示"请求的指标已产出"，本身不意味着质量验收通过。

SongBench 的七维报告

对 SongBench，必须保留其七个维度及报告的全局平均：Melody、Arrangement、Musicality、Vocal、Instrumental、Mixing、Structure，并标识每个结果对应的确切版本与解码器。规范特别提醒：不要把全局平均重新解释为专门的爵士或和声一致性分数。

PER 协议的完整性

被检查的 PER 协议执行四次 ASR 遍历：必须保留全部转录、选中结果与首次遍历结果，报告分数时要说明协议本身；不得用单次转录顶替而仍沿用同一协议标签。对修订后的英文歌词，还要检查参考语言与实际新歌词文本，并审视残余错误——不能把标量当完整验证。

小检查就按小检查报告

几条自写 prompt 的平均值不是完整基准；个人编辑对比也不是独立质量排名。规范要求把模型生成、基准测量与音乐判断作为三类可追踪的独立声明，彼此不混同、不互相替代。这与 SKILL.md 的交付要求一致：Do not claim exact note realization, instrument removal or sample-accurate preservation from an ABC check or SongBench score alone.

一页速查：完整评测交付清单

□ 生成并保存原生 SongResult 目录（save_artifacts：result.json、request.json、 config.json、score.abc、semantic.npy、latent.npy、audio.flac） □ 听感预览：YuE2-Vae 解码缓存 latent（run_yue2.py decode，--output 指向新目录） □ 基准复现：YuE2-Vae-legacy + 已核验 revision 解码同一份 latent.npy □ 验证：解码后 latent 哈希与源一致；不把 vae_seconds 当作完整生成速度 □ 听感对比：scripts/listen.py 生成本地 HTML 页 + manifest.json □ 检查条目：版本/意图/style/歌词/前后 ABC/模型与解码器身份/seed/模式/ 时长/截断/结构检查/变更记录/节选起止/归一化情况 □ 证据分离：符号检查、ASR/PER、对齐、SongBench、听感分别报告、互不越界 □ 评测包：若可用，按其入口与冻结清单复现；否则如实报告"评测不可用" □ 公开前审查 bundle：剔除私有路径/凭据/日志，不改动原始生成收据与基准音频 □ 报告完整性：保留失败模式与部分分数，注明样本数与分母，小检查按小检查报告

延伸阅读

• 技能总览与工作流选择：SKILL.md
• 模型环境与音频到乐谱桥接：models-and-setup.md
• 生成、翻唱与缓存解码细节：generation-and-covers.md
• 听感对比页实现：listen.py 及其测试 test_skill_listen.py
• 原生工件存储与验证：storage.py、pipeline.py

【免费下载链接】YuEYuE2: frontier music generation with symbolic planning, zero-shot covers, and agentic music editing.项目地址: https://gitcode.com/GitHub_Trending/yue/YuE