From 0682ccc140b2fe1fca1bb1fc0aa0e64bdd90a84a Mon Sep 17 00:00:00 2001 From: Masahiko AMANO Date: Wed, 20 May 2026 12:46:09 +0300 Subject: [PATCH] docs: actualize README, architecture, requirements (v1.1) README: - processed/ tree now shows mcgill/ and user/ subdirs - --style user -> --style H1K0 in quick-start prefix example - pretrained.report.txt and finetuned.report.txt added to artifact tables architecture.md (-> v1.1): - remove stale music21 fallback mention from chord_parser section - fix ChordDataset: on-demand loading, not eager; remove non-existent make_dataloader from public interface - fix train function name: train_model -> train - update logging description: report goes to .report.txt, not stdout - note that scripts use max_seq_len=256 (sequences top out at 195 tokens) requirements.md (-> v1.1): - FT-12: update from unified script to pretrain.py + train.py pair Co-Authored-By: Claude Sonnet 4.6 --- README.md | 10 +++++++--- docs/architecture.md | 43 +++++++++++++++++++++++-------------------- docs/requirements.md | 19 ++++++++++--------- 3 files changed, 40 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 3cfdcbb..4a3a0d4 100644 --- a/README.md +++ b/README.md @@ -112,7 +112,9 @@ hamori/ ├── data/ │ ├── raw_user/ .chord-файлы собственного корпуса │ ├── raw_external/ публичные корпуса (McGill Billboard и др.) -│ ├── processed/ токенизированные .pt-файлы для обучения +│ ├── processed/ +│ │ ├── mcgill/ токенизированные .pt-файлы McGill (train/val) +│ │ └── user/ токенизированные .pt-файлы собственного корпуса │ └── holdout/ отложенная выборка для итоговой оценки ├── src/ │ ├── chord_parser.py парсинг аккордовых символов @@ -159,7 +161,7 @@ python scripts/generate.py \ ```bash python scripts/generate.py \ --checkpoint checkpoints/finetuned.pt \ - --mode major --key C --style user --function verse --time 4/4 \ + --mode major --key C --style H1K0 --function verse --time 4/4 \ --prefix "Cmaj7 Am7 Dm7" \ --output reports/samples/continuation.chord ``` @@ -266,6 +268,7 @@ python scripts/pretrain.py | `checkpoints/pretrained.pt` | лучший чекпоинт (по val loss) | | `checkpoints/pretrained.log.csv` | метрики по эпохам | | `checkpoints/pretrained_curves.png` | график кривых train/val loss | +| `checkpoints/pretrained.report.txt` | сводный отчёт о прогоне | Если обучение было прервано, повторно построить график и отчёт без повторного обучения: @@ -282,7 +285,8 @@ python scripts/train.py Загружает `checkpoints/pretrained.pt` и дообучает на собственном корпусе (`data/processed/user/`). Сохраняет `checkpoints/finetuned.pt` и аналогичный -набор артефактов (`finetuned.log.csv`, `finetuned_curves.png`). +набор артефактов (`finetuned.log.csv`, `finetuned_curves.png`, +`finetuned.report.txt`). Существенно более низкая скорость обучения (lr=1e-5 против 3e-4) и небольшое число эпох (15) предотвращают катастрофическое забывание закономерностей, diff --git a/docs/architecture.md b/docs/architecture.md index 4212780..d57b54b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -229,7 +229,7 @@ reports/figures/, reports/metrics.json **Связи.** Используется модулем `tokenizer.py` для разбора аккордов внутри периода. Не имеет зависимостей внутри проекта, кроме стандартной библиотеки -Python и опционально `music21` (как fallback для нетипичных написаний). +Python. ### 3.2 `src/tokenizer.py` @@ -304,12 +304,10 @@ Voicing внутри аккорда выполняется минимально длину последовательности. - `__getitem__` возвращает тензор токенов, обрезанный или дополненный паддингом до максимальной длины. -- Функция `make_dataloader(dataset, batch_size, shuffle) -> DataLoader` — - удобная фабрика. -**Ключевые соображения реализации.** Все `.pt`-файлы загружаются в память при -создании датасета. Это допустимо при текущем размере данных (тысячи периодов -максимум) и существенно ускоряет обучение по сравнению с подгрузкой с диска. +**Ключевые соображения реализации.** При инициализации датасет собирает список +путей к `.pt`-файлам; сами тензоры загружаются с диска по запросу в +`__getitem__`. При текущем размере данных это не является узким местом. Паддинг выполняется специальным токеном `` с индексом 2 в словаре. В функции потерь этот индекс игнорируется через параметр `ignore_index`. @@ -350,7 +348,7 @@ Voicing внутри аккорда выполняется минимально **Публичный интерфейс.** -- Функция `train_model(config: TrainConfig) -> Path` — основная точка +- Функция `train(config: TrainConfig) -> Path` — основная точка входа. Возвращает путь к лучшему чекпоинту. - Dataclass `TrainConfig` с полями для всех гиперпараметров. @@ -360,10 +358,12 @@ Voicing внутри аккорда выполняется минимально тот же код для предобучения и дообучения, различающихся только параметрами запуска (низкий learning rate, меньшее число эпох для дообучения). -Логирование: после каждой эпохи в stdout выводится строка с номером эпохи, -тренировочной потерей, валидационной потерей и валидационной перплексией. -Параллельно строка добавляется в CSV-лог. Лучший по валидационной потере -чекпоинт сохраняется отдельно. +Логирование: после каждой эпохи строка с номером эпохи, тренировочной +потерей, валидационной потерей и перплексией выводится через `logging.INFO`. +Параллельно строка добавляется в CSV-лог (`.log.csv`). По окончании +прогона скрипты `scripts/pretrain.py` и `scripts/train.py` записывают сводный +отчёт с полной таблицей метрик в текстовый файл (`.report.txt`). +Лучший по валидационной потере чекпоинт сохраняется отдельно. Ранняя остановка: если валидационная потеря не улучшается на протяжении N эпох (по умолчанию 5), обучение завершается досрочно. @@ -471,15 +471,15 @@ key, prefix=None, temperature=1.0, top_p=0.9, max_tokens=300, seed=None) крупная модель неизбежно переобучится, а компактная сохранит способность к обобщению. Рекомендуемая конфигурация: -| Параметр | Значение | -| ---------------------------- | ----------- | -| Число слоёв | 3 | -| Размерность модели (d_model) | 192 | -| Число голов внимания | 6 | -| Размерность FFN | 768 | -| Длина контекста | 512 токенов | -| Размер словаря | 85 | -| Dropout | 0.1 | +| Параметр | Значение | +| ---------------------------- | ------------------------------------------------------------------------------------------ | +| Число слоёв | 3 | +| Размерность модели (d_model) | 192 | +| Число голов внимания | 6 | +| Размерность FFN | 768 | +| Длина контекста | 512 токенов (256 в скриптах обучения — последовательности McGill не превышают 195 токенов) | +| Размер словаря | 85 | +| Dropout | 0.1 | При необходимости конфигурация может быть пересмотрена в сторону уменьшения (если модель не сходится) или увеличения (если результаты явно недостаточны @@ -912,4 +912,7 @@ Python. Реализация возможна, но требует погруж ## 9. История изменений +- **1.1** (2026-05-20) — актуализация: убрана ссылка на music21, исправлено + описание ChordDataset (on-demand загрузка), исправлено имя функции train, + добавлено описание report-файла, уточнена рабочая длина контекста (256). - **1.0** (2026-05-19) — первоначальная редакция документа. diff --git a/docs/requirements.md b/docs/requirements.md index 4007fa9..8d84598 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -182,16 +182,15 @@ serialize` должна давать `.chord`-файл, эквивалентны - Контекстное окно: 512 токенов. - Связанные веса входного и выходного эмбеддингов. -**ФТ-12.** Система должна предоставлять единый скрипт обучения, параметризуемый -аргументами командной строки, поддерживающий: +**ФТ-12.** Система должна предоставлять два высокоуровневых скрипта обучения: -- Обучение модели с нуля (предобучение). -- Дообучение существующей модели (fine-tuning) — через параметр инициализации - весов из указанного чекпоинта. -- Настройку всех ключевых гиперпараметров через аргументы. -- Установку случайного зерна для воспроизводимости. -- Автоматический выбор вычислительного устройства (CPU/GPU) с возможностью - принудительного задания. +- `scripts/pretrain.py` — предобучение на публичном корпусе McGill. +- `scripts/train.py` — дообучение на собственном корпусе с инициализацией + весов из чекпоинта предобучения. + +Оба скрипта имеют флаг `--skip-training` для повторного построения графиков и +отчёта без перезапуска обучения. Низкоуровневая параметризация (гиперпараметры, +архитектурные параметры, устройство) доступна через `src/train.TrainConfig`. **ФТ-13.** В процессе обучения система должна: @@ -464,4 +463,6 @@ serialize` должна давать `.chord`-файл, эквивалентны ## 8. История изменений +- **1.1** (2026-05-20) — ФТ-12 обновлён: два скрипта (pretrain.py, train.py) + вместо единого универсального CLI. - **1.0** (2026-05-19) — первоначальная редакция документа.