YuE 2 本地部署教程：24GB 显存配置与生成实测

YuE 2 官方支持在支持 BF16 的 24GB 显存 NVIDIA 显卡上本地运行，系统要求 Linux，Python 3.12 环境，模型免费。官方 GitHub 仓库 与 Hugging Face 模型页 有完整文档。跑通第一首歌只需要三步：建虚拟环境、装推理包、执行官方示例脚本，输出是一段 48kHz 立体声的完整歌曲。

前置准备：先把这四件事确认掉

1. 系统：官方明确支持 Linux。Windows 不在支持列表里，要跑就上 WSL2 或者直接换 Linux 主机。

2. 显卡：需要支持 BF16 的 NVIDIA GPU，显存 24GB，一次只处理一个请求。官方同时建议准备 24GB 可用主机内存。

3. Python：官方 Quick start 用 Python 3.12 建环境，模型卡标注的最低版本是 Python 3.10 以上，装 3.12 最稳。

4. 网络：模型文件第一次使用时从 Hugging Face 下载，国内网络需要提前准备镜像或代理，否则会卡在下载环节。

这套门槛不低，主要还是显卡。想先听效果再决定要不要折腾，可以先去官方 Demo 页试听，不需要账号也不需要显卡。

安装：两种官方路径任选

路径一：装官方推理包（适合只想用，不改代码）

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

这条路的优点是干净，不用拖整份仓库；缺点是拿不到仓库里的示例请求文件和 Agent Skill。

路径二：克隆仓库装（推荐，跟官方文档同步）

git clone https://github.com/multimodal-art-projection/YuE.git
cd YuE
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

仓库里带 examples/ 目录，有官方示例请求文件，也带 skills/yue2-music/ 这个 Agent Skill，后面想接编码 Agent 做对话式改歌就靠它。

生成第一首歌

命令行最省事：

python examples/generate.py --output outputs/first-song

跑完打开 outputs/first-song/audio.flac，这就是你的第一首生成歌曲。

想要更细的控制，直接调 Python 接口：

import json
from pathlib import Path
from yue2 import YuE2Pipeline

request = json.loads(Path("examples/song.json").read_text(encoding="utf-8"))
with YuE2Pipeline.from_pretrained("m-a-p/YuE2-3B", device="cuda") as pipe:
    song = pipe(**request)
    song.save_artifacts("outputs/my-song")

生成过程默认会打印英文进度，包含当前阶段、耗时和 token 吞吐。不想要这些日志，Python 里传 progress=False，命令行加 --quiet。

显存与速度实测数据

官方模型卡给了完整实测，这是判断自己显卡够不够用的直接依据：

数据来源：YuE2-3B 官方模型卡速度与资源章节。

三个结论直接给：

1. 一首 3.6 分钟的歌，在 4090 上 71 秒出结果，实时倍率约 1:3，比大多数人预期的快。

2. 单次生成峰值显存 11 GiB 左右，官方要求 24GB 是留了余量；官方另测了最大上下文场景，峰值 14.08 GiB，这才是真正贴着 16GB 卡上限的位置，所以 16GB 卡不要硬试。

3. 换 CoT 模式能明显省时间：关掉符号规划（cot=off）从 71 秒降到 58 秒，代价是失去可编辑的乐谱。

显存不够怎么办：能省的和不能省的

• 能省的：切换 CoT 模式，cot=off 最省时间和显存；单请求一次只跑一首，不要并发。

• 不能省的：官方明确该包不做量化，输出就是 48kHz 立体声，没有「低精度版」可以选。想要低显存方案只能等社区或官方后续版本。

• 想批量出歌：官方给了另一条路，用 H800（80GB）加 vLLM 做服务化，并发 16 时约 340 首/小时，并发 32 时约 373 首/小时，代价是显存占用涨到 76 GiB 以上。个人用户用不上这条路。

• 显卡确实不够：先用官方 Demo 和 Music Arena 在线听，等换卡或者用云 GPU 再本地跑。

验证是否跑通：看产物目录

save_artifacts() 会把一次生成的全部中间产物留下，判断是否真跑通，看这几个文件就行：

• audio.flac：最终音频，48kHz 立体声，能正常播放说明链路通了。
• score.abc：符号规划出来的乐谱，用 cot=full 或 melody 时才有。
• plan.json：结构化生成计划。
• latent.npy 与语义 token：声学与语义中间结果，换解码器复现时要靠它。
• result.json：里面有 truncated 标记，用来判断这一首有没有被截断。

官方特别提醒一点：音频能播不代表完整。如果模型撞到了 token 上限，音频仍可能是可播放的，但内容被截断了，这种情况要去 result.json 里看 truncated 标记。

常见报错速查

进阶配置：三个值得先改的参数

1. 换解码器：默认听歌用 YuE2-Vae，复现官方跑分要显式切成 YuE2-Vae-legacy，写法是 from_pretrained("m-a-p/YuE2-3B", vae="m-a-p/YuE2-Vae-legacy")。做对比时应该解码同一份缓存潜变量，而不是重新生成一首。

2. 分阶段调用：plan() 先出乐谱，generate_semantic() 出语义 token，synthesize() 出声学潜变量，decode() 出音频。想先看乐谱再决定要不要渲染，就走这条链路。

3. 用 ABC 谱控制编曲：自己写好或在生成的谱上改，再用 abc=... 传进去，要求配合 cot=full 或 melody 使用。翻唱场景官方推荐 cot=melody 且乐谱不带和弦符号。