grabber-ai/docs/training-windows.md

# Обучение на Windows с GPU (RTX 5070 Ti)

## Почему cu128

RTX 5070 Ti — архитектура Blackwell (compute capability `sm_120`). Колёса
PyTorch с PyPI для Windows по умолчанию CPU-only, а старые CUDA-сборки не
знают sm_120. Нужны колёса с индекса cu128 (torch >= 2.7; проверено на
torch 2.11.0+cu128).

## Установка (один раз)

```bat
cd C:\Users\shats\Dev\grabber-ai
python -m venv .venv
.venv\Scripts\python -m pip install --upgrade pip

:: torch с GPU-поддержкой (Blackwell)
.venv\Scripts\python -m pip install torch --index-url https://download.pytorch.org/whl/cu128

:: остальное
.venv\Scripts\python -m pip install -r requirements.txt
```

Проверка (ожидаемый вывод — `True` и имя карты):

```bat
.venv\Scripts\python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"
:: True NVIDIA GeForce RTX 5070 Ti
```

## Обучение

```bat
.venv\Scripts\python -m src.prepare_data            :: данные -> data/processed
.venv\Scripts\python -m src.train                   :: обе модели: 5-fold CV + финальные
.venv\Scripts\python -m src.train --models base     :: только ruBert-base
.venv\Scripts\python -m src.train --epochs-override 5 --folds 3   :: быстрый прогон
```

Время на RTX 5070 Ti (3742 строки, max_len=128): rubert-tiny2 — ~2 мин
полный цикл; ruBert-base — ~7 мин. Автоматически: bf16 autocast на
CUDA, GroupKFold-сплиты, ранний stopping (patience 3), метрики и графики в
`reports/`, чекпоинты в `models/`, лучшая модель — `models/best`.

Гиперпараметры — в `MODEL_CONFIGS` (src/train.py): tiny2 — lr 1e-4, batch
64, до 20 эпох; base — lr 3e-5, batch 32, до 10 эпох; AdamW, weight_decay
0.01, linear warmup 10%, grad clip 1.0, seed 42.

## Выбор основы и сравнение моделей (меню, пункты 2 и 7)

`python tools/collect.py` → «2 Переобучить»: после вопроса «сегментатор + основные модели» предлагается
список основ. Каждая обучается отдельным запуском в `models/runs/<время>_<профиль>/` (`python -m src.train
--runs`), **`models/best`, `reports/final_*` и `summary.md` при этом не меняются**.

| профиль | основа | замечания |
|---|---|---|
| `tiny2` | rubert-tiny2, 30M | самая быстрая, подходит для ONNX/CPU |
| `base` | ruBert-base, 178M | текущий рабочий выбор |
| `large` | ruBert-large, 427M | помещается в 16 ГБ (bf16, batch 16); обучение ~3× дольше base, инференс на CPU медленнее |
| `modern` | RuModernBERT-base, 149M | новая архитектура; ONNX-экспорт проекта (`token_type_ids`) её не принимает |

Кросс-валидация (5 прогонов) на итоговую модель не влияет, нужна только для оценки устойчивости; без неё
обучение примерно в 6 раз короче. Флаги CLI: `--folds 0`, `--lr`, `--batch`, `--epochs-override`, `--tag`.

Пункт «7 Модели» (и конец пункта 2) сравнивает **все** модели (`models/best`, запуски, `best_backup_*`,
`models/tiny2`) на **одной и той же текущей тестовой выборке**: каждая оценивается заново, в своём входном
формате (без «[RUS AC3 …]» для моделей, обученных без аудио-контекста). Цифры кэшируются в
`<модель>/eval.json` под отпечатком выборки. Таблица показывает joint exact с 95% интервалом и парное
сравнение с `models/best`: сколько строк новая модель починила и сколько сломала, значима ли разница
(знаковый критерий). Разница в пределах шума так и помечается. Звёздочка у модели означает, что она обучена
на другом разбиении и часть текущих тестовых строк могла видеть — её цифры завышены. Выбранная модель
копируется в `models/best` (прежняя уходит в `models/best_backup_*`, откат — тем же пунктом); перед заменой
выводятся предупреждения (другая основа нужна в кэше Hugging Face на машине сервиса, вес, ONNX).
Запуски и архивные копии можно удалять из того же меню (каждая 0.1–1.4 ГБ).

## Переобучение на свежем датасете

Сборщик (`deepseek-harness/default-workspace/dataset.py`) дописывает
`labels.csv`. Когда появится новый снимок:

```bat
copy /Y <путь>\labels.csv data\labels.csv
.venv\Scripts\python -m src.prepare_data
.venv\Scripts\python -m src.train
```

Если поменялась только логика разметки студий (без перекачки страниц), сначала
`.venv\Scripts\python tools\relabel_studios.py` (см. `docs/collecting.md`), затем
`prepare_data` и обучение. Кандидата из `models/runs/` перед заменой `models/best`
сравнить: `python -m src.runs --out runs.json --dirs models/best models/runs/<запуск>` (test-сплит) и
`E2E_MODEL=models/runs/<запуск>` + `tests/e2e_segmenter.py` (релизы). Поставить —
меню `tools/collect.py`, пункт 7, или `src.runs.promote`; для Docker затем
`python tools/pack_models.py --stage docker-models`.

## Troubleshooting

| Симптом | Причина | Решение |
|---|---|---|
| `torch.cuda.is_available()` = False | установлен CPU-torch | переустановить с `--index-url .../whl/cu128` |
| `CUDA error: no kernel image is available` | колёса без sm_120 (старый cu126 и т.п.) | то же — нужны именно cu128 |
| `CUDA driver version is insufficient` | старый драйвер NVIDIA | обновить драйвер (нужен 5xx+) |
| Память GPU занята другими приложениями (WDDM) | Windows держит ~4 ГБ VRAM под систему | batch уже мал (32-64 на коротких seq хватает); при нехватке уменьшить `batch` в MODEL_CONFIGS |
| Хочется обучить без GPU | — | `base` медленно, но `tiny2` обучаема на CPU за десятки минут: тот же запуск, torch можно ставить CPU-версией |

## Что сохраняется после обучения

* `models/<имя>/model.pt` — веса; `dub_config.json` — конфигурация;
  `label_maps.json` — классы; файлы токенизатора; `train_config.json` —
  гиперпараметры и финальные метрики.
* `models/best/` — копия лучшей модели (используется инференсом по умолчанию).
* `reports/summary.md` — таблица сравнения; `final_<имя>.json` — метрики;
  `history_<имя>.png` — кривые; `confusion_<имя>.png` — матрица ошибок.