跳到主要內容

Heartmula

設置並運行 HeartMuLa，這是一個開源音樂生成模型家族（類似 Suno）。支持從歌詞和標籤生成完整歌曲，並提供多語言支持。

技能元數據​

來源捆綁（默認安裝）
路徑skills/media/heartmula
版本1.0.0
標籤music, audio, generation, ai, heartmula, heartcodec, lyrics, songs
相關技能audiocraft

參考：完整 SKILL.md​

信息

以下是 Hermes 在觸發此技能時加載的完整技能定義。這是技能激活時代理所看到的指令。

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 分配負載
  • 啟用 lazy_load 的 3B 模型峰值顯存佔用約為 ~6.2GB

安裝步驟​

1. 克隆倉庫​

cd ~/  # or desired directory
git clone https://github.com/HeartMuLa/heartlib.git
cd heartlib

2. 創建虛擬環境（需要 Python 3.10）​

uv venv --python 3.10 .venv
. .venv/bin/activate
uv pip install -e .

3. 修復依賴兼容性問題​

重要提示：截至 2026 年 2 月，鎖定的依賴項與較新的包存在衝突。請應用以下修復：

# Upgrade datasets (old version incompatible with current pyarrow)
uv pip install --upgrade datasets

# Upgrade transformers (needed for huggingface-hub 1.x compatibility)
uv pip install --upgrade transformers

4. 修補源代碼（transformers 5.x 必需）​

補丁 1 - RoPE 緩存修復，位於 src/heartlib/heartmula/modeling_heartmula.py：

在 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 - HeartCodec 加載修復，位於 src/heartlib/pipelines/music_generation.py：

向所有 HeartCodec.from_pretrained() 調用添加 ignore_mismatched_sizes=True（共有兩處：__init__ 中的 eager load 和 codec 屬性中的 lazy load）。

原因：VQ 碼本 initted 緩衝區在檢查點中的形狀為 [1]，而在模型中為 []。數據相同，只是標量與 0 維張量的區別。可以安全忽略。

5. 下載模型檢查點​

cd heartlib  # project root
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'

所有 3 個模型可以並行下載。總大小為幾 GB。

GPU / CUDA​

HeartMuLa 默認使用 CUDA（--mula_device cuda --codec_device cuda）。如果用戶擁有安裝了 PyTorch CUDA 支持的 NVIDIA GPU，則無需額外設置。

  • 安裝的 torch==2.4.1 開箱即支持 CUDA 12.1
  • torchtune 可能報告版本為 0.4.0+cpu — 這僅是包元數據，它仍然通過 PyTorch 使用 CUDA
  • 要驗證是否正在使用 GPU，請在輸出中查找 "CUDA memory" 行（例如 "CUDA memory before unloading: 6.20 GB"）
  • 沒有 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_ms240000最大長度（毫秒）（240s = 4 分鐘）
--topk50Top-k 採樣
--temperature1.0採樣溫度
--cfg_scale1.5分類器自由引導尺度
--lazy_loadfalse按需加載/卸載模型（節省顯存）
--mula_dtypebfloat16HeartMuLa 的數據類型（推薦 bf16）
--codec_dtypefloat32HeartCodec 的數據類型（為保證質量推薦 fp32）

性能​

  • RTF（實時因子）≈ 1.0 — 生成一首 4 分鐘的歌曲大約需要 4 分鐘
  • 輸出：MP3，48kHz 立體聲，128kbps

陷阱​

  1. HeartCodec 切勿使用 bf16 — 會降低音頻質量。請使用 fp32（默認）。
  2. 標籤可能被忽略 — 已知問題 (#90)。歌詞往往占主導地位；請嘗試調整標籤順序。
  3. macOS 上不可用 Triton — GPU 加速僅支持 Linux/CUDA。
  4. 上游問題中報告了 RTX 5080 不兼容。
  5. 依賴項版本鎖定衝突需要上述的手動升級和補丁。