YuE2 本地运行指南：安装、硬件与歌词生成歌曲实测

YuE2 可以把歌词和风格描述生成带人声与伴奏的歌曲。 本地运行要区分官方未量化 Python 路径与 GGUF / audio.cpp 路径：硬件、文件、可用控制项并不相同。YuE2-3B 当前模型卡标注 CC-BY-NC-4.0，选型前请确认非商业限制是否适合你的项目。

资料核验于 2026 年 10 月 5 日；下方 Mac 数据来自 9 月 23 日历史测试，不是对每个当前安装包与设备的新测。更广泛的选择见开源音乐模型综述。

下载与硬件：先分清运行路径

官方文件在 m-a-p/YuE2-3B；桌面目录使用的是另一个转换发行包 audio-cpp/Yue2-3B-GGUF。不要把 GGUF 文件混进官方 Python loader。软件标注约 4.6 GB 下载量不等于运行显存；官方 24 GB 显卡建议也不意味着量化 Mac 路径需要 24 GB 独立显存。

官方本地安装

在兼容的 Linux/NVIDIA 环境中创建独立 Python 环境。当前模型卡给出的安装入口为：

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

官方 pipeline 可同时保存音频与生成资料。下面使用新写的示范歌词，不是历史测试输入，也没有声称已生成结果：

from yue2 import YuE2Pipeline

pipe = YuE2Pipeline.from_pretrained("m-a-p/YuE2-3B", device="cuda")
song = pipe(
    style="Acoustic folk, warm vocal, fingerpicked guitar, gentle drums",
    lyrics="[verse]\nA window catches morning light\nThe road unfolds beyond the night\n[chorus]\nWe carry little sparks of day\nAnd sing them softly on our way",
    cot="full",
    seed=11,
)
song.save("first-song.flac")
song.save_artifacts("outputs/first-song")

首次运行会下载资源。把设置与乐谱和音频一起保留，后续修改才有可追溯起点。包名或 API 更新时以官方模型卡为准。本次核对了文档接口，没有执行这条 CUDA 路径。

Mac 桌面工作流

Local AI Music当前目录包含 audio.cpp 的 YuE2 Q8。先确认安装版本中可选择 YuE2，阅读许可、下载完整模型，再从短歌词开始。选一种主要语言和一致的风格描述，保留输入及输出。

先做一段主歌加副歌，再扩成完整歌曲。漏唱时缩短或重组句子，如果界面提供 seed，比较时固定 seed。历史测试中的 YuE2 时长随歌词变化，不能用“生成两分钟”保证精确两分钟。

官方乐谱编辑能力不代表每个桌面界面都开放了相同控制项。以安装版本为准；歌词结构可参考歌词生成歌曲。

Mac 实测：YuE2 与 ACE-Step

下载本次引用的历史测量摘要 CSV。这是 9 月 23 日记录的摘录，不是新测试。

2026 年 9 月 23 日，MacBook Pro M5 Pro、64 GB 统一内存，audio.cpp 487800f5、Metal。每首歌独立进程冷启动，耗时包含模型加载，使用项目原创歌词与 seed 11。

中文输入要求女声 city pop、电钢琴、干净的 funk 吉他与 104 BPM，开头是：

[verse]
晚风轻轻掠过长街
霓虹倒映熟悉的脸
我把沉默写成明信片
等一句回答穿过时间

完整输入还有预副歌、重复副歌与桥段，只用此节选不能复现 144 秒输出。风格和 BPM 是输入要求，不是成品测量结果。

用 Qwen3-ASR-1.7B 转写生成歌曲后，中文字符错误率为 YuE2 Q8 3.8%、Q4 13.0%、ACE-Step 7.7%。识别模型自身也会误识别唱歌，因此只能作为小样本歌词遵循对比，不能当音乐质量排名。YuE2 英文样例开头多唱了一句；本轮没有 YuE2 纯音乐测试。

先试听再选

以下是已有 YuE2 产品演示，不是上表的计时测试输出。它们供你判断人声与编曲，上表则说明一种设备上的运行记录。

《晚风吹过旧车站》：

《门前的老槐树》：

YuE2 与 ACE-Step 怎么选

• 非商业歌词实验，可以先试 YuE2 Q8。 这组小样本中中文歌词保留更好；仍要看当前模型许可和使用场景是否需要其他授权。
• 快速打样或明确时长，可先试 ACE-Step。 官方项目采用 MIT 许可，但具体模型与参考素材仍需核对。一次测试不能证明所有任务都更快。
• 不要仅凭文件大小选 Q4。 本次内存更低，但歌词错误更多，需试听再接受取舍。

排错与下一步

转换包缺 VAE 或配置会无法加载，应下载后端要求的完整文件。内存不足先关其他模型、缩短任务，再考虑量化。保留未处理音频，分发前在音频编辑器检查削波和响度。历史测试的输出峰值达到 0 dBFS，需要检查，不能自动称为“已完成母带”。

安装包和模型许可是两回事：付费获取安装包不会取消 YuE2 的非商业条件，本地生成也不自动解决歌词、参考录音的权利问题。云端与本地选型看离线 Suno 替代方案，输入编排看离线 AI 写歌。