Структура проекта,
инструменты и управление экспериментами

project structure configuration experiment tracking hyperparameter tuning reproducibility
02 / 26

Структура проекта

.
├── config/ │ ├── inference.yaml
│ └── train.yaml
├── data/
├── logs/
├── notebooks/
├── src/
├── scripts/
├── pyproject.toml
└── README.md

Конфигурация всех компонентов для запуска обучения и инференса:

  • – исходные данные и их преобразования
  • – гиперпараметры: модель, оптимизатор, цикл обучения
  • – вспомогательные компоненты: метрики, графики, логирование
03 / 26

Структура проекта

.
├── config/
├── data/ │ ├── test.csv
│ ├── train.csv
│ └── val.csv
├── logs/
├── notebooks/
├── src/
├── scripts/
├── pyproject.toml
└── README.md

Данные, используемые для обучения и тестирования

  • – В идеале должны версионироваться вместе с кодовой базой
  • – Используйте DVC для отслеживания больших файлов данных
04 / 26

Структура проекта

.
├── config/
├── data/
├── logs/ │ └── runs/
│ └── 2025-04-26-11:16:35/
│ ├── checkpoints/
│ │ └── epoch_002.ckpt
│ ├── tensorboard/
│ └── train.log
├── notebooks/
├── src/
├── scripts/
└── ...

Логи экспериментов для каждого запуска:

  • – метадата: когда запущен, с какой версией кода, краткое описание, теги
  • – конфигурация
  • – чекпоинты
  • – метрики
  • – консольный вывод
05 / 26

Структура проекта

.
├── config/
├── data/
├── logs/
├── notebooks/ │ └── dataset.ipynb
├── src/
├── scripts/
├── pyproject.toml
└── README.md

Ноутбуки для демонстрации отдельных компонентов:

  • – анализ данных
  • – визуализация предсказаний
  • – удобны для отладки и быстрой проверки гипотез
06 / 26

Структура проекта

.
├── config/
├── data/
├── logs/
├── notebooks/
├── src/ │ ├── data/
│ │ ├── datamodule.py
│ │ └── dataset.py
│ ├── model/
│ │ ├── lightning.py
│ │ └── modules.py
│ └── utils/
│ ├── metrics.py
│ └── training.py
└── ...

Код для отдельных компонентов пайплайна обучения:

  • – работа с данными
  • – архитектуры моделей
  • – цикл обучения, функции ошибок, метрики, callbacks
  • – Вместо src (либо внутри src) — название вашего проекта
07 / 26

Структура проекта

.
├── config/
├── data/
├── logs/
├── notebooks/
├── src/
├── scripts/ │ ├── inference.py
│ └── train.py
├── pyproject.toml
└── README.md

Скрипты для запуска обучения и инференса

  • – При удачной конфигурации мало варьируются от проекта к проекту
08 / 26

Структура проекта

.
├── config/
├── data/
├── logs/
├── notebooks/
├── src/
├── scripts/
├── pyproject.toml └── README.md

Настройки python проекта:

  • – зависимости (пользуйтесь uv / poetry вместо pip)
  • – форматирование: isort, black, ruff
  • – линтер: flake8, ruff
  • – type checker: mypy, pyright, ty
  • – testing: pytest
09 / 26

Структура проекта

.
├── config/
├── data/
├── logs/
├── notebooks/
├── src/
├── scripts/
├── pyproject.toml
└── README.md

Описание проекта:

  • – в чём задача
  • – основная идея решения
  • – результаты
  • – как запустить инференс
  • – как воспроизвести обучение
10 / 26

Hydra: управление конфигурацией

config/train.yaml
seed: 42
trainer:
  _target_: lightning.Trainer
  accelerator: cpu
  max_epochs: 10
train.py
import hydra
from omegaconf import DictConfig

@hydra.main(config_path="config")
def train(cfg: DictConfig):
    trainer = hydra.utils.instantiate(cfg.trainer)
    trainer.fit(...)
1
Переопределение через командную строку

python train.py trainer.max_epochs=20

2
Создание объектов

Объекты создаются из конфига через _target_

3
Композиция конфигурационных файлов

Сборка единого конфигурационного файла из частей

refs hydra.cc
11 / 26

Hydra: композиция конфигурации

Структура config/
config/
├── model/
│ ├── gru.yaml
│ └── lstm.yaml
└── train.yaml
config/train.yaml
defaults:
  - model: gru

seed: 42
trainer:
  _target_: lightning.Trainer
  max_epochs: 10
config/model/gru.yaml
_target_: torch.nn.GRU
input_size: 8
hidden_size: 64
config/model/lstm.yaml
_target_: torch.nn.LSTM
input_size: 8
hidden_size: 64
Переключение модели из командной строки
# использовать lstm вместо gru
$ python train.py model=lstm
12 / 26

Hydra: множественный запуск

Запуск нескольких конфигураций одной командой
# запустить обучение для обеих моделей последовательно
$ python train.py --multirun model=gru,lstm

# можно комбинировать несколько осей поиска
$ python train.py --multirun model=gru,lstm seed=42,123
Что происходит
  • – Hydra создаёт отдельный подкаталог в logs/ для каждого запуска
  • – В каждом подкаталоге сохраняется итоговый конфиг hparams.yaml
  • – Удобно сравнивать результаты в MLflow или TensorBoard
Интеграция с Optuna
  • – Hydra поддерживает Optuna как launcher для --multirun
  • – Байесовская оптимизация гиперпараметров без изменения кода
13 / 26

MLflow: трекинг экспериментов

Возможности

  • Ручное и автоматическое логирование
  • Визуализация метрик
  • Хранение артефактов
  • Реестр моделей
  • Версионирование датасетов

Интеграция с PyTorch

import mlflow

mlflow.pytorch.autolog()  # Вот и всё! 🎉

# Существующий код работает без изменений
for epoch in range(num_epochs):
    model.train()
    # ... цикл обучения остаётся прежним
Варианты развёртывания
Локально

Хранение в файловой системе, удобно для экспериментов

Командная работа

Удалённый сервер трекинга с базой данных

refs mlflow.org
14 / 26

DVC: версионирование данных

Основной рабочий процесс
# Initialize and track data
$ dvc init
$ dvc add data/train.csv

# Setup remote storage
$ dvc remote add -d storage s3://bucket/store

# Sync data
$ dvc push    # Upload to remote
$ dvc pull    # Download from remote
✓ Рекомендации
  • Версионировать данные вместе с кодом
  • Хранить большие файлы в удалённом хранилище
  • Тегировать версии данных для воспроизводимости
✗ Антипаттерны
  • Коммитить большие файлы в Git
  • Синхронизировать данные вручную
  • Несогласованные разбивки данных
refs dvc.org
15 / 26
часть 2

Управление экспериментами

Основано на Google Deep Learning Tuning Playbook — практическом руководстве по систематической оптимизации нейронных сетей.

1. Инициализация

Разумная начальная конфигурация: архитектура, оптимизатор, размер батча. Фиксируются до начала улучшений.

2. Итеративное улучшение

Научный подход к настройке гиперпараметров и анализу экспериментов

refs Google Deep Learning Tuning Playbook
16 / 26

Старт проекта: архитектура

Найдите задокументированную кодовую базу, решающую похожую задачу

Воспроизведите её как отправную точку, затем переключайтесь на собственные варианты. Если такой базы не существует — используйте популярную архитектуру.

✓ Хорошие практики
  • Задокументированные бейзлайны для вашей задачи
  • Устоявшиеся архитектуры (ResNet, Transformer…)
  • Предобученные модели там, где возможно
  • Сначала простые модели, сложные — позже
✗ Избегайте
  • Новых архитектур без бейзлайнов
  • Проектирования с нуля до изучения существующих решений
  • Преждевременного усложнения
17 / 26

Старт проекта: оптимизатор

Единого «лучшего» оптимизатора нет — всё зависит от задачи

  • – Начать с простого: мало гиперпараметров
  • – SGD с инерцией — хорошо изучен
  • – Adam — безопасный выбор по умолчанию
  • – Настройка гиперпараметров оптимизатора — на фазе итеративного улучшения
SGD с инерцией
optimizer:
  _target_: torch.optim.SGD
  lr: 0.1
  momentum: 0.9
  weight_decay: 1e-4

✓ Меньше гиперпараметров

Adam (хороший выбор по умолчанию)
optimizer:
  _target_: torch.optim.Adam
  lr: 3e-4
  betas: [0.9, 0.999]
  eps: 1e-8

⚠ Больше гиперпараметров — настраивать позже

18 / 26

Старт проекта: размер мини-батча

Больший батч → меньше шагов → быстрее обучение

Смена батча требует перенастройки большинства гиперпараметров

Фиксировать на весь раунд экспериментов

Нюанс: малые батчи устойчивее к выбору гиперпараметров

Marek et al. (2025) показали, что batch size 1 допускает гораздо более широкий диапазон learning rate и β₁, чем batch size 512.

19 / 26

Научный подход к настройке гиперпараметров

Исследуемые (scientific)

Параметры, чей эффект вы изучаете — то, что вы пытаетесь понять.

Мешающие (nuisance)

Нужно оптимизировать для честного сравнения исследуемых параметров.

Фиксированные (fixed)

Не меняются в текущем раунде. Любые выводы справедливы только при зафиксированных значениях — это оговорка к результатам.

Примеры
Цель: сравнить ReLU и Tanh
  • Исследуемые: функция активации
  • Мешающие: learning rate, batch size
  • Фиксированные: архитектура модели
Цель: оптимальное число слоёв
  • Исследуемые: число слоёв
  • Мешающие: learning rate, оптимизатор
  • Фиксированные: функция активации
20 / 26

Пространство поиска имеет значение

Достаточно исследуемых значений

Шире охват — больше выводов из экспериментов

Достаточно широкое пространство для мешающих

Где-то в пространстве должны существовать хорошие значения

Достаточно плотная выборка

Высокая вероятность найти хорошие настройки, если они есть

21 / 26

Процесс проведения экспериментов

1
Определить цель

Чётко сформулировать задачу. Проверять одно изменение за раз.

2
Спроектировать эксперименты

Разделить гиперпараметры на исследуемые, мешающие и фиксированные

3
Запустить и проанализировать

Проверить пространство поиска, изучить кривые обучения, валидировать результаты

4
Принять решение

Принимать изменения на основе убедительных свидетельств, а не удачных запусков

Ключевой принцип: знание важнее сиюминутного результата

Больше времени на исследование, меньше — на немедленную оптимизацию метрики.

22 / 26

Анализ кривых обучения

✓ Хорошие признаки
  • Переобучение: ошибка валидации растёт — добавить регуляризацию
  • Стабильность: гладкие кривые без избыточной дисперсии
  • Сходимость: метрика выходит на плато в нужный момент
  • Learning rate: не слишком высокий (расходимость) и не низкий (медленно)
⚠ Red Flags
  • Высокая дисперсия шаг-за-шагом в конце обучения
  • Ошибка обучения растёт — обычно указывает на баги
  • Преждевременная остановка при ещё продолжающемся улучшении
  • Нет улучшений с самого начала

Совет: автоматизируйте построение графиков для всех запусков — чем сложнее их получить, тем реже вы будете на них смотреть. Каждый новый график — новое знание.

23 / 26

Что делать с проблемными кривыми

Переобучение →
Регуляризация: dropout, weight decay, label smoothing
Высокая дисперсия →
Увеличить батч, learning rate decay, Polyak averaging
Ещё улучшается →
Увеличить число шагов или скорректировать LR schedule
Плато с начала →
Уменьшить число шагов — модель не ограничена вычислениями

Главное: не сводите эксперимент к одному числу — смотрите на всю кривую целиком.

24 / 26

Отладка обучения

Типичные проблемы и решения
1
Loss взрывается или NaN

Слишком высокий learning rate → gradient clipping (1.0)

2
Loss сразу выходит на плато

Learning rate слишком низкий, неправильная функция потерь или проблема с данными

3
Модель не обучается

Проверить загрузку данных, метки, архитектуру модели, градиенты

Стратегия отладки

Переобучите модель на одном батче — если не получается, проблема в коде, а не в гиперпараметрах. Затем масштабируйте. Большинство проблем — в пайплайне данных или learning rate.

refs Andrej Karpathy — A Recipe for Training Neural Networks
25 / 26

Воспроизводимость экспериментов

✓ Окружение и зависимости
  • Фиксировать версии всех пакетов
  • Использовать uv / Poetry вместо pip
  • Докеризировать окружение
✓ Код и конфигурация
  • Версионировать всё через Git
  • Коммитить точные конфиги запуска
  • Тегировать релизы и эксперименты
✓ Данные и случайность
  • Документировать источники и версии данных
  • Фиксировать random seed везде
  • Версионировать разбивки train/val/test
✓ Результаты и артефакты
  • Сохранять чекпоинты модели
  • Логировать все метрики и гиперпараметры
  • Документировать используемое железо
26 / 26

Итоги

1
Структура

Правильная организация, управление конфигурацией, версионирование

2
Автоматизация

Автоматическое построение графиков, воспроизводимое окружение

3
Трекинг

Логируйте всё: метрики, конфиги, артефакты — с первого дня

4
Начинайте с простого

Задокументированные бейзлайны, устоявшиеся архитектуры, сложность — постепенно

5
Будьте последовательны

Одно изменение за раз

6
Знание важнее метрики

Больше исследования, меньше погони за немедленным результатом

refs Google Deep Learning Tuning Playbook hydra.cc mlflow.org dvc.org