From f6b7f7630511f1bbe433364f5a4b29c9ebf9f16b Mon Sep 17 00:00:00 2001 From: DimaRus05 Date: Sun, 27 Sep 2026 14:05:27 +0300 Subject: [PATCH] docs(ml): document retraining behavior in main --- README.md | 4 +++- retraining/README.md | 28 ++++++++++++++++++++++------ 2 files changed, 25 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 52ab938..bcafc29 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ # Moscow Hack 2026 — Prediction Service V2 +Повторное обучение модели описано в [retraining/README.md](retraining/README.md). +Этот процесс запускается отдельно от сервиса прогноза и не заменяет его модель автоматически. + Production-сервис для online-прогноза критического события по логам датчиков на произвольном положительном горизонте в часах. Модель: `CatBoostRegressor` с `SurvivalAft`. @@ -906,4 +909,3 @@ weather = get_weather( ``` Именно такой словарь с названиями полей выше ожидает сервис модели для каждого необходимого часа (`current`, `+1h`, `+4h`, `+8h`, `+12h`, `+16h`, `+20h`, `+24h`). - diff --git a/retraining/README.md b/retraining/README.md index 8750202..6bea2a3 100644 --- a/retraining/README.md +++ b/retraining/README.md @@ -1,8 +1,8 @@ # Общий пайплайн обучения -Эта папка — самостоятельная точка повторного обучения модели на исходных и новых данных. Добавьте новые журналы событий в `data/incoming_events/` и запустите один скрипт: он объединит все записи, сформирует признаки, заново разобьёт устройства на train/val/test, выполнит feature selection, Optuna-тюнинг, обучит итоговую модель и посчитает метрики. +Этот каталог содержит пять ноутбуков и `run_pipeline.py` для последовательной подготовки данных, разделения на train/val/test, отбора признаков, подбора параметров и обучения CatBoost. Скрипт не запускает облачную VM и не заменяет модель сервиса инференса. Описание относится к коду ветки `main`; экспериментальная автоматизация облачного запуска в неё не входит. -Шаблоны в `notebooks/` — копии исходных тетрадок. Они **не перезаписываются**. Для каждого прогона скрипт создаёт рабочие копии в `artifacts/runs//notebooks/` и только там подставляет найденные годы и реально доступные чанки. Поэтому старый запуск не ломается, а новые данные (в том числе за новые годы) участвуют в обучении автоматически. +Шаблоны в `notebooks/` не перезаписываются. Для каждого запуска создаются рабочие копии в `artifacts/runs//notebooks/`. В них подставляются годы входных событий и числа доступных чанков. Результат зависит от фактически переданных файлов, настроек и версии кода; пример из репозитория не заменяет полный набор событий. ## Состав @@ -20,7 +20,7 @@ Перейдите в папку пайплайна и установите зависимости в нужное Python-окружение: ```bash -cd general_training_pipeline +cd retraining python -m pip install -r requirements.txt python run_pipeline.py ``` @@ -33,11 +33,11 @@ python run_pipeline.py - `notebooks/` — фактически выполненные тетрадки с выводами; - `data/` — точный снимок данных, использованных в этом запуске. -Для фиксированного имени прогона используйте `python run_pipeline.py --run-id retrain_2026_09_25`. +Для фиксированного имени прогона используйте `python run_pipeline.py --run-id <уникальный-id>`. Если каталог с таким именем уже существует, скрипт завершится с ошибкой и не перезапишет артефакты. ## Как добавить новые данные -1. Скопируйте один или несколько parquet-файлов в `data/incoming_events/`. Файлы с любым именем принимаются; записи за одинаковый год автоматически объединяются. Не удаляйте старые файлы, если они тоже должны остаться в обучающей выборке. +1. Скопируйте один или несколько parquet-файлов в `data/incoming_events/`. Скрипт читает только файлы по `input.events_glob` из `config.yaml`; по умолчанию это `*.parquet`. Записи одного года объединяются. Если файл не должен участвовать в запуске, уберите его из входного каталога или настройте glob до запуска. 2. Убедитесь, что у каждого файла есть колонки: `ид_события`, `ид_канала_данных`, `дата`, `время`, `значение_датчика`, `тревожное`. 3. При изменении справочников или погоды замените соответствующий файл в `data/reference/` либо поменяйте путь в `config.yaml`. 4. Запустите `python run_pipeline.py`. @@ -46,6 +46,22 @@ python run_pipeline.py ## Конфигурация -В `config.yaml` можно изменить каталоги данных, Jupyter kernel, таймаут и максимальное число чанков для этапов feature selection и tuning. Лимиты не могут привести к ошибке на маленьком наборе: запускатор автоматически берёт не больше существующих чанков. +В `config.yaml` можно изменить каталоги данных, Jupyter kernel, таймаут и максимальное число чанков для этапов feature selection и tuning. Скрипт уменьшает лимит до числа существующих чанков; при нуле чанков этап завершится ошибкой. Новые данные должны быть в том же формате, что и пример. Дата должна приводиться к календарной дате; погодный CSV должен содержать колонку `time` и погодные поля из исходной тетрадки. + +## Фактическое использование чанков в `main` + +| Этап | Train | Validation | Test | +| --- | --- | --- | --- | +| Отбор признаков | До 4 чанков | До 20 чанков | До 20 чанков | +| Подбор параметров | До 8 чанков | До 80 чанков | До 20 чанков в шаблоне | +| Итоговое обучение | До 8 чанков | До 80 чанков | Все `chunk_*.parquet` для итоговой оценки | + +Числа заданы в `notebook_limits` и ограничиваются фактическим количеством файлов. Итоговый ноутбук получает лимиты train/val из секции `tuning`; поэтому текущий код `main` **не гарантирует обучение на всех train-чанках**. Все test-файлы читаются в итоговой оценке пакетами. Test не используется для обучения итоговой модели, но ноутбук отбора признаков считает `test_pr_auc` по кандидатам. Поэтому итоговую test-метрику нельзя считать оценкой на полностью закрытой выборке. + +## Проверка результата + +Прогон считается завершённым после успешного выхода `run_pipeline.py` и проверки `best_model.cbm`, `scores_final.csv`, `best_params.json` и выполненных ноутбуков в одном каталоге запуска. В выводе последнего ноутбука сверяйте число найденных test-файлов с входным набором. Для сравнения с прежней моделью и правилами «тревога вчера» и «не менее десяти тревог вчера» нужны отдельные расчёты на тех же строках и горизонте прогноза; текущий скрипт `main` их не выполняет. Автоматической выкладки модели нет. + +Для воспроизводимости фиксируйте commit, `config.yaml`, перечень Parquet и их SHA-256, число train/val/test-чанков и итоговые артефакты. Данные и секреты размещайте вне Git, если они не предназначены для публикации.