YuE2 是一个能生成带人声完整歌曲的开源音乐生成模型，最大特点是先写出可编辑的乐谱（ABC 记谱法），再渲染成音频。它能在单张 24GB 显存的 NVIDIA GPU 上运行，生成一首 3.6 分钟的歌曲约需 71 秒。

下面是详细的本地部署教程。

📋 环境要求

在开始之前，请确认你的设备满足以下要求：

  • 操作系统：Linux 是官方推荐和主要支持的系统。Windows 用户可尝试通过 ComfyUI 插件或 WSL2 部署，但兼容性可能因环境而异。
  • Python 版本：官方推荐 Python 3.12。
  • GPU：必须使用支持 BF16 的 NVIDIA GPU，显存建议 24GB。实测在 RTX 4090 上峰值显存约 11-14 GiB。
  • 磁盘空间：建议预留 45GB 以上，用于存放模型权重和依赖。

🚀 部署步骤：官方 Python 方式

这是最直接的部署方式，适合开发和直接使用。

  1. 克隆仓库与创建虚拟环境

    1
    2
    3
    4
    git clone https://github.com/multimodal-art-projection/YuE.git
    cd YuE
    python3.12 -m venv .venv
    source .venv/bin/activate

    如果你需要保留旧版 YuE 的功能，可以切换到 YuE-v1 分支。

  2. 安装项目与依赖

    1
    2
    python -m pip install --upgrade pip
    python -m pip install .

    安装过程会自动处理 PyTorch、FlashAttention 等核心依赖。

  3. 运行官方示例生成第一首歌
    项目自带一个示例请求，执行以下命令即可生成并保存到 outputs/first-song 目录：

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

    完成后，打开 outputs/first-song/audio.flac 就能听到生成的歌曲了。输出目录里还会保留乐谱、语义 token 和生成设置，方便你复现或修改。

🎵 使用 Python API 进行创作

YuE2 的核心能力通过分阶段的 Python API 提供，你可以用它来构建更复杂的生成流程。

基础生成

1
2
3
4
5
6
7
8
9
10
11
12
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")
    print(song.truncated)

关键参数：控制生成方式
模型通过 cot 参数控制是否进行符号规划，以适应不同任务：

设置 行为
cot="full" 默认。生成可编辑的旋律与和弦计划，适用于全新创作。
cot="melody" 仅使用旋律计划，伴奏自由发挥。推荐用于翻唱。
cot="off" 跳过乐谱规划，直接从歌词和风格生成。

进阶：翻唱与编辑

  • 翻唱：先用 SheetSage2 转录原曲得到旋律乐谱，再用 cot="melody" 模式配合新歌词或风格进行生成。
  • 编辑：先用 pipe.plan(**request) 生成乐谱计划并保存为 .abc 文件，手动修改后再用 --abc-file 参数重新渲染。

🧩 备选方案：ComfyUI 插件

如果你更习惯图形化操作，社区已经为 YuE2 开发了 ComfyUI 插件，提供了另一种部署选择。

  • 优点：节点式操作，可视化流程；部分插件包集成了模型下载和运行时环境，安装相对简便。
  • 缺点：可能存在版本兼容性问题（如 Windows 下 FlashAttention 缺失）；对显存的要求依然存在，但插件可能提供更灵活的显存优化选项（如分块解码）。

📝 重要注意事项

  • 许可证：YuE2 的代码基于 Apache 2.0 许可，但预训练权重采用 CC BY-NC 4.0 许可，仅限非商业用途。在考虑任何商业化应用前，请务必核实许可条款。
  • 性能预期：官方引用的“71 秒生成 3.6 分钟歌曲”是在 RTX 4090 上测得的。你的实际速度取决于 GPU 型号和生成参数。官方模型卡未报告量化的性能数据，社区有尝试将其降至 8GB 显存，但非官方支持。

YuE2 的部署门槛主要体现在对 NVIDIA GPU 和 Linux 环境的依赖上。如果你有符合配置的机器，按照上面的步骤通常可以顺利跑通。如果遇到具体的报错，比如依赖冲突或显存不足，可以再告诉我细节。