DUB-AI: multi-task модель (тип озвучки + автор-спан + 18+), обучение/инференс/ONNX/сервис, тесты и документация

README.md

@@ -0,0 +1,111 @@
+# DUB-AI — нейро-модель «тип озвучки + автор + 18+»
+
+По тексту дорожки озвучки (или HTML-странице релиза с трекеров rutracker /
+kinozal / nnm-club) модель определяет:
+
+* **тип озвучки** (`translation_type`, 14 классов: проф. дубляж, проф. многоголосый,
+  авт. одноголосый, …) — классификация;
+* **автора** (`studio`: студия или переводчик) — извлечение имени прямо из текста
+  (работает и для авторов, которых не было в обучении) + нормализация по словарю
+  алиасов («HDRezka Studio» → `HDrezka`, «Ю. Сербин» → «Юрий Сербин»);
+* **18+** дорожка или нет — бинарная голова.
+
+Обучено на датасете из 3286 разметанных дорожек + 458 аугментированных
+морфологических вариантов (снимок `labels.csv` из deepseek-harness).
+Multi-task RuBERT: сравниваются `rubert-tiny2` и `ruBert-base`,
+лучшая кладётся в `models/best`.
+
+## Квикстарт (5 минут)
+
+```bash
+# 1. окружение (Windows, Python 3.13; GPU требует колёс cu128 — см. docs/training-windows.md)
+python -m venv .venv
+.venv\Scripts\python -m pip install torch --index-url https://download.pytorch.org/whl/cu128
+.venv\Scripts\python -m pip install -r requirements.txt
+
+# 2. данные -> подготовка (data/labels.csv уже в репозитории)
+.venv\Scripts\python -m src.prepare_data
+
+# 3. обучение (обе модели, 5-fold CV; ~15-20 мин на RTX 5070 Ti)
+.venv\Scripts\python -m src.train
+#    результат: models/best, reports/summary.md, reports/*.png
+
+# 4. инференс
+.venv\Scripts\python -m src.predict --text "Перевод: Профессиональный (многоголосый закадровый) | HDRezka Studio 18+"
+.venv\Scripts\python -m src.predict --html data/samples/rt-topic.html
+.venv\Scripts\python -m src.predict --file data/pages/6907007.txt --out result.json
+```
+
+Python API:
+
+```python
+from src.predict import DubPredictor
+
+model = DubPredictor()                      # models/best по умолчанию
+model.predict_text("Авторский (одноголосый закадровый) - Ю. Сербин")
+# {'translation_type': 'авт. одноголосый', 'studio': 'Юрий Сербин', 'is_18plus': False, ...}
+
+model.predict_html(open("data/samples/rt-topic.html", encoding="utf-8").read())
+# [ {...дорожка 1...}, {...дорожка 2...}, ... ]
+```
+
+HTTP-сервис и интеграция из Rust/TypeScript (ONNX без Python) — см.
+**[docs/integration.md](docs/integration.md)**.
+
+## Структура
+
+```
+data/            датасет (labels.csv — снимок) и HTML-дампы страниц
+data/processed/  подготовленные данные (dataset.json, label_maps.json)
+src/             код: подготовка, модель, обучение, инференс, сервис, ONNX-экспорт
+models/          чекпоинты (best — итоговая модель)
+reports/         метрики, аудит датасета, confusion matrix, ONNX-parity
+tests/           юнит-тесты (tests/run_tests.py)
+examples/        клиенты: rust (HTTP, ONNX), typescript (HTTP, ONNX)
+docs/            документация
+```
+
+## Документация
+
+* [docs/architecture.md](docs/architecture.md) — устройство модели и пайплайна
+* [docs/dataset.md](docs/dataset.md) — схема датасета, семантика классов, аудит
+* [docs/training-windows.md](docs/training-windows.md) — обучение на Windows+GPU, troubleshooting
+* [docs/inference.md](docs/inference.md) — CLI/API, JSON-контракт
+* [docs/integration.md](docs/integration.md) — Rust/TypeScript: HTTP-сервис и ONNX
+
+## Качество
+
+Held-out test (645 строк, группировка по релизам и текстам; полная таблица и
+графики — [reports/summary.md](reports/summary.md)):
+
+| модель | type acc | type macro-F1 | span exact | 18+ acc | joint exact |
+|---|---|---|---|---|---|
+| rubert-tiny2 | 0.991 | 0.970 | 0.918 | 1.000 | 0.915 |
+| **ruBert-base (models/best)** | **0.994** | 0.966 | **0.950** | **1.000** | **0.946** |
+
+* joint exact — строка распознана полностью (тип + автор + 18+).
+* E2E на сохранённых страницах релизов: rutracker — precision 0.83 / recall 0.98
+  по парам (тип, автор); kinozal-текстовые дампы содержат только тех-вкладку
+  без авторов (автор подгружался на сайте через JS), поэтому там автор
+  недоступен в принципе.
+* ONNX-экспорт эквивалентен PyTorch на 100% строк test — [reports/onnx_parity.md](reports/onnx_parity.md).
+* Smoke на формулировках, которых нет в датасете: тип 9/10, 18+ 10/10,
+  автор 5/10 (полное извлечение автора на непривычных форматах записи —
+  известное ограничение, см. ниже).
+
+## Ограничения
+
+* Метки датасета сгенерированы регулярками (пайплайн deepseek-harness) — метрики
+  измеряют согласование с этой разметкой; ценность модели — обобщение на новые
+  формулировки без сопровождения регулярок.
+* Источники несбалансированы (rutracker 1658 / nnm 1549 / kinozal 77 строк).
+* Извлечение автора уверенно работает на форматах записи, представленных в
+  датасете (имя после типа через разделитель, в скобках у AVO/MVO/DVO-дорожек,
+  после тире); на непривычных форматах («Одноголосый закадровый (Фамилия)»)
+  модель может не выделить имя — span остаётся пустым, тип при этом верный.
+* kinozal-страницы: авторы озвучки подгружаются на сайте JavaScript-ом; в
+  статическом HTML и текстовых дампах их нет — модель их не увидит (это
+  ограничение данных, не модели).
+* Классы с 1–8 примерами почти не выучиваются (видно в macro-F1 и confusion
+  matrix); морфологическая аугментация (458 вариантов: «многоголосое» и т.п.)
+  частично закрывает этот пробел.