YuE2 模型配置与环境搭建实战指南模型选型、多环境隔离与音频到乐谱桥接【免费下载链接】YuEYuE2: frontier music generation with symbolic planning, zero-shot covers, and agentic music editing.项目地址: https://gitcode.com/GitHub_Trending/yue/YuE本文面向想要完整跑通 YuE2 生成、翻唱cover与智能体音乐编辑agentic editing全流程的开发者聚焦于 YuE2 技能栈yue2-musicskill中的模型选型、环境安装与音频到乐谱audio-to-score桥接方案。文中将以 models-and-setup.md 为核心骨架结合仓库源码pyproject.toml、transcribe.py、run_yue2.py、abc_tools.py 等展开深度解析。读完本文你将能够正确选择并区分 YuE2-3B、YuE2-Vae、SheetSage2、MERT-v2 各模型的职责边界在相互冲突的 PyTorch/Transformers/NumPy 版本约束下搭建隔离的运行环境通过 SheetSage2 的transcribeAPI 把任意音频变成可编辑的 ABC 乐谱并与 YuE2 的符号规划symbolic planning无缝衔接。模型全景YuE2 技能栈由哪些模型构成整个yue2-music技能的工作流围绕六个公开模型快照展开。理解它们各自的分工是搭建环境的第一步。下表是各模型在技能中的角色定位模型分发 IDDistribution ID在技能中的角色YuE2-3Bm-a-p/YuE2-3B风格与歌词 →可选的符号规划→ 语义 token → 声学 latent。用于生成以及编辑后的再生成。YuE2-Vaem-a-p/YuE2-Vae默认听音解码器声学 latent → 立体声音频。YuE2-Vae-legacym-a-p/YuE2-Vae-legacy基准解码器。复现记录的评测协议时用它解码同一批 latents。SheetSage2m-a-p/SheetSage2音频 → 旋律、和弦、节拍、调性、结构、ABC 与 MIDI。用于获取翻唱/编辑的起始乐谱或检查生成的音频。MERT-v2-FullSongm-a-p/MERT-v2-FullSongSheetSage2 自动加载的编码器父模型。也可独立用于连续音乐特征提取。MERT-v2-30sm-a-p/MERT-v2-30s面向短录音的可选连续特征提取器。生成、翻唱、编辑流程中不需要它。关于 YuE2-Vae 与 YuE2-Vae-legacy不要因为名字里的 legacy 就主观推断两者的时序关系或质量高低。正确的用法是——听音用YuE2-Vae复现仓库记录的基准评测协议见 docs/benchmarks.md用YuE2-Vae-legacy并在每次运行清单中记录完整的模型名、revision 与哈希。两种解码器产出的音频文件与 manifest 必须分开存放。模型连接链路典型的翻唱链路如下source audio → SheetSage2 (automatically loads its MERT-v2-FullSong parent) → melody_onlyTrue → inspect/correct melody ABC without chord symbols → YuE2-3B with cotmelody, target style, and target lyrics → acoustic latents → YuE2-Vae → listening audio做乐谱编辑score edit时保留或修订和弦符号使用cotfull。做智能体编辑时智能体在规划planning与再生成regeneration两个步骤之间编辑导出的乐谱与提示词不存在额外的智能体专用模型 API——智能体只是编排已有接口。一条必须牢记的模型边界公开的 MERT-v2 编码器返回的是连续特征continuous features不是 YuE2 内部使用的因果离散语义 token ID。因此绝不把 MERT 的 embedding 当作语义 token 喂给 YuE2普通 YuE2 生成不需要单独的 MERT 推理调用MERT 只是 SheetSage2 的编码器父模型由 SheetSage2 自动加载两个公开 MERT 变体都是双向编码器因果 tokenizer 谱系是另一条独立的模型分支。这一点在 SKILL.md 中被重复强调Do not feed public MERT feature tensors to YuE2 as codec tokens。环境隔离为什么必须分开安装这些发布版本各自固定了不同的 PyTorch、Transformers 与 NumPy 版本放在同一个环境里会直接冲突。原则是使用相互独立的环境环境之间只交换音频 / ABC / MIDI 文件共享一个 Hugging Face 缓存目录没有问题各阶段串行执行加载下一个模型前先释放 GPU 显存。从 pyproject.toml 可以看到 YuE2 运行时yue2-infer0.1.6固定的依赖dependencies [ torch2.10.0, transformers4.57.6, huggingface-hub0.36.2, safetensors0.7.0, tiktoken0.12.0, numpy2.2.6, soundfile0.13.1, accelerate1.13.0, ]而 SheetSage2 模型卡要求的环境则固定为 Transformers 4.45.2 与 NumPy 1.24.3并配套 PyTorch 2.8.0。二者版本跨度巨大Transformers 4.45.2 vs 4.57.6、NumPy 1.24.3 vs 2.2.6同环境共存不可行这正是环境隔离成为硬性要求的原因。YuE2 环境搭建发布卡片的目标环境是Linux、Python 3.10、支持 BF16 的 24 GB NVIDIA GPU。安装命令python3.12 -m venv .venv-yue2 .venv-yue2/bin/python -m pip install \ githttps://github.com/multimodal-art-projection/YuE.git也可以从克隆的官方 YuE 仓库安装.venv-yue2/bin/python -m pip install /path/to/YuE。要点包会安装自己固定的依赖上面 pyproject.toml 所列不要从 PyPI 用一个名字相似的未验证包替代当前仓库代码与技能采用 Apache 2.0更早的 v0.1.6 wheel 与技能 ZIP 归档保留其自带许可证详见 LICENSE、THIRD_PARTY_NOTICES.md模型权重由模型仓库独立分发与运行时版本无关安装完成后用主技能中的生成示例SKILL.md 中的scripts/run_yue2.py generate验证一次全新输出再把它当作可复现实验。SheetSage2 环境搭建该接口没有已核验的pip install sheetsage2发行版。正确做法是下载模型快照、安装其 requirements并通过 Transformers 加载。使用 Python 3.10 或 3.11模型卡还要求 FFmpeg 6.1 及其共享库用宿主系统的包/容器工具安装并确认ffmpeg在PATH上python3.11 -m venv .venv-sheetsage2 .venv-sheetsage2/bin/python -m pip install huggingface-hub0.36.0 .venv-sheetsage2/bin/huggingface-cli download m-a-p/SheetSage2 \ --local-dir models/SheetSage2 .venv-sheetsage2/bin/python -m pip install \ torch2.8.0 torchaudio2.8.0 \ --index-url https://download.pytorch.org/whl/cu126 .venv-sheetsage2/bin/python -m pip install \ -r models/SheetSage2/requirements.txt加载适配器快照时模型会自动获取其 config 指定的确切 MERT-v2-FullSong 父模型、校验父模型文件并在 FP32 下合并适配器。因此不要用 MERT-v2-30s 替换那个父模型也不要手工替换成其他 FullSong revisiontrust_remote_codeTrue会执行模型仓库内的 Python 实现务必使用经过审核的 revision并把 revision 与输出一起记录这一下载一次、离线可用的需求正是 transcribe.py 中--offline与--base-model参数存在的意义。转录 API音频到乐谱的桥SheetSage2 通过 Transformers 接口暴露transcribe方法。最小可用示例本地目录加载from pathlib import Path import torch from transformers import AutoModel device cuda if torch.cuda.is_available() else cpu model AutoModel.from_pretrained( models/SheetSage2, trust_remote_codeTrue, ).eval().to(device) result model.transcribe( source.wav, output_dirruns/source-score, dtypebf16 if device cuda else fp32, ) if result.get(abc_error) or not result.get(abc): raise RuntimeError(fNo usable ABC: {result.get(abc_error)}) print(result[warnings]) print(Path(runs/source-score/score.abc))若想直接从 Hub 加载把本地目录替换为仓库 ID并把同一提交分别传给revision与code_revisionmodel AutoModel.from_pretrained( m-a-p/SheetSage2, trust_remote_codeTrue, revisionrecorded-commit, code_revisionrecorded-commit, ).eval().to(device)一步式 melody-only 乐谱翻唱专用技能提供顶层选项melody_onlyTrue同时保留Vocal与Ins两条旋律但从 ABC 中省略和弦符号从播放/合并 MIDI 中省略和弦伴奏。默认的全量转录行为不变。注意该选项只改变导出不改变推理——当所选任务包含和弦预测时原始预测的和弦事件与 LAB 标注仍然可用。try: result model.transcribe( song.mp3, output_dircover-score, melody_onlyTrue, ) except RuntimeError as error: partial getattr(error, result, None) # Completed transcription, if available. if partial is not None: print(partial.get(abc_error), partial.get(warnings, [])) raise abc result[abc] # Also saved in cover-score/score.abc.行为契约如果请求的 melody-only ABC 无法构建Python 侧抛出RuntimeError并把已完成转录挂在error.result上CLI 则以非零码退出。不要把保存了标注当作翻唱乐谱成功。CLI 等价命令.venv-sheetsage2/bin/python models/SheetSage2/infer.py song.mp3 \ --output cover-score --melody-only技能自带助手 transcribe.py 也封装了该能力--task melody-full等价于启用melody_onlyTrue--task melody-vocal额外只选择人声旋律任务。这两个辅助模式不包含和弦预测任务因此不会请求原始和弦预测若需要保留原始和弦标注请使用上面的直接默认任务调用。关于版本兼容旧快照可能没有melody_only关键字。助手的实现transcribe.py 第 44-54 行会通过inspect.signature显式校验该方法是否公开了melody_only参数若不存在则拒绝假设旧的**kwargs包装实现了导出保证——必须把下载的模型代码刷新到显式暴露melody_only的已审核 revision。这一防御性设计说明转录能力以模型仓库代码为准不要依赖未验证的兼容包装。转录完成后把这段无和弦 ABC 交给 YuE2cotmelody 目标风格 目标歌词。完整流程见 SKILL.md 的 Cover a recording 一节。完整可调用接口model.transcribe的完整签名如下参数均有关键字默认值model.transcribe( audio, output_dirNone, *, sampling_rateNone, dtypebf16, # bf16 or fp32 presetdefault, # default or paper prompts(timestamp, downbeat_meter, structure, key, chord_full, melody_full), max_secondsNone, overlap_secondsNone, lookahead_secondsNone, progressNone, export_logitsFalse, export_scoresFalse, export_embeddingsFalse, output_hidden_statesFalse, melody_onlyFalse, # Chord-free ABC and playback when True. render_audioFalse, render_scoreFalse, render_parts(mix,), )逐项行为说明输入解码路径、编码后的音频字节、二进制音频流都会被自动解码、混为单声道并重采样到 24 kHz。数组与张量输入必须提供sampling_rate且形状须为[samples]或[channels, samples]。注意soundfile.read(..., always_2dTrue)返回的是[samples, channels]传入前要先转置。最短输入重采样后至少要有 1,025 个有限样本短片段仍可能因节拍/调性解码信息不足而无法构建 ABC。窗口参数默认使用 300 秒窗口、200 秒重叠、100 秒 lookahead。max_seconds是主动裁剪输入不是仅控内存的设置减小重叠要求0 lookahead overlap 300。presetpaper将重叠固定为 100 秒、lookahead 固定为 0使用记录的音频前端并改变生成停止条件——仅在复现该评测协议连同其记录的任务提示词时使用。导出开关export_logits与各层导出可能很大普通翻唱/编辑流程保持关闭。模型会报告peak_gpu_mib与窗口统计可用于评估具体负载所需显存。如何选择转录任务任务名不是自由文本提示。两条硬约束chord_full与chord_majmin互斥melody_full与melody_vocal互斥时间导出需要timestamp可用 ABC 还需要解码出的节拍与调性信息。比如无和弦条件的人声旋律任务组合result model.transcribe( source.wav, output_dirruns/source-melody, prompts(timestamp, downbeat_meter, structure, key, melody_vocal), melody_onlyTrue, )需要同时保留人声与器乐两条旋律轨时改用melody_full。做和声感知编辑harmony-aware editing时使用默认六任务组合。每次转录后都要检查warnings、diagnostics、abc_error与乐谱再进入再生成——转录即使记谱合法也可能存在音乐性错误。输出产物清单数据内存中的值文件输出ABC 乐谱result[abc]字符串默认全量模式在记谱失败时可返回Nonescore.abc合并播放melody_onlyTrue时省略和弦result[midi]bytestranscription.mid旋律轨result[midis][melody]、melody_vocal、melody_instrumentalbytesmelody.mid、melody_vocal.mid、melody_instrumental.mid和弦播放melody_onlyTrue时无和弦音符result[midis][chords]byteschords.mid定时事件result[events]listresult[num_events]数量events.json标注文本result[labs]映射beat.lab、downbeat.lab、key.lab、chord.lab、structure.lab、旋律 LAB每窗口 token IDresult[tokens]listtokens.json、tokens.txt可选张量result[tensors]按窗口分组的 CPU 张量tensors/指定输出目录时两个易混淆点output_dirNone时推理结果仅驻留内存保存的result.json中events是整数统计量而 Python 结果中是事件列表——两种 schema 不要混用。notation/目录中的伴生文件包含重建乐谱所用的节拍网格、音程与单声部 MIDI原始 MIDI 保留了量化记谱可能简化的时间细节。规范记谱与渲染SheetSage2 导出的 ABC 使用其原生双声部序列化器并对照重建乐谱进行校验。其捆绑模块下载实现中的notation_sheetsage2模块暴露以下函数generate_abc_from_exports(melody_midi_path, *, output_pathNone, meter_conflictinfer, melody_onlyFalse) # - (abc_text, score_object, companion_paths) generate_abc_from_data(melody_midi, beats, chords, keys, structures, *, meter_conflictinfer, melody_onlyFalse) # - (abc_text, score_object) score_to_abc(score_object) # Also validates its own serialization. validate_serialized_abc(text, score_object)注意这些是下载实现中的函数不是通用 ABC 解析器也不是单参数的validate_abc(text)API。新转录可以用顶层melody_onlyTrue选项。对已有的全量转录下面这段代码可在不再次推理的情况下把它保存的旋律重新序列化为无和弦乐谱from importlib import import_module from pathlib import Path package model.__class__.__module__.rsplit(., 1)[0] notation import_module(package .notation_sheetsage2) abc, score, _ notation.generate_abc_from_exports( runs/source-score/notation/song_melody.mid, melody_onlyTrue, ) Path(runs/source-score/melody-only.abc).write_text(abc, encodingutf-8)文件辅助函数要求精确的*_melody.mid文件名以及同级的*_beats.txt、*_keys.txt、*_structures.txt全量乐谱转换还需*_chords.txt。它不会从任意 MIDI 推断节拍网格或调性。智能体撰写的文本请使用技能自带的 ABC 检查见 abc_tools.py 与 abc-editing.md涵盖时长、声部、音高与编辑保持性检查。渲染可选不使用 YuE2 VAE.venv-sheetsage2/bin/python models/SheetSage2/setup_render.py .venv-sheetsage2/bin/python models/SheetSage2/infer.py source.wav \ --output runs/source-score --render-audio --render-score pdf,svg,png .venv-sheetsage2/bin/python models/SheetSage2/render.py \ --input runs/source-score --output runs/source-rendered \ --audio --score pdf,svg,png在极简 Linux 安装上渲染器还提供setup_render.py --with-deps来安装浏览器/渲染依赖。两个重要细节钢琴预览piano preview使用MIDI 音符时序乐谱渲染sheet rendering使用ABC只编辑score.abc不会更新已有的 MIDI随后的钢琴预览仍会播放旧音符。因此先用兼容的 ABC 转换器同步 MIDI再用钢琴音频来判断编辑效果。离线自包含使用model.save_pretrained(models/SheetSage2-merged) offline_model AutoModel.from_pretrained( models/SheetSage2-merged, trust_remote_codeTrue, local_files_onlyTrue, ).eval().to(device)在离线前一次性加载/下载所需文件。纯适配器快照仍需父模型文件合并保存merged save可去掉该依赖。可选 MERT 表征MERT 特征提取适合独立的检索或分析工具。它不是连接 SheetSage2 与 YuE2 的必要环节且embedding 距离小本身不能证明旋律或和声保真度。python3.11 -m venv .venv-mert2 .venv-mert2/bin/python -m pip install \ torch2.6.0 torchaudio2.6.0 transformers4.53.2 \ huggingface-hub safetensors soundfileimport soundfile as sf import torch import torchaudio.functional as AF from transformers import AutoFeatureExtractor, AutoModel repo m-a-p/MERT-v2-FullSong # Or m-a-p/MERT-v2-30s. device cuda if torch.cuda.is_available() else cpu processor AutoFeatureExtractor.from_pretrained(repo, trust_remote_codeTrue) encoder AutoModel.from_pretrained(repo, trust_remote_codeTrue).eval().to(device) audio, rate sf.read(source.wav, dtypefloat32, always_2dTrue) waveform torch.from_numpy(audio[:30 * rate].mean(axis1)) waveform AF.resample(waveform, rate, processor.sampling_rate) inputs processor(waveform.numpy(), sampling_rateprocessor.sampling_rate, return_tensorspt).to(device) with torch.inference_mode(): output encoder(**inputs, output_hidden_statesTrue) mask output.feature_attention_mask[..., None] embedding (output.last_hidden_state * mask).sum(1) / mask.sum(1).clamp_min(1)行为要点两个变体都接受24 kHz 单声道返回25 Hz、1,024 维的帧特征hidden_states恰好包含24 个 post-block 张量索引 0 是 block 1 的输出不是输入 embeddingFullSong 适配整曲30–360 秒示例代码故意只取 30 秒audio[:30 * rate]。做整曲分析时移除该切片保持在意向上下文内更长的录音要显式分块底层模型不提供SheetSage2 的整曲拼接stitchingAPI。分发与许可证边界已核验的模型卡将模型权重标识为CC BY-NC 4.0。技能的许可证不会重新授权这些权重也不会移除其非商业条款代码与依赖保留各自适用的条款。实操要求引导用户阅读每个模型的LICENSE与 THIRD_PARTY_NOTICES.md不要把模型权重、认证材料、缓存数据集或不相关示例打包进技能归档渲染依赖也有各自条款abcjs 为 MIT、Playwright 为 Apache 2.0、Chromium 自带声明、捆绑的 FluidR3 钢琴采样在 CC BY 3.0 US 下需署名。技能可以调用已安装的渲染器而不重新分发这些资产。仓库侧许可证全景见 LICENSE代码、技能与文档Apache 2.0与 MODEL_LICENSE模型权重CC BY-NC 4.0 附加创作者许可。与技能工作流的衔接源码级佐证最后把以上环境与 API 放回yue2-music技能的整体工作流中你会看到每个环节都有对应的可复现性设计转录端transcribe.py 会为每次运行写出input.json源音频名、SHA-256、模型、revision、offline 标志、prompts、melody_only、preset、device、dtype、model_provenance.jsonconfig、快照文件 SHA-256、torch/transformers/huggingface-hub 版本与transcription_manifest.jsonwarnings、产物哈希。这正好落实了本指南记录实际模型与代码 revision的要求——每个运行清单都自带证据。生成端run_yue2.py 通过--cot选择full/melody/off并做输入预检cotmelody时若 ABC 中仍含和弦符号会直接报错提示先用abc_tools.py strip-chordscotoff不接受 ABC。all-modes要求纯文本输入off无法接受 ABC。这与本指南中melody-only 乐谱 →cotmelody的桥接严格对应。记谱方言abc_tools.py 实现的是受限的双声部原生 ABC 方言VocalInsDURATIONS集合{1,2,3,4,6,8,12,16,24,32,48}原生和弦品质集合QUALITIES它刻意不是通用 ABC 解析器。SheetSage2 导出的乐谱与 YuE2 规划的乐谱都遵循这一方言这是转录 → 编辑 → 再生成能够闭环的记谱前提。端到端示例完整的翻唱与编辑命令序列含strip-chords、compare、--allow-tempo-change见 SKILL.md 与 editing-workflows.mdPython 级的分阶段调用plan()→generate_semantic()→synthesize()→decode()见 generation-and-covers.md听音对比与评测交付规范见 listening-and-evaluation.md。总而言之YuE2 技能栈的可靠运行建立在三个支柱之上清晰的模型职责边界YuE2-3B 生成、双 VAE 解码分工、SheetSage2 转谱、MERT 仅作可选特征、严格的环境隔离三个 venv、各自固定的依赖版本、以及以文件为媒介的桥接协议音频 → ABC → 编辑 → 再生成。按照本文步骤完成安装后建议先用一次完整的新输出验证环境再进入翻唱或编辑工作流。【免费下载链接】YuEYuE2: frontier music generation with symbolic planning, zero-shot covers, and agentic music editing.项目地址: https://gitcode.com/GitHub_Trending/yue/YuE创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 YuE2 模型配置与环境搭建实战指南：模型选型、多环境隔离与音频到乐谱桥接
YuE2 模型配置与环境搭建实战指南模型选型、多环境隔离与音频到乐谱桥接【免费下载链接】YuEYuE2: frontier music generation with symbolic planning, zero-shot covers, and agentic music editing.项目地址: https://gitcode.com/GitHub_Trending/yue/YuE本文面向想要完整跑通 YuE2 生成、翻唱cover与智能体音乐编辑agentic editing全流程的开发者聚焦于 YuE2 技能栈yue2-musicskill中的模型选型、环境安装与音频到乐谱audio-to-score桥接方案。文中将以 models-and-setup.md 为核心骨架结合仓库源码pyproject.toml、transcribe.py、run_yue2.py、abc_tools.py 等展开深度解析。读完本文你将能够正确选择并区分 YuE2-3B、YuE2-Vae、SheetSage2、MERT-v2 各模型的职责边界在相互冲突的 PyTorch/Transformers/NumPy 版本约束下搭建隔离的运行环境通过 SheetSage2 的transcribeAPI 把任意音频变成可编辑的 ABC 乐谱并与 YuE2 的符号规划symbolic planning无缝衔接。模型全景YuE2 技能栈由哪些模型构成整个yue2-music技能的工作流围绕六个公开模型快照展开。理解它们各自的分工是搭建环境的第一步。下表是各模型在技能中的角色定位模型分发 IDDistribution ID在技能中的角色YuE2-3Bm-a-p/YuE2-3B风格与歌词 →可选的符号规划→ 语义 token → 声学 latent。用于生成以及编辑后的再生成。YuE2-Vaem-a-p/YuE2-Vae默认听音解码器声学 latent → 立体声音频。YuE2-Vae-legacym-a-p/YuE2-Vae-legacy基准解码器。复现记录的评测协议时用它解码同一批 latents。SheetSage2m-a-p/SheetSage2音频 → 旋律、和弦、节拍、调性、结构、ABC 与 MIDI。用于获取翻唱/编辑的起始乐谱或检查生成的音频。MERT-v2-FullSongm-a-p/MERT-v2-FullSongSheetSage2 自动加载的编码器父模型。也可独立用于连续音乐特征提取。MERT-v2-30sm-a-p/MERT-v2-30s面向短录音的可选连续特征提取器。生成、翻唱、编辑流程中不需要它。关于 YuE2-Vae 与 YuE2-Vae-legacy不要因为名字里的 legacy 就主观推断两者的时序关系或质量高低。正确的用法是——听音用YuE2-Vae复现仓库记录的基准评测协议见 docs/benchmarks.md用YuE2-Vae-legacy并在每次运行清单中记录完整的模型名、revision 与哈希。两种解码器产出的音频文件与 manifest 必须分开存放。模型连接链路典型的翻唱链路如下source audio → SheetSage2 (automatically loads its MERT-v2-FullSong parent) → melody_onlyTrue → inspect/correct melody ABC without chord symbols → YuE2-3B with cotmelody, target style, and target lyrics → acoustic latents → YuE2-Vae → listening audio做乐谱编辑score edit时保留或修订和弦符号使用cotfull。做智能体编辑时智能体在规划planning与再生成regeneration两个步骤之间编辑导出的乐谱与提示词不存在额外的智能体专用模型 API——智能体只是编排已有接口。一条必须牢记的模型边界公开的 MERT-v2 编码器返回的是连续特征continuous features不是 YuE2 内部使用的因果离散语义 token ID。因此绝不把 MERT 的 embedding 当作语义 token 喂给 YuE2普通 YuE2 生成不需要单独的 MERT 推理调用MERT 只是 SheetSage2 的编码器父模型由 SheetSage2 自动加载两个公开 MERT 变体都是双向编码器因果 tokenizer 谱系是另一条独立的模型分支。这一点在 SKILL.md 中被重复强调Do not feed public MERT feature tensors to YuE2 as codec tokens。环境隔离为什么必须分开安装这些发布版本各自固定了不同的 PyTorch、Transformers 与 NumPy 版本放在同一个环境里会直接冲突。原则是使用相互独立的环境环境之间只交换音频 / ABC / MIDI 文件共享一个 Hugging Face 缓存目录没有问题各阶段串行执行加载下一个模型前先释放 GPU 显存。从 pyproject.toml 可以看到 YuE2 运行时yue2-infer0.1.6固定的依赖dependencies [ torch2.10.0, transformers4.57.6, huggingface-hub0.36.2, safetensors0.7.0, tiktoken0.12.0, numpy2.2.6, soundfile0.13.1, accelerate1.13.0, ]而 SheetSage2 模型卡要求的环境则固定为 Transformers 4.45.2 与 NumPy 1.24.3并配套 PyTorch 2.8.0。二者版本跨度巨大Transformers 4.45.2 vs 4.57.6、NumPy 1.24.3 vs 2.2.6同环境共存不可行这正是环境隔离成为硬性要求的原因。YuE2 环境搭建发布卡片的目标环境是Linux、Python 3.10、支持 BF16 的 24 GB NVIDIA GPU。安装命令python3.12 -m venv .venv-yue2 .venv-yue2/bin/python -m pip install \ githttps://github.com/multimodal-art-projection/YuE.git也可以从克隆的官方 YuE 仓库安装.venv-yue2/bin/python -m pip install /path/to/YuE。要点包会安装自己固定的依赖上面 pyproject.toml 所列不要从 PyPI 用一个名字相似的未验证包替代当前仓库代码与技能采用 Apache 2.0更早的 v0.1.6 wheel 与技能 ZIP 归档保留其自带许可证详见 LICENSE、THIRD_PARTY_NOTICES.md模型权重由模型仓库独立分发与运行时版本无关安装完成后用主技能中的生成示例SKILL.md 中的scripts/run_yue2.py generate验证一次全新输出再把它当作可复现实验。SheetSage2 环境搭建该接口没有已核验的pip install sheetsage2发行版。正确做法是下载模型快照、安装其 requirements并通过 Transformers 加载。使用 Python 3.10 或 3.11模型卡还要求 FFmpeg 6.1 及其共享库用宿主系统的包/容器工具安装并确认ffmpeg在PATH上python3.11 -m venv .venv-sheetsage2 .venv-sheetsage2/bin/python -m pip install huggingface-hub0.36.0 .venv-sheetsage2/bin/huggingface-cli download m-a-p/SheetSage2 \ --local-dir models/SheetSage2 .venv-sheetsage2/bin/python -m pip install \ torch2.8.0 torchaudio2.8.0 \ --index-url https://download.pytorch.org/whl/cu126 .venv-sheetsage2/bin/python -m pip install \ -r models/SheetSage2/requirements.txt加载适配器快照时模型会自动获取其 config 指定的确切 MERT-v2-FullSong 父模型、校验父模型文件并在 FP32 下合并适配器。因此不要用 MERT-v2-30s 替换那个父模型也不要手工替换成其他 FullSong revisiontrust_remote_codeTrue会执行模型仓库内的 Python 实现务必使用经过审核的 revision并把 revision 与输出一起记录这一下载一次、离线可用的需求正是 transcribe.py 中--offline与--base-model参数存在的意义。转录 API音频到乐谱的桥SheetSage2 通过 Transformers 接口暴露transcribe方法。最小可用示例本地目录加载from pathlib import Path import torch from transformers import AutoModel device cuda if torch.cuda.is_available() else cpu model AutoModel.from_pretrained( models/SheetSage2, trust_remote_codeTrue, ).eval().to(device) result model.transcribe( source.wav, output_dirruns/source-score, dtypebf16 if device cuda else fp32, ) if result.get(abc_error) or not result.get(abc): raise RuntimeError(fNo usable ABC: {result.get(abc_error)}) print(result[warnings]) print(Path(runs/source-score/score.abc))若想直接从 Hub 加载把本地目录替换为仓库 ID并把同一提交分别传给revision与code_revisionmodel AutoModel.from_pretrained( m-a-p/SheetSage2, trust_remote_codeTrue, revisionrecorded-commit, code_revisionrecorded-commit, ).eval().to(device)一步式 melody-only 乐谱翻唱专用技能提供顶层选项melody_onlyTrue同时保留Vocal与Ins两条旋律但从 ABC 中省略和弦符号从播放/合并 MIDI 中省略和弦伴奏。默认的全量转录行为不变。注意该选项只改变导出不改变推理——当所选任务包含和弦预测时原始预测的和弦事件与 LAB 标注仍然可用。try: result model.transcribe( song.mp3, output_dircover-score, melody_onlyTrue, ) except RuntimeError as error: partial getattr(error, result, None) # Completed transcription, if available. if partial is not None: print(partial.get(abc_error), partial.get(warnings, [])) raise abc result[abc] # Also saved in cover-score/score.abc.行为契约如果请求的 melody-only ABC 无法构建Python 侧抛出RuntimeError并把已完成转录挂在error.result上CLI 则以非零码退出。不要把保存了标注当作翻唱乐谱成功。CLI 等价命令.venv-sheetsage2/bin/python models/SheetSage2/infer.py song.mp3 \ --output cover-score --melody-only技能自带助手 transcribe.py 也封装了该能力--task melody-full等价于启用melody_onlyTrue--task melody-vocal额外只选择人声旋律任务。这两个辅助模式不包含和弦预测任务因此不会请求原始和弦预测若需要保留原始和弦标注请使用上面的直接默认任务调用。关于版本兼容旧快照可能没有melody_only关键字。助手的实现transcribe.py 第 44-54 行会通过inspect.signature显式校验该方法是否公开了melody_only参数若不存在则拒绝假设旧的**kwargs包装实现了导出保证——必须把下载的模型代码刷新到显式暴露melody_only的已审核 revision。这一防御性设计说明转录能力以模型仓库代码为准不要依赖未验证的兼容包装。转录完成后把这段无和弦 ABC 交给 YuE2cotmelody 目标风格 目标歌词。完整流程见 SKILL.md 的 Cover a recording 一节。完整可调用接口model.transcribe的完整签名如下参数均有关键字默认值model.transcribe( audio, output_dirNone, *, sampling_rateNone, dtypebf16, # bf16 or fp32 presetdefault, # default or paper prompts(timestamp, downbeat_meter, structure, key, chord_full, melody_full), max_secondsNone, overlap_secondsNone, lookahead_secondsNone, progressNone, export_logitsFalse, export_scoresFalse, export_embeddingsFalse, output_hidden_statesFalse, melody_onlyFalse, # Chord-free ABC and playback when True. render_audioFalse, render_scoreFalse, render_parts(mix,), )逐项行为说明输入解码路径、编码后的音频字节、二进制音频流都会被自动解码、混为单声道并重采样到 24 kHz。数组与张量输入必须提供sampling_rate且形状须为[samples]或[channels, samples]。注意soundfile.read(..., always_2dTrue)返回的是[samples, channels]传入前要先转置。最短输入重采样后至少要有 1,025 个有限样本短片段仍可能因节拍/调性解码信息不足而无法构建 ABC。窗口参数默认使用 300 秒窗口、200 秒重叠、100 秒 lookahead。max_seconds是主动裁剪输入不是仅控内存的设置减小重叠要求0 lookahead overlap 300。presetpaper将重叠固定为 100 秒、lookahead 固定为 0使用记录的音频前端并改变生成停止条件——仅在复现该评测协议连同其记录的任务提示词时使用。导出开关export_logits与各层导出可能很大普通翻唱/编辑流程保持关闭。模型会报告peak_gpu_mib与窗口统计可用于评估具体负载所需显存。如何选择转录任务任务名不是自由文本提示。两条硬约束chord_full与chord_majmin互斥melody_full与melody_vocal互斥时间导出需要timestamp可用 ABC 还需要解码出的节拍与调性信息。比如无和弦条件的人声旋律任务组合result model.transcribe( source.wav, output_dirruns/source-melody, prompts(timestamp, downbeat_meter, structure, key, melody_vocal), melody_onlyTrue, )需要同时保留人声与器乐两条旋律轨时改用melody_full。做和声感知编辑harmony-aware editing时使用默认六任务组合。每次转录后都要检查warnings、diagnostics、abc_error与乐谱再进入再生成——转录即使记谱合法也可能存在音乐性错误。输出产物清单数据内存中的值文件输出ABC 乐谱result[abc]字符串默认全量模式在记谱失败时可返回Nonescore.abc合并播放melody_onlyTrue时省略和弦result[midi]bytestranscription.mid旋律轨result[midis][melody]、melody_vocal、melody_instrumentalbytesmelody.mid、melody_vocal.mid、melody_instrumental.mid和弦播放melody_onlyTrue时无和弦音符result[midis][chords]byteschords.mid定时事件result[events]listresult[num_events]数量events.json标注文本result[labs]映射beat.lab、downbeat.lab、key.lab、chord.lab、structure.lab、旋律 LAB每窗口 token IDresult[tokens]listtokens.json、tokens.txt可选张量result[tensors]按窗口分组的 CPU 张量tensors/指定输出目录时两个易混淆点output_dirNone时推理结果仅驻留内存保存的result.json中events是整数统计量而 Python 结果中是事件列表——两种 schema 不要混用。notation/目录中的伴生文件包含重建乐谱所用的节拍网格、音程与单声部 MIDI原始 MIDI 保留了量化记谱可能简化的时间细节。规范记谱与渲染SheetSage2 导出的 ABC 使用其原生双声部序列化器并对照重建乐谱进行校验。其捆绑模块下载实现中的notation_sheetsage2模块暴露以下函数generate_abc_from_exports(melody_midi_path, *, output_pathNone, meter_conflictinfer, melody_onlyFalse) # - (abc_text, score_object, companion_paths) generate_abc_from_data(melody_midi, beats, chords, keys, structures, *, meter_conflictinfer, melody_onlyFalse) # - (abc_text, score_object) score_to_abc(score_object) # Also validates its own serialization. validate_serialized_abc(text, score_object)注意这些是下载实现中的函数不是通用 ABC 解析器也不是单参数的validate_abc(text)API。新转录可以用顶层melody_onlyTrue选项。对已有的全量转录下面这段代码可在不再次推理的情况下把它保存的旋律重新序列化为无和弦乐谱from importlib import import_module from pathlib import Path package model.__class__.__module__.rsplit(., 1)[0] notation import_module(package .notation_sheetsage2) abc, score, _ notation.generate_abc_from_exports( runs/source-score/notation/song_melody.mid, melody_onlyTrue, ) Path(runs/source-score/melody-only.abc).write_text(abc, encodingutf-8)文件辅助函数要求精确的*_melody.mid文件名以及同级的*_beats.txt、*_keys.txt、*_structures.txt全量乐谱转换还需*_chords.txt。它不会从任意 MIDI 推断节拍网格或调性。智能体撰写的文本请使用技能自带的 ABC 检查见 abc_tools.py 与 abc-editing.md涵盖时长、声部、音高与编辑保持性检查。渲染可选不使用 YuE2 VAE.venv-sheetsage2/bin/python models/SheetSage2/setup_render.py .venv-sheetsage2/bin/python models/SheetSage2/infer.py source.wav \ --output runs/source-score --render-audio --render-score pdf,svg,png .venv-sheetsage2/bin/python models/SheetSage2/render.py \ --input runs/source-score --output runs/source-rendered \ --audio --score pdf,svg,png在极简 Linux 安装上渲染器还提供setup_render.py --with-deps来安装浏览器/渲染依赖。两个重要细节钢琴预览piano preview使用MIDI 音符时序乐谱渲染sheet rendering使用ABC只编辑score.abc不会更新已有的 MIDI随后的钢琴预览仍会播放旧音符。因此先用兼容的 ABC 转换器同步 MIDI再用钢琴音频来判断编辑效果。离线自包含使用model.save_pretrained(models/SheetSage2-merged) offline_model AutoModel.from_pretrained( models/SheetSage2-merged, trust_remote_codeTrue, local_files_onlyTrue, ).eval().to(device)在离线前一次性加载/下载所需文件。纯适配器快照仍需父模型文件合并保存merged save可去掉该依赖。可选 MERT 表征MERT 特征提取适合独立的检索或分析工具。它不是连接 SheetSage2 与 YuE2 的必要环节且embedding 距离小本身不能证明旋律或和声保真度。python3.11 -m venv .venv-mert2 .venv-mert2/bin/python -m pip install \ torch2.6.0 torchaudio2.6.0 transformers4.53.2 \ huggingface-hub safetensors soundfileimport soundfile as sf import torch import torchaudio.functional as AF from transformers import AutoFeatureExtractor, AutoModel repo m-a-p/MERT-v2-FullSong # Or m-a-p/MERT-v2-30s. device cuda if torch.cuda.is_available() else cpu processor AutoFeatureExtractor.from_pretrained(repo, trust_remote_codeTrue) encoder AutoModel.from_pretrained(repo, trust_remote_codeTrue).eval().to(device) audio, rate sf.read(source.wav, dtypefloat32, always_2dTrue) waveform torch.from_numpy(audio[:30 * rate].mean(axis1)) waveform AF.resample(waveform, rate, processor.sampling_rate) inputs processor(waveform.numpy(), sampling_rateprocessor.sampling_rate, return_tensorspt).to(device) with torch.inference_mode(): output encoder(**inputs, output_hidden_statesTrue) mask output.feature_attention_mask[..., None] embedding (output.last_hidden_state * mask).sum(1) / mask.sum(1).clamp_min(1)行为要点两个变体都接受24 kHz 单声道返回25 Hz、1,024 维的帧特征hidden_states恰好包含24 个 post-block 张量索引 0 是 block 1 的输出不是输入 embeddingFullSong 适配整曲30–360 秒示例代码故意只取 30 秒audio[:30 * rate]。做整曲分析时移除该切片保持在意向上下文内更长的录音要显式分块底层模型不提供SheetSage2 的整曲拼接stitchingAPI。分发与许可证边界已核验的模型卡将模型权重标识为CC BY-NC 4.0。技能的许可证不会重新授权这些权重也不会移除其非商业条款代码与依赖保留各自适用的条款。实操要求引导用户阅读每个模型的LICENSE与 THIRD_PARTY_NOTICES.md不要把模型权重、认证材料、缓存数据集或不相关示例打包进技能归档渲染依赖也有各自条款abcjs 为 MIT、Playwright 为 Apache 2.0、Chromium 自带声明、捆绑的 FluidR3 钢琴采样在 CC BY 3.0 US 下需署名。技能可以调用已安装的渲染器而不重新分发这些资产。仓库侧许可证全景见 LICENSE代码、技能与文档Apache 2.0与 MODEL_LICENSE模型权重CC BY-NC 4.0 附加创作者许可。与技能工作流的衔接源码级佐证最后把以上环境与 API 放回yue2-music技能的整体工作流中你会看到每个环节都有对应的可复现性设计转录端transcribe.py 会为每次运行写出input.json源音频名、SHA-256、模型、revision、offline 标志、prompts、melody_only、preset、device、dtype、model_provenance.jsonconfig、快照文件 SHA-256、torch/transformers/huggingface-hub 版本与transcription_manifest.jsonwarnings、产物哈希。这正好落实了本指南记录实际模型与代码 revision的要求——每个运行清单都自带证据。生成端run_yue2.py 通过--cot选择full/melody/off并做输入预检cotmelody时若 ABC 中仍含和弦符号会直接报错提示先用abc_tools.py strip-chordscotoff不接受 ABC。all-modes要求纯文本输入off无法接受 ABC。这与本指南中melody-only 乐谱 →cotmelody的桥接严格对应。记谱方言abc_tools.py 实现的是受限的双声部原生 ABC 方言VocalInsDURATIONS集合{1,2,3,4,6,8,12,16,24,32,48}原生和弦品质集合QUALITIES它刻意不是通用 ABC 解析器。SheetSage2 导出的乐谱与 YuE2 规划的乐谱都遵循这一方言这是转录 → 编辑 → 再生成能够闭环的记谱前提。端到端示例完整的翻唱与编辑命令序列含strip-chords、compare、--allow-tempo-change见 SKILL.md 与 editing-workflows.mdPython 级的分阶段调用plan()→generate_semantic()→synthesize()→decode()见 generation-and-covers.md听音对比与评测交付规范见 listening-and-evaluation.md。总而言之YuE2 技能栈的可靠运行建立在三个支柱之上清晰的模型职责边界YuE2-3B 生成、双 VAE 解码分工、SheetSage2 转谱、MERT 仅作可选特征、严格的环境隔离三个 venv、各自固定的依赖版本、以及以文件为媒介的桥接协议音频 → ABC → 编辑 → 再生成。按照本文步骤完成安装后建议先用一次完整的新输出验证环境再进入翻唱或编辑工作流。【免费下载链接】YuEYuE2: frontier music generation with symbolic planning, zero-shot covers, and agentic music editing.项目地址: https://gitcode.com/GitHub_Trending/yue/YuE创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考