docs: revise glossary to v1.1 — fix factual errors, improve ML explanations for beginners

Six factual corrections: slash chord definition (inversions vs on-chords),
logits described as unnormalized, #11 = eleventh not fourth, duplicate
Polukadentsiya sentence removed, pre-training LR corrected to 1e-4,
unverified PAD index claim removed. All ML term explanations rewritten
with analogies accessible to a near-beginner.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/glossary.md

@@ -1,6 +1,6 @@
 # Глоссарий hamori
 
-**Версия документа:** 1.0
+**Версия документа:** 1.1
 **Дата:** 2026-05-19
 
 Документ содержит определения терминов, используемых в проекте _hamori_,
@@ -38,8 +38,8 @@
 
 ### Бас
 
-Самая нижняя нота аккорда. Может совпадать с корневым тоном (основной
-позиции) или отличаться от него (в инверсиях и слэш-аккордах). В формате
+Самая нижняя нота аккорда. Может совпадать с корневым тоном (основная
+позиция) или отличаться от него (в инверсиях и слэш-аккордах). В формате
 проекта бас выделен в отдельный слот токенизации.
 
 ### Гармоническая функция
@@ -83,8 +83,8 @@
 
 Гармонический оборот, завершающий музыкальную фразу. Полная каденция —
 переход доминанты в тонику (V → I). Полукаденция — остановка на
-доминанте, создающая ожидание продолжения. Полукаденция — характерный
-признак середины периода в классических формах.
+доминанте, создающая ожидание продолжения; характерный признак середины
+периода в классических формах.
 
 ### Качество (тип) аккорда
 
@@ -135,8 +135,8 @@
 Аккорд, расширенный девятой ступенью от корня. В формате проекта —
 `Cmaj9` (мажорный септаккорд + натуральная нона), `C9` (доминантовый
 септаккорд + нона), `Cm9` (минорный септаккорд + нона), `Cmaj7#11` (с
-повышенной квартой), и другие. Записывается как качество + расширение в
-слоте `EXT`.
+повышенной ундецимой, лидийский аккорд) и другие. Расширение кодируется
+токеном в слоте `EXT`, качество (например, `maj7`) — в слоте `QUAL`.
 
 ### Подразделение доли (subdivision)
 
@@ -179,10 +179,12 @@ IV — V — iii — vi (например, в C major: `F → G → Em → Am`).
 
 ### Слэш-аккорд (slash chord, on-аккорд)
 
-Аккорд с явно указанным басом, отличным от любой ноты собственного состава.
-Записывается как `<аккорд>/<бас>`. Характерный приём японской поп-музыки:
-`F/G`, `C/D`, `Em7/A` — обеспечивают плавное движение баса и характерное
-напряжение.
+Аккорд с явно указанным басовым тоном, записываемым через косую черту:
+`<аккорд>/<бас>`. Бас может быть любой из 12 нот. Если он входит в состав
+аккорда — это инверсия: `C/E` (C major с E в басу, первое обращение).
+Если не входит — это он-аккорд: `F/G` (F major с чужим G в басу).
+Характерный приём японской поп-музыки; создаёт плавное движение баса и
+характерное напряжение.
 
 ### Тактовый размер
 
@@ -225,43 +227,55 @@ IV — V — iii — vi (например, в C major: `F → G → Em → Am`).
 ### Авторегрессионная модель
 
 Модель, генерирующая последовательность по одному элементу за раз, причём
-каждый следующий элемент условен на всех предыдущих. Декодер-only
-трансформер, используемый в проекте, — пример авторегрессионной модели.
+каждый следующий элемент определяется всеми предыдущими. По сути —
+«предсказание следующего слова» в расширенном смысле: модель получает на
+вход всё сгенерированное до сих пор и выдаёт вероятность каждого
+возможного продолжения. Точно так же работает автодополнение на смартфоне,
+только на более сложных данных. Декодер-only трансформер, используемый в
+проекте, — пример авторегрессионной модели.
 
 ### Beam search
 
 Алгоритм поиска наиболее вероятной последовательности при генерации:
-вместо сэмплирования удерживается несколько лучших кандидатов на каждом
-шаге, выбирается итоговая последовательность с максимальной совместной
-вероятностью. В проекте **не используется**, поскольку для генеративных
-творческих задач даёт монотонные результаты.
+вместо того чтобы выбирать один токен и двигаться дальше, алгоритм
+удерживает несколько (обычно 3–10) лучших «кандидатных» продолжений
+одновременно, а в конце возвращает то, у которого наибольшая суммарная
+вероятность. Даёт более «правильные» последовательности, но монотонные —
+разнообразие и неожиданные идеи теряются. В проекте **не используется**
+именно по этой причине.
 
 ### Catastrophic forgetting (катастрофическое забывание)
 
-Феномен, при котором при дообучении модели на новом наборе данных она
-теряет знания, выученные на исходном корпусе. В проекте митигируется
-существенным снижением скорости обучения на этапе дообучения и
-ограничением числа эпох.
+Феномен, при котором дообучение модели на новых данных «вытесняет» знания,
+полученные на исходном корпусе. Аналогия: студент, который интенсивно
+зубрит новый предмет, со временем начинает хуже помнить старый материал.
+В проекте митигируется существенным снижением скорости обучения на этапе
+дообучения и ограничением числа эпох.
 
 ### Causal mask (причинная маска)
 
-Маска внимания в декодер-only трансформере, не позволяющая каждой позиции
-«видеть» будущие позиции в последовательности. Обеспечивает корректное
-обучение задачи предсказания следующего токена.
+Маска внимания в декодер-only трансформере, запрещающая каждой позиции
+«видеть» будущие позиции в последовательности. Без неё во время обучения
+модель могла бы просто подсматривать правильный ответ — следующий токен,
+— вместо того чтобы его предсказывать, и обучение стало бы бессмысленным.
+На инференсе маска не нужна: следующего токена ещё нет.
 
 ### Cross-entropy loss
 
-Функция потерь, измеряющая расхождение между предсказанным моделью
-распределением вероятностей следующего токена и истинным значением. Стандартная
-функция потерь для задач классификации и генерации последовательностей.
+Функция потерь, измеряющая качество предсказания следующего токена. Если
+модель назначила правильному токену высокую вероятность (например, 0.9) —
+потеря мала; если низкую (0.01) — потеря велика. Оптимизатор двигает веса
+в сторону уменьшения этой потери. Стандартная функция потерь для задач
+предсказания следующего элемента последовательности.
 
 ### Декодер-only трансформер
 
-Архитектура нейросети, состоящая из стека одинаковых блоков, каждый из
-которых содержит self-attention с причинной маской и feedforward-слой.
-В отличие от encoder-decoder архитектуры, у декодер-only нет отдельного
-блока для кодирования входа — всё обрабатывается одной башней. GPT-семейство
-языковых моделей — наиболее известный пример. Используется в данном проекте.
+Архитектура нейросети: несколько одинаковых блоков, уложенных стопкой.
+Каждый блок содержит механизм self-attention с причинной маской и
+feedforward-слой (две матрицы с нелинейностью между ними). Весь ввод
+обрабатывается в одном стеке — без разделения на «кодировщик» и
+«декодировщик», как в ранних переводческих моделях. GPT — наиболее
+известный пример. Используется в данном проекте.
 
 ### Дообучение (fine-tuning)
 
@@ -272,14 +286,17 @@ IV — V — iii — vi (например, в C major: `F → G → Em → Am`).
 
 ### Embedding (эмбеддинг)
 
-Числовое векторное представление дискретного элемента (токена). В трансформере
-эмбеддинги токенов и позиций суммируются и подаются в первый блок. Размерность
-эмбеддинга равна размерности модели (`d_model`).
+Числовое векторное представление дискретного элемента: каждому из 81
+токенов словаря сопоставляется вектор из `d_model` (128–256) вещественных
+чисел. Эти числа не задаются вручную — они обучаются вместе с остальными
+весами. Можно думать об эмбеддинге как о «характеристике» токена: похожие
+по контексту токены оказываются близко друг к другу в пространстве
+эмбеддингов. Размерность эмбеддинга равна `d_model`.
 
 ### Epoch (эпоха)
 
-Один полный проход обучающего цикла по всем элементам тренировочной выборки.
-В проекте предобучение длится до 50 эпох с ранней остановкой,
+Один полный проход обучающего цикла по всем примерам тренировочной
+выборки. В проекте предобучение длится до 50 эпох с ранней остановкой,
 дообучение — до 15.
 
 ### Holdout (отложенная выборка)
@@ -292,75 +309,98 @@ IV — V — iii — vi (например, в C major: `F → G → Em → Am`).
 
 ### LayerNorm (нормализация слоя)
 
-Нормализующее преобразование, стабилизирующее распределение активаций
-внутри сети. В архитектуре проекта применяется в pre-norm варианте
-(перед residual connection, не после).
+Нормализующее преобразование, которое пересчитывает активации внутри
+каждого слоя так, чтобы их среднее было около нуля, а дисперсия — около
+единицы. Без нормализации числа в глубоких сетях склонны расти или убывать
+экспоненциально («взрываться» или «затухать»), что делает обучение
+нестабильным. В архитектуре проекта применяется в pre-norm варианте
+(перед операцией внимания, не после).
 
 ### Learning rate
 
-Скорость обучения, коэффициент шага оптимизатора. В проекте используется
-значение `3e-4` на этапе предобучения и `1e-5` на этапе дообучения —
-двухпорядковая разница принципиальна для предотвращения катастрофического
-забывания.
+Скорость обучения — насколько большой шаг делает оптимизатор при каждом
+обновлении весов. Большое значение — обучение быстрее, но легко
+«перескочить» мимо оптимума. Малое — стабильно, но медленно. В проекте
+используется значение около 1e-4 на этапе предобучения и 1e-5 на этапе
+дообучения: десятикратная разница принципиальна для предотвращения
+катастрофического забывания.
 
 ### Logits
 
-Выход модели перед применением softmax — нормализованные числовые
-оценки, отражающие предпочтения модели по каждому возможному следующему
-токену. Используются в функции потерь и в процессе сэмплирования.
+Выход последнего слоя модели до применения softmax — 81 ненормализованное
+вещественное число (по одному на каждый токен словаря), отражающих
+«предпочтения» модели. Большой логит означает, что модель считает токен
+более вероятным продолжением. Softmax преобразует их в нормализованное
+распределение вероятностей с суммой 1.
 
 ### Multi-head attention
 
-Механизм self-attention, в котором операция внимания выполняется
-параллельно несколькими «головами», каждая со своими обучаемыми
-проекциями. Результаты голов конкатенируются. В проекте используется
-6 голов.
+Механизм self-attention (см.), в котором внимание вычисляется параллельно
+несколькими «головами» — каждая со своими обучаемыми проекциями. Результаты
+всех голов конкатенируются и проецируются линейным слоем в итоговый вектор.
+Интуиция: разные головы специализируются на разных типах связей — одна
+может улавливать смену аккорда, другая — структуру такта, третья — позицию
+относительно границ бара. В проекте используется 6 голов.
 
 ### Nucleus sampling (top-p sampling)
 
-Стратегия сэмплирования, при которой на каждом шаге сохраняется
-минимальный по числу элементов набор кандидатов с накопленной
-вероятностью не менее заданного порога `p`, после чего из этого набора
-происходит сэмплирование. Применяется в проекте с `p = 0.9` по умолчанию.
+Стратегия сэмплирования: на каждом шаге берётся минимальное подмножество
+токенов, чьи вероятности в сумме составляют не менее порога `p` (например,
+0.9), — и следующий токен выбирается случайно из этого подмножества. Это
+позволяет избежать двух крайностей: «жадный» выбор (всегда берём самый
+вероятный токен) даёт монотонные результаты, а полностью случайный — бессвязные.
+Применяется в проекте с `p = 0.9` по умолчанию.
 
 ### Padding
 
 Дополнение коротких последовательностей до фиксированной длины специальным
-токеном. В проекте — токен `<PAD>` (индекс 2 в словаре), игнорируемый в
-функции потерь через параметр `ignore_index`.
+токеном `<PAD>`. При батчевой обработке все последовательности в батче
+должны быть одной длины; паддинг — технический приём для выравнивания.
+Паддинговые позиции игнорируются в функции потерь через параметр
+`ignore_index`.
 
 ### Perplexity (перплексия)
 
 Метрика качества языковой модели, рассчитываемая как экспонента средней
 кросс-энтропии. Содержательно — «эффективное число равновероятных
-альтернатив», между которыми модель колеблется на каждом шаге. Чем
-меньше, тем лучше. В проекте используется как основная численная метрика
-сравнения базовой и дообученной моделей.
+альтернатив», между которыми модель колеблется на каждом шаге. Например,
+perplexity = 5 означает: в среднем модель как будто выбирает из пяти
+одинаково вероятных токенов — лучше, чем случайный выбор из всех 81, но
+далеко от идеала (perplexity = 1). Чем меньше, тем лучше. В проекте
+используется как основная численная метрика сравнения предобученной и
+дообученной моделей.
 
 ### Positional embedding (позиционный эмбеддинг)
 
 Векторное представление позиции токена в последовательности, добавляемое
-к токеновому эмбеддингу. Позволяет модели учитывать порядок элементов
-(сам по себе self-attention перестановочно-инвариантен). В проекте
+к токеновому эмбеддингу. Механизм self-attention сам по себе не различает
+порядок: для него перестановка токенов местами незаметна — обрабатывается
+«как множество, а не список». Позиционный эмбеддинг исправляет это: первый
+токен получает один вектор позиции, второй — другой и т. д. В проекте
 используются обучаемые позиционные эмбеддинги.
 
 ### Pre-norm vs post-norm
 
-Два варианта размещения LayerNorm в блоке трансформера: до residual
-connection (pre-norm) или после (post-norm). Pre-norm обычно более
-стабилен при обучении. В проекте используется pre-norm.
+Два варианта размещения LayerNorm внутри блока трансформера. В pre-norm
+нормализация идёт до операции (attention или feedforward), и результат
+добавляется к исходному вектору через residual connection (прямое
+сложение): `x + Sublayer(LN(x))`. В post-norm нормализация идёт после
+сложения: `LN(x + Sublayer(x))`. Pre-norm обычно более стабилен при
+обучении глубоких моделей. В проекте используется pre-norm.
 
 ### Предобучение (pre-training)
 
-Этап обучения модели на большом и общем по содержанию корпусе данных,
-после которого следует адаптация модели к более узкой задаче или домену.
-В проекте предобучение выполняется на McGill Billboard Project.
+Этап обучения модели на большом и разнообразном корпусе данных, после
+которого следует адаптация к более узкой задаче. В проекте предобучение
+выполняется на McGill Billboard Project, чтобы модель усвоила общие
+закономерности гармонии до знакомства с личным корпусом автора.
 
 ### Ранняя остановка (early stopping)
 
 Приём, прекращающий обучение, когда метрика на валидационной выборке
-перестаёт улучшаться на протяжении заданного числа эпох. Предотвращает
-переобучение. В проекте используется с параметром терпения 5 эпох.
+перестаёт улучшаться на протяжении заданного числа эпох. Защищает от
+переобучения: модель не успевает «вызубрить» тренировочные данные в ущерб
+обобщению. В проекте используется с параметром терпения 5 эпох.
 
 ### Round-trip эквивалентность
 
@@ -372,23 +412,30 @@ connection (pre-norm) или после (post-norm). Pre-norm обычно бо
 
 ### Self-attention
 
-Механизм внимания, в котором последовательность взаимодействует сама с
-собой: для каждой позиции рассчитываются взвешенные средние значений с
-других позиций, веса определяются скалярными произведениями обучаемых
-проекций. Центральный элемент архитектуры трансформера.
+Механизм, позволяющий каждому токену «посмотреть» на все остальные токены
+в последовательности и взять от них взвешенную сумму. Для каждой пары
+позиций вычисляется «вес внимания» — насколько одна позиция важна для
+другой. Веса определяются скалярным произведением обучаемых проекций:
+каждая позиция имеет вектор «вопроса» (query) и «ключа» (key), а суммируются
+«значения» (value). Благодаря этому токен аккорда может «знать» о контексте
+предыдущего аккорда или о своём положении внутри такта.
 
 ### Softmax с температурой
 
-Модификация softmax, в которой логиты предварительно делятся на
-параметр температуры. При температуре больше 1 распределение становится
-более равномерным (генерация разнообразнее), при меньше 1 — более
-концентрированным (генерация консервативнее). По умолчанию в проекте — 1.0.
+Модификация softmax, в которой логиты предварительно делятся на параметр
+температуры. При температуре выше 1 распределение становится более
+равномерным (генерация разнообразнее и рискованнее), при температуре ниже
+1 — более концентрированным на лучших вариантах (генерация консервативнее).
+Температура 1.0 оставляет исходные вероятности без изменений. В проекте
+по умолчанию используется 1.0.
 
 ### Tied weights (связанные веса)
 
-Приём, при котором веса входного эмбеддинга и финальной проекции на
-словарь совпадают (одна и та же матрица). Снижает число параметров и
-часто улучшает обобщающую способность. Применяется в проекте.
+Приём, при котором матрица входного эмбеддинга и матрица финальной
+проекции на словарь — это одна и та же матрица. Снижает число параметров
+и нередко улучшает качество: логично, что вектор, представляющий токен
+на входе, должен быть похож на то, с чем сравниваются логиты на выходе.
+Применяется в проекте.
 
 ### Токен
 
@@ -412,9 +459,11 @@ connection (pre-norm) или после (post-norm). Pre-norm обычно бо
 
 ### Warmup (разогрев)
 
-Начальная фаза обучения, в течение которой learning rate линейно растёт
-от нуля до целевого значения. Стабилизирует обучение трансформеров на
-первых шагах. В проекте — 5% от общего числа шагов.
+Начальная фаза обучения, в течение которой learning rate линейно возрастает
+от нуля до целевого значения. На самых первых шагах веса ещё не настроены,
+и большой шаг оптимизатора может «сломать» начальную конфигурацию — привести
+к нестабильным потерям. Постепенный разогрев решает эту проблему. В проекте
+warmup составляет 5% от общего числа шагов.
 
 ### Чекпоинт
 
@@ -564,4 +613,11 @@ Dataclass, представляющий полностью разобранны
 
 ## 4. История изменений
 
+- **1.1** (2026-05-19) — исправлены ошибки: определение слэш-аккорда
+  (бас может входить в состав аккорда), термин для `#11` (ундецима, не
+  кварта), определение logits (ненормализованные оценки), значение learning
+  rate для предобучения, паддинг (убрана непроверенная привязка к индексу).
+  Все термины машинного обучения переработаны для читателя без опыта в ML:
+  добавлены аналогии, конкретные примеры и пояснения для понятий
+  residual connection, causal mask, warmup и positional embedding.
 - **1.0** (2026-05-19) — первоначальная редакция документа.