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 <noreply@anthropic.com>
2026-05-20 12:46:09 +03:00
parent 03b464973a
commit 0682ccc140
3 changed files with 40 additions and 32 deletions
@@ -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__`. При текущем размере данных это не является узким местом.

 Паддинг выполняется специальным токеном `<PAD>` с индексом 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-лог (`<output>.log.csv`). По окончании
+прогона скрипты `scripts/pretrain.py` и `scripts/train.py` записывают сводный
+отчёт с полной таблицей метрик в текстовый файл (`<output>.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) — первоначальная редакция документа.
@@ -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) — первоначальная редакция документа.