YuE2-GGUF

YuE2-GGUF

yue2.cpp 的预量化 GGUF 文件，yue2.cpp 是一个 C++ 歌曲生成器，把风格标签和歌词变成立体声音频，并附上它写出的乐谱。适合想在自己电脑上运行的音乐人和爱好者。

由 Serveurperso 在 Hugging Face 上制作。这些说明是 Mindket 根据它的模型页面和模型卡写的，模型自己的文件和许可证在 Hugging Face 上。

简介

它是什么：YuE2-GGUF 存放 yue2.cpp 的预量化 GGUF 文件。yue2.cpp 是 YuE2 歌曲生成器基于 GGML 的可移植 C++17 版本。你给它风格标签和歌词，结果是一段 48 kHz 的立体声曲目，你还会拿到模型作曲时写下的 ABC 乐谱。它能在 CPU、CUDA 和 Vulkan 上运行。

适合谁：想在自己机器上生成音乐的词曲作者和爱好者，以及想要带网页界面和命令行工具的本地歌曲模型的开发者和研究者。

行业 | 谁在用 | 怎么用 | 例子
音乐 | 词曲作者 | 把风格标签和歌词变成试听曲目 | 用自己的歌词做出一首短歌
自托管 | 有闲置 GPU 的爱好者 | 通过内置网页界面在本地运行歌曲生成 | 启动服务器，在浏览器里写提示词
音乐研究 | 研究生成音乐的人 | 在渲染音频之前查看 ABC 乐谱 | 只运行规划步骤并阅读乐谱

如果你需要商用，可以跳过它，因为许可证是非商业的；如果你想要不用自己编译的现成应用，也可以跳过。

用在哪里：

• 装有 C++ 工具链和 CMake 的电脑，可用 CPU、CUDA 或 Vulkan
• 网页浏览器，用来打开服务器提供的界面
• 终端，用来运行命令行工具

用途 | 适合谁 | 得到什么
生成歌曲 | 词曲作者 | 根据风格标签和歌词得到的音频
阅读生成的乐谱 | 音乐人 | 模型写出的 ABC 乐谱
根据录音生成 | 翻唱制作者 | 先用可选的转录器把录音变成旋律的翻唱路径

如何设置：你要从源码构建 yue2.cpp，再用它自带的脚本下载模型文件。默认脚本会下载 Q8_0 文件集，约 5.4 GB。

• Git、CMake 和支持 C++17 的编译器
• Python 和 pip，用来安装 hf 工具
• 用 CUDA 时需要 GPU，也可以用 CPU 或 Vulkan

1. 连同子模块一起克隆 yue2.cpp 仓库。
2. 安装 hf 并运行模型下载脚本。
3. 用 CMake 构建项目。

cd yue2.cpp

pip install hf
./models.sh           # downloads the Q8_0 set (~5.4 GB)

mkdir build && cd build
cmake .. -DGGML_CUDA=ON
cmake --build . --config Release -j$(nproc)
cd ..

如果想自己获取仓库里的文件，Hugging Face 给出这些步骤：

pip install -U huggingface_hub
hf download Serveurperso/YuE2-GGUF

如何使用：启动服务器，然后在浏览器里打开它在 8087 端口提供的网页界面。在这个界面里，你输入标签和歌词，点生成，查看乐谱，然后试听或保存曲目。

./build/yue-server --host 0.0.0.0 --port 8087 \
    --model models/YuE2-3B-Q8_0.gguf \
    --vae models/YuE2-Vae-F32.gguf

命令行工具读取一个请求文件，里面有风格、歌词和随机种子。

# full pipeline: score, semantic codes, flow matching, VAE
./build/yue-synth \
    --model models/YuE2-3B-Q8_0.gguf \
    --vae models/YuE2-Vae-F32.gguf \
    --request request.json \
    --out song.mp3

# symbolic stage alone: the ABC score the model intends to play
./build/yue-plan \
    --model models/YuE2-3B-Q8_0.gguf \
    --request request.json \
    --out score.abc

工具 | 作用
yue-server | 提供网页界面，用来写作、生成和播放曲目
yue-synth | 运行完整流程并写出 mp3 文件
yue-plan | 只写出 ABC 乐谱
models.sh | 下载 Q8_0 模型文件集

示例：你在网页界面里输入几个风格标签，比如“mellow piano, slow tempo”，再写两行歌词，然后点生成。你会得到一首立体声歌曲，界面也会显示模型为它写的 ABC 乐谱。

新手与专家：如果你是新手，先构建项目、启动服务器，用几个标签做一首短歌。你需要的一切都在那一个页面上。

对专家来说，一个骨干文件里有两个共享注意力的 Transformer。前一半写乐谱，再写语义编码。后一半用流匹配把它们渲染出来，再由 VAE 解码成音频。Q8_0 近乎无损。没有 Q4 文件，因为作者说音频编码模型低于 Q5 就会出问题。

风格标签和歌词
自回归部分写出乐谱和编码
非自回归部分生成音频
VAE 解码成 48 kHz 立体声

注意事项：

Title: 骨干文件各量化类型的大小，单位 GB
BF16: 7.17 GB
Q8_0: 3.81 GB
Q6_K: 2.94 GB
Q5_K_M: 2.62 GB

• Optional parts: 翻唱路径有转录器和音频分词器，两者都不是必需的
• VAE: 保持 F32，从不量化
• License: CC BY-NC 4.0，因此只能非商业使用
• Cost to run: 没有提到 API 密钥或付费服务，但需要一台能构建并运行 C++ 代码的电脑
• Data it reaches: 下载模型文件，服务器会在你机器上的某个端口监听
• Not for: 商业用途，因为许可证是非商业的

Hugging Face 上的数据（2026年11月13日）

• 参数量：632M
• Weights: about 316 MB at 4-bit (estimate)
• Formats: GGUF
• 最近 30 天下载：8,466,401
• 点赞：31
• 许可证：cc-by-nc-4.0
• 语言：en, zh, ja, ko, fr, es
• 基于：m-a-p/YuE2-3B
• 标签：gguf, music-generation, text-to-music, ggml, yue2, flow-matching, abc-notation

链接

• 模型：https://huggingface.co/Serveurperso/YuE2-GGUF
• 文件：https://huggingface.co/Serveurperso/YuE2-GGUF/tree/main

获取模型

用 Hugging Face 的命令行下载它的文件：

pip install -U huggingface_hub
hf download Serveurperso/YuE2-GGUF

然后按它的模型卡使用它。这个工具包里没有会自己运行的东西。