🏠 Главная › user guide › media heartmula

{/ Эта страница автоматически передается из файла навыков SKILL.md с помощью сайта/scripts/generate-skill-docs.py. Редактируйте исходный SKILL.md, а не эту страницу. /}

Хартмула

HeartMuLa: генерация песен из текста и тегов, отмеченных Suno.

Метаданные навыки
Источник Встроенный (установлен по умолчанию)
Путь навыки/медиа/сердечко
Версия 1.0.0
Платформы Linux, MacOS, Windows
Теги музыка, аудио, генерация, ai, heartmula, heartcodec, тексты, песни
Связанные навыки аудиокрафт

Справочник: полный SKILL.md:::информация

Ниже приведено полное описание навыка, который загружает Hermes при активации этого навыка. Это то, что агент видит в качестве инструкций, когда навыки активны.

HeartMuLa — Открытая генерация музыки

Обзор

HeartMuLa — это семейство фундаментальных открытых моделей для музыки (лицензия Apache-2.0), которые генерируют музыку на основе текста и тегов, с поддержкой нескольких языков. Генерирует полноценные песни из текста + тегов. Сравнимо с Suno для открытого исходного кода. Включает: - HeartMuLa — языковая модель музыки (3B/7B) для генерации по тексту + тегам - HeartCodec — музыкальный кодек 12,5 Гц для высококачественного восстановления звука - HeartTranscriptor — транскрипция текста на основе Whisper - HeartCLAP — модель спортивных аудио и текста

Когда использовать

Требования к оборудованию

Шаги установки

1. Клонирование репозитория

cd ~/  # или желаемая директория
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 года зафиксированные в зависимости от того, возникнут ли конфликты с новыми пакетами. Замените следующие исправления:

# Обновить datasets (старая версия несовместима с текущим pyarrow)
uv pip install --upgrade datasets

# Обновить transformers (требуется для совместимости с huggingface-hub 1.x)
uv pip install --upgrade transformers

4. Патч исходного кода (требуется для трансформеров 5.x)

Патч 1 — Исправление кэша RoPE в src/heartlib/heartmula/modeling_heartmula.py:

В методе setup_caches класса HeartMuLa группы реинициализации RoPE после блока try/кроме reset_caches и перед блоком with device::

# Переинициализация кэшей RoPE, которые были пропущены при загрузке на мета-устройство
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 первым создаёт модель мета-устройства; Llama3ScaledRoPE.rope_init() пропускает построение кэша на мета-тензорах, а затем никогда не перестраивает его после загрузки весов на реальное устройство.

Патч 2 — Исправление загрузки HeartCodec в src/heartlib/pipelines/music_generation.py:

Добавьте ignore_mismatched_sizes=True во ВСЕ-вызовы HeartCodec.from_pretrained() (их два: нетерпеливая загрузка в __init__ и ленивая загрузка в свойстве codec).

Почему: Буферы initted кодовой книги VQ имеют форму [1] в чекпоинте против [] в моделях. Те же данные, просто скаляр против 0-мерного тензора. Безопасно сосед.

5. Скачивание чекпоинтов моделей

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'

Все 3 можно скачивать параллельно. Общий объём — несколько гигабайт.

GPU/CUDA

HeartMuLa по умолчанию использует CUDA (--mula_device cuda --codec_device cuda). Дополнительная настройка не требуется, если у пользователя есть графический процессор NVIDIA с установленной поддержкой PyTorch CUDA.

Использование

Базовая генерация

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]
Ваш текст здесь...

[Chorus]
Текст припева...

[Bridge]
Текст бриджа...

[Outro]

Ключевые параметры

Параметр По умолчанию Описание
--max_audio_length_ms 240000 Максимальная продолжительность в мс (240 с = 4 мин)
--topk 50 Топ-к сэмплирование
--температура 1.0 Температурный сэмплирования
--cfg_scale 1,5 Масштаб направляющего сигнала без классификатора
--lazy_load ложный Загрузить/выгрузить модели по запросу (экономит VRAM)
--mula_dtype bfloat16 Тип данных для HeartMuLa (рекомендуется bf16)
--codec_dtype поплавок32 Тип данных для HeartCodec (рекомендуется fp32 для качества)

Производительность

Подводные камни

  1. НЕ воспользуйтесь bf16 для HeartCodec — превосходное качество звука. Используйте fp32 (по умолчанию).
  2. Теги могут стоять — известная проблема (№90). Текст часто доминирует; Экспериментируйте с порядком тегов.
  3. Triton недоступен для macOS — только Linux/CUDA для ускорения графического процессора.
  4. Сообщается о несовместимости с RTX 5080 по вопросам исходного кода.
  5. Конфликты зафиксированных зависимостей требуют ручных обновлений и патчей, описанных выше.

Ссылки