# Руководство по параметрам сэмплирования **Версия документа:** 1.0 **Дата:** 2026-05-21 Документ объясняет, как параметры `--temperature` и `--top-p` скрипта `scripts/generate.py` влияют на качество генерации аккордовых прогрессий. --- ## 1. Температура (--temperature) Перед вычислением softmax каждый токен имеет сырой балл — **логит**. Температура `T` делит все логиты на себя перед нормировкой: ``` p(token) = softmax(logits / T) ``` | T | Эффект | Характер генерации | | --- | --------------------------------------------------------------------------------------------- | -------------------------------------------------- | | < 1 | Распределение **заостряется**: вероятность топ-токенов растёт, хвост коллапсирует | Консервативно, предсказуемо, склонно к повторениям | | = 1 | Распределение без изменений — именно то, что видела модель при обучении | Нейтрально (умолчание) | | > 1 | Распределение **сглаживается**: разрыв между вероятными и маловероятными токенами уменьшается | Разнообразно, экспериментально, больше «ошибок» | **Аналогия:** температура — это «уверенность» модели в своём выборе. При `T=0.5` модель действует как перфекционист, всегда выбирая самый «правильный» следующий аккорд. При `T=1.5` — как импровизатор, готовый рискнуть. --- ## 2. Nucleus sampling (--top-p) После применения температуры токены сортируются по убыванию вероятности. Идём по списку, накапливая вероятность, пока сумма не достигнет `p`. Всё, что осталось за порогом, обнуляется; оставшиеся вероятности перенормируются. ``` Пример при p=0.9: токен A: 0.45 → cumsum 0.45 ✓ оставить токен B: 0.30 → cumsum 0.75 ✓ оставить токен C: 0.15 → cumsum 0.90 ✓ оставить (граница) токен D: 0.07 → cumsum 0.97 ✗ отсечь ... ``` | p | Размер «ядра» | Характер генерации | | ---- | ---------------------------------------- | ------------------------------------------ | | 1.0 | Все токены | Только температура определяет выбор | | 0.95 | Широкое — много вариантов | Разнообразно, редко срезает хорошие токены | | 0.90 | Стандартное (умолчание) | Баланс разнообразия и связности | | 0.80 | Умеренно узкое | Меньше «случайных» аккордов | | 0.60 | Узкое — 1–5 токенов при уверенной модели | Ближе к жадному декодированию | **Ключевой момент:** размер ядра не фиксирован — он зависит от формы распределения. Если модель уверена (острое распределение), `p=0.9` может включать лишь 2–3 токена. Если неуверена (плоское распределение), те же `p=0.9` охватят 20+ токенов. --- ## 3. Взаимодействие параметров Температура и top-p **действуют последовательно**: сначала T, затем p. | | top-p высокий (0.95–1.0) | top-p низкий (0.5–0.7) | | ----------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------- | | **T высокая (1.2–1.5)** | Максимальное разнообразие, высокий риск нефункциональных прогрессий | T сглаживает, p отсекает — частично компенсируют друг друга | | **T низкая (0.6–0.9)** | T заостряет, хвост и так мал — p практически не влияет | Почти детерминированный вывод, высок риск повторений | **Вывод:** при низкой T повышение p бессмысленно — хвост уже ничтожен. При высокой T понижение p сдерживает хаос, но убивает часть разнообразия. --- ## 4. Шпаргалка для hamori ### 4.1 Шаблоны по задаче | Задача | --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 | Надёжный, с умеренным разнообразием | ### 4.2 Симптомы и лечение | Симптом | Вероятная причина | Что сделать | | -------------------------------------------------- | ------------------------------------------- | ------------------------------ | | Повторяющийся паттерн 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 такта | Модель уверена в EOS — используйте `--bars` | Добавить `--bars N` | ### 4.3 Примеры вызовов ```bash # Стандартный хорус в Ab major, 8 тактов python scripts/generate.py \ --checkpoint checkpoints/finetuned.pt \ --mode major --key Ab --function chorus \ --bars 8 --seed 42 # Экспериментальная версия того же python scripts/generate.py \ --checkpoint checkpoints/finetuned.pt \ --mode major --key Ab --function chorus \ --bars 8 --temperature 1.3 --top-p 0.9 --seed 42 # Консервативный куплет с якорным префиксом python scripts/generate.py \ --checkpoint checkpoints/finetuned.pt \ --mode minor --key F# --function verse \ --bars 8 --temperature 0.85 --top-p 0.85 \ --prefix "F#m . . . Dmaj7 . . ." ``` --- ## 5. Технические детали Реализация в `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_y`, и никакая высокая температура это не изменит.