heartmula

HeartMuLa 是一套开源音乐基础模型家族（Apache-2.0 许可），能够根据歌词与标签生成音乐，并支持多语言。它可从歌词+标签生成完整歌曲，常被视为开源领域的 Suno 对标方案。

【组成模型】

HeartMuLa：音乐语言模型（3B/7B），根据歌词+标签进行生成。
HeartCodec：12.5Hz 音乐编解码器，用于高保真音频重建。
HeartTranscriptor：基于 Whisper 的歌词转写。
HeartCLAP：音频-文本对齐模型。

【适用时机】用户希望从文本描述生成音乐/歌曲、寻找开源 Suno 替代方案、进行本地/离线音乐生成，或咨询 HeartMuLa、heartlib、AI 音乐生成相关问题时适用。

【硬件要求】

最低：8GB 显存，配合 --lazy_load true（顺序加载/卸载模型）。
推荐：16GB 以上显存，便于单 GPU 舒适使用。
多 GPU：使用 --mula_device cuda:0 --codec_device cuda:1 拆分到多张 GPU。
3B 模型配合 lazy_load 峰值约 6.2GB 显存。

【安装步骤】

克隆仓库： cd ~/ # 或目标目录 git clone https://github.com/HeartMuLa/heartlib.git cd heartlib
创建虚拟环境（要求 Python 3.10）： uv venv --python 3.10 .venv . .venv/bin/activate uv pip install -e .
修复依赖兼容问题（重要：截至 2026 年 2 月，锁定的依赖与较新包存在冲突，需执行以下修复）：

升级 datasets（旧版本与当前 pyarrow 不兼容）

uv pip install --upgrade datasets

升级 transformers（huggingface-hub 1.x 兼容所需）

uv pip install --upgrade transformers

修补源代码（transformers 5.x 需要）：修补 1 - src/heartlib/heartmula/modeling_heartmula.py 中的 RoPE 缓存修复：在 HeartMuLa 类的 setup_caches 方法中，在 reset_caches try/except 块之后、with device: 块之前，加入 RoPE 重新初始化：

Re-initialize RoPE caches that were skipped during meta-device loading

from torchtune.models.llama3_1._position_embeddings import Llama3ScaledRoPE for module in self.modules(): if isinstance(module, Llama3ScaledRoPE) and not module.is_cache_built: module.rope_init() module.to(device) 原因：from_pretrained 会先在 meta 设备上创建模型；Llama3ScaledRoPE.rope_init() 在 meta 张量上会跳过缓存构建，之后权重加载到真实设备后也不会重建。

修补 2 - src/heartlib/pipelines/music_generation.py 中的 HeartCodec 加载修复：为所有 HeartCodec.from_pretrained() 调用添加 ignore_mismatched_sizes=True（共 2 处：init 中的 eager 加载与 codec 属性中的 lazy 加载）。原因：检查点中初始化的 VQ 码本缓冲区形状为 [1]，而模型中为 []。数据相同，只是标量与 0 维张量之别，可安全忽略。

下载模型检查点： cd heartlib # 项目根目录 hf download --local-dir './ckpt' 'HeartMuLa/HeartMuLaGen' hf download --local-dir './ckpt/HeartMuLa-oss-3B' 'HeartMuLa/HeartMuLa-oss-3B-happy-new-year' hf download --local-dir './ckpt/HeartCodec-oss' 'HeartMuLa/HeartCodec-oss-20260123' 三个下载可并行进行，总大小数 GB。

【GPU / CUDA】 HeartMuLa 默认使用 CUDA（--mula_device cuda --codec_device cuda）。若已安装支持 CUDA 的 PyTorch 与 NVIDIA GPU，无需额外配置。安装的 torch==2.4.1 已内置 CUDA 12.1 支持。torchtune 可能报告版本号 0.4.0+cpu，这只是包元数据，它仍通过 PyTorch 使用 CUDA。可通过输出中是否出现 “CUDA memory” 行（如 “CUDA memory before unloading: 6.20 GB”）确认 GPU 是否被使用。

没有 GPU？可用 --mula_device cpu --codec_device cpu 在 CPU 上运行，但生成会极其缓慢（单首歌可能需 30–60 分钟以上，而 GPU 上约 4 分钟）；CPU 模式还需大量内存（约 12GB 以上空闲）。若用户没有 NVIDIA GPU，建议使用云 GPU 服务（如 Google Colab 免费层 T4、Lambda Labs 等）或在线演示 https://heartmula.github.io/。

【使用方式】基本生成： cd heartlib . .venv/bin/activate python ./examples/run_music_generation.py
--model_path=./ckpt
--version="3B"
--lyrics="./assets/lyrics.txt"
--tags="./assets/tags.txt"
--save_path="./assets/output.mp3"
--lazy_load true

输入格式：标签（逗号分隔，不带空格）：piano,happy,wedding,synthesizer,romantic 或 rock,energetic,guitar,drums,male-vocal。歌词（使用方括号结构标签）： [Intro]

[Verse] Your lyrics here...

[Chorus] Chorus lyrics...

[Bridge] Bridge lyrics...

[Outro]

【关键参数】

--max_audio_length_ms 默认 240000：最大长度（毫秒），240s=4 分钟。
--topk 默认 50：Top-k 采样。
--temperature 默认 1.0：采样温度。
--cfg_scale 默认 1.5：无分类器引导（classifier-free guidance）尺度。
--lazy_load 默认 false：按需加载/卸载模型（节省显存）。
--mula_dtype 默认 bfloat16：HeartMuLa 的数据类型（推荐 bf16）。
--codec_dtype 默认 float32：HeartCodec 的数据类型（推荐 fp32 以保证质量）。

【性能】 RTF（实时因子）≈ 1.0，即 4 分钟歌曲约需 4 分钟生成。输出为 MP3、48kHz 立体声、128kbps。

【注意事项】

不要对 HeartCodec 使用 bf16，会降低音频质量；请使用 fp32（默认）。
标签可能被忽略（已知问题 #90）。歌词往往占主导，可尝试调整标签顺序。
macOS 上 Triton 不可用，GPU 加速仅限 Linux/CUDA。
上游问题中报告了 RTX 5080 不兼容。
依赖锁定冲突需要上述手动升级与补丁。

【链接】仓库：https://github.com/HeartMuLa/heartlib 模型：https://huggingface.co/HeartMuLa 论文：https://arxiv.org/abs/2601.10547 许可：Apache-2.0

技能介绍

升级 datasets（旧版本与当前 pyarrow 不兼容）

升级 transformers（huggingface-hub 1.x 兼容所需）

Re-initialize RoPE caches that were skipped during meta-device loading