企业官网建设流程全解析

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技能的工作流围绕六个公开模型快照展开。理解它们各自的分工是搭建环境的第一步。下表是各模型在技能中的角色定位：

关于 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_only=True → inspect/correct melody ABC without chord symbols → YuE2-3B with cot="melody", target style, and target lyrics → acoustic latents → YuE2-Vae → listening audio

• 做乐谱编辑（score edit）时：保留或修订和弦符号，使用cot="full"。
• 做智能体编辑时：智能体在规划（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 版本，放在同一个环境里会直接冲突。原则是：

1. 使用相互独立的环境，环境之间只交换音频 / ABC / MIDI 文件；
2. 共享一个 Hugging Face 缓存目录没有问题；
3. 各阶段串行执行，加载下一个模型前先释放 GPU 显存。

从 pyproject.toml 可以看到 YuE2 运行时（yue2-infer0.1.6）固定的依赖：

dependencies = [ "torch==2.10.0", "transformers==4.57.6", "huggingface-hub==0.36.2", "safetensors==0.7.0", "tiktoken==0.12.0", "numpy==2.2.6", "soundfile==0.13.1", "accelerate==1.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 \ git+https://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-hub==0.36.0 .venv-sheetsage2/bin/huggingface-cli download m-a-p/SheetSage2 \ --local-dir models/SheetSage2 .venv-sheetsage2/bin/python -m pip install \ torch==2.8.0 torchaudio==2.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 revision；
• trust_remote_code=True会执行模型仓库内的 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_code=True, ).eval().to(device) result = model.transcribe( "source.wav", output_dir="runs/source-score", dtype="bf16" if device == "cuda" else "fp32", ) if result.get("abc_error") or not result.get("abc"): raise RuntimeError(f"No usable ABC: {result.get('abc_error')}") print(result["warnings"]) print(Path("runs/source-score/score.abc"))

若想直接从 Hub 加载，把本地目录替换为仓库 ID，并把同一提交分别传给revision与code_revision：

model = AutoModel.from_pretrained( "m-a-p/SheetSage2", trust_remote_code=True, revision="<recorded-commit>", code_revision="<recorded-commit>", ).eval().to(device)

一步式 melody-only 乐谱（翻唱专用）

技能提供顶层选项melody_only=True：同时保留Vocal与Ins两条旋律，但从 ABC 中省略和弦符号，从播放/合并 MIDI 中省略和弦伴奏。默认的全量转录行为不变。注意：该选项只改变导出，不改变推理——当所选任务包含和弦预测时，原始预测的和弦事件与 LAB 标注仍然可用。

try: result = model.transcribe( "song.mp3", output_dir="cover-score", melody_only=True, ) 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_only=True；--task melody-vocal额外只选择人声旋律任务。这两个辅助模式不包含和弦预测任务，因此不会请求原始和弦预测；若需要保留原始和弦标注，请使用上面的直接默认任务调用。

关于版本兼容：旧快照可能没有melody_only关键字。助手的实现（transcribe.py 第 44-54 行）会通过inspect.signature显式校验该方法是否公开了melody_only参数，若不存在则拒绝假设旧的**kwargs包装实现了导出保证——必须把下载的模型代码刷新到显式暴露melody_only的已审核 revision。这一防御性设计说明：转录能力以模型仓库代码为准，不要依赖未验证的兼容包装。

转录完成后，把这段无和弦 ABC 交给 YuE2：cot="melody"+ 目标风格 + 目标歌词。完整流程见 SKILL.md 的 "Cover a recording" 一节。

完整可调用接口

model.transcribe的完整签名如下（参数均有关键字默认值）：

model.transcribe( audio, output_dir=None, *, sampling_rate=None, dtype="bf16", # "bf16" or "fp32" preset="default", # "default" or "paper" prompts=("timestamp", "downbeat_meter", "structure", "key", "chord_full", "melody_full"), max_seconds=None, overlap_seconds=None, lookahead_seconds=None, progress=None, export_logits=False, export_scores=False, export_embeddings=False, output_hidden_states=False, melody_only=False, # Chord-free ABC and playback when True. render_audio=False, render_score=False, render_parts=("mix",), )

逐项行为说明：

• 输入解码：路径、编码后的音频字节、二进制音频流都会被自动解码、混为单声道并重采样到 24 kHz。
• 数组与张量输入：必须提供sampling_rate，且形状须为[samples]或[channels, samples]。注意soundfile.read(..., always_2d=True)返回的是[samples, channels]，传入前要先转置。
• 最短输入：重采样后至少要有 1,025 个有限样本；短片段仍可能因节拍/调性解码信息不足而无法构建 ABC。
• 窗口参数：默认使用 300 秒窗口、200 秒重叠、100 秒 lookahead。max_seconds是主动裁剪输入，不是仅控内存的设置；减小重叠要求0 <= lookahead <= overlap < 300。
• preset="paper"：将重叠固定为 100 秒、lookahead 固定为 0，使用记录的音频前端并改变生成停止条件——仅在复现该评测协议（连同其记录的任务提示词）时使用。
• 导出开关：export_logits与各层导出可能很大，普通翻唱/编辑流程保持关闭。模型会报告peak_gpu_mib与窗口统计，可用于评估具体负载所需显存。

如何选择转录任务

任务名不是自由文本提示。两条硬约束：

• chord_full与chord_majmin互斥；
• melody_full与melody_vocal互斥；
• 时间导出需要timestamp；可用 ABC 还需要解码出的节拍与调性信息。

比如"无和弦条件的人声旋律"任务组合：

result = model.transcribe( "source.wav", output_dir="runs/source-melody", prompts=("timestamp", "downbeat_meter", "structure", "key", "melody_vocal"), melody_only=True, )

需要同时保留人声与器乐两条旋律轨时，改用melody_full。做和声感知编辑（harmony-aware editing）时，使用默认六任务组合。每次转录后都要检查warnings、diagnostics、abc_error与乐谱再进入再生成——转录即使记谱合法，也可能存在音乐性错误。

输出产物清单

两个易混淆点：

1. output_dir=None时推理结果仅驻留内存；
2. 保存的result.json中events是整数统计量，而 Python 结果中是事件列表——两种 schema 不要混用。notation/目录中的伴生文件包含重建乐谱所用的节拍网格、音程与单声部 MIDI；原始 MIDI 保留了量化记谱可能简化的时间细节。

规范记谱与渲染

SheetSage2 导出的 ABC 使用其原生双声部序列化器，并对照重建乐谱进行校验。其捆绑模块（下载实现中的notation_sheetsage2模块）暴露以下函数：

generate_abc_from_exports(melody_midi_path, *, output_path=None, meter_conflict="infer", melody_only=False) # -> (abc_text, score_object, companion_paths) generate_abc_from_data(melody_midi, beats, chords, keys, structures, *, meter_conflict="infer", melody_only=False) # -> (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_only=True选项。对已有的全量转录，下面这段代码可在不再次推理的情况下，把它保存的旋律重新序列化为无和弦乐谱：

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_only=True, ) Path("runs/source-score/melody-only.abc").write_text(abc, encoding="utf-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_code=True, local_files_only=True, ).eval().to(device)

在离线前一次性加载/下载所需文件。纯适配器快照仍需父模型文件；合并保存（merged save）可去掉该依赖。

可选 MERT 表征

MERT 特征提取适合独立的检索或分析工具。它不是连接 SheetSage2 与 YuE2 的必要环节，且"embedding 距离小"本身不能证明旋律或和声保真度。

python3.11 -m venv .venv-mert2 .venv-mert2/bin/python -m pip install \ torch==2.6.0 torchaudio==2.6.0 transformers==4.53.2 \ huggingface-hub safetensors soundfile

import 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_code=True) encoder = AutoModel.from_pretrained(repo, trust_remote_code=True).eval().to(device) audio, rate = sf.read("source.wav", dtype="float32", always_2d=True) waveform = torch.from_numpy(audio[:30 * rate].mean(axis=1)) waveform = AF.resample(waveform, rate, processor.sampling_rate) inputs = processor(waveform.numpy(), sampling_rate=processor.sampling_rate, return_tensors="pt").to(device) with torch.inference_mode(): output = encoder(**inputs, output_hidden_states=True) 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 的输出，不是输入 embedding；
• FullSong 适配整曲（30–360 秒）；示例代码故意只取 30 秒（audio[:30 * rate]）。做整曲分析时移除该切片（保持在意向上下文内），更长的录音要显式分块；
• 底层模型不提供SheetSage2 的整曲拼接（stitching）API。

分发与许可证边界

已核验的模型卡将模型权重标识为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技能的整体工作流中，你会看到每个环节都有对应的可复现性设计：

1. 转录端：transcribe.py 会为每次运行写出input.json（源音频名、SHA-256、模型、revision、offline 标志、prompts、melody_only、preset、device、dtype）、model_provenance.json（config、快照文件 SHA-256、torch/transformers/huggingface-hub 版本）与transcription_manifest.json（warnings、产物哈希）。这正好落实了本指南"记录实际模型与代码 revision"的要求——每个运行清单都自带证据。
2. 生成端：run_yue2.py 通过--cot选择full/melody/off，并做输入预检：cot="melody"时若 ABC 中仍含和弦符号会直接报错（提示先用abc_tools.py strip-chords）；cot="off"不接受 ABC。all-modes要求纯文本输入（off无法接受 ABC）。这与本指南中"melody-only 乐谱 →cot="melody""的桥接严格对应。
3. 记谱方言：abc_tools.py 实现的是受限的双声部原生 ABC 方言（Vocal+Ins，DURATIONS集合{1,2,3,4,6,8,12,16,24,32,48}，原生和弦品质集合QUALITIES），它刻意不是通用 ABC 解析器。SheetSage2 导出的乐谱与 YuE2 规划的乐谱都遵循这一方言，这是"转录 → 编辑 → 再生成"能够闭环的记谱前提。
4. 端到端示例：完整的翻唱与编辑命令序列（含strip-chords、compare、--allow-tempo-change）见 SKILL.md 与 editing-workflows.md；Python 级的分阶段调用（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