ACE-Step
Шаг к фундаментальной модели генерации музыки
Проект |
Hugging Face |
ModelScope |
Демо (Space) |
Discord |
Технический отчёт |
ACE-Step v1.5
Язык: English | Русский
## Содержание
- [✨ Возможности](#-возможности)
- [📦 Установка](#-установка)
- [⚡ Быстрый старт](#-быстрый-старт)
- [🚀 Использование](#-использование)
- [📱 Описание интерфейса](#-описание-интерфейса)
- [🔨 Обучение](#-обучение)
## 📝 Аннотация
Мы представляем ACE-Step — новую открытую фундаментальную модель для генерации музыки, которая преодолевает ключевые ограничения существующих подходов и достигает state-of-the-art качества за счёт целостной архитектуры. Нынешние методы вынуждены искать компромисс между скоростью генерации, музыкальной связностью и управляемостью. Например, модели на базе LLM (Yue, SongGen) хорошо попадают в текст песни, но страдают от медленного инференса и структурных артефактов. Диффузионные модели (например, DiffRhythm), напротив, синтезируют быстрее, но часто теряют структурную связность на длинных отрезках.
ACE-Step закрывает этот разрыв, объединяя диффузионную генерацию с Deep Compression AutoEncoder (DCAE) из Sana и лёгким линейным трансформером. Дополнительно модель использует MERT и m-hubert для выравнивания семантических представлений (REPA) во время обучения, что обеспечивает быструю сходимость. В результате модель синтезирует до 4 минут музыки за 20 секунд на GPU A100 — в 15 раз быстрее решений на базе LLM — при этом превосходя их по музыкальной связности и попаданию в текст по метрикам мелодии, гармонии и ритма. Кроме того, ACE-Step сохраняет тонкие акустические детали, что позволяет реализовать продвинутые механизмы управления: клонирование голоса, редактирование текста, ремиксы и генерацию отдельных дорожек (например, lyric2vocal, singing2accompaniment).
Вместо очередного end-to-end пайплайна text-to-music наша цель — создать фундаментальную модель для музыкального ИИ: быструю, универсальную, эффективную и при этом гибкую архитектуру, поверх которой легко обучать подзадачи. Это открывает путь к мощным инструментам, органично встраивающимся в творческий процесс музыкантов, продюсеров и авторов контента. Коротко говоря, мы хотим повторить для музыки то, чем стал Stable Diffusion для изображений.
## 📢 Новости и обновления
- 🎉 **28.01.2026:** Вышла [ACE-Step v1.5](https://ace-step.github.io/ace-step-v1.5.github.io/) — наша самая свежая и продвинутая модель!
- 📃 02.06.2025: Опубликован [технический отчёт ACE-Step (PDF)](https://arxiv.org/abs/2506.00045).
- 🎮 14.05.2025: Добавлен сэмплер `pingpong` из `Stable Audio Open Small`. Использование SDE даёт лучшую консистентность и качество музыки, включая попадание в текст и в стиль. Также заново реализован `Audio2Audio` более удачным способом.
- 🎤 12.05.2025: Выпущен [RapMachine](https://huggingface.co/ACE-Step/ACE-Step-v1-chinese-rap-LoRA), исправлены проблемы обучения LoRA
- Подробности в [ZH_RAP_LORA.md](./ZH_RAP_LORA.md). Примеры аудио: https://ace-step.github.io/#RapMachine
- Подробная инструкция по обучению — в [TRAIN_INSTRUCTION.md](./TRAIN_INSTRUCTION.md).
- 🔥 **10.05.2025:** Оптимизация потребления памяти
- Максимальный расход VRAM снижен до 8 ГБ — модель стала доступнее для домашних видеокарт
- Рекомендуемые параметры запуска:
```bash
acestep --torch_compile true --cpu_offload true --overlapped_decode true
```
На Windows нужно установить triton:
```
pip install triton-windows
```
- 📢 **09.05.2025:** Демо на Gradio поддерживает Audio2Audio. ComfyUI: [Ace_Step_4x_a2a.json](./assets/Ace_Step_4x_a2a.json)
- 🚀 **08.05.2025:** Доступен узел [ComfyUI_ACE-Step](https://t.co/GeRSTrIvn0)! Используйте возможности ACE-Step прямо в ComfyUI. 🎉
- 🚀 06.05.2025: Открыты исходный код демо и модель
## ✨ Возможности
### 🎯 Базовое качество
#### 🌈 Разнообразие стилей и жанров
- 🎸 Поддерживаются все основные музыкальные стили, описание задаётся короткими тегами, развёрнутым текстом или описанием сценария использования
- 🎷 Генерация музыки в разных жанрах с подходящим инструментарием и стилистикой
#### 🌍 Многоязычность
- 🗣️ Поддерживается 19 языков, из них 10 с наилучшим качеством:
- 🇺🇸 английский, 🇨🇳 китайский, 🇷🇺 русский, 🇪🇸 испанский, 🇯🇵 японский, 🇩🇪 немецкий, 🇫🇷 французский, 🇵🇹 португальский, 🇮🇹 итальянский, 🇰🇷 корейский
- ⚠️ Из-за дисбаланса обучающих данных менее распространённые языки могут работать хуже
#### 🎻 Инструментальные стили
- 🎹 Поддерживается генерация инструментальной музыки в разных жанрах и стилях
- 🎺 Реалистичные инструментальные дорожки с корректным тембром и выразительностью каждого инструмента
- 🎼 Возможны сложные аранжировки с несколькими инструментами при сохранении музыкальной связности
#### 🎤 Вокальные техники
- 🎙️ Качественная передача различных вокальных стилей и техник
- 🗣️ Поддержка разной вокальной подачи, включая разные приёмы и манеры пения
### 🎛️ Управляемость
#### 🔄 Генерация вариаций
- ⚙️ Реализовано через оптимизацию на этапе инференса, без дообучения
- 🌊 Flow-matching модель генерирует начальный шум, затем по формуле шума из trigFlow добавляется дополнительный гауссов шум
- 🎚️ Соотношение исходного и нового шума регулируется — так задаётся степень отличия вариации
#### 🎨 Перерисовка (Repainting)
- 🖌️ Реализовано добавлением шума к целевому аудио и наложением масочных ограничений в процессе ODE
- 🔍 Если условия генерации меняются относительно исходных, можно изменить только отдельные аспекты, сохранив остальное
- 🔀 Комбинируется с генерацией вариаций — можно делать локальные вариации стиля, текста или вокала
#### ✏️ Редактирование текста песни
- 💡 Технология flow-edit применена для локального изменения текста с сохранением мелодии, вокала и аккомпанемента
- 🔄 Работает и со сгенерированным, и с загруженным аудио, что заметно расширяет творческие возможности
- ℹ️ Текущее ограничение: за раз можно менять только небольшие фрагменты текста, иначе появляются искажения; но правки можно применять последовательно
### 🚀 Применения
#### 🎤 Lyric2Vocal (LoRA)
- 🔊 LoRA, дообученная на чистом вокале, позволяет генерировать вокальные сэмплы прямо из текста
- 🛠️ Практическое применение: вокальные демо, гайд-треки, помощь в написании песен, эксперименты с вокальной аранжировкой
- ⏱️ Быстрый способ проверить, как текст зазвучит в исполнении, — ускоряет итерации автора
#### 📝 Text2Samples (LoRA)
- 🎛️ Аналог Lyric2Vocal, но дообучен на чисто инструментальных данных и сэмплах
- 🎵 Генерация концептуальных сэмплов для музыкального продакшена по текстовому описанию
- 🧰 Удобно для быстрого создания инструментальных лупов, звуковых эффектов и музыкальных элементов
### 🔮 Скоро
#### 🎤 RapMachine
- 🔥 Дообучение на чистых рэп-данных для создания ИИ, специализирующегося на рэпе
- 🏆 Ожидаемые возможности: ИИ-баттлы и повествование через рэп
- 📚 Рэп обладает исключительными нарративными и выразительными возможностями — потенциал применения огромен
#### 🎛️ StemGen
- 🎚️ ControlNet-LoRA, обученная на многодорожечных данных для генерации отдельных инструментальных стемов
- 🎯 На вход подаётся референсный трек и нужный инструмент (или референсное аудио инструмента)
- 🎹 На выходе — стем инструмента, дополняющий референс: например, фортепианный аккомпанемент к мелодии флейты или джазовые барабаны к соло-гитаре
#### 🎤 Singing2Accompaniment
- 🔄 Обратный процесс к StemGen: из одной вокальной дорожки собирается сведённый мастер-трек
- 🎵 На вход подаётся вокал и нужный стиль, на выходе — полноценный аккомпанемент к вокалу
- 🎸 Создаётся полное инструментальное сопровождение — легко добавить профессиональное звучание к любой вокальной записи
## 📋 Дорожная карта
- [x] Публикация кода обучения 🔥
- [x] Публикация кода обучения LoRA 🔥
- [x] Публикация RapMachine LoRA 🎤
- [x] Публикация результатов оценки и технического отчёта 📄
- [ ] Обучение и публикация ACE-Step V1.5
- [ ] Публикация кода обучения ControlNet 🔥
- [ ] Публикация Singing2Accompaniment ControlNet 🎮
## 🖥️ Производительность на разном железе
Мы измерили производительность ACE-Step на разных конфигурациях:
| Устройство | RTF (27 шагов) | Время на 1 мин аудио (27 шагов) | RTF (60 шагов) | Время на 1 мин аудио (60 шагов) |
| --------------- | -------------- | ------------------------------- | -------------- | ------------------------------- |
| NVIDIA RTX 4090 | 34.48 × | 1.74 с | 15.63 × | 3.84 с |
| NVIDIA A100 | 27.27 × | 2.20 с | 12.27 × | 4.89 с |
| NVIDIA RTX 3090 | 12.76 × | 4.70 с | 6.48 × | 9.26 с |
| MacBook M2 Max | 2.27 × | 26.43 с | 1.03 × | 58.25 с |
Производительность измеряется в RTF (Real-Time Factor, коэффициент реального времени). Чем больше значение, тем быстрее генерация. 27.27× означает, что на 1 минуту музыки уходит 2.2 секунды (60/27.27). Измерения проводились на одном GPU с batch size 1 и 27 шагами.
## 📦 Установка
### 1. Клонирование репозитория
Сначала склонируйте репозиторий ACE-Step и перейдите в каталог проекта:
```bash
git clone https://github.com/ace-step/ACE-Step.git
cd ACE-Step
```
### 2. Требования
Убедитесь, что у вас установлено:
* `Python`: рекомендуется версия 3.10 или новее. Скачать можно на [python.org](https://www.python.org/).
* `Conda` или `venv`: для создания виртуального окружения (Conda предпочтительнее).
### 3. Создание виртуального окружения
Настоятельно рекомендуем использовать виртуальное окружение, чтобы не конфликтовать с другими пакетами. Выберите один из вариантов:
#### Вариант A: Conda
1. **Создайте окружение** с именем `ace_step` и Python 3.10:
```bash
conda create -n ace_step python=3.10 -y
```
2. **Активируйте окружение:**
```bash
conda activate ace_step
```
#### Вариант B: venv
1. **Перейдите в каталог склонированного репозитория ACE-Step.**
2. **Создайте виртуальное окружение** (обычно его называют `venv`):
```bash
python -m venv venv
```
3. **Активируйте окружение:**
* **Windows (cmd.exe):**
```bash
venv\Scripts\activate.bat
```
* **Windows (PowerShell):**
```powershell
.\venv\Scripts\Activate.ps1
```
*(Если возникает ошибка политики выполнения, сначала выполните `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process`)*
* **Linux / macOS (bash/zsh):**
```bash
source venv/bin/activate
```
### 4. Установка зависимостей
После активации виртуального окружения:
**a.** (Только Windows) Если вы на Windows и планируете использовать NVIDIA GPU, сначала поставьте PyTorch со сборкой под CUDA:
```bash
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
```
(Замените `cu126`, если у вас другая версия CUDA. Другие варианты установки — на [официальном сайте PyTorch](https://pytorch.org/get-started/locally/)).
**b.** Установите ACE-Step и основные зависимости:
```bash
pip install -e .
```
Если планируете обучать или дообучать модель, поставьте дополнительно зависимости для обучения — для инференса они не нужны:
```bash
pip install -e ".[train]"
```
На этом установка завершена. Графический интерфейс работает на Windows, macOS и Linux. Как запускать — см. раздел [Использование](#-использование).
## ⚡ Быстрый старт
В репозитории есть скрипты запуска, которые делают всё сами: проверяют Python, создают виртуальное окружение, ставят PyTorch с нужным бэкендом, устанавливают ACE-Step и запускают веб-интерфейс.
**Windows** — достаточно дважды кликнуть по [`start.bat`](./start.bat) или запустить из командной строки:
```bat
start.bat
```
**Linux / macOS** — запустите [`start.sh`](./start.sh):
```bash
./start.sh
```
При первом запуске установка займёт несколько минут (скачивается около 3 ГБ пакетов). Веса модели (~8 ГБ) докачаются автоматически при первой генерации. Последующие запуски стартуют сразу.
### Флаги скрипта
| Флаг | Что делает |
| --- | --- |
| `--lowvram` | Режим экономии видеопамяти (до ~8 ГБ VRAM): включает `--cpu_offload`, `--overlapped_decode` и `--torch_compile`, доустанавливает `triton-windows` |
| `--cpu` | Запуск на процессоре, без CUDA (очень медленно, но работает без видеокарты NVIDIA) |
| `--share` | Публичная ссылка Gradio для доступа снаружи |
| `--port ` | Порт веб-интерфейса (по умолчанию 7865) |
| `--device ` | Номер видеокарты (по умолчанию 0) |
| `--listen` | Слушать `0.0.0.0`, чтобы зайти с других устройств в локальной сети |
| `--reinstall` | Полностью пересоздать виртуальное окружение с нуля |
| `--update` | Обновить зависимости в существующем окружении |
| `--setup` | Только установка, без запуска |
| `--help` | Показать справку |
Флаги можно комбинировать, например:
```bat
start.bat --lowvram --listen --port 7870
```
Настройки по умолчанию (порт, номер GPU, путь к весам модели) задаются в блоке `==== НАСТРОЙКИ ====` в начале каждого скрипта. В `start.sh` их можно переопределить переменными окружения (`PORT=7870 ./start.sh`). На macOS скрипт сам ставит сборку PyTorch с MPS и передаёт `--bf16 false`.
## 🚀 Использование
### 🔍 Базовый запуск
```bash
acestep --port 7865
```
### ⚙️ Расширенный запуск
```bash
acestep --checkpoint_path /path/to/checkpoint --port 7865 --device_id 0 --share true --bf16 true
```
* Если `--checkpoint_path` задан и модели по этому пути есть, они загружаются оттуда.
* Если `--checkpoint_path` задан, но моделей там нет, они автоматически скачаются в этот каталог.
* Если `--checkpoint_path` не задан, модели скачаются в путь по умолчанию `~/.cache/ace-step/checkpoints`.
На macOS используйте `--bf16 false`, чтобы избежать ошибок.
#### 🖥️ Генерация из командной строки
Чтобы генерировать без веб-интерфейса, используйте `infer.py`:
```bash
python infer.py \
--prompt "synth-pop, female vocal, warm analog synths, 110 bpm" \
--lyrics_file my_song.txt \
--duration 120 --steps 60 --seed 7 \
--format mp3 --output_path outputs/my_song.mp3
```
Полный список — `python infer.py --help`. Основные опции: `--prompt`, `--lyrics` / `--lyrics_file`, `--duration`, `--steps`, `--guidance_scale`, `--scheduler`, `--cfg_type`, `--omega_scale`, `--seed`, `--format`, `--output_path`. Флаги режима работы (`--bf16`, `--cpu_offload`, `--overlapped_decode`, `--torch_compile`, `--device_id`) те же, что у графического интерфейса.
Без `--prompt` скрипт ведёт себя как раньше и генерирует по случайному примеру из `examples/input_params`.
#### 🔍 Использование как библиотеки
Если вы хотите встроить ACE-Step как библиотеку в собственный Python-проект, можно поставить последнюю версию прямо из GitHub.
**Установка через pip:**
1. **Убедитесь, что установлен Git:** этот способ требует наличия Git в системе и в переменной PATH.
2. **Выполните команду установки:**
```bash
pip install git+https://github.com/ace-step/ACE-Step.git
```
Рекомендуется выполнять её внутри виртуального окружения, чтобы не ломать другие пакеты.
#### 🛠️ Аргументы командной строки
- `--checkpoint_path`: путь к весам модели (по умолчанию скачиваются автоматически)
- `--server_name`: IP-адрес или имя хоста, на котором слушает сервер Gradio (по умолчанию `127.0.0.1`). Укажите `0.0.0.0`, чтобы открыть доступ с других устройств в сети.
- `--port`: порт сервера Gradio (по умолчанию 7865)
- `--device_id`: номер GPU (по умолчанию 0)
- `--share`: включить публичную ссылку Gradio (по умолчанию False)
- `--bf16`: использовать точность bfloat16 для ускорения инференса (по умолчанию True)
- `--torch_compile`: использовать `torch.compile()` для оптимизации модели и ускорения инференса (по умолчанию False).
- **На Windows нужен triton**:
```
pip install triton-windows
```
- `--cpu_offload`: выгружать веса модели в оперативную память для экономии видеопамяти (по умолчанию False)
- `--overlapped_decode`: перекрывающееся декодирование для ускорения инференса (по умолчанию False)
## 📱 Описание интерфейса
Интерфейс ACE-Step разделён на вкладки под разные задачи генерации и редактирования:
### 📝 Вкладка Text2Music
1. **📋 Поля ввода**:
- **🏷️ Tags**: описательные теги, жанры или описание сцены через запятую
- **📜 Lyrics**: текст песни со структурными тегами вроде [verse], [chorus], [bridge]
- **⏱️ Audio Duration**: желаемая длительность аудио (-1 — случайная)
2. **⚙️ Настройки**:
- **🔧 Basic Settings**: количество шагов инференса, guidance scale, сиды
- **🔬 Advanced Settings**: тонкая настройка типа планировщика, типа CFG, параметров ERG и прочего
3. **🚀 Генерация**: нажмите «Generate», чтобы создать музыку по введённым данным
### 🔄 Вкладка Retake
- 🎲 Повторная генерация с небольшими отличиями за счёт других сидов
- 🎚️ Параметр variance задаёт, насколько результат будет отличаться от оригинала
### 🎨 Вкладка Repainting
- 🖌️ Выборочная перегенерация отдельных фрагментов трека
- ⏱️ Задаются время начала и конца перерисовываемого участка
- 🔍 Источник аудио выбирается: результат text2music, последняя перерисовка или загруженный файл
### ✏️ Вкладка Edit
- 🔄 Изменение готовой музыки через правку тегов или текста
- 🎛️ Режим «only_lyrics» сохраняет мелодию, режим «remix» её меняет
- 🎚️ Параметры редактирования задают, насколько сохраняется оригинал
### 📏 Вкладка Extend
- ➕ Добавление музыки в начало или в конец существующего трека
- 📐 Задаются длины расширения слева и справа
- 🔍 Выбирается источник аудио для расширения
## 📂 Примеры
В каталоге `examples/input_params` лежат примеры входных параметров — их можно использовать как образец для генерации.
## 🏗️ Архитектура
## 🔨 Обучение
Подробная инструкция — в [TRAIN_INSTRUCTION.md](./TRAIN_INSTRUCTION.md).
## 📜 Лицензия и отказ от ответственности
Проект распространяется по лицензии [Apache License 2.0](./LICENSE)
ACE-Step позволяет создавать оригинальную музыку в самых разных жанрах и применим в творческом продакшене, образовании и развлечениях. Модель создавалась для позитивных и художественных сценариев использования, но мы осознаём и риски: непреднамеренное нарушение авторских прав из-за стилистического сходства, некорректное смешение культурных элементов, а также использование для генерации вредоносного контента. Для ответственного использования мы призываем проверять оригинальность полученных работ, явно указывать участие ИИ и получать необходимые разрешения при адаптации защищённых стилей или материалов. Используя ACE-Step, вы соглашаетесь придерживаться этих принципов и уважать художественную целостность, культурное разнообразие и требования законодательства. Авторы не несут ответственности за неправомерное использование модели, включая, помимо прочего, нарушение авторских прав, культурную бестактность или создание вредоносного контента.
🔔 Важное замечание
Единственный официальный сайт проекта ACE-Step — наша страница на GitHub Pages.
Никаких других сайтов мы не ведём.
🚫 Поддельные домены включают (но не ограничиваются ими):
ac\*\*p.com, a\*\*p.org, a\*\*\*c.org
⚠️ Будьте осторожны. Не заходите на эти сайты, не доверяйте им и не совершайте на них платежей.
## 🙏 Благодарности
Проект развивается совместно ACE Studio и StepFun.
## 📖 Цитирование
Если проект оказался полезен для вашего исследования, пожалуйста, сошлитесь на него:
```BibTeX
@misc{gong2025acestep,
title={ACE-Step: A Step Towards Music Generation Foundation Model},
author={Junmin Gong, Wenxiao Zhao, Sen Wang, Shengyuan Xu, Jing Guo},
howpublished={\url{https://github.com/ace-step/ACE-Step}},
year={2025},
note={GitHub repository}
}
```