# Шпаргалка по генерации — hamori **Версия документа:** 1.0 **Дата:** 2026-05-21 Единый справочник по запуску `scripts/generate.py`: параметры, поведение модели, покрытие корпуса, паттерны префиксов и настройка сэмплирования. --- ## 1. Быстрый старт ```bash # Минимальный вызов — хорус в Ab major, 8 тактов python scripts/generate.py \ --checkpoint checkpoints/finetuned.pt \ --mode major --key Ab --function chorus \ --bars 8 --midi output/gen.mid --output output/gen.chord # С префиксом (первые два такта заданы вручную) python scripts/generate.py \ --checkpoint checkpoints/finetuned.pt \ --mode minor --key F# --function verse \ --bars 8 --prefix "F#m . . . Dmaj7 . . ." \ --temperature 1.1 --midi output/gen.mid --output output/gen.chord ``` Если `--bars` не задан, модель сама решает, когда закончить (обычно 2–8 тактов). Если `--prefix` не задан, автоматически подставляется тоника (`--no-tonic-anchor` отключает это поведение). --- ## 2. Полный справочник параметров ### 2.1 Обязательные | Параметр | Тип | Описание | | -------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `--checkpoint` | путь | `.pt`-файл чекпоинта. Используйте `checkpoints/finetuned.pt` после дообучения или `checkpoints/pretrained.pt` как базовый вариант. | | `--mode` | `major` \| `minor` | Тональный наклон. Определяет канонический ключ для нормировки (C major / A minor). | | `--key` | нота | Корневой тон выходного ключа: `C`, `F#`, `Bb`, `Ab` и т.д. | | `--output` | путь | Путь к выходному `.chord`-файлу (расширение добавляется автоматически). | ### 2.2 Музыкальный контекст | Параметр | Умолчание | Допустимые значения | Описание | | --------------- | ------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------- | | `--function` | `unspecified` | `verse`, `chorus`, `bridge`, `prechorus`, `intro`, `interlude`, `outro` | Раздел произведения. Напрямую влияет на стиль прогрессии — см. §3.2. | | `--style` | `H1K0` | `H1K0` (единственный обученный) | Тег стиля. Другие значения тихо заменяются на `other`. | | `--time` | `4/4` | `4/4`, `3/4`, `6/8` и др. | Размер. Модель обучена почти исключительно на `4/4`. | | `--subdivision` | `4` | `4`, `8` | Позиций на единицу счёта. `4` = одна позиция на четверть в 4/4. | ### 2.3 Управление длиной | Параметр | Умолчание | Описание | | -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ | | `--bars` | `None` | Остановиться ровно после N полных тактов. EOS подавляется до достижения цели. Без этого параметра модель останавливается сама. | | `--max-tokens` | `300` | Жёсткий предел токенов. Страховочный — при нормальной работе не достигается (8 тактов ≈ 70–130 токенов). | ### 2.4 Префикс | Параметр | Умолчание | Описание | | ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `--prefix` | `None` | Пробел-разделённые аккорды в заданном ключе: `"Cmaj7 . Am7 ."`. Поддерживаются `.` (держать) и `NC` (без аккорда). Подробнее — §4. | | `--no-tonic-anchor` | выкл. | Не подставлять тонику автоматически, когда `--prefix` не задан. | ### 2.5 Сэмплирование | Параметр | Умолчание | Рекомендованный диапазон | Описание | | --------------- | --------- | ------------------------ | --------------------------------------------- | | `--temperature` | `1.0` | `0.8–1.3` | Степень «рискованности». Подробнее — §5. | | `--top-p` | `0.9` | `0.85–0.95` | Ширина ядра nucleus sampling. Подробнее — §5. | | `--seed` | `None` | любое целое | Фиксирует RNG для воспроизводимости. | ### 2.6 Вывод | Параметр | Умолчание | Описание | | ---------- | --------- | -------------------------------------------------------------- | | `--midi` | `None` | Путь к MIDI-файлу (`.mid` добавляется автоматически). | | `--tempo` | `90` | Темп MIDI в BPM. Не влияет на генерацию аккордов. | | `--device` | `auto` | `cpu`, `cuda` или `auto`. Для инференса CPU вполне достаточно. | --- ## 3. Покрытие корпуса Модель обучена на нормализованных ключах (всё → C major / A minor), поэтому **транспозиция не влияет на качество**. Однако количество примеров по функциям и соотношение major/minor всё же сказываются на уверенности модели. ### 3.1 Ключи (до нормировки) Ключ в `.chord`-файле используется только для транспозиции результата обратно. Генерация происходит в C/Am — модель «не знает», в каком ключе вы запросили результат. Тем не менее ниже показано фактическое распределение корпуса: | Тир | Ключ | Файлов | Заметки | | ----------------- | -------------------------- | ------ | ---------------------------------- | | ★★★ высокий охват | C major | 15 | Наибольшее число примеров | | ★★★ | F minor | 12 | | | ★★☆ средний охват | G major | 9 | | | ★★☆ | Ab major | 8 | | | ★★☆ | Eb major | 7 | | | ★☆☆ низкий охват | E minor | 4 | | | ★☆☆ | D major | 3 | | | ★☆☆ | B minor | 3 | | | ☆☆☆ единичные | G minor, Db major | 2 | Стиль может быть менее характерным | | ☆☆☆ | E major, F# minor, F major | 1 | | Низкий охват влияет не на «правильность» гармонии (модель транспонирует из C/Am), а на то, насколько сгенерированная прогрессия будет похожа именно на ваш стиль в этой тональности. ### 3.2 Функции | Функция | Файлов | Характер | | ----------- | ------ | ------------------------------------------------------------- | | `chorus` | 21 | Наилучшее покрытие. Прогрессии, как правило, более активные. | | `verse` | 19 | Хорошее покрытие. Тяготеет к более спокойным движениям. | | `bridge` | 9 | Среднее. Модальные сдвиги, неожиданные обороты. | | `intro` | 6 | Среднее. Часто тоника-доминанта. | | `prechorus` | 6 | Среднее. Направленное движение к доминанте. | | `interlude` | 5 | Ниже среднего. Может быть менее предсказуемым. | | `outro` | 2 | Минимум. Результат неустойчив — экспериментируйте с `--seed`. | ### 3.3 Наклон (mode) Корпус содержит 46 major-файлов и 22 minor-файла (соотношение ~2:1). При генерации в minor-ладу модель чуть менее уверена — рекомендуется чуть снизить температуру (`--temperature 0.9–1.0`) или задать prefix. --- ## 4. Паттерны префиксов Префикс — это начало прогрессии, которое вы задаёте вручную. Модель продолжает с того места, где вы остановились. ### 4.1 Синтаксис ``` --prefix "Аккорд позиция позиция позиция Аккорд позиция ..." ``` - Каждый **аккорд** занимает одну позицию, записывается символом (`Fm7`, `Db`, `G/B`). - `.` — держать предыдущий аккорд ещё одну позицию. - `NC` — нет аккорда на этой позиции. - В 4/4 с `--subdivision 4` один такт = 4 позиции. ### 4.2 Шаблоны **Тоника-якорь (по умолчанию, без --prefix)** Автоматически подставляется один аккорд тоники. Даёт модели минимальный контекст. ```bash # Неявно: --prefix "Ab" (для --mode major --key Ab) ``` **Один такт (4 позиции)** Самый короткий полезный префикс — задаёт начало и тональный центр. ```bash --prefix "Fm . . ." # Fm на весь такт --prefix "Fm . Db ." # Fm половину, Db половину --prefix "Fm7 . Eb . " # сменная гармония в рамках такта ``` **Два такта (8 позиций)** Надёжно задаёт функцию и движение. ```bash --prefix "Abmaj7 . Fm7 . Db . Bbm ." # типичная прогрессия в Ab major --prefix "Bm . . . G . . ." # I–VI в B minor ``` **Развёрнутый контекст (12–16 позиций)** Для строгого продолжения заданной темы. ```bash --prefix "Fm . . . Db . Dbmaj7 . Fm . Fm7 . Eb . . ." ``` ### 4.3 Рекомендации | Ситуация | Рекомендация | | -------------------------------------------- | ------------------------------------------------------- | | Нужна характерная прогрессия в стиле корпуса | Хватит 1–2 тактов префикса | | Продолжение конкретной темы из вашей песни | 3–4 такта; используйте реальные аккорды из трека | | Полностью свободная генерация | `--no-tonic-anchor` (без префикса) | | Модель «соскальзывает» в I–IV–V | Задайте нетривиальный первый аккорд (`Abmaj7`, `Bm7b5`) | | Результат слишком похож на префикс | Повысьте температуру до 1.1–1.3 | --- ## 5. Температура и top-p ### 5.1 Температура (--temperature) ``` p(token) = softmax(logits / T) ``` | T | Эффект | Характер генерации | | --- | ------------------------------ | ------------------------------------------- | | < 1 | Распределение **заостряется** | Консервативно, склонно к повторениям | | = 1 | Без изменений (умолчание) | Нейтрально | | > 1 | Распределение **сглаживается** | Разнообразно, выше риск «странных» аккордов | ### 5.2 Nucleus sampling (--top-p) После применения T токены сортируются по убыванию вероятности. Накапливаем, пока сумма не достигнет `p` — остальное обнуляется. | p | Характер генерации | | -------- | ----------------------------------------------- | | 1.0 | Только T управляет выбором | | 0.95 | Широкое ядро, редко отсекает хорошие варианты | | **0.90** | **Умолчание** — баланс разнообразия и связности | | 0.80 | Меньше случайных аккордов | | 0.60 | Почти детерминированно | **Важно:** размер ядра не фиксирован. При уверенной модели `p=0.9` даёт 2–3 токена, при неуверенной — 20+. ### 5.3 Взаимодействие | | top-p высокий (0.95–1.0) | top-p низкий (0.5–0.7) | | ----------------------- | ----------------------------------------------------------- | -------------------------------------- | | **T высокая (1.2–1.5)** | Максимальное разнообразие, риск нефункциональных прогрессий | T и p частично компенсируют друг друга | | **T низкая (0.6–0.9)** | p практически не влияет — хвост уже ничтожен | Почти детерминированный вывод | ### 5.4 Шаблоны по задаче | Задача | --temperature | --top-p | Комментарий | | ------------------------- | ------------- | -------- | ------------------------------------------ | | Быстрый «рабочий» вариант | 0.8 | 0.9 | Консервативно, функционально | | **Стандартная генерация** | **1.0** | **0.9** | **Умолчание** | | Больше разнообразия | 1.1–1.2 | 0.9 | Расширения и заимствования появляются чаще | | Эксперимент | 1.3–1.5 | 0.85–0.9 | Неожиданные ходы, выше риск ошибок | | Финал / отчёт | 0.9 | 0.85 | Надёжный результат | ### 5.5 Симптомы и лечение | Симптом | Причина | Что сделать | | ---------------------------------------- | --------------------- | ---------------------- | | Повторяющийся I–IV–V, нет расширений | T слишком низкая | Поднять T до 1.1–1.3 | | Аккорды «не в тональности» | T слишком высокая | Снизить T до 0.8–1.0 | | Одинаковый результат при разных `--seed` | p слишком низкий | Поднять p до 0.9–0.95 | | Слишком много экзотических аккордов | p высокий + T высокая | Снизить p до 0.8 или T | | Прогрессия из 1–2 тактов (без `--bars`) | Модель уверена в EOS | Добавить `--bars N` | --- ## 6. Технические детали Реализация nucleus sampling в `src/generate.py`, функция `_sample_top_p`: ```python logits = logits / max(temperature, 1e-8) # применить температуру probs = softmax(logits) sorted_probs, sorted_idx = sort(probs, desc) cumulative = cumsum(sorted_probs) cut = (cumulative - sorted_probs) >= top_p # найти границу ядра sorted_probs[cut] = 0.0 # обнулить хвост sorted_probs /= sorted_probs.sum() # перенормировать token = multinomial(sorted_probs, 1) # сэмплировать ``` **Граммарная маска** (`_grammar_bias`) применяется поверх логитов до сэмплирования и блокирует синтаксически недопустимые токены независимо от T и p: - После `ROOT_x` допустимы только `QUAL_*`. - После `QUAL_x` — только `EXT_*`. - После `EXT_x` — только `BASS_*`. - `EOS` допустим только на границе такта (`pos_in_bar == 0`). - При заданном `--bars N`: `EOS` подавляется, пока не завершено N тактов.