From 355341dab9e9e970612ecf3c98e73f2bcb4edacc Mon Sep 17 00:00:00 2001 From: Masahiko AMANO Date: Tue, 19 May 2026 15:39:25 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20revise=20glossary=20to=20v1.1=20?= =?UTF-8?q?=E2=80=94=20fix=20factual=20errors,=20improve=20ML=20explanatio?= =?UTF-8?q?ns=20for=20beginners?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/glossary.md | 224 +++++++++++++++++++++++++++++------------------ 1 file changed, 140 insertions(+), 84 deletions(-) diff --git a/docs/glossary.md b/docs/glossary.md index 5147716..e21114d 100644 --- a/docs/glossary.md +++ b/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 Дополнение коротких последовательностей до фиксированной длины специальным -токеном. В проекте — токен `` (индекс 2 в словаре), игнорируемый в -функции потерь через параметр `ignore_index`. +токеном ``. При батчевой обработке все последовательности в батче +должны быть одной длины; паддинг — технический приём для выравнивания. +Паддинговые позиции игнорируются в функции потерь через параметр +`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) — первоначальная редакция документа.