# Архитектура

## Пайплайн

```
labels.csv (снимок датасета)                HTML/текст страницы (инференс)
        │                                            │
        ▼                                            ▼
 src/prepare_data.py                        src/html_extract.py
  • снять префикс «Перевод/Аудио N:»         • HTML -> текст (BeautifulSoup:
  • BIO-разметка автора (спан в тексте)        .post_body / #tabs / весь текст)
  • фильтры: мусорный studio,                 • сегментация на дорожки
    «оригинал/субтитры», противоречия           (строки «Перевод/Озвучка/Аудио N:»,
  • 18+ флаг (age_18 / note / «18+» в raw)      нумерация, «+ ; /», запятые-типы)
  • сплиты: test 20% + 5-fold CV                       │
    (группы = релиз ∪ одинаковый текст)                ▼
        │                                     src/predict.py (DubPredictor)
        ▼                                      • токенизация (max_len=128,
 src/train.py                                     offsets)
  • multi-task обучение (CUDA, bf16)           • модель -> тип, спан, 18+
  • 5-fold CV + финальная модель               • нормализация автора
  • метрики, reports/, models/best             • JSON
```

## Модель (src/model.py)

Один BERT-подобный энкодер и три головы (общий `[CLS]`/токенные состояния):

| Голова | Тип | Выход | Задача |
|---|---|---|---|
| `type_head` | Linear(hidden, 14) | `[CLS]` → класс | тип озвучки |
| `bio_head` | Linear(hidden, 3) | по токенам → O/B/I | позиция имени автора в тексте |
| `age_head` | Linear(hidden, 2) | `[CLS]` → 0/1 | дорожка 18+ |

Loss = CE(тип) + 1.0·CE(BIO, ignore_index=-100) + 0.5·CE(18+).

BIO-разметка строится по символьным спанам через `offsets_mapping`
токенизатора: токены, пересекающие спан, получают `B` (первый) и `I`
(остальные); все реальные токены вне спана — `O`; паддинг — `-100`.
Спецтокены ([CLS]/[SEP]) размечены как `O` — иначе их необученные логиты
при инференсе дают ложный «B» (эта ошибка была найдена при обучении и
исправлена; см. `decode_span` — он дополнительно пропускает токены с
пустыми offsets).

Декодирование спана: первый `B`-токен, затем цепочка `I` → символьный
диапазон через offsets → текст спана → каноническое имя автора через
словарь алиасов (`src/studio_norm.py`, порт из генератора датасета).

## Почему автор — извлечение, а не классификация

В датасете 253+ уникальных авторов, 177 из них встречаются ровно 1 раз.
Классификацией такие классы не выучить. При этом имя автора почти всегда
дословно присутствует в тексте дорожки (95.8% + варианты написания),
поэтому BIO-извлечение решает задачу и автоматически работает для авторов,
которых в обучении не было вовсе.

## Сравнение конфигураций

Обе модели учатся одинаково (5-fold CV + финальный запуск, ранний stopping
по среднему type-F1/span/age-F1):

* `cointegrated/rubert-tiny2` — 30M, lr 1e-4, batch 64, до 20 эпох;
* `ai-forever/ruBert-base` — 110M, lr 3e-5, batch 32, до 10 эпох.

Лучшая по joint exact на held-out test копируется в `models/best`.
Итог — в `reports/summary.md`.

## Сегментатор страниц (src/segmenter.py) — главный путь

Какие строки страницы описывают дорожки, решает обученная модель
(rubert-tiny2, бинарная классификация строки с контекстом «пред. || след.»),
а не регулярки. Правила (`html_extract.extract_segments`) — запасной путь:
используются, если `models/segmenter` нет или модель не нашла ни одной строки;
режим можно форсировать: `predict_release(..., segmenter="rules")`.

* Обучение: `python -m src.segmenter --train --out models/segmenter_v2` (или меню
  `tools/collect.py` → «2»). Разметка строк — по `raw` и `audio_raw` из `labels.csv`
  (страницы `data/pages`); синтетика: `raw` всех train-строк вставляются в контекст
  реальных строк страниц. Страницы делятся по хешу `release_id` (≈20% в тест).
* Текст kinozal берётся из `data/raw/kinozal/<id>.json` (`h1` + «Техданные» +
  «Релиз», `segmenter.page_text`): в `data/pages/kz-*.txt` нет ни заголовка, ни
  «Техданных», откуда взята половина меток kinozal, а сервис (`fetch_html`)
  видит обе вкладки.
* Кодек-строка русской дорожки («Аудио 3: AC3 … Русский (MVO, LostFilm)»,
  «Аудио Rus: … | LostFilm»), не попавшая в разметку, в обучение не идёт
  (метка -1): у rutracker `raw` — строка «Перевод N:», и как негатив она учила
  модель отбрасывать кодек-строки — а на kinozal студии только в них.
* В `predict_release` выбранные моделью кодек-строки — второстепенный источник
  (`source: codec`): подключаются, только если у какой-то дорожки страницы нет
  студии; если других строк нет (nnm), они и есть дорожки.
* e2e: `tests/e2e_segmenter.py [каталог]` — пары (тип, студия) на тестовых
  страницах, не больше `E2E_MAX` (400) на трекер; `--train-pages` — ещё и train.
* Нарезка ВНУТРИ строки («Дублированный, многоголосый») в данных не размечена
  (91 группа из 6735) — остаётся на правилах `_split_entries`, но только на
  строках, выбранных моделью.
* ONNX-путь (Rust/TS) сегментатор пока не включает: там по-прежнему правила.