ADR про распознавание контента

2026-06-15 11:38:18 +03:00
parent d149cb7481
commit d727966f29
3 changed files with 73 additions and 0 deletions
@@ -0,0 +1,69 @@
+# Авто-раскладка только при подтверждённом матче в метабазе
+
+- Дата: 2026-06-13
+
+## Контекст
+
+jellybit распознаёт содержимое релиза через LLM по **недоверенным**
+сигналам: имя торрента, текстовый контекст человека, распарсенное
+сообщение бота — всё управляется извне и может содержать инъекции. По
+результату распознавания нужно решить: разложить файлы хардлинками
+автоматически или отправить на ревью человеку. Цена ошибки авто-раскладки
+реальна — мусор в библиотеке Jellyfin под неверным названием/папкой,
+возможно поверх чужого. Хочется максимум авто, но не ценой тихих ошибок.
+
+Силы и ограничения:
+
+- LLM хорошо разбирает русские и релиз-имена, но галлюцинирует, а его
+  самооценка (`confidence`) плохо откалибрована и тривиально поддаётся
+  инъекции из тех же недоверенных сигналов.
+- Внешние базы (TMDB/TVDB/TVMaze) дают **независимый** авторитетный сигнал:
+  каноническое имя + `provider_id`. Но русские релизы и аниме часто в них
+  отсутствуют.
+- Безопасность раскладки уже держится на валидации пути, не на промпте
+  (см. [recognition.md](../specs/recognition.md)); решение «авто vs review» —
+  второй слой защиты, на уровне доверия результату.
+
+## Рассмотренные варианты
+
+- **Гейт по самооценке LLM (`confidence ≥ порог`).** Просто и даёт
+  максимум авто. Но `confidence` не откалибрована и инъектируема —
+  «уверенный» неверный ответ прошёл бы молча. Небезопасно.
+- **LLM + структурная валидация, без обязательной базы.** Ловит часть
+  ошибок (число файлов у фильма, дыры/дубли в нумерации S·E), но не ловит
+  «правильную структуру под неверным названием». Недостаточно как
+  единственный гейт авто.
+- **Авто только при подтверждённом матче в базе + валидация +
+  согласованность сигналов.** Независимый авторитет снимает риск «LLM
+  придумал». Цена — рус/аниме (нет в базах) всегда идут в review, но это и
+  так нужный кейс.
+
+## Решение
+
+Авто-раскладку делаем, только если выполнено **всё**: (1) единственный
+сильный матч в метабазе по названию+году, давший `provider_id`;
+(2) структурная валидация без предупреждений; (3) пред-парс (`go-ptn`) и
+LLM не противоречат по типу/названию/году. Нет матча или база выключена →
+**всегда review**. Самооценку LLM учитываем лишь как вспомогательный
+сигнал, не как гейт.
+
+Почему так: безопасность держится на **независимой** проверке (база), а не
+на доверии к выходу LLM, построенному из недоверенных данных. Это разом
+закрывает основной кейс (рус/аниме отсутствуют в базах → человек
+подтверждает) и убирает целый класс тихих ошибок «модель уверенно
+ошиблась». Review здесь — не наказание, а штатный режим для всего, что
+база не подтвердила (петля «догадка → подсказка → перераспознавание», см.
+[review-ux.md](../specs/review-ux.md)). Полная модель уверенности — в
+[recognition.md](../specs/recognition.md).
+
+## Последствия
+
+- `+` Нет тихих авто-ошибок раскладки: всё неподтверждённое видит человек.
+- `+` `provider_id` из базы заодно даёт каноническое имя папки
+  (`[tmdbid-…]`) — Jellyfin не путает русские названия.
+- `−` Рус/аниме и всё, чего нет в базах, всегда требует ручного
+  подтверждения — авто там недоступно by design.
+- `−` Без включённых TMDB/TVDB/TVMaze авто-раскладки нет вовсе: сервис
+  работает в режиме «распознал → review».
+- Делает цикл ревью критичным: если он неудобен, ручное подтверждение
+  станет узким местом — поэтому review-ux вынесен в отдельную спеку.
@@ -56,6 +56,7 @@

 | Дата       | Запись                                                            | Статус |
 | ---------- | ---------------------------------------------------------------- | ------ |
+| 2026-06-13 | [Авто-раскладка только при матче в метабазе](ADR-2026-06-13-auto-link-requires-db-match.md) | — |
 | 2026-06-13 | [Docker как единица деплоя](ADR-2026-06-13-docker-deploy.md)      | —      |
 | 2026-06-13 | [Хардлинки вместо копирования и симлинков](ADR-2026-06-13-hardlinks.md) | — |
 | 2026-06-13 | [Go и доставка одним бинарём](ADR-2026-06-13-go-single-binary.md) | —      |