YuE2-3B-bf16完整安装指南:模型下载、mlx-yue2-swift接入与内存占用清单

原创2026-10-31 11:10:271,271 阅读

YuE2-3B-bf16完整安装指南:模型下载、mlx-yue2-swift接入与内存占用清单

YuE2-3B-bf16 是 YuE2 音乐生成模型在 MLX 生态下的 bf16 主干权重,专为 Apple Silicon 设计:输入「歌词 + 风格描述」,即可生成带人声的完整歌曲(48 kHz 立体声,最长 6 分钟)。本指南带你完成 模型下载、mlx-yue2-swift 接入与内存占用核对三步,帮你在 Mac 上快速跑通第一首 AI 生成的歌。🎵

🧩 安装前须知:硬件与许可要求

在动手之前,先确认两点:

检查项 要求
硬件 Apple Silicon(M 系列芯片)Mac,内存建议 16 GB 起步
开发环境 Xcode Command Line Tools + Swift(通过 Swift Package Manager 管理依赖)
许可协议 权重采用 CC BY-NC 4.0(非商用);个人创作者可发布/售卖自己制作的歌曲,公司商用需向 M-A-P 取得授权

许可细节可查阅 LICENSE 与 MODEL_LICENSE。该模型是 3.58 B 的 Mixture-of-Transformers 主干,628 个张量保持 bf16 精度,与官方发布逐位一致(改动说明见 NOTICE)。

📦 模型文件清单:下载前核对 4 个核心文件

仓库结构非常精简,全部核心文件如下(清单也收录在 README.md 中):

文件 大小 作用
model.safetensors 7.26 GB bf16 主干权重(628 张量),模型本体
qwen.tiktoken 2.6 MB 分词器,随官方原样分发
config.json 1.6 KB 模型配置 + mlx_yue2 段(dtype、来源锁定、生成默认参数)
许可文件 — LICENSE、MODEL_LICENSE、licenses/stable-audio-tools-MIT.txt、licenses/SnakeBeta-NVIDIA-MIT.txt 等

config.json 中的 mlx_yue2 段还预置了生成默认值:ABC 规划温度 0.7 / top_p 0.9,语义生成 top_k 100,ODE 32 步(midpoint),上下文窗口 24576,无需手动调参即可开箱使用。

⬇️ 模型下载:一键 clone 步骤

⚠️ model.safetensors 通过 Git LFS 存储(见 .gitattributes),克隆前建议先安装 git-lfs,否则拉下来的只是几百字节的指针文件。

git lfs install
git clone https://gitcode.com/hf_mirrors/mlx-community/YuE2-3B-bf16

克隆完成后核对权重文件大小应为 7.26 GB 左右。若 model.safetensors 只有 135 字节,说明 LFS 未拉取,执行:

git lfs pull

📌 注意:本仓库只包含主干模型。音频解码用的 VAE(YuE2-Vae-fp32)会在首次 prepare 时由引擎自动下载,无需手动获取。

🛠️ mlx-yue2-swift 接入:3 步注册模型引擎

在 Swift 工程的 Package.swift 中添加 mlx-yue2-swift 包依赖(版本 from: "0.1.0",引用 product MLXYuE2),然后只需三步:注册 → 准备 → 生成。

import MLXServeCore, MLXToolKit, MLXYuE2

let engine = MLXServeEngine()
// 第 1 步:注册(tier 选择精度档位,.bf16 为原始精度)
let id = try await engine.register(YuE2Package.registration,
                                   configuration: YuE2Configuration(tier: .bf16, modelsRootDirectory: modelsRoot),
                                   id: "yue2-3b")
// 第 2 步:准备(首次运行自动下载本仓库 + VAE)
try await engine.prepare(.music, package: id)
// 第 3 步:生成
let song = try await engine.run(MusicRequest(caption: "English, warm piano pop, expressive female voice, 88 BPM",
                                             lyrics: "[Verse]\n…\n\n[Chorus]\n…", seed: 831001),
                                package: id) as! MusicResponse
// song.audio → 48 kHz 立体声 WAV;song.score → 可编辑的 ABC 乐谱规划

几个实用细节:

  • caption 写风格描述(语言、乐器、音色、BPM),lyrics 用 [Verse] / [Chorus] 等段落标注歌词;
  • 模型会先生成一份带和弦标注的 ABC 乐谱规划,song.score 可编辑后作为 MusicRequest.score 回传重新渲染——相当于「先打谱、再演唱」;
  • 规划模式支持 full 与 off 两档(melody 模式未开放)。

📊 内存占用清单:bf16 / ar8 / int8 三档怎么选

三档量化都从本 bf16 仓库加载时在线量化(无需另下权重)。以下为 M5 Max 上「6 分钟最长歌曲最坏情况」的实测内存(phys_footprint):

档位 常驻内存 峰值内存 量化方式 适合机型
.bf16 7.6 GB 14.6 GB 原始精度,不量化 32 GB+ 内存,追求最高质量
.ar8 6.4 GB 13.3 GB 仅 AR 路径 8-bit 16~24 GB 内存,兼顾质量
.int8 5.1 GB 11.9 GB AR + NAR 路径均 8-bit 16 GB 内存入门之选

选型建议:16 GB 机型从 .int8 起步,把 YuE2Configuration 中的 tier 参数改掉即可;追求音质上限且内存充足,直接 .bf16。参考速度:M5 Max 上 bf16 渲染一首 58 秒英文歌曲约需 41 秒。🚀

❓ 常见问题排查

Q1:clone 后 model.safetensors 只有 135 字节? LFS 指针未替换。安装 git-lfs 后执行 git lfs pull 重新拉取完整权重。

Q2:运行报错提示缺少 VAE? VAE(YuE2-Vae-fp32)依赖网络首次自动下载,请确认网络通畅,或手动将其放入 modelsRoot 指定的模型根目录。

Q3:内存不足导致崩溃? 把 tier 从 .bf16 降到 .int8,峰值内存可直接减少约 2.7 GB;同时缩短歌曲时长也能降低占用。

Q4:生成的歌曲可以商用吗? 权重为非商用许可(CC BY-NC 4.0)。个人创作者以个人身份制作、发布、售卖自己的歌曲是被允许的;公司层面商用或为付费用户代生成歌曲则需先取得 M-A-P 授权,详见 MODEL_LICENSE。

📚 延伸阅读

  • README.md:仓库说明、使用示例与精度对比(Parity)数据
  • config.json:mlx_yue2 生成默认参数(ABC 规划、语义生成、ODE 步数)
  • THIRD_PARTY_NOTICES.md:Oobleck VAE(MIT)与 SnakeBeta/BigVGAN(MIT)第三方代码声明
  • NOTICE:权重改动声明(628 张量与源检查点逐位一致)

按以上步骤完成「下载 → 注册 → 生成」后,你就可以在 Apple Silicon 上用歌词和一句话风格描述,稳定产出带人声的 48 kHz 立体声歌曲了。🎧

登录后查看全文
YuE2-3B-bf16