Обучение: как скармливать тексты и файлы

Раздел /manage/ak/training — для админа, который хочет научить AI-агента знаниям из ваших источников: статьи блога, инструкции маркетплейса, внутренний регламент, PDF-выгрузки от поставщика, экспорт из Notion/Google Docs.

👤 Кому доступно: только админам компании. Обычные пользователи раздел не видят.

Когда это нужно

Хороший повод открыть «Обучение»:

• Вы прочитали статью на VC.ru про новые правила Ozon и хотите, чтобы агент об этом знал
• У вас есть памятка для сотрудников по упаковке поставок — пусть агент её цитирует
• Вышло обновление API Wildberries — добавляем кратко в базу
• Поставщик прислал прайс-лист в PDF — выжимка таблицы как memorable facts

Плохой повод:

• ❌ «Запомни, что сегодня вторник» (одноразовый факт, не для long-term)
• ❌ «У нас сейчас распродажа до пятницы» (time-bound, протухнет)
• ❌ Юридический контракт целиком (слишком длинно, нет атомарных фактов)

Шаг 1 — Загрузка материала

Два режима:

• Вставить текст — <textarea>, от 50 до 100 000 символов. Markdown работает (заголовки, списки, жирный — LLM их понимает).
• Загрузить файл — .md, .txt, .pdf, .docx. Лимит 5 MB.

⚠️ PDF без OCR-слоя (только сканы изображений) система отвергнет. Прогоните через ABBYY FineReader / Adobe OCR.

Параметры:

Нажмите «Обработать через Gemini →». LLM прочитает текст и попытается вытащить 0..15 атомарных фактов. Занимает 5–15 секунд.

Шаг 2 — Проверка (preview)

Каждый факт показан как карточка:

┌─────────────────────────────────────────────┐
│ [Термин ▾]   conf 0.92  ozon  [✓ Принят]    │
├─────────────────────────────────────────────┤
│ FBO definition                              │
│ Fulfillment by Ozon — продавец отгружает    │
│ на склад Ozon, дальше всё делает Ozon.      │
│ Теги: fbo, logistics                        │
└─────────────────────────────────────────────┘

Что можно сделать с каждой:

• Изменить kind (выпадающий список)
• Изменить title / body (поля редактируются на месте)
• «↶ Оригинал» — вернуть title и body к исходному предложению Gemini (кнопка появляется только после правок)
• Отклонить или вернуть «✓ Принят»

Кнопки сверху:

• «Принять все» — массово
• «Отклонить все» — массово
• «К началу» — стереть всё и начать сначала

Снизу — «Сохранить (N) →». Уйдут только принятые.

Что происходит после «Сохранить»

1. Каждый принятый факт пишется в ak_pending_observations с пометками:
   • source = 'manual_ingest'
   • meta.auto_approved = true
   • meta.manual_ingest.operator_user_id = <вы>
   • meta.manual_ingest.source_hash = <sha256 текста>
2. Конфликт-резолвер (запускается каждую минуту, Celery beat task ak-conflict-resolver-processor) проверяет, нет ли среди существующих чанков уже похожего по cosine ≥ 0.75 — это защита от дублей.
3. Если факт новый, он сразу попадает в ak_knowledge_chunks со статусом tier='confirmed' (а не draft). Это и есть «auto-approved short-circuit» — вы уже проверили глазами, дополнительного ревью не нужно.
4. Если факт дублирует существующий — резолвер сам решит:
   • NOOP — точный дубль, ничего не меняется
   • UPDATE — merge с существующим чанком; если он был в draft, ваша auto-approve поднимет его до confirmed
   • DELETE — новый факт явно противоречит и заменяет старый (с гейтами безопасности)
5. Audit: если вы отредактировали preview перед сохранением, оригинал суждения Gemini сохраняется в meta.manual_ingest.original_title / original_body — оператор-ревизор позже сможет сравнить, что предложила LLM против того, что записали.

После записи появляется зелёная плашка с ссылкой /manage/ak/pending?source=manual_ingest — можно проверить, что наблюдения легли.

Лучшие практики

• Атомарные факты лучше длинных саммари. «Ozon FBO" — это" — это атомарно. «Регламент FBO 2026 года в Ozon включает несколько подразделов» — нет.
• Один документ ≠ один чанк. Из статьи на 5 000 знаков обычно вытаскивается 6–10 чанков.
• Не грузите контракты целиком. Юридический документ → лучше выписка 2–3 ключевых пунктов.
• Используйте «Метка источника». Помогает потом найти, откуда что взялось, через lineage.
• Маркетплейс-подсказка реально работает. Если документ про WB, выберите wb — LLM будет аккуратнее с отнесением.

Что НЕЛЬЗЯ через этот раздел

• ❌ Перезаписать существующий чанк — это делается на /manage/ak/chunks/{id}
• ❌ Удалить чанк — то же самое
• ❌ Изменить visibility уже созданных — отдельный поток
• ❌ Тренировать на текстах с PII (паспорта, банковские реквизиты) — сенситив-скруббер их вычистит, но лучше не давать вообще