• 音乐生成
  • 大模型
  • 人工智能
  • 媒体生成

【免费下载链接】YuE2-3B

项目地址: https://ai.gitcode.com/hf_mirrors/m-a-p/YuE2-3B
点击查看 免费下载

YuE2 是一个开源音乐生成模型,能够把一段歌词与一个风格提示词(style prompt)转化为带人声和伴奏的完整歌曲,并支持通过可编辑的 ABC 乐谱来塑形旋律与和声。本文基于当前仓库的 README.md、核心推理源码 与示例配置文件,完整讲解 YuE2-3B 的本地安装、三种生成模式(创建 / Cover / 编辑与 Agentic 编辑)、模型架构(AR–NAR 混合 Transformer + Flow Matching + VAE)以及推理性能与基准数据,帮助你快速跑通并深入理解这一套"符号规划 + 可编辑乐谱"的音乐生成方案。

关联演示音频:本文提及的全部示例音频(Cyber Metal、今晚不眠、Passion、Auld Lang Syne Jazz-funk cover、最炫民族风 ballad cover、Jingle Bells heavy metal cover)及对应参数元数据均收录于 assets/audio/examples.json。

YuE2 architecture

YuE2 的整体架构:一个 AR–NAR Mixture-of-Transformers 骨干网络先写出乐谱与语义 token,再通过 flow matching 生成声学 latent,最后由 VAE 还原为立体声音频。

概览:YuE2 的核心能力

YuE2 是面向歌曲质量的开放音乐生成模型。 它的核心流程是:给定歌词(lyrics)与风格提示词(style prompt),先生成一个符号化的音乐规划(symbolic plan,即 ABC 乐谱形式的旋律 + 和弦),再依据该规划渲染出带人声与伴奏的完整歌曲。这一"符号规划 + 编辑"的设计让用户能够:

  • 创作与编辑(Compose and edit):支持"旋律 + 和弦"、"仅旋律"以及"无规划直接生成"三种模式;也支持自己提供 ABC 乐谱作为输入;
  • Agent 化编辑(Edit with an agent):把音乐反馈转成乐谱、风格与歌词的修订,再由 YuE2 渲染下一版本(官方提供了 9 步 14 个版本的多轮编辑演示);
  • 本地运行(Run locally):在 24GB 显存 GPU 上无需量化即可生成 48 kHz 立体声歌曲;
  • 可扩展构建(Build on it):支持 Hugging Face 加载、文本引导(CFG,classifier-free guidance)以及分离的规划 / 合成 API(pipe.plan() → pipe.generate_semantic() → pipe.synthesize() → pipe.decode())。

许可证提示:模型权重采用 CC BY-NC 4.0(见 LICENSE),第三方代码许可见 THIRD_PARTY_NOTICES.md(其中 VAE 的 Oobleck/SnakeBeta 实现源自 stable-audio-tools 与 NVIDIA BigVGAN,均保留 MIT 许可)。

环境要求与安装

官方 Quick start 对运行环境的要求是:

  • Linux 操作系统;
  • Python 3.10 及以上;
  • 24GB NVIDIA GPU,且支持 BF16(bfloat16)精度。

安装推理包(注意需要先固定 huggingface-hub==0.36.2 以兼容 hf download 命令):

python -m pip install huggingface-hub==0.36.2
hf download m-a-p/YuE2-3B yue2_infer-0.1.5-py3-none-any.whl --local-dir .
python -m pip install ./yue2_infer-0.1.5-py3-none-any.whl

当前仓库内同时提供了 yue2_infer-0.1.3-py3-none-any.whl 与 yue2_infer-0.1.5-py3-none-any.whl 两个版本的推理包,README 以 0.1.5 为准。

安装完成后,加载一次 Pipeline 即可复用(后续示例均基于此 pipe 对象):

from pathlib import Path
from yue2 import YuE2Pipeline

pipe = YuE2Pipeline.from_pretrained("m-a-p/YuE2-3B", device="cuda")

from_pretrained 还支持几个重要参数:

  • device="cuda":指定推理设备;
  • progress=False:关闭生成过程中的英文进度消息(包括当前阶段、已用时间与 token 吞吐量),命令行对应 yue2 generate --quiet / yue2 batch --quiet;
  • vae="m-a-p/YuE2-Vae-legacy":切换解码器(详见下文"VAE 的选择")。

模式一:创作(Create)——从歌词生成完整歌曲

把一段风格提示词和歌词变成一首带人声与伴奏的完整歌曲。仓库在 examples/tonight-awake.json 中提供了演示曲目《今晚不眠》的完整风格与歌词(即上文音频演示中的 Mandarin funk / nu-disco 曲目),其中 style 字段包含风格描述、lyrics 字段为带章节标记([Intro]/[Verse]/[Pre-Chorus]/[Chorus]/[Bridge]/[Outro])的完整歌词、seed 为 12300、cot 为 "full"。

import json
from huggingface_hub import hf_hub_download

repo = "m-a-p/YuE2-3B"
prompt_path = hf_hub_download(repo, "examples/tonight-awake.json")
demo = json.loads(Path(prompt_path).read_text(encoding="utf-8"))
style, lyrics = demo["style"], demo["lyrics"]

song = pipe(style=style, lyrics=lyrics, cot="full", seed=demo["seed"])
song.save("song.flac")
song.save_artifacts("outputs/song")  # ABC, tokens, latents, audio and settings

save_artifacts("outputs/song") 会把本次生成的全部中间产物写入目录:ABC 乐谱(score.abc)、token、latent、音频与生成设置,这些正是后续"编辑"流程的数据基础。

默认参数已开箱可用:cot="full" 与默认的 YuE2-Vae。常用生成选项如下:

选项作用
cot="full"旋律 + 和弦规划(默认)
cot="melody"仅旋律规划;Cover 场景推荐
cot="off"不生成符号规划,直接生成
cfg_scale=1.2尝试更强的文本引导强度

从仓库的 yue2_generation_config.json 可以看到各生成阶段的默认采样参数(这些参数由推理包读取,可作为理解默认行为的参考):

  • ABC 乐谱采样:temperature=0.7、top_p=0.9、top_k=30、repetition_penalty=1.005、penalty_window=100、min_tokens=32、max_tokens=4096——ABC 规划使用较低温度与强重复惩罚,保证乐谱结构稳定;
  • Semantic(语义 token)采样:temperature=1.0、top_p=0.95、top_k=100、repetition_penalty=1.2、penalty_window=50、min_tokens=200、max_tokens=9000——语义 token 使用更高温度与 1.2 的重复惩罚,以维持歌声的自然度;
  • 声学 ODE:ode_steps=32、ode_method="midpoint"——flow matching 使用 32 步中点法求解;
  • 上下文长度:context=24576,与模型 max_position_embeddings 一致。

模式二:Cover——把已有歌曲改编成新编曲

Cover 流程从一段已有录音出发,生成一个新的编曲版本。官方建议 Cover 使用仅旋律模式(cot="melody")。整个流程分三步:

  1. 获取乐谱(Get the score):用 SheetSage2 转录原曲,把不含和弦符号的旋律 ABC 保存为 melody.abc;
  2. 获取歌词(Get the lyrics):让 Agent 在线查找歌词,或用 Qwen3-ASR / Gemini API 转录人声;核对歌词后按录音的段落结构组织,保存为 cover_lyrics.txt;
  3. 选择目标风格并生成(Choose a target style and generate):审阅或编辑乐谱与歌词后,以 cot="melody" 加目标风格提示词交给 YuE2。

转录工具应在各自独立的环境中运行,然后用 YuE2 Pipeline 生成:

cover = pipe(
    style="Jazz-funk, warm lead vocal, Rhodes piano, electric bass, tight drums",
    lyrics=Path("cover_lyrics.txt").read_text(encoding="utf-8"),
    abc=Path("melody.abc").read_text(encoding="utf-8"),
    cot="melody", seed=831001,
)
cover.save("cover.flac")
cover.save_artifacts("outputs/cover")

注意:cot="melody" 不会自动去除和弦符号。如果你希望在 Cover 时同时提供原始或改编后的和声,应使用 cot="full"。

模式三:编辑与 Agentic 编辑——修改乐谱后重新渲染

编辑模式让你自己修改 ABC 乐谱,或者把乐谱、原始提示词、歌词和修改要求交给一个 Agent;Agent 可以重新配和声(reharmonize)、发展独奏(develop a solo)、改编歌词与风格,而 YuE2 负责把每个修订版渲染成音频。

获取一个规划(plan):对于上面"创作"流程生成的歌曲,复制 outputs/song/score.abc 为 edited.abc。如果只想先拿到规划(先不出音频),可用相同的提示词与 seed 调用 plan:

plan = pipe.plan(style=style, lyrics=lyrics, cot="full", seed=demo["seed"])
plan.save("original_plan")
# 保留原版,并把副本编辑为 edited.abc。

严格的重新配和声(strict reharmonization)建议:让 Agent 保持旋律的音高与节奏,并核对长音与新的和弦是否协调;若希望更大幅度的改编,则可允许选定的旋律或歌词改动。审阅 edited.abc 后,用修订后的风格重新生成(本例沿用"创作"流程的歌词与 seed):

edited_style = (
    "Jazz, expressive lead vocal, piano, tenor saxophone, upright bass, "
    "brushed drums, no guitar, spacious modern harmony"
)
song = pipe(style=edited_style, lyrics=lyrics, cot="full", seed=demo["seed"],
            abc=Path("edited.abc").read_text(encoding="utf-8"))
song.save("edited.flac")
song.save_artifacts("outputs/edited")

分阶段 API 与 CFG 细节(README 中以可折叠块给出的补充说明):

  • 完整调用链为 pipe.plan() → pipe.generate_semantic(plan) → pipe.synthesize(semantic) → pipe.decode(latents);使用完毕调用 pipe.close() 释放资源;
  • 每个 CoT 模式选择其原生的指令(instruction);Semantic 阶段的 CFG 默认值:full/melody 为 1.0,off 为 1.01;ABC 乐谱采样不使用 CFG;
  • 生成默认显示英文进度消息(当前阶段、耗时、token 吞吐量),可用 from_pretrained(repo, progress=False) 或命令行 yue2 generate --quiet / yue2 batch --quiet 关闭;
  • 如需复现论文基准的解码器,在 from_pretrained 时传 vae="m-a-p/YuE2-Vae-legacy"。

源码级解析:AR–NAR 混合 Transformer 骨干

README 用一张架构图概括了模型主干,仓库中的 modeling_yue2.py 则提供了自包含的推理实现(通过 Transformers trust_remote_code 加载,不依赖 CUDA 扩展),可以从源码结构确认其设计:

  • Mixture-of-Transformers(MoT)双层路由:DecoderLayer 同时包含 AR 与 NAR 两套独立的 QKV 投影、LayerNorm 与 MLP;在前向计算中按 ar_mask 对每个位置选择 AR 或 NAR 路径(torch.where 按位置合并 Q/K/V 与 MLP 输出),AR 模式(生成阶段)则只走 AR 路径;
  • AR 因果语言模型(generate):YuE2ForCausalLM.forward 是标准带 KV cache 的因果 LM 前向,负责写乐谱与语义 token;推理包在此基础上结合 CUDA graphs 与 FlashAttention 加速;
  • NAR flow matching(ODE):nar_velocity 计算流匹配的速度场 v_theta(x_t, t)(modeling_yue2.py)。它把 token 词嵌入、vae2llm(x_t) 映射的 latent、正弦时间步嵌入(TimestepEmbedder)与音频 latent 位置编码(AudioPositionEmbedding)在 NAR 位置融合,并构造混合注意力掩码——AR→AR 因果、NAR→AR 全连接、NAR→NAR 双向、AR→NAR 屏蔽;时间步通过 timestep_shift(配置默认 1.0)做 sigmoid 偏移;
  • 静态 KV Cache:StaticKVCache 为显式单请求 AR 循环提供有界、只追加的缓存,超限时抛出异常而不是悄悄截断生成;
  • 配置事实:config.json 中 architectures=["YuE2ForCausalLM"]、model_type="yue2",auto_map 指向本仓库的 YuE2Config/YuE2ForCausalLM;模型为 28 层、hidden size 2048、16 个注意力头 / 8 个 KV 头、intermediate_size=6144、词表 184704,latent_type="vae"、latent_dim=64、max_latent_frames=24576、timestep_shift=1.0。权重文件 model.safetensors 约 7.26 GB(见 weights_manifest.json)。

阶段流水线的完整链路

把 README 的操作与源码对照,一次完整生成可拆解为:

  1. plan:由歌词 + 风格 + CoT 模式生成 ABC 乐谱(旋律与和弦的符号规划);
  2. generate_semantic:在规划条件下生成语义 token(歌声内容);Semantic CFG 在此阶段生效;
  3. synthesize:以语义 token 为条件,通过 flow matching(ode_steps=32、midpoint 法)生成声学 latent;
  4. decode:VAE 把 latent 解码为 48 kHz 立体声 PCM。

VAE 的选择

README 的"Choosing a VAE"一节给出的结论是:基准对比中,YuE2-Vae-legacy 的音乐性(musicality)分数更高,而 YuE2-Vae 的感知音频质量更好。因此默认使用 YuE2-Vae;只有复现论文基准结果时才改用 YuE2-Vae-legacy(vae="m-a-p/YuE2-Vae-legacy")。THIRD_PARTY_NOTICES.md 说明 VAE 的 Oobleck 与 SnakeBeta 实现分别源自 stable-audio-tools(MIT)与 NVIDIA BigVGAN(MIT),保留原始许可。

性能与资源

一条关键数据:在 RTX 4090 上,一首 3.6 分钟的歌曲只需 71 秒即可生成。 HF 推理包基于 PyTorch、CUDA graphs 与 FlashAttention,AR/NAR 使用 BF16、VAE 使用 FP32。

GPUCoT预热样本LM tokens/s生成 / 音频耗时峰值显存
RTX 4090 24GBfull32139.4871.04 / 214.85 s11.18 GiB
RTX 4090 24GBmelody32139.3268.68 / 214.67 s11.02 GiB
RTX 4090 24GBoff32121.0757.91 / 196.88 s11.09 GiB
H800 80GBfull1164.3854.74 / 224.96 s10.34 GiB

资源建议:一次只生成一首歌曲;需要 24GB GPU 和 24GB 可用主机内存;最大上下文测试峰值显存为 14.08 GiB。

README 还给出了一个独立的 H800 服务器(vLLM 0.19,full CoT) 并发服务数据,它用于并发请求:

AR 并发上限LM system tokens/s歌曲/小时峰值显存
1378.42119.4378.55 GiB
162418.63340.3878.66 GiB
323231.74373.5376.61 GiB

测量口径说明:HF 环境为 PyTorch 2.10、Transformers 4.57.6、无量化、默认 YuE2-Vae;4090 为每种模式 32 次预热请求的平均值,H800 为单曲下载与生成的检查;耗时为同步 Pipeline 调用(不含路径解析与保存),显存由 NVML 记录整轮峰值。服务器行每行为 32 首歌;AR/NAR 使用 PyTorch 2.10 与 Triton 3.6,VAE 使用 PyTorch 2.6;歌曲/小时是各阶段全部完成后的 warm batch 吞吐(非请求延迟);TPS 对输出 token 只计一次,不含前缀、提供的 ABC 与第二条 CFG 分支;显存包含预留 KV cache。该服务器运行环境与 HF Quick start 相互独立。

基准结果:WildSongBench 与 SHS100K

WildSongBench · 整曲生成

README 报告了 YuE2(含 best-of-8)在 192 个 prompt 上与开源及闭源模型的对比(图中还给出了音乐性与文本对齐的可视化,见 assets/figure1.png,矢量版见 assets/figure1.pdf / assets/figure1.svg)。

开源模型(节选):

ModelMusicality ↑SongBench Avg ↑MuLan ↑AllMusicCaps ↑Q3O ↑PER ↓
YuE 14.08474.91650.26230.28823.730136.38%
LeVo 25.45906.32470.35420.26803.945826.12%
ACE-Step 1.55.15886.01180.43720.38694.58097.46%
MiniMax Music 35.34826.28300.39280.36094.43626.27%
YuE25.90756.73160.50680.40544.68198.44%
YuE2 (best-of-8)6.26666.96320.50510.39804.70099.79%

闭源模型(节选):

ModelMusicality ↑SongBench Avg ↑MuLan ↑AllMusicCaps ↑Q3O ↑PER ↓
Suno v55.99186.87210.54280.43534.59078.10%
Suno v65.65586.55620.49160.43054.62587.58%
Mureka 96.04886.93770.43940.41024.636811.69%
YuE25.90756.73160.50680.40544.68198.44%
YuE2 (best-of-8)6.26666.96320.50510.39804.70099.79%

192 个 prompt。两个 YuE2 设置均使用符号规划与 YuE2-Vae-legacy;标准 YuE2 从两个候选中选择,best-of-8 从八个候选中选择。

SHS100K · 零样本 Cover 生成

MethodCLEWS mAP ↑CLEWS Hit@1 ↑VINet mAP ↑MuLan ↑Musicality ↑
SongEcho0.41948.4%0.1220.3663.286
ACE-Step 1.50.0242.4%0.0060.1663.689
YuE2 (full score)0.64771.3%0.2880.3825.104
YuE2 (without chords)0.59867.3%0.1790.4175.490
YuE2 (without score)0.0060.3%0.0040.4745.691

948 首作品 × 2 种风格 × 2 个 seed,每个方法 3,792 首歌,无候选选择;基于乐谱的变体使用提供的源乐谱;所有 YuE2 变体使用 YuE2-Vae-legacy。

评估协议要点:WSB 的 SongBench Avg 对七个维度取平均;Q3O 为 0–5 刻度的提示遵循度;PER 为音素错误率;标准 YuE2 从两个候选中选 PER 更低者,best-of-8 按 Musicality → Q3O → PER 顺序选择,每个候选的 PER 取四次 ASR 中最低者。SHS100K 中 CLEWS 与 Discogs-VINet 衡量在排除源录音(10,545 条)后保留的歌曲身份,MuLan 衡量目标风格相似度,Musicality 来自 SongBench;身份与质量指标需一起解读。这些都是声明了候选选择协议下的自动评测结果。

引用与许可

官方技术报告尚未发布("Technical report coming soon"),当前建议在研究中引用 YuE 论文(arXiv:2503.08638):

@article{yuan2025yue,
  title = {{YuE}: Scaling Open Foundation Models for Long-Form Music Generation},
  author = {Yuan, Ruibin and Lin, Hanfeng and Guo, Shuyue and Zhang, Ge and Pan, Jiahao and Zang, Yongyi and Liu, Haohe and Liang, Yiming and Ma, Wenye and Du, Xingjian and Du, Xinrun and Ye, Zhen and Zheng, Tianyu and Jiang, Zhengxuan and Ma, Yinghao and Liu, Minghao and Tian, Zeyue and Zhou, Ziya and Xue, Liumeng and Qu, Xingwei and Li, Yizhi and Wu, Shangda and Shen, Tianhao and Ma, Ziyang and Zhan, Jun and Wang, Chunhui and Wang, Yatian and Chi, Xiaowei and Zhang, Xinyue and Yang, Zhenzhu and Wang, Xiangzhou and Liu, Shansong and Mei, Lingrui and Li, Peng and Wang, Junjie and Yu, Jianwei and Pang, Guojian and Li, Xu and Wang, Zihao and Zhou, Xiaohuan and Yu, Lijun and Benetos, Emmanouil and Chen, Yong and Lin, Chenghua and Li, Xue and Wu, Yiran and Zhang, Ge and Jiang, Hongqiu and Liu, Jiaheng and Yang, Jian and Huang, Wenhao and Xue, Wei and Tan, Xu and Guo, Yike},
  journal = {arXiv preprint arXiv:2503.08638},
  year = {2025},
  eprint = {2503.08638},
  archivePrefix = {arXiv},
  url = {https://arxiv.org/abs/2503.08638}
}

权重采用 CC BY-NC 4.0 许可,第三方代码许可见 THIRD_PARTY_NOTICES.md。官方还提供盲听投票的 Music Arena 与交互式 Demo,可用来给 YuE2 与主流商业模型做主观听感对比。

  • 音乐生成
  • 大模型
  • 人工智能
  • 媒体生成

【免费下载链接】YuE2-3B

项目地址: https://ai.gitcode.com/hf_mirrors/m-a-p/YuE2-3B
点击查看 免费下载
Logo

openEuler 是由开放原子开源基金会孵化的全场景开源操作系统项目,面向数字基础设施四大核心场景(服务器、云计算、边缘计算、嵌入式),全面支持 ARM、x86、RISC-V、loongArch、PowerPC、SW-64 等多样性计算架构

更多推荐