{/* Trang này được tạo tự động từ SKILL.md của kỹ năng bởi website/scripts/generate-skill-docs.py. Chỉnh sửa nguồn SKILL.md, không phải trang này. */}

trái tim

HeartMuLa: Tạo bài hát giống Suno từ lời bài hát + thẻ.

Siêu dữ liệu kỹ năng

Nguồn	Đi kèm (được cài đặt theo mặc định)
Đường dẫn

skills/media/heartmula ` | | Phiên bản |

1.0.0 ` | | Nền tảng | Linux, macOS, Windows | | Thẻ |

music

, `audio

, `generation

, `ai

, `heartmula

, `heartcodec

, `lyrics

, songs | | Kỹ năng liên quan |

audiocraft ` |

Tham khảo: đầy đủ SKILL.md

thông tin

Sau đây là định nghĩa kỹ năng đầy đủ mà Hermes tải khi kỹ năng này được kích hoạt. Đây là những gì tác nhân coi là hướng dẫn khi kỹ năng được kích hoạt.

HeartMuLa - Thế hệ âm nhạc mã nguồn mở

Tổng quan

HeartMuLa là một nhóm các mô hình nền tảng âm nhạc nguồn mở (Apache-2.0) tạo ra âm nhạc dựa trên lời bài hát và thẻ, với sự hỗ trợ đa ngôn ngữ. Tạo bài hát đầy đủ từ lời bài hát + thẻ. Có thể so sánh với Suno về nguồn mở. Bao gồm:

• HeartMuLa - Mô hình ngôn ngữ âm nhạc (3B/7B) để tạo từ lời bài hát + thẻ
• HeartCodec - Bộ giải mã âm nhạc 12,5Hz để tái tạo âm thanh có độ trung thực cao
• HeartTranscriptor - Phiên âm lời bài hát dựa trên lời thì thầm
• HeartCLAP - Mô hình căn chỉnh âm thanh-văn bản

Khi nào nên sử dụng

• Người dùng muốn tạo nhạc/bài hát từ mô tả văn bản
• Người dùng muốn một giải pháp thay thế Suno mã nguồn mở
• Người dùng muốn tạo nhạc cục bộ/ngoại tuyến
• Người dùng hỏi về HeartMuLa, heartlib hoặc thế hệ nhạc AI

Yêu cầu phần cứng

• Tối thiểu: 8GB VRAM với

--lazy_load true ` (tải/dỡ các mô hình một cách tuần tự)

• Khuyến nghị: 16GB+ VRAM để sử dụng GPU đơn một cách thoải mái
• Đa GPU: Sử dụng

--mula_device cuda:0 --codec_device cuda:1 ` để phân chia giữa các GPU

• Mô hình 3B có đỉnh lười_load ở mức ~6,2GB VRAM

Các bước cài đặt

1. Sao chép kho lưu trữ

`

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

`

### 2. Tạo môi trường ảo (yêu cầu Python 3.10)

`
`bash
uv venv --Python 3.10 .venv
. .venv/bin/activate
uv pip install -e .

`

### 3. Khắc phục sự cố tương thích phụ thuộc`**QUAN TRỌNG**: Kể từ tháng 2 năm 2026, các phần phụ thuộc được ghim có xung đột với các gói mới hơn. Áp dụng các bản sửa lỗi sau:

`bash

# 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. Patch Source Code (Bắt buộc đối với Transformers 5.x)

**Bản vá 1 - Sửa lỗi bộ đệm RoPE** trong 
`src/heartlib/heartmula/modeling_heartmula.py

:

Trong phương thức 
`setup_caches
` của lớp 
`HeartMuLa

, thêm khởi tạo lại RoPE sau khối thử/ngoại trừ 
`reset_caches
` và trước khối 
`with device:

:

``` python

# 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)

`
``**Tại sao**: 
`from_pretrained
` tạo mô hình trên thiết bị meta trước tiên; 
`Llama3ScaledRoPE.rope_init()
` bỏ qua việc xây dựng bộ nhớ đệm trên các tensor meta, sau đó không bao giờ xây dựng lại sau khi trọng lượng được tải vào thiết bị thực.

**Bản vá 2 - Sửa lỗi tải HeartCodec** trong 
`src/heartlib/pipelines/music_generation.py

:

Thêm 
`ignore_mismatched_sizes=True
` vào TẤT CẢ lệnh gọi 
`HeartCodec.from_pretrained()
` (có 2: tải háo hức trong 
`__init__
` và tải lười trong thuộc tính 
`codec

).

**Tại sao**: Bộ đệm 
`initted
` của bảng mã VQ có hình dạng 

[1]
` trong điểm kiểm tra so với 

[]
` trong mô hình. Cùng một dữ liệu, chỉ là vô hướng so với tensor 0-d. An toàn để bỏ qua.

### 5. Tải xuống điểm kiểm tra mô hình

`
``` bash
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'

`
``Cả 3 đều có thể được tải xuống song song. Tổng kích thước là vài GB.`##GPU / CUDA

HeartMuLa sử dụng CUDA theo mặc định (

`
--mula_device cuda --codec_device cuda

). Không cần thiết lập thêm nếu người dùng đã cài đặt GPU NVIDIA có hỗ trợ PyTorch CUDA.
- 
`torch==2.4.1
` đã cài đặt bao gồm hỗ trợ CUDA 12.1 ngay lập tức
- 
`torchtune
` có thể báo cáo phiên bản 
`0.4.0+cpu

 - đây chỉ là siêu dữ liệu gói, nó vẫn sử dụng CUDA qua PyTorch
- Để xác minh GPU đang được sử dụng, hãy tìm dòng "Bộ nhớ CUDA" ở đầu ra (ví dụ: "Bộ nhớ CUDA trước khi dỡ tải: 6,20 GB")
- **Không có GPU?** Bạn có thể chạy trên CPU với 

--mula_device cpu --codec_device cpu

, nhưng dự kiến quá trình tạo sẽ **cực kỳ chậm** (có thể mất hơn 30-60 phút cho một bài hát so với ~4 phút trên GPU). Chế độ CPU cũng yêu cầu RAM đáng kể (~12GB+ trống). Nếu người dùng không có GPU NVIDIA, bạn nên sử dụng dịch vụ GPU đám mây (cấp miễn phí của Google Colab với T4, Lambda Labs, v.v.) hoặc bản demo trực tuyến tại https://heartmula.GitHub.io/.

## Cách sử dụng

### Thế hệ cơ bản

`
``` bash
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

`

### Định dạng đầu vào`**Thẻ** (được phân tách bằng dấu phẩy, không có dấu cách):

`

piano,happy,wedding,synthesizer,romantic

`

hoặc

`

rock,energetic,guitar,drums,male-vocal

`
``**Lời bài hát** (sử dụng thẻ cấu trúc trong ngoặc):

`

[Intro]

[Verse]
Your lyrics here...

[Chorus]
Chorus lyrics...

[Bridge]
Bridge lyrics...

[Outro]

`

### Thông số chính
| Tham số | Mặc định | Mô tả |
|----------||----------|-------------|
| 

--max_audio_length_ms
` | 240000 | Độ dài tối đa tính bằng ms (240 giây = 4 phút) |
| 

--topk
` | 50 | Lấy mẫu Top-k |
| 

--temperature
` | 1.0 | Nhiệt độ lấy mẫu |
| 

--cfg_scale
` | 1,5 | Thang hướng dẫn không cần phân loại |
| 

--lazy_load
` | sai | Tải/dỡ các mô hình theo yêu cầu (tiết kiệm VRAM) |
| 

--mula_dtype
` | bfloat16 | Dtype cho HeartMuLa (khuyên dùng bf16) |
| 

--codec_dtype
` | phao32 | Dtype cho HeartCodec (khuyên dùng fp32 để đảm bảo chất lượng) |

### Hiệu suất
- RTF (Hệ số thời gian thực) ≈ 1.0 — một bài hát dài 4 phút mất ~4 phút để tạo
- Đầu ra: MP3, âm thanh nổi 48kHz, 128kbps

## Cạm bẫy
1. **KHÔNG sử dụng bf16 cho HeartCodec** — làm giảm chất lượng âm thanh. Sử dụng fp32 (mặc định).
2. **Thẻ có thể bị bỏ qua** — sự cố đã biết (#90). Lời bài hát có xu hướng chiếm ưu thế; thử nghiệm với thứ tự thẻ.
3. **Triton không khả dụng trên macOS** — Linux/CUDA chỉ dành cho tăng tốc GPU.
4. **Không tương thích với RTX 5080** được báo cáo trong các sự cố ở thượng nguồn.
5. Xung đột chân phụ thuộc yêu cầu nâng cấp thủ công và vá lỗi được mô tả ở trên.

## Liên kết
- Kho lưu trữ: https://GitHub.com/HeartMuLa/heartlib
- Người mẫu: https://huggingface.co/HeartMuLa
- Giấy: https://arxiv.org/abs/2601.10547
- Giấy phép: Apache-2.0