vk_hackathon/doc/ai_update.md

AI Update по ТЗ

Дата: 2026-04-18

Что просмотрено

• doc/ТЗ_на_хакатон_Индексация_и_поиск_по_сообщениям.pdf
• README.md
• docker-compose.yml
• index/main.py, search/main.py
• index/Dockerfile, search/Dockerfile
• index/Makefile, search/Makefile
• data/Go Nova.json

По примеру данных:

• всего сообщений: 25
• с parts: 14
• с цитатами: 5
• с пересланными сообщениями: 2
• с mentions: 4
• с file_snippets: 1
• системных сообщений: 1

Это важно, потому что в текущем коде часть этих сигналов либо не используется вообще, либо теряет смысл при индексации.

Что уже соответствует ТЗ

1. В репозитории есть оба требуемых сервиса: index и search.
2. Обязательные endpoints реализованы:
   • GET /health, POST /index, POST /sparse_embedding в index/main.py
   • GET /health, POST /search в search/main.py
3. Контракты request/response по основным endpoint'ам не менялись и в целом совпадают с шаблоном и ТЗ.
4. search использует Qdrant, dense endpoint и reranker через HTTP.
5. В обоих Dockerfile sparse-модель предзагружается внутрь образа, что соответствует оффлайн-ограничению контейнеров.
6. HOST и PORT читаются из env, как требует ТЗ.

Что отсутствует или реализовано частично

1. Обогащенный вопрос из ТЗ почти не используется

В search/main.py:90-100 описаны поля:

• search_text
• variants
• hyde
• keywords
• entities
• date_mentions
• date_range
• asker

Но в реальном поиске используется только question.text:

• search/main.py:307-316

Это главный недобор относительно ТЗ. Само ТЗ явно дает эти поля как сигналы для retrieval, а код их сейчас просто игнорирует.

2. Метаданные чанков объявлены, но не участвуют в поиске

В README.md:52-58 отдельно сказано, что в metadata чанка сохраняются:

• participants
• mentions
• contains_forward
• contains_quote

В search/main.py:132-145 есть модель ChunkMetadata, но дальше она никак не используется в query_points. Поиск не делает:

• фильтрацию по mentions
• фильтрацию по participants
• учет thread_sn
• учет временного диапазона через start/end
• отдельную обработку quote/forward чанков

То есть сильный канал улучшения качества уже предусмотрен схемой, но сейчас не задействован.

3. Реранк отбрасывает часть кандидатов

Сейчас:

• retrieval берет до 20 чанков: search/main.py:174-177
• rerank берет только первые 10: search/main.py:278-296
• после rerank возвращаются только эти 10, а хвост 11-20 теряется: search/main.py:321-328

Это не нарушение контракта, но это реальная потеря recall.

4. Выдача не дедуплицируется и не ограничивается по полезному top-K

Сейчас message_ids просто конкатенируются:

• search/main.py:323-328

Проблемы:

• дубликаты message id не удаляются
• результаты не агрегируются по лучшему score сообщения
• нет явного ограничения на топ полезных 50, хотя именно K=50 участвует в метрике из ТЗ

Если один и тот же message_id попал в несколько чанков, он тратит место в выдаче.

5. Индексация пока очень базовая: фиксированные символьные чанки

В index/main.py:118-190 чанки строятся просто по длине строки:

• CHUNK_SIZE = 512
• OVERLAP_SIZE = 256
• разбиение идет по символам, а не по сообщениям, тайм-гепам, тредам или смысловым блокам

Из-за этого:

• длинные пересланные сообщения и цитаты могут резаться в неудобных местах
• один и тот же смысловой блок может быть разнесен по чанкам неестественно
• overlap строится по хвосту текста, а не по границе сообщений

6. page_content, dense_content и sparse_content сейчас одинаковые

См. index/main.py:180-186.

ТЗ прямо оставляет это место как точку оптимизации качества, но пока этот резерв не используется.

7. Индексация берет только text и parts[*].text, остальное почти теряется

См. index/main.py:99-115.

Сейчас не используются как поисковые сигналы:

• sender_id
• mentions
• file_snippets
• member_event
• thread_sn
• is_hidden
• is_system
• явное различение quote и forward

Особенно важные пробелы:

• member_event у системных сообщений сейчас фактически пропадает, если обычного текста нет
• file_snippets не разбирается, хотя там могут быть имена файлов, URL и служебные поля
• запросы вида "кто писал", "кого упоминали", "какой файл/документ кидали" сейчас поддержаны слабо

8. Смысл quote и forward не маркируется

В index/main.py:105-113 текст из parts просто подшивается в общий текст без явных маркеров вида:

• "цитата:"
• "пересланное сообщение:"
• "автор цитаты:"

В итоге dense/sparse видят просто общий текстовый комок. Для поиска по обсуждениям это ощутимая потеря контекста.

9. Есть расхождение между локальной инфраструктурой и ТЗ

По ТЗ для search ожидается API_KEY.

В коде это поддержано:

• search/main.py:21-30
• search/main.py:42-47
• search/Makefile:10-15

Но локальный docker-compose.yml:57-60 требует OPEN_API_LOGIN и OPEN_API_PASSWORD.

Итог:

• сам сервис гибче ТЗ
• локальный compose не повторяет боевую схему из ТЗ один в один

Это не ломает контракт, но может запутать при локальной отладке.

10. Есть еще одна инфраструктурная несостыковка со сдачей

В doc/upload_to_docker.md:45-48 явно сказано собирать образы с --platform linux/amd64.

Но index/Makefile:16-18 и search/Makefile:26-28 собирают без --platform linux/amd64.

На x86 это может пройти незаметно, а на ARM-машине дать неправильный образ для отправки.

11. Есть неоднозначность между README и PDF по sparse в search

• README.md:211 говорит, что sparse-модель для search должна быть локально внутри образа
• PDF в формулировке требований к Search Service делает акцент, что обращения к dense/sparse/rerank идут через проверяющую систему

Текущий код следует логике README/example: sparse считается локально в search/main.py:148-151 и search/main.py:198-207.

Я бы это не считал блокером, но как минимум это место стоит держать в голове как неоднозначное требование.

Что улучшать в первую очередь

Приоритет 1. Начать использовать все поля question

Минимально стоит задействовать:

• search_text как основной нормализованный запрос
• variants как дополнительные формулировки
• hyde как дополнительные dense-запросы
• keywords как основу для sparse
• entities для фильтров и lexical boost
• date_range и date_mentions для ограничения по времени
• asker как сигнал по людям и email

Самый логичный путь без смены стэка: несколько dense/sparse запросов + fusion в Qdrant.

Приоритет 2. Перестроить chunking под структуру чата, а не под символы

Нужны чанки по:

• окнам сообщений
• временным разрывам
• границам thread/forward/quote
• ограничению на размер по сообщениям, а не только по символам

Для чатов это обычно дает больше пользы, чем любые косметические тюнинги rerank.

Приоритет 3. Развести page_content, dense_content, sparse_content

Хорошая схема:

• page_content: читабельный исходный текст чанка
• dense_content: нормализованный текст с ролями, автором, маркерами quote/forward
• sparse_content: keyword-heavy версия с email, mentions, именами файлов, ссылками, документами, леммами

Сейчас эта возможность не используется вообще.

Приоритет 4. Нормально собирать финальную выдачу

Нужно:

• не терять кандидатов после rerank
• удалять дубликаты message_id
• агрегировать по лучшему score сообщения или чанка
• отдавать осмысленный top-50

Это прямой выигрыш по Recall@50 и nDCG@50.

Приоритет 5. Начать использовать metadata в Qdrant

Особенно полезно для:

• mentions
• participants
• contains_quote
• contains_forward
• thread_sn
• start / end

Для многих вопросов это позволит не просто "лучше ранжировать", а сразу отрезать нерелевантный шум.

Приоритет 6. Превратить скрытые сигналы в индексируемый текст

Стоит отдельно материализовать:

• member_event в текст вида "пользователь X добавил Y"
• file_snippets в текст вида "файл: NAME, url: ..."
• автора сообщения
• список упомянутых пользователей

Сейчас эти сигналы либо не попадают в индекс, либо попадают слишком слабо.

Что можно добавить по Python-библиотекам, не меняя стек

Стек Qdrant менять не нужно. Самые полезные добавки я бы смотрел такие:

• pymorphy3 для лемматизации русских слов при подготовке sparse_content
• razdel для аккуратной токенизации русского текста
• rapidfuzz для точного lexical match по именам, email, документам, ссылкам и названиям
• python-dateutil или dateparser для нормализации дат, если захотите усиливать работу с date_mentions
• tenacity для аккуратных retry/timeout-оберток вокруг dense/rerank HTTP вызовов

Что не нужно делать:

• менять Qdrant
• тащить внешние LLM/API
• усложнять архитектуру ради "модности", пока не использованы базовые сигналы из самого ТЗ

Короткий вывод

Сейчас репозиторий соответствует ТЗ как рабочий базовый шаблон, но почти не использует те сигналы, ради которых это ТЗ вообще интересно:

• обогащение вопроса
• metadata чанков
• структуру chat messages
• сигналы автора, упоминаний, файлов, системных событий, цитат и пересылок

Самый большой потенциал улучшения здесь не в замене базы или модели, а в трех вещах:

1. умный chunking
2. multi-query hybrid retrieval
3. использование metadata и нормальной сборки финального top-50