Ниже — компактный, практически ориентированный комплект правил и процедур для полной воспроизводимости ML‑экспериментов. Разделён по областям: что фиксировать, как версионировать, какие инструменты и форматы использовать, и пошаговый чек‑лист для стороннего исследователя.
1) Обязательные метаданные (experiment manifest — одно JSON/YAML на запуск)
- идентификатор запуска: `experiment_id`, git‑коммит: `git_commit` (SHA1).
- дата/время запуска: `timestamp`.
- команда запуска: `cmd` (полная CLI строка).
- конфигурация/гиперпараметры: все ключи/значения (пример: `batch_size`, `lr`, `optimizer`, `epochs`).
- Примеры значений: `batch_size`: $64$, `lr`: $1\times 10^{-3}$, `seed`: $42$.
- версии кода/пакетов: `requirements.txt` или lockfile + хэши пакетов (pip/conda/poetry).
- контейнер: `container_image` + digest (например, `sha256:...`).
- аппаратные детали: `cpu_model`, `num_cpus`, `gpu_model`, `cuda_version`, `cudnn_version`, `ram_gb`.
- Пример: `num_cpus`: $8$, `ram_gb`: $64$.
- ОС/ядро: `os_name`, `os_version`, `kernel`.
- источники данных: для каждого датасета — `name`, `uri`, `acquisition_date`, `sha256` (файла/архива), лицензия.
- предобработка/трансформации: ссылки на скрипты и их хэши; описание последовательности шагов и параметры.
- точные разбиения: файлы с индексами train/val/test и их sha256; seed для генерации разбиения.
- чекпоинты/артефакты: URI, формат, sha256, размер.
- метрики и способы вычисления: определение метрик (точные формулы), режимы агрегации.
- параметры детерминизма и nondeterministic ops: перечислить включённые/выключенные небезопасные операции (cuDNN autotune и т.п.).
- заметки о запуске: `notes` (пара слов об отклонениях).
2) Контроль версий данных и кода
- Код: git + фиксированный коммит; все подмодули и патчи. Укажите `git_commit`.
- Данные: хранить «raw» (immutable) и версионированные промежуточные файлы. Использовать DVC / Git‑LFS / Pachyderm / LakeFS. Для каждого артефакта хранить checksum (SHA256).
- Зафиксировать split indices и seed, либо хранить готовые split файлы.
- Для больших данных — публичные URI + скрипт загрузки с контрольной суммой и датой получения.
3) Среды и контейнеризация
- Обязательно предоставить:
- Dockerfile и готовый образ с immutable digest (`docker pull imagename@sha256:...`).
- Альтернатива для HPC: Singularity/Apptainer образ, или инструкции конвертации из Docker.
- Lockfile окружения: `requirements.txt` + `pip freeze --all` или `environment.yml` и `conda-lock`/`poetry.lock`.
- Рекомендации: базовый образ зафиксировать ОС и пакеты; избегать `latest`.
- Для абсолютной воспроизводимости — использовать Nix/Guix или ReproZip (опционально).
4) Контроль случайности и детерминизм
- Установить и логировать все seed’ы: Python, numpy, framework, OS randomness (пример: `python_seed`: $42$, `numpy_seed`: $42$, `torch_seed`: $42$).
- Включить/выключить детерминизм фреймворка и задокументировать последствия (например, `torch.use_deterministic_algorithms(True)`).
- Логировать nondeterministic ops; если невозможна полная детерминизация — проводить $N$ запусков и репортировать статистику (см. раздел «Оценка стабильности»).
5) Форматы артефактов модели и состояния
- Сохранять:
- финальную модель (в формате ONNX/torchscript/TensorFlow SavedModel) + sha256;
- чекпоинты обучения, включая optimizer state, scheduler state и epoch/step;
- весы и архитектуру отдельно и вместе.
- Описать совместимость форматов и инструкции по загрузке.
6) Мониторинг, логирование и трекинг экспериментов
- Вести логирование метрик по эпохам/шагам (loss, accuracy, lr и т.д.) в формате, удобном для парсинга (JSONL, CSV).
- Использовать инструмент: MLflow / Weights & Biases / Sacred / ClearML — и экспортировать эксперимент в JSON/YAML.
- Хранить сырые логи (stdout/stderr), скрипты запуска, и метрики мониторинга ресурсов (GPU utilization, memory) — например, `nvidia-smi` логи.
- Сохранить конфигурацию визуализации (tensorboard logs).
7) Метрики, оценка и статистика
- Чётко определить метрики (формулы). Пример: точность = $\frac{\text{TP}}{\text{TP}+\text{FP}}$.
- Для основных метрик указывать:
- набор данных/подмножество, на котором меряются;
- postprocessing (например, thresholding, NMS).
- Оценивать воспроизводимость:
- запускать минимум $N$ независимых повторов (рекомендация $N\ge 5$); репортировать среднее, стандартное отклонение и доверительные интервалы.
- стандартная ошибка: $\text{SE}=\frac{\sigma }{\sqrt{N}}$.
- При сравнении моделей указывать критерий значимости (t‑test / bootstrap) и p‑value для различий.
8) Процедура воспроизведения — пошаговый чек‑лист для третьей стороны
1. клонировать репозиторий и зафиксировать `git_commit`.
2. получить/проверить данные: скачать raw по `uri`, проверить `sha256`.
3. восстановить окружение: загрузить образ по digest либо воспроизвести lockfile.
4. запустить контейнер/сессию, установить переменные окружения (например, `OMP_NUM_THREADS` = $4$), и проверить `python --version`, `pip list`.
5. запустить команду из manifest (`cmd`) с теми же параметрами/seed’ами.
6. дождаться сохранения чекпоинтов/логов и сравнить хэши артефактов и метрики с опубликованными.
7. при несовпадении — просмотреть логи, nondeterministic ops и аппаратные различия.
9) Автоматизация CI и тесты
- Автоматические тесты воспроизводимости: запуск минимального эпизода тренировки на уменьшенной подвыборке (smoke test), проверка хэша артефактов и метрик.
- CI должен подтверждать, что Dockerfile билдится и что `manifest` генерируется при каждом запуске.
10) Хранение, доступ и лицензирование
- Хранить публичные или реплицируемые URIs; указывать права доступа и лицензии данных/кода.
- Для чувствительных данных — предоставить синтетические/аналогичные подвыборки и скрипты трансформации.
11) Инструменты и шаблоны (рекомендации)
- DVC / Git‑LFS для версий данных.
- Docker + Singularity для образов.
- MLflow / Weights & Biases / Sacred для трекинга экспериментов.
- `sha256sum` для контрольных сумм.
- ReproZip / Nix для дополнительной повторяемости.
12) Пример минимального manifest (поля)
- `experiment_id`, `git_commit`, `container_image`, `container_digest`, `cmd`, `timestamp`, `seeds`:{py, numpy, torch}, `data`:[{name, uri, sha256}], `splits`:{train_indices_sha256, val_indices_sha256, test_indices_sha256}, `hyperparameters`:{batch_size:$64$, lr:$1\times 10^{-3}$, epochs:$100$}, `hardware`:{gpu:"NVIDIA V100", cuda:"11.3"}, `metrics`:{accuracy:0.912,... with definitions}, `artifacts`:[{path, sha256}].
Заключение (одно предложение): выполнение и публикация всех перечисленных пунктов (manifest + контейнер + зафиксированные данные + чекпоинты + логи + инструкции) позволяет третьей стороне воспроизвести результаты с высокой точностью и диагностировать отклонения.