Add Russian songwriting & lyrics guide for ACE-Step

research/ace-step-xl-research.md

@@ -0,0 +1,100 @@
+# ACE-Step 1.5 XL — исследование для RTX A2000 12GB
+
+**Дата:** 2026-08-30
+**Цель:** определить, что нужно изучить для вывода генерации на более высокий уровень
+**Модель:** `acestep-v15-xl-turbo` (4B DiT) на RTX A2000 12GB
+
+---
+
+## Ключевой вывод
+
+**RTX A2000 12GB = Tier 4 по классификации ACE-Step.** XL DiT официально НЕ поддерживается на этом tier — работает только через aggressive CPU offload + INT8 quantization, и только с LM-моделью **0.6B** (не 1.7B). Это накладывает жёсткие ограничения на «высокий уровень»: LoRA нельзя грузить на INT8-модель, а качество вокала на turbo-режиме всегда будет «грубее», чем на base.
+
+---
+
+## Обзор (синтез источников)
+
+ACE-Step 1.5 использует гибридную LM+DiT архитектуру: 5Hz Language Model строит Chain-of-Thought (планирует BPM/тональность/структуру), DiT генерирует звук [1][2]. Разделение на `caption` (звучание) и `lyrics` (структура песни) — ключевое отличие от Suno [3].
+
+Система автоматически определяет tier GPU по VRAM и подбирает настройки [2]:
+
+| VRAM | Tier | XL DiT | LM модель | Backend |
+|---|---|---|---|---|
+| ≤4GB | 1 | ❌ | None | pt |
+| 4–6GB | 2 | ❌ | None | pt |
+| 6–8GB | 3 | ⚠️ 0.6B | 0.6B | pt |
+| **8–12GB** | **4** | **⚠️ 0.6B** | **0.6B** | **vllm** |
+| 12–16GB | 5 | ⚠️ 0.6B, 1.7B | 1.7B | vllm |
+| 16–20GB | 6a | ✅ offload | 1.7B | vllm |
+| 20–24GB | 6b | ✅ | 1.7B | vllm |
+| ≥24GB | Unlimited | ✅ все | 4B | vllm |
+
+XL (4B) DiT весит ~9GB (vs ~4.7GB для 2B) [2]. На A2000 XL влезает только с offload + INT8, поэтому в текущей конфигурации `offload_to_cpu=True` — правильный выбор.
+
+---
+
+## Подтемы
+
+### 1. Качество генерации: turbo vs base
+
+- **Turbo** = 8 шагов, быстро (~12–22 сек на A2000), но вокал «грубее» с микроартефактами. guidance_scale=1.0 (CFG не поддерживается на turbo) [4].
+- **Base** = 32–100 шагов, медленнее, чище вокал, поддерживает CFG. Используется для стемов (`task_type="extract"`).
+- **XL turbo vs 2B turbo**: XL даёт чище и разборчивее вокал, но на A2000 XL требует offload [4].
+
+### 2. Параметры caption (что влияет на результат)
+
+Рекомендации из официальной документации [1][2]:
+- **Style**: конкретно про жанр, инструменты, настроение
+- **Natural language**: LM-DiT отлично понимает «a soft Bengali love song for a quiet evening»
+- **Formatting**: можно использовать `format_sample` API, чтобы LM-модель улучшила raw-теги в структурированный промпт
+- **vocal_language**: 50+ языков; указание языка помогает LM спланировать фонетику
+- caption — **английский** (модель лучше ловит стиль), lyrics — русский
+
+### 3. Качество русского вокала
+
+- `ru` есть в `VALID_LANGUAGES` — официально поддержан [4]
+- ACE-Step — единственная локальная модель с русским вокалом в топ-10 (v1.5: 50+ языков)
+- Вокал «грубоват» (признание авторов), русский звучит разборчиво, но с лёгкой синтетичностью
+- Для чистого русского вокала — base-модель вместо turbo
+
+### 4. Fine-tuning (LoRA) — путь к «высокому уровню»
+
+- LoRA позволяет обучить модель на свой/эталонный вокал [1]
+- **Работает с 8 песнями**; ~1 час на RTX 3090 для базового style LoRA
+- **КРИТИЧЕСКИЙ ПИТФОЛЛ**: LoRA-адаптеры НЕ грузятся на INT8-модели. Нужно `INT8 Quantization = None` перед загрузкой адаптера [2]
+- На A2000 12GB для LoRA-обучения нужен режим без INT8 → VRAM будет ~9.6GB для XL → рискованно, но возможно с offload
+- **Альтернатива**: обучить LoRA на 2B-модели (4.7GB, легко влезает) — быстрее, стабильнее
+
+### 5. Оптимизация VRAM (уже частично применена)
+
+- **CPU Offload**: модели переносятся в RAM когда не используются; автоматически на GPU <20GB [2]
+- **INT8 Quantization**: уменьшает VRAM DiT; автоматически на Tier 1–6a [2]
+- **Tiled VAE decode**: 3-уровневый фолбэк (GPU tiled → GPU+CPU → CPU) [2]
+- **Auto Chunk Size**: VAE decode chunk 64/128/256/512/1024/1536 адаптируется под свободный VRAM
+- **VRAM Guard**: перед каждой генерацией оценивает VRAM и уменьшает batch при необходимости
+- **Adaptive VAE Decode**: если free VRAM <2GB → tiled decode (именно это мы видим в логах: `Effective free VRAM: 1.81 GB`)
+
+### 6. Что НЕ изучено (рекомендации)
+
+- **benchmark** XL на A2000: реальная скорость при offload+INT8 (в логах ~22 сек — это с tiled decode)
+- **timestep shift / cfg_interval**: параметры качества diffusion
+- **constrained decoding / FSM**: контроль структуры
+- **DCW correction** (wavelet-фильтрация): уже активна в текущей конфигурации — стоит изучить влияние на качество
+
+---
+
+## Дополнительные вопросы
+
+1. Стоит ли обучать LoRA на 2B-модели (быстрее, стабильнее) или ждать XL?
+2. Какой эталонный вокал использовать для LoRA — свой или конкретный артист?
+3. Нужен ли base-режим для русского вокала (чище, но медленнее)?
+4. Стоит ли исследовать Side-Step (fine-tuning framework) для кастомных пресетов?
+
+---
+
+## Источники
+
+[1] DeepWiki — ACE-Step 1.5 Tutorials & Best Practices: https://deepwiki.com/ace-step/ACE-Step-1.5/10-tutorials-and-best-practices
+[2] ACE-Step 1.5 GPU Compatibility Guide: https://ace-step.github.io/ACE-Step-1.5/en/GPU_COMPATIBILITY
+[3] deAPI — ACE-Step 1.5 Prompting Guide: https://deapi.ai/blog/ace-step-1-5-prompting-guide-how-to-write-tags-structure-lyrics-and-generate-better-music
+[4] ACE-Step 1.5 README (skill ace-step-music-generation): https://github.com/ace-step/ACE-Step-1.5

research/ru-lyrics-guide.md

@@ -0,0 +1,206 @@
+# Русская песенная поэтика для ACE-Step
+
+**Дата:** 2026-08-30
+**Цель:** как писать красивые русские тексты с рифмой, как структурировать песню
+**Применение:** ACE-Step 1.5 (vocal_language="ru")
+
+---
+
+## Ключевой вывод
+
+ACE-Step читает **структуру** из квадратных тегов `[Verse]`/`[Chorus]` и **язык** из `lyrics`. Для русского:
+- **Рифма** = созвучие в окончании строк. Определяется **позиционно** (где стоит в конце строки).
+- **Ударение** задаёт тип рифмы: мужская (последний слог), женская (предпоследний), дактилическая (третий от конца).
+- **Согласованность рифмы в строфе** = паттерн (abab, aabb, abba, aaa). ACE-Step лучше понимает, если строфы однотипны.
+- **6–10 слогов в строке** — оптимально для модели (ACE-Step рекомендация).
+
+---
+
+## Обзор (синтез источников)
+
+Русская рифма — созвучие в двух или нескольких словах, определяемое **позиционно** (в конце строки, перед цезурой) [1]. Различают рифмы по месту ударения (мужские/женские/дактилические) и по точности созвучия (богатые/бедные/ассонанс/диссонанс) [1].
+
+ACE-Step 1.5 использует два «мозга»: LM (Songwriter) планирует структуру/тональность, DiT (Studio Engineer) строит звук [2]. Теги в `lyrics` указывают LM, *как* песня должна быть структурирована во времени [2].
+
+---
+
+## Подтемы
+
+### 1. Типы рифм по месту ударения
+
+**Мужская рифма** — ударение на последнем слоге. Звучит резко, уверенно.
+```
+Оборвана цепь жизни молодой,
+Пора туда, где будущего нет.
+```
+
+**Женская рифма** — ударение на предпоследнем слоге. Мягче, текучее.
+```
+Везде сребро да злато,
+Всё светло и богато.
+```
+
+**Дактилическая рифма** — ударение на третьем слоге от конца. Торжественная, размашистая.
+```
+Потонула деревня в ухабинах,
+Как синеют кругом небеса.
+```
+
+**Гипердактилическая** — ударение на 4-м слоге и далее. Редко, торжественно.
+
+> **Для ACE-Step:** чередуйте мужские и женские рифмы в строфе — так текст звучит естественнее. Сплошная мужская рифма (как «К детям» Хомякова) звучит монотонно.
+
+### 2. Типы рифм по точности
+
+**Богатая рифма** — совпадает опорный согласный. Звучит плотно, выразительно.
+```
+Любви, надежды, тихой славы
+Недолго нежил нас обман.
+```
+
+**Бедная рифма** — совпадает только ударный гласный. Мягче.
+
+**Ассонансная рифма** — совпадает только ударный гласный (согные разные).
+```
+За невестою своей
+Коровлевич Елисей.
+```
+
+**Диссонансная рифма** — не совпадают ударные гласные. Тёмная, напряжённая.
+
+> **Для ACE-Step:** богатая рифма даёт более «связанное» звучание вокала. Ассонанс — для более свободного, разговорного стиля.
+
+### 3. Паттерны рифмы в строфе
+
+В четверостишии возможны:
+
+| Паттерн | Название | Пример |
+|---|---|---|
+| **aabb** | смежная (парная) | `дом — дом / свет — свет` |
+| **abab** | перекрёстная | `дом — свет / дом — свет` |
+| **abba** | кольцевая (опоясывающая) | `дом — свет / свет — дом` |
+| **aaa** | сквозная | всё на одну рифму |
+| **aaxa** | с холостыми строками | рифмуются 1 и 3 строки |
+
+> **Для ACE-Step:** перекрёстная (abab) и кольцевая (abba) рифмы звучат богаче. Парная (aabb) — проще, лучше для припева.
+
+### 4. Структура песни (теги ACE-Step)
+
+```
+[Intro]          → Вступление, задаёт атмосферу, обычно инструментал
+[Verse]          → Основной рассказ, умеренная энергия
+[Pre-Chorus]     → Нарастание напряжения перед припевом
+[Chorus]         → Эмоциональный пик, максимальная энергия
+[Bridge]         → Смена: другая мелодия, другой настрой
+[Instrumental]   → Без вокала, только инструменты
+[Outro]          → Затухание, финал
+```
+
+> **ACE-Step рекомендует:** строки 6–10 слогов, UPPERCASE для акцента, `(скобки)` для бэк-вокала, описания к тегам: `[Chorus - anthemic]`, `[Verse - whispered]`.
+
+### 5. Типичная структура русской песни
+
+| Секция | Функция | Энергия |
+|---|---|---|
+| Intro | Настройка настроения | — |
+| Verse 1 | Задание сцены/сюжета | ★★ |
+| Chorus | Главная мысль, крюк | ★★★★★ |
+| Verse 2 | Развитие сюжета | ★★★ |
+| Chorus | Повтор крюка | ★★★★★ |
+| Bridge | Поворот, свежий взгляд | ★★★ |
+| Chorus | Финальный крюк | ★★★★★ |
+| Outro | Развязка | ★ |
+
+> **Крюк (hook):** фраза, которая запоминается. Обычно в припеве. ACE-Step «цепляется» за повторяющиеся строки.
+
+### 6. Ритм и размер
+
+- **Слог** = основа русского размера (4-сложный дактиль, 3-сложный амфибрахий, анапест).
+- **Цезура** = пауза в середине строки (перед рифмой или в середине).
+- **Согласованность числа слогов** в строках = ровный ритм. ACE-Step чувствителен к этому.
+
+> **Практика:** считайте слоги в каждой строке. Разница в 1–2 слога допустима, но 3+ ломает ритм.
+
+### 7. Рифмовальные приёмы
+
+- **Панторифма** — все слова в строке рифмуются (редко, эффектно).
+- **Внутренняя рифма** — рифма не только в конце строки, но и в середине.
+- **Энжамбем** — фраза не заканчивается в конце строки, продолжается в следующей.
+- **Анафора** — повтор слов в начале строк.
+- **Эпифора** — повтор слов в конце строк.
+
+---
+
+## Практические советы для ACE-Step
+
+1. **caption — английский, lyrics — русский.** Модели проще понять стиль по англ. caption, но вокал должен быть на русском.
+2. **Структура обязательна.** ACE-Step читает `[Verse]`/`[Chorus]` как карту. Без тегов — хаос.
+3. **Повторяйте припев.** ACE-Step «запоминает» повторяющиеся строки — это крюк.
+4. **6–10 слогов в строке.** Слишком длинные строки модель «жевает».
+5. **Описания к тегам.** `[Chorus - anthemic]` помогает LM понять энергию.
+6. **UPPERCASE** для акцента, `(скобки)` для бэк-вокала.
+7. **Считайте слоги.** Ровный ритм = ровный вокал.
+8. **Чередуйте мужские/женские рифмы.** Сплошная рифма = монотонность.
+
+---
+
+## Шаблон русской песни для ACE-Step
+
+```
+[Verse 1]
+Ты опять в дожде, под дождём идёт разговор,
+Говоришь про мечты, про который не спит.
+Мы с тобой на краю, где кончается город,
+Где слова не нужны — и не нужно торопить.
+
+[Pre-Chorus]
+И ветер в волосах, и свет впереди,
+Мы не оглянёмся — впереди мы.
+
+[Chorus]
+Мы идём вперёд, не сдаёмся,
+Мы поём эту песню вдвоём,
+Мы не знаем, что будет, но знаем —
+Мы не отпустим друг друга.
+
+[Verse 2]
+Прошёл уже год, но ты всё ещё здесь,
+Твои мечты не сгорели в огне.
+Мы с тобой не одни, мы с тобой не в плену,
+Мы с тобой не одни — мы с тобой.
+
+[Chorus]
+Мы идём вперёд, не сдаёмся,
+Мы поём эту песню вдвоём,
+Мы не знаем, что будет, но знаем —
+Мы не отпустим друг друга.
+
+[Bridge]
+Если станет темно — я зажгу свет,
+Если станет холодно — я согрею.
+Мы не знаем, что будет, но знаем —
+Мы не отпустим друг друга.
+
+[Chorus]
+Мы идём вперёд, не сдаёмся,
+Мы поём эту песню вдвоём,
+Мы не знаем, что будет, но знаем —
+Мы не отпустим друг друга.
+
+[Outro]
+Мы не отпустим... мы не отпустим...
+```
+
+**Анализ шаблона:**
+- Структура: abab в куплетах (разговор — город / не спит — торопить), припев aabb
+- 8–10 слогов в строках
+- Повтор крюка «Мы не отпустим друг друга» в каждой строке припева
+- Мужские рифмы в припеве (сдаёмся/не знаем — вдвоём/пути), женские в куплетах
+
+---
+
+## Источники
+
+[1] Википедия — Рифма: https://ru.wikipedia.org/wiki/Рифма
+[2] ACE-Step 1.5 — A Musician's Guide: https://github.com/ace-step/ACE-Step-1.5/blob/main/docs/en/ace_step_musicians_guide.md
+[3] ACE-Step 1.5 — DeepWiki Tutorials & Best Practices: https://deepwiki.com/ace-step/ACE-Step-1.5/10-tutorials-and-best-practices