YuE2 歌曲生成实战指南：从风格与歌词到 48kHz 立体声的完整管线

YuE2 歌曲生成实战指南从风格与歌词到 48kHz 立体声的完整管线【免费下载链接】YuEYuE2: frontier music generation with symbolic planning, zero-shot covers, and agentic music editing.项目地址: https://gitcode.com/GitHub_Trending/yue/YuE本篇技术指南完整讲解如何在本地运行 YuE2 的端到端歌曲生成流程从书写风格提示style与带段落标签的歌词lyrics到符号化规划symbolic planning生成可编辑的旋律与和弦乐谱再到语义 token 生成、声学隐变量合成与 VAE 解码输出 48 kHz 立体声音频。你将掌握 YuE2 的 Python 分阶段 APIplan()→generate_semantic()→synthesize()→decode()、一键式save_artifacts()产物保留机制、符号计划的保存/校验/复用方法以及如何显式选择聆听解码器与基准解码器从而获得可复现、可审计的完整生成记录。运行环境与安装YuE2 的安装与运行前提在 docs/generation.md 中有明确约定并在 README.md 的 Quick Start 中得到印证Python 3.12从仓库根目录执行python -m pip install .完成安装受支持的起点配置为支持 BF16 的 NVIDIA GPU 且显存不低于 24 GB同时一次只处理一个请求CLI 的batch命令也明确要求concurrency1见 src/yue2/cli.py默认输出为48 kHz 立体声启用完整符号化规划full symbolic planning并使用聆听解码器YuE2-Vae模型权重在首次使用时从 Hugging Face 自动下载m-a-p/YuE2-3B与m-a-p/YuE2-Vae也支持本地模型目录。一个典型的快速启动流程为python3.12 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install . python examples/generate.py --output outputs/first-song运行结束后outputs/first-song/目录中会同时保留乐谱、语义 token、声学隐变量、生成配置与模型身份信息具体构成见后文输出产物与可复现性一节。从源码看YuE2Pipeline在 CUDA 环境下会主动检查torch.cuda.is_bf16_supported()未量化预设unquantized preset强制要求 BF16 支持同时通过set_per_process_memory_fraction将进程显存限制在memory_budget_gib - 2GiB保留 2 GiB 余量见 src/yue2/pipeline.py。这也解释了为什么 24 GB 显存是受支持的推荐起点。风格、歌词与符号化规划YuE2 的输入协议非常简洁风格style 歌词lyrics即可驱动一次完整生成。约定如下style中集中描述曲风、乐器、人声特质、语言与速度tempolyrics中写入要演唱的歌词文本并用[Verse]、[Chorus]等段落标签标注结构推荐直接以仓库中的 examples/song.json 为起点修改。examples/song.json的完整内容为{ id: city_lights, style: English, warm piano pop, expressive female voice, acoustic piano, rounded bass and light drums, lyrical memorable melody, unhurried phrasing, 88 BPM, lyrics: [Verse]\nNeon fades along the lane\nFootsteps keep the time of rain\nFold the night and leave it here\nMorning has a sky to clear\n\n[Chorus]\nLet the day come into view\nEvery road begins with you\nHold a little room for light\nWe will sing beyond the night, cot: full, seed: 831001 }其中seed默认 831001用于控制采样随机性id是文件名安全的请求标识正则约束为[A-Za-z0-9][A-Za-z0-9_.-]{0,179}见 src/yue2/protocol.py。Python 端到端生成的最小代码为import json from pathlib import Path from yue2 import YuE2Pipeline request json.loads(Path(examples/song.json).read_text(encodingutf-8)) with YuE2Pipeline.from_pretrained(m-a-p/YuE2-3B, devicecuda) as pipe: song pipe(**request) song.save_artifacts(outputs/song) print(song.truncated)cot三种符号化规划模式cotchain-of-thought字段控制符号化规划的深度取值与语义在 src/yue2/protocol.py 的INSTRUCTIONS中定义cot取值含义full先生成带和弦标注的 ABC 乐谱melody chords再据其生成音乐新歌创作默认值melody仅生成旋律线无和弦符号的 ABC 转写伴奏自由封面cover推荐off不生成符号计划直接从歌词与风格条件生成 codec token此外向请求提供abc字段可以直接使用一份现成的 ABC 乐谱作为输入但必须配合full或melody模式off模式不接受 ABCSongRequest的校验会直接抛错见 src/yue2/protocol.py。关于原生 ABC 输入需要特别注意两点原生旋律输入使用Vocal与Ins两个声部Ins承载器乐主题/独奏而非钢琴和弦织体且不含和弦符号任意 ABC 方言可能需要转换才能被接受skills/yue2-music/references/abc-editing.md 详细描述了受支持的原生记谱法小节划分、L:1/32节奏网格、临时记号与延音线语义、和弦符号词汇表等值得在提交自定义乐谱前通读。从源码实现看当提供外部 ABC 时pipe.plan()会直接tokenizer.encode(request.abc)将其编码为 token ID而不经过任何模型推理见 src/yue2/pipeline.py因此自带乐谱的规划阶段几乎是零开销的。cfg_scale 与候选生成一次 pipeline 调用产生一个候选评测流程中的候选选择如 README 中 best-of-8是独立于生成之外的评估步骤不属于单次调用范围。cfg_scale控制文本引导强度即 classifier-free guidance 的权重。协议层默认值cotfull/melody时为 1.0cotoff时为 1.01合法取值范围为[0, 20]见 src/yue2/protocol.py。文档明确提示默认采样与引导参数开箱即用随意更改采样或引导参数可能改变生成质量——在未理解其影响前不建议调整。命令行等价操作Python API 的 CLI 等价命令为yue2 generate --request examples/song.json --output outputs/song-cliyue2CLI 与 Python pipeline 共享同一套默认值与产物协议见 src/yue2/cli.py支持以下关键参数参数说明--model生成模型默认m-a-p/YuE2-3B或本地models/YuE2-3B目录--vaestandard聆听解码器/legacy论文评估解码器/ 本地路径 / HF 仓库--revision/--vae-revision固定模型与 VAE 的远程 revision--device默认autocuda → mps → cpu--budget显存预算GiB默认 24 12时自动将 VAE 分块核心帧数降至 512--backendtorch默认/torch-eager/vllm--quantizationnone默认/fp8--offload-ar合成阶段将 AR 模型卸载到 CPU降低显存占用--offline等价于local_files_onlyTrue仅使用本地缓存--config以 JSON 文件覆盖GenerationConfigabc/semantic 采样参数等--cot覆盖请求中的规划模式--stageplan只做规划并保存/audio默认完整生成--resume输出目录已有result.json时校验并复用不重新生成--quiet/--no-progress隐藏 stderr 进度保留 stdout 结果此外 CLI 还提供yue2 doctor环境自检依赖版本、CUDA 设备、模型权重哈希与yue2 batch --input requests.jsonl每行一个带唯一id的 JSON 请求串行批量生成。这些命令的可用性在 tests/test_cli_public.py 中有对应测试覆盖。先生成并检查符号计划再进行合成YuE2 的管线是白盒的你可以先只做符号化规划、保存并检查乐谱确认无误后再继续语义生成与音频合成。这在检查创作意图和编辑乐谱后重新渲染两类场景中非常有用。import json from pathlib import Path from yue2 import YuE2Pipeline, SymbolicPlan request json.loads(Path(examples/song.json).read_text(encodingutf-8)) with YuE2Pipeline.from_pretrained(m-a-p/YuE2-3B, devicecuda) as pipe: plan pipe.plan(**request) plan.save(outputs/plan) restored SymbolicPlan.load(outputs/plan) semantic pipe.generate_semantic(restored) latents pipe.synthesize(semantic) audio pipe.decode(latents) import soundfile as sf sf.write(outputs/plan/audio.flac, audio, 48000)这里展示的plan()→generate_semantic()→synthesize()→decode()正是pipe(**request)内部完整调用的四个阶段见 src/yue2/pipeline.py分阶段调用让你能在任意阶段介入plan()生成或直接编码外部ABC 符号计划返回SymbolicPlangenerate_semantic()基于计划与请求前缀自回归生成语义音乐 token该阶段会对plan.prefix与请求 精确 ABC token ID的一致性做校验不一致直接抛错synthesize()用 NAR非自回归流匹配模型把语义 token 合成为声学隐变量默认 32 步中点法 ODEcontext24576见 src/yue2/protocol.pydecode()VAE 将隐变量解码为 48 kHz 立体声音频默认decode_tiled分块解码core_frames1024、halo_frames16并校验音频有限性与幅值裁剪。SymbolicPlan 的保存、校验与修改纪律SymbolicPlan.save(directory)会写入一组文件实现见 src/yue2/pipeline.pyscore.abcABC 乐谱文本存在时abc_tokens.npyABC 的精确 token ID 数组prefix.npy发送给模型的完整前缀 token 序列plan.json请求、时间统计、截断标志与上述 token 的 JSON 备份plan_manifest.json上述每个文件的SHA-256 摘要清单。而SymbolicPlan.load(directory)则原样恢复精确的 token ID 并校验全部保存文件逐一核对plan_manifest.json中的哈希任何文件缺失、被修改或为符号链接都会抛错Saved plan changed; supply modified ABC as an external planner input将plan.json中记录的 token 与npy数组逐元素比对防止不一致校验score.abc文本与plan.json中内嵌的abc完全一致。这套机制保证了加载即原样SymbolicPlan.load只用于复用未变更的计划。若要修改创作内容正确做法是复制score.abc为副本、编辑该副本然后作为新的abc输入提交cot保持full或melody而不要原地修改已保存的计划。对绝大多数场景端到端的save_artifacts()是保留完整生成记录的最简路径CLI 的examples/generate.py --abc-file edited.abc --cot full即采用该模式。输出产物与可复现性save_artifacts(directory)会将一次完整生成沉淀为一个可审计的目录实现见 src/yue2/pipeline.py文件内容audio.flac48 kHz 立体声音频FLAC24-bit PCMscore.abc本次生成的符号乐谱适用时off模式无plan.json/abc_tokens.npy/prefix.npy/plan_manifest.json符号计划及其完整性清单semantic.npy语义音乐 token 序列latent.npy声学隐变量float32request.json/config.json请求参数与有效生成配置含后端、量化、VAE 分块参数、运行时 SHA-256 等result.json状态、请求-配置-权重三元组的身份哈希identity、truncated标志、音频时长、各阶段耗时与全部产物的哈希清单需要重点理解的三个约定truncated标志result.json中记录{abc: ..., semantic: ...}两个阶段的截断标志。即使模型在 token 上限处被截断保存的音频仍然可能可播放因此应通过song.truncated或result.json判断完整性而不是仅凭能否出声。目录纪律每次变更请求都应使用全新的输出目录CLI 遇到非空输出目录会直接报错除非显式--resume并且在对比实验中保留失败记录CLI 会把异常写入failure.json。这与verify_result的全量哈希校验见 src/yue2/storage.py共同保证了目录内容与result.json的一致性。身份哈希request.json、config.json与模型权重指纹weights共同参与 SHA-256 身份计算--resume时verify_result会比对身份任何请求/配置/权重变化都会被识别并要求使用新目录。固定模型与解码器版本from_pretrained完整支持的参数见 src/yue2/pipeline.pymodelHF 仓库名或本地模型目录vae解码器仓库名/本地目录revision与vae_revision分别为生成模型与 VAE 固定 revisioncache_dir自定义 Hugging Face 缓存目录local_files_onlyTrue纯离线模式仅用本地缓存token私有仓库访问令牌。示例with YuE2Pipeline.from_pretrained( m-a-p/YuE2-3B, vaem-a-p/YuE2-Vae-legacy, revisioncommit, vae_revisioncommit, local_files_onlyTrue, devicecuda, ) as pipe: ...可复现性要点对比实验必须同时固定模型与 VAE 的 revision或直接使用本地目录文档明确提示不同的 GPU、运行时版本或采样设置都可能改变给定种子的生成结果——seed只保证同一环境下可复现不跨环境保证逐位一致。聆听与评估解码器显式选择分目录管理YuE2 提供两个 VAE 解码器用途不同不能混为一谈解码器用途YuE2-Vae默认生成与聆听解码器YuE2-Vae-legacy复现论文/仓库公布的基准评测协议显式选择第二个解码器with YuE2Pipeline.from_pretrained(m-a-p/YuE2-3B, vaem-a-p/YuE2-Vae-legacy, devicecuda) as pipe: ...实操纪律聆听音频与评估音频分目录存放避免混淆哪份产物用的是哪个解码器在比较两个解码器时应对同一份缓存的隐变量重新解码而不是为每个解码器重新生成一首新歌——这样才能隔离解码器差异排除采样差异。这一步可以直接用技能脚本完成python skills/yue2-music/scripts/run_yue2.py decode \ --source outputs/song --output outputs/song-benchmark \ --vae m-a-p/YuE2-Vae-legacyrun_yue2.py decode的行为在源码中得到印证见 skills/yue2-music/scripts/run_yue2.py它会先verify_result(source)验证源产物完整性、通过SymbolicPlan.load恢复计划、读取缓存的semantic.npy与latent.npy再以指定的 VAE 重新解码同时强制要求--model与源生成的模型身份一致并在结束时校验重解码前后的latent.npySHA-256 完全一致Latents changed during re-decoding从而保证解码对比只改变解码器这一变量。最后需要明确边界基准测试的结论只对应其声明所用的评估模型与解码器你自己在本地做一次新的生成并不等同于对已公布聚合分数的复现。相关协议细节可进一步参考 docs/benchmarks.md封面与编辑流程则见 docs/covers.md 与 docs/editing.md。进阶采样配置与协议层默认值若需要深入调整生成行为GenerationConfig见 src/yue2/protocol.py提供了两套独立采样配置abc规划阶段默认值Sampling(.7, .9, 30, 1.005, 100, 32, 4096)即 temperature 0.7、top-p 0.9、top-k 30、重复惩罚 1.005、惩罚窗口 100、最少 32 token、最多 4096 tokensemantic语义阶段默认值Sampling(1.0, .95, 100, 1.2, 50, 200, 9000)全局ode_steps32中点法、context24576协议强制要求该值见__post_init__校验。Sampling各字段均有约束temperature ∈ [0, 5]、top_p ∈ (0, 1]、top_k ≥ 1、penalty_window ∈ [1, 100]、0 ≤ min_tokens ≤ max_tokens非法组合直接抛ValueError。你可以通过构造GenerationConfig或 CLI--configJSON覆盖这些默认值也可以在调用时以字典形式传入abc_sampling/semantic_sampling覆盖单次采样的部分字段——但请记住文档的告诫默认值是为质量准备的修改采样与引导可能改变生成质量。架构总览YuE2 中风格与歌词先进入 AR–NAR 混合 Transformer 生成可编辑乐谱与语义 token再以流匹配合成声学隐变量最终由 VAE 解码为 48 kHz 立体声音频示意图见 assets/architecture.pngREADME 的 How it works 一节有对应文字说明。创建、封面与编辑三种任务的区别仅在于乐谱来源YuE2 自行生成、对录音转写、或人工编辑后的乐谱。小结围绕 YuE2 的生成流程本文覆盖了从环境安装、请求协议stylelyricscot到四阶段管线、符号计划校验、产物完整性与解码器选择的全链路。实践中最值得记住的四条纪律是用全新目录保留每一次变更版本用SymbolicPlan.load复用未变更计划、用新abc输入表达修改固定模型与 VAE revision 后再谈可复现比较解码器时对同一份缓存的隐变量重解码。遵循这些约定你就能把 YuE2 当作一个可审计、可干预、可复现的白盒音乐创作工具来使用。【免费下载链接】YuEYuE2: frontier music generation with symbolic planning, zero-shot covers, and agentic music editing.项目地址: https://gitcode.com/GitHub_Trending/yue/YuE创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考