Compare commits
28 commits
4800e25dd6
...
19af82ba11
| Author | SHA1 | Date | |
|---|---|---|---|
|
19af82ba11 | ||
|
|
dc3a5b9dfd | ||
|
|
6f122eabd0 | ||
|
|
3561a064d5 | ||
|
|
f9f1b332bd | ||
|
|
7247248b27 | ||
|
|
a4475abfb2 | ||
|
|
91aae61b65 | ||
|
|
24505baa1c | ||
|
|
deb422d03e | ||
|
|
d2e531cc07 | ||
|
|
965fc906f3 | ||
|
|
9750868ea8 | ||
|
|
0fbf69e359 | ||
|
|
f4b14edabf | ||
|
|
d5ed8c7764 | ||
|
|
bd4c7c24a3 | ||
|
|
143efd6531 | ||
|
|
1e276512fb | ||
|
|
e244b8bf30 | ||
|
|
d28964aa7e | ||
|
|
b15c59a579 | ||
|
|
3423200625 | ||
|
|
e95ca82a4a | ||
|
|
9db7d3544c | ||
|
|
6c75cc8376 | ||
|
|
aad36f0ac5 | ||
|
|
e49e3417eb |
12 changed files with 0 additions and 1956 deletions
|
|
@ -1,280 +0,0 @@
|
|||
---
|
||||
name: team-sync-hackathon
|
||||
description: Use this skill for any work inside this repository when the task involves collaborative development, continuing previous work, restoring project context, updating shared progress logs, handing off work to another Codex or human, or bootstrapping the local dev stack. Do not use for unrelated one-off questions outside the repo.
|
||||
---
|
||||
|
||||
# Team Sync Hackathon Skill
|
||||
|
||||
This skill makes Codex behave like a persistent teammate inside the repository.
|
||||
|
||||
Its purpose is to:
|
||||
- restore context at the start of every session
|
||||
- keep a shared machine-readable and human-readable progress trail
|
||||
- reduce repeated analysis
|
||||
- make handoff between humans and Codex reliable
|
||||
- automatically orient to the current repo state before coding
|
||||
- keep the project runnable locally whenever validation is needed
|
||||
|
||||
---
|
||||
|
||||
## Core rule
|
||||
|
||||
Do not start changing code blindly.
|
||||
|
||||
First restore context, then inspect git state, then inspect runtime state, then work, then write handoff.
|
||||
|
||||
If context is missing, create it.
|
||||
|
||||
---
|
||||
|
||||
## Shared state directory
|
||||
|
||||
Use `.ai_update/` as the canonical shared state area.
|
||||
|
||||
Required files:
|
||||
|
||||
- `.ai_update/current_status.md`
|
||||
- `.ai_update/handoff.md`
|
||||
- `.ai_update/changelog.md`
|
||||
- `.ai_update/touched_files.md`
|
||||
- `.ai_update/sessions/` (directory with per-session notes)
|
||||
|
||||
These files are part of the collaboration workflow and should be committed unless the team explicitly decides otherwise.
|
||||
|
||||
---
|
||||
|
||||
## Mandatory startup workflow
|
||||
|
||||
At the beginning of each repo task, do this in order:
|
||||
|
||||
1. Read:
|
||||
- `AGENTS.md`
|
||||
- `README.md`
|
||||
- relevant docs/config files
|
||||
- `.ai_update/current_status.md`
|
||||
- `.ai_update/handoff.md`
|
||||
- latest 3 to 5 files from `.ai_update/sessions/`
|
||||
- `.ai_update/changelog.md`
|
||||
- `.ai_update/touched_files.md`
|
||||
|
||||
2. Inspect repository state:
|
||||
- `git status --short --branch`
|
||||
- `git log --oneline --decorate -n 15`
|
||||
- inspect main app entrypoints and service layout
|
||||
- identify current branch
|
||||
- identify uncommitted work
|
||||
- identify likely active area of development
|
||||
|
||||
3. If `.ai_update/` files are missing:
|
||||
- create them immediately
|
||||
- infer current project state from repository files and git history
|
||||
- write a minimal baseline before making new code changes
|
||||
|
||||
4. Create a new session note:
|
||||
- `.ai_update/sessions/YYYY-MM-DD_HH-MM-SS.md`
|
||||
- include:
|
||||
- task requested
|
||||
- starting branch
|
||||
- starting commit
|
||||
- initial repo observations
|
||||
- assumptions
|
||||
- risks/blockers
|
||||
|
||||
5. Only after that begin implementation.
|
||||
|
||||
---
|
||||
|
||||
## Runtime bootstrapping workflow
|
||||
|
||||
When local validation is required, use the least destructive startup path.
|
||||
|
||||
Try in this order:
|
||||
|
||||
1. If `./bin/codex-start` exists, use it.
|
||||
2. Else if `docker-compose.yml` exists:
|
||||
- check whether services are already up
|
||||
- if not, run `docker compose up -d --build`
|
||||
3. Else if `compose.yaml` or `compose.yml` exists:
|
||||
- run `docker compose up -d --build`
|
||||
4. Else if `Makefile` exists and has a relevant target:
|
||||
- try `make dev`
|
||||
- otherwise `make up`
|
||||
- otherwise `make run`
|
||||
5. Else inspect project docs for the correct startup command.
|
||||
|
||||
Rules:
|
||||
- do not run destructive cleanup automatically
|
||||
- do not remove volumes automatically
|
||||
- do not rebuild everything if a simple start is enough
|
||||
- if startup fails, record the failure and exact reason in `.ai_update/current_status.md` and the current session note
|
||||
|
||||
---
|
||||
|
||||
## Required logging during work
|
||||
|
||||
For each meaningful step, keep `.ai_update/` current.
|
||||
|
||||
### Update `.ai_update/current_status.md`
|
||||
|
||||
This file is the canonical current snapshot.
|
||||
|
||||
It must always contain:
|
||||
|
||||
- current goal
|
||||
- done
|
||||
- in progress
|
||||
- blocked
|
||||
- next actions
|
||||
- current branch
|
||||
- validation status
|
||||
- known risks
|
||||
|
||||
### Append to `.ai_update/changelog.md`
|
||||
|
||||
Append a short entry for every meaningful change:
|
||||
- timestamp
|
||||
- what changed
|
||||
- why
|
||||
- files
|
||||
- verification result
|
||||
|
||||
### Update `.ai_update/touched_files.md`
|
||||
|
||||
Maintain a concise list:
|
||||
- file path
|
||||
- purpose
|
||||
- why touched
|
||||
- whether complete/incomplete
|
||||
- whether needs review
|
||||
|
||||
### Write session notes
|
||||
|
||||
Each session file should capture:
|
||||
- objective
|
||||
- context read
|
||||
- commands run
|
||||
- findings
|
||||
- code changes
|
||||
- test results
|
||||
- unresolved issues
|
||||
- handoff notes
|
||||
|
||||
---
|
||||
|
||||
## Mandatory handoff before stopping
|
||||
|
||||
Before ending the session:
|
||||
|
||||
1. Update `.ai_update/current_status.md`
|
||||
2. Update `.ai_update/handoff.md`
|
||||
3. Append `.ai_update/changelog.md`
|
||||
4. Update `.ai_update/touched_files.md`
|
||||
5. Finalize current session note
|
||||
|
||||
`handoff.md` must answer:
|
||||
|
||||
- what was completed
|
||||
- what was not completed
|
||||
- what the next Codex/human should do first
|
||||
- what files matter most
|
||||
- how to run/verify
|
||||
- what is risky or fragile
|
||||
- whether there are uncommitted changes
|
||||
|
||||
Another engineer should be able to continue without rereading the full repo history.
|
||||
|
||||
---
|
||||
|
||||
## Repository-specific guidance for this hackathon
|
||||
|
||||
Assume this repository follows a hackathon task with:
|
||||
- an indexing service
|
||||
- a search service
|
||||
- vector storage in Qdrant
|
||||
- fixed API contracts for `/index`, `/sparse_embedding`, and `/search`
|
||||
- local docker-based development
|
||||
- quality measured by retrieval relevance rather than just code style
|
||||
|
||||
When working on search/index logic:
|
||||
|
||||
- preserve public request/response contracts
|
||||
- do not introduce runtime internet dependency inside index/search containers
|
||||
- prefer retrieval quality improvements over cosmetic refactors
|
||||
- avoid breaking dockerized local startup
|
||||
- keep local validation straightforward
|
||||
|
||||
For search logic, prefer this query priority:
|
||||
1. `question.search_text`
|
||||
2. fallback to `question.text`
|
||||
3. enrich with `question.variants`
|
||||
4. consider `question.hyde`
|
||||
5. consider `question.keywords`
|
||||
6. consider `question.entities`
|
||||
7. consider `question.date_mentions` and `question.date_range`
|
||||
8. keep rerank/retrieval consistent with top-50 relevance goals
|
||||
|
||||
For indexing logic:
|
||||
- keep chunking explainable
|
||||
- preserve `message_ids` coverage clarity
|
||||
- think explicitly about `page_content`, `dense_content`, and `sparse_content`
|
||||
- log chunking and retrieval decisions if they affect quality significantly
|
||||
|
||||
---
|
||||
|
||||
## Collaboration rules
|
||||
|
||||
- Never assume previous work is obsolete without evidence.
|
||||
- Read before rewriting.
|
||||
- Prefer extending existing modules over creating parallel implementations.
|
||||
- Preserve teammate intent when possible.
|
||||
- If you must replace an approach, document why in `.ai_update/changelog.md` and `handoff.md`.
|
||||
|
||||
---
|
||||
|
||||
## Git rules
|
||||
|
||||
- Do not commit unrelated changes.
|
||||
- Do not revert teammate changes without explicit reason.
|
||||
- Do not force push unless explicitly instructed.
|
||||
- Before commit, summarize exactly what changed in `.ai_update/`.
|
||||
- Commit messages should be specific and scoped.
|
||||
|
||||
Preferred commit style:
|
||||
- `search: use search_text with fallback to text`
|
||||
- `index: enrich sparse content with metadata`
|
||||
- `infra: add codex shared handoff workflow`
|
||||
|
||||
---
|
||||
|
||||
## Minimal file templates
|
||||
|
||||
If files are missing, initialize them with these templates.
|
||||
|
||||
### `.ai_update/current_status.md`
|
||||
|
||||
```md
|
||||
# Current Status
|
||||
|
||||
## Current goal
|
||||
-
|
||||
|
||||
## Done
|
||||
-
|
||||
|
||||
## In progress
|
||||
-
|
||||
|
||||
## Blocked
|
||||
-
|
||||
|
||||
## Next actions
|
||||
-
|
||||
|
||||
## Current branch
|
||||
-
|
||||
|
||||
## Validation
|
||||
- Not run / Passed / Failed
|
||||
|
||||
## Risks / notes
|
||||
-
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
# AI Update Log
|
||||
|
||||
## Scope
|
||||
- File: `search/main.py`
|
||||
- Purpose: fixed and extended retrieval/rerank pipeline according to TODO items.
|
||||
|
||||
## Done Changes
|
||||
- Switched base query selection to `question.search_text` with fallback to `question.text`.
|
||||
- Added support for `question.variants` as additional query variants in retrieval.
|
||||
- Added support for `question.hyde` as additional dense-only queries.
|
||||
- Added support for `question.keywords` as the primary source for sparse query text with fallback to current query variant.
|
||||
- Stopped losing retrieval candidates after rerank: rerank is applied to head (`RERANK_LIMIT`), tail candidates are preserved.
|
||||
- Added deduplication of retrieval points by Qdrant point id before rerank.
|
||||
- Implemented score aggregation by `message_id` (sum of chunk scores mapped to same message).
|
||||
- Limited final response to `top-50` message ids via `FINAL_TOP_K = 50`.
|
||||
- Final output message ids are now selected from aggregated scores (sorted by score desc, tie-break by message_id).
|
||||
|
||||
## Notes
|
||||
- Earlier step introduced direct `message_ids` deduplication before response.
|
||||
- Current logic supersedes this by ranking and selecting unique `message_id` values from aggregated scores.
|
||||
|
||||
## Verification
|
||||
- Syntax check passed after each main change: `python -m py_compile search/main.py`.
|
||||
|
||||
## How To Use This Log
|
||||
- Treat this file as the source of truth for already completed `search/main.py` tasks.
|
||||
- On next tasks, read this file first to avoid duplicate edits.
|
||||
0
.codex
0
.codex
290
doc/ai_update.md
290
doc/ai_update.md
|
|
@ -1,290 +0,0 @@
|
|||
# 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
|
||||
|
|
@ -1,366 +0,0 @@
|
|||
# Curl API Test
|
||||
|
||||
## Sources
|
||||
|
||||
- Canonical contracts: `doc/ТЗ_на_хакатон_Индексация_и_поиск_по_сообщениям.pdf`
|
||||
- Runnable examples and local launch notes: `README.md`
|
||||
- Actual local wiring: `docker-compose.yml`
|
||||
|
||||
PDF gives the strict request/response schemas for `POST /index`, `POST /sparse_embedding`, and `POST /search`.
|
||||
`README.md` adds ready curl examples for the minimal requests.
|
||||
This file normalizes both into checks against the current local compose stack.
|
||||
|
||||
## Compose Wiring
|
||||
|
||||
- `index`: `http://localhost:8001`
|
||||
- `search`: `http://localhost:8002`
|
||||
- `qdrant`: `http://localhost:6334`
|
||||
- Inside compose, services use `QDRANT_URL=http://qdrant:6333`
|
||||
- Collection name from `.env`: `evaluation`
|
||||
- Vector names from `.env`: `dense` and `sparse`
|
||||
|
||||
Note: current `docker-compose.yml` publishes Qdrant as `6334:6333`, while `README.md` still says `localhost:6333`. For local checks in this repo state, use `localhost:6334`.
|
||||
|
||||
## Extracted API Requests
|
||||
|
||||
### `GET /health`
|
||||
|
||||
Both services must answer `200 OK`.
|
||||
|
||||
```bash
|
||||
curl -sS http://localhost:8001/health
|
||||
curl -sS http://localhost:8002/health
|
||||
```
|
||||
|
||||
Expected shape:
|
||||
|
||||
```json
|
||||
{"status":"ok"}
|
||||
```
|
||||
|
||||
### `POST /index`
|
||||
|
||||
Schema from the PDF:
|
||||
|
||||
- body root: `data`
|
||||
- `data.chat`
|
||||
- `data.overlap_messages[]`
|
||||
- `data.new_messages[]`
|
||||
|
||||
Runnable request:
|
||||
|
||||
```bash
|
||||
curl -sS -X POST http://localhost:8001/index \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"data": {
|
||||
"chat": {
|
||||
"id": "chat-1",
|
||||
"name": "Go Nova",
|
||||
"sn": "chat-1@chat.agent",
|
||||
"type": "channel",
|
||||
"is_public": true
|
||||
},
|
||||
"overlap_messages": [
|
||||
{
|
||||
"id": "1",
|
||||
"time": 1710000000,
|
||||
"text": "Обсуждаем релиз Go",
|
||||
"sender_id": "u1",
|
||||
"file_snippets": "",
|
||||
"parts": [],
|
||||
"mentions": [],
|
||||
"member_event": null,
|
||||
"is_system": false,
|
||||
"is_hidden": false,
|
||||
"is_forward": false,
|
||||
"is_quote": false
|
||||
}
|
||||
],
|
||||
"new_messages": [
|
||||
{
|
||||
"id": "2",
|
||||
"time": 1710000060,
|
||||
"text": "Релиз Go перенесли на следующую неделю",
|
||||
"sender_id": "u2",
|
||||
"file_snippets": "",
|
||||
"parts": [],
|
||||
"mentions": [],
|
||||
"member_event": null,
|
||||
"is_system": false,
|
||||
"is_hidden": false,
|
||||
"is_forward": false,
|
||||
"is_quote": false
|
||||
}
|
||||
]
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Observed response:
|
||||
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"page_content": "u1: Обсуждаем релиз Go\nu2: Релиз Go перенесли на следующую неделю",
|
||||
"dense_content": "[2024-03-09 16:00] sender:u1\nОбсуждаем релиз Go\n[2024-03-09 16:01] sender:u2\nРелиз Go перенесли на следующую неделю",
|
||||
"sparse_content": "u1 Обсуждаем релиз Go u2 Релиз Go перенесли на следующую неделю",
|
||||
"message_ids": ["2"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Note: overlap messages are used as context, but are not included in returned `message_ids`.
|
||||
|
||||
### `POST /sparse_embedding`
|
||||
|
||||
Schema from the PDF:
|
||||
|
||||
- body root: `texts: string[]`
|
||||
|
||||
Runnable request:
|
||||
|
||||
```bash
|
||||
curl -sS -X POST http://localhost:8001/sparse_embedding \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"texts": [
|
||||
"Релиз Go перенесли на следующую неделю",
|
||||
"VK GPT обсуждали в отдельном чате"
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
Observed response:
|
||||
|
||||
```json
|
||||
{
|
||||
"vectors": [
|
||||
{
|
||||
"indices": [275068001, 108710752, 842257583, 1159207840, 2129888840, 703082301],
|
||||
"values": [1.6652868125369606, 1.6652868125369606, 1.6652868125369606, 1.6652868125369606, 1.6652868125369606, 1.6652868125369606]
|
||||
},
|
||||
{
|
||||
"indices": [73209461, 751565418, 59863655, 1856729543, 2036701913, 1943620510],
|
||||
"values": [1.6652868125369606, 1.6652868125369606, 1.6652868125369606, 1.6652868125369606, 1.6652868125369606, 1.6652868125369606]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### `POST /search`
|
||||
|
||||
Minimal request from `README.md`:
|
||||
|
||||
```bash
|
||||
curl -sS -X POST http://localhost:8002/search \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"question": {
|
||||
"text": "Что писали про релиз Go?"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Full schema from the PDF:
|
||||
|
||||
```json
|
||||
{
|
||||
"question": {
|
||||
"text": "Что писали про релиз Go?",
|
||||
"asker": "u2",
|
||||
"asked_on": "2024-03-09",
|
||||
"variants": ["релиз go перенесли?", "обсуждение релиза go"],
|
||||
"hyde": ["В чате пишут, что релиз Go перенесли на следующую неделю."],
|
||||
"keywords": ["релиз", "Go", "перенесли"],
|
||||
"entities": {
|
||||
"people": ["u2"],
|
||||
"emails": [],
|
||||
"documents": [],
|
||||
"names": ["Go"],
|
||||
"links": []
|
||||
},
|
||||
"date_mentions": ["следующая неделя", "2024-03-09"],
|
||||
"date_range": {
|
||||
"from": "2024-03-09T00:00:00Z",
|
||||
"to": "2024-03-10T00:00:00Z"
|
||||
},
|
||||
"search_text": "релиз Go перенесли на следующую неделю"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Checks Run
|
||||
|
||||
### 1. Health checks
|
||||
|
||||
Commands:
|
||||
|
||||
```bash
|
||||
curl -sS http://localhost:8001/health
|
||||
curl -sS http://localhost:8002/health
|
||||
```
|
||||
|
||||
Observed:
|
||||
|
||||
```json
|
||||
{"status":"ok"}
|
||||
{"status":"ok"}
|
||||
```
|
||||
|
||||
### 2. Qdrant collection exists, but starts empty
|
||||
|
||||
Command:
|
||||
|
||||
```bash
|
||||
curl -sS http://localhost:6334/collections/evaluation
|
||||
```
|
||||
|
||||
Observed before manual insert:
|
||||
|
||||
- `points_count: 0`
|
||||
- `indexed_vectors_count: 0`
|
||||
|
||||
This matches the README note that local compose creates the collection, but the template flow does not automatically upsert `/index` output into Qdrant.
|
||||
|
||||
### 3. `/index` works
|
||||
|
||||
Observed:
|
||||
|
||||
- HTTP request completed successfully
|
||||
- service returned one chunk
|
||||
- returned fields match the contract: `page_content`, `dense_content`, `sparse_content`, `message_ids`
|
||||
|
||||
### 4. `/sparse_embedding` works
|
||||
|
||||
Observed:
|
||||
|
||||
- HTTP request completed successfully
|
||||
- response returned `vectors[]`
|
||||
- each vector contains `indices[]` and `values[]`
|
||||
|
||||
### 5. `/search` on an empty collection returns an empty result
|
||||
|
||||
Command:
|
||||
|
||||
```bash
|
||||
curl -sS -X POST http://localhost:8002/search \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"question":{"text":"Что писали про релиз Go?"}}'
|
||||
```
|
||||
|
||||
Observed:
|
||||
|
||||
```json
|
||||
{"results":[]}
|
||||
```
|
||||
|
||||
This is expected while `evaluation` has no points.
|
||||
|
||||
### 6. Manual Qdrant upsert for end-to-end smoke test
|
||||
|
||||
To verify `/search` end-to-end, I inserted one synthetic point into local Qdrant with:
|
||||
|
||||
- point id `1001`
|
||||
- dummy dense vector of size `1024`
|
||||
- sparse vector under field `sparse`
|
||||
- payload containing `page_content` and `metadata.message_ids=["2"]`
|
||||
|
||||
Command:
|
||||
|
||||
```bash
|
||||
vec=$(awk 'BEGIN{for(i=0;i<1024;i++) printf "%s%d", (i?",":""), (i==0)}')
|
||||
curl -sS -X PUT 'http://localhost:6334/collections/evaluation/points?wait=true' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d "{\"points\":[{\"id\":1001,\"vector\":{\"dense\":[${vec}],\"sparse\":{\"indices\":[1],\"values\":[1.0]}},\"payload\":{\"page_content\":\"u1: Обсуждаем релиз Go\\nu2: Релиз Go перенесли на следующую неделю\",\"metadata\":{\"message_ids\":[\"2\"],\"participants\":[\"u1\",\"u2\"],\"start\":\"2024-03-09T16:00:00Z\",\"end\":\"2024-03-09T16:01:00Z\",\"chat_id\":\"chat-1\",\"chat_name\":\"Go Nova\",\"chat_type\":\"channel\",\"chat_sn\":\"chat-1@chat.agent\"}}}]}"
|
||||
```
|
||||
|
||||
Observed:
|
||||
|
||||
```json
|
||||
{"result":{"operation_id":0,"status":"completed"},"status":"ok","time":0.008234969}
|
||||
```
|
||||
|
||||
Collection state after insert:
|
||||
|
||||
- `points_count: 1`
|
||||
- `indexed_vectors_count: 1`
|
||||
|
||||
### 7. `/search` works after one point is present
|
||||
|
||||
Minimal request:
|
||||
|
||||
```bash
|
||||
curl -sS -X POST http://localhost:8002/search \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"question":{"text":"Что писали про релиз Go?"}}'
|
||||
```
|
||||
|
||||
Observed:
|
||||
|
||||
```json
|
||||
{"results":[{"message_ids":["2"]}]}
|
||||
```
|
||||
|
||||
Enriched request without `date_range`:
|
||||
|
||||
```bash
|
||||
curl -sS -X POST http://localhost:8002/search \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"question": {
|
||||
"text": "Что писали про релиз Go?",
|
||||
"asker": "u2",
|
||||
"asked_on": "2024-03-09",
|
||||
"variants": ["релиз go перенесли?", "обсуждение релиза go"],
|
||||
"hyde": ["В чате пишут, что релиз Go перенесли на следующую неделю."],
|
||||
"keywords": ["релиз", "Go", "перенесли"],
|
||||
"entities": {
|
||||
"people": ["u2"],
|
||||
"emails": [],
|
||||
"documents": [],
|
||||
"names": ["Go"],
|
||||
"links": []
|
||||
},
|
||||
"date_mentions": ["следующая неделя", "2024-03-09"],
|
||||
"search_text": "релиз Go перенесли на следующую неделю"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Observed:
|
||||
|
||||
```json
|
||||
{"results":[{"message_ids":["2"]}]}
|
||||
```
|
||||
|
||||
### 8. Defect: `date_range` request currently fails
|
||||
|
||||
The full PDF-shaped request with ISO timestamps in `question.date_range` does not work in the current implementation.
|
||||
|
||||
Observed:
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "2 validation errors for Range\ngte\n Input should be a valid number, unable to parse string as a number [type=float_parsing, input_value='2024-03-09T00:00:00Z', input_type=str]\n For further information visit https://errors.pydantic.dev/2.12/v/float_parsing\nlte\n Input should be a valid number, unable to parse string as a number [type=float_parsing, input_value='2024-03-10T00:00:00Z', input_type=str]\n For further information visit https://errors.pydantic.dev/2.12/v/float_parsing"
|
||||
}
|
||||
```
|
||||
|
||||
Interpretation:
|
||||
|
||||
- the public request schema accepts ISO date strings
|
||||
- current `search` code tries to pass them into a numeric `qdrant_client.models.Range`
|
||||
- so `date_range` is a real runtime bug in the current local build
|
||||
|
||||
## Bottom Line
|
||||
|
||||
- `index /health`: OK
|
||||
- `search /health`: OK
|
||||
- `POST /index`: OK
|
||||
- `POST /sparse_embedding`: OK
|
||||
- `POST /search` on empty collection: OK, returns empty list
|
||||
- `POST /search` after one test point is inserted: OK
|
||||
- `POST /search` with enriched request excluding `date_range`: OK
|
||||
- `POST /search` with `date_range` from the PDF schema: FAILS in current implementation
|
||||
329
doc/output.md
329
doc/output.md
|
|
@ -1,329 +0,0 @@
|
|||
# Report: Go Nova Data Audit
|
||||
|
||||
Дата: 2026-04-18
|
||||
|
||||
## Что анализировал
|
||||
|
||||
Под "Go Data.js" интерпретировал файл [data/Go Nova.json](/home/q/doc/hackaton/data/Go%20Nova.json), потому что в репозитории это единственный релевантный датасет для `index` и `search`.
|
||||
|
||||
## Краткая статистика по данным
|
||||
|
||||
- всего сообщений: `25`
|
||||
- сообщений с пустым верхнеуровневым `text`: `15`
|
||||
- сообщений с `parts`: `14`
|
||||
- сообщений с `mentions`: `4`
|
||||
- сообщений с `member_event`: `1`
|
||||
- сообщений с `file_snippets`: `1`
|
||||
- сообщений с `is_forward = true`: `2`
|
||||
- сообщений с `is_quote = true`: `5`
|
||||
- сообщений с `thread_sn`: `0`
|
||||
- сообщений с zero-width символом `\u200b`: `1`
|
||||
|
||||
## Что это значит для индексации
|
||||
|
||||
Текущий `index` теряет заметную часть смысла, потому что:
|
||||
|
||||
- слишком сильно полагается на `message.text`
|
||||
- не различает `mediaType` внутри `parts`
|
||||
- не превращает `member_event` в индексируемый текст
|
||||
- не разбирает JSON в `file_snippets`
|
||||
- не нормализует артефакты вроде zero-width символов
|
||||
|
||||
На этом датасете это критично: существенная доля сообщений живет целиком внутри `parts[*].text`.
|
||||
|
||||
## Наблюдаемые паттерны в сообщениях
|
||||
|
||||
### 1. Системные сообщения
|
||||
|
||||
Есть системное сообщение без текста, но с `member_event`:
|
||||
|
||||
- `type = addMembers`
|
||||
- список участников лежит в `members`
|
||||
|
||||
Такое сообщение нельзя отбрасывать. Его нужно материализовать в текст вроде:
|
||||
|
||||
```text
|
||||
system event: add members
|
||||
actor: n.lebedev@corp.example
|
||||
members: l.smirnova@corp.example, m.orlova@corp.example, v.baranova@corp.example, n.lebedev@corp.example
|
||||
```
|
||||
|
||||
### 2. Сообщения, где весь смысл в `parts`
|
||||
|
||||
Во многих сообщениях `text == ""`, а контент лежит в `parts[*].text`.
|
||||
|
||||
Наблюдаемые `mediaType`:
|
||||
|
||||
- `text`
|
||||
- `quote`
|
||||
- `forward`
|
||||
|
||||
Следствие:
|
||||
|
||||
- `parts` должны быть первичным источником текста, а не вторичным придатком к `text`
|
||||
|
||||
### 3. Цитаты
|
||||
|
||||
У quote-part встречаются:
|
||||
|
||||
- `mediaType = quote`
|
||||
- `sn` как источник цитаты
|
||||
- `time`
|
||||
- `text`
|
||||
|
||||
Quote нельзя просто склеивать с ответом. Нужна разметка, например:
|
||||
|
||||
```text
|
||||
quote_from: n.ermakova@team.example
|
||||
quote_text: ...
|
||||
reply_text: ...
|
||||
```
|
||||
|
||||
Иначе dense/sparse видят просто один большой комок текста и теряют отношение "на что отвечали".
|
||||
|
||||
### 4. Forward-сообщения
|
||||
|
||||
Forward приходит как `parts[*].mediaType = forward`, часто с длинным телом анонса.
|
||||
|
||||
Для них полезно явно сохранять:
|
||||
|
||||
- что это пересланное сообщение
|
||||
- источник `sn`
|
||||
- текст forwarded-блока
|
||||
|
||||
Пример нормализованного вида:
|
||||
|
||||
```text
|
||||
forwarded_from: 48377@chat.example
|
||||
forward_text: ...
|
||||
```
|
||||
|
||||
### 5. Файлы и ссылки
|
||||
|
||||
В `file_snippets` лежит JSON-строка, внутри которой есть полезные поля:
|
||||
|
||||
- `name`
|
||||
- `mime`
|
||||
- `original_url`
|
||||
- `date_create`
|
||||
|
||||
Это нужно разбирать локально и добавлять в нормализованный текст, а не хранить сырой JSON.
|
||||
|
||||
Минимально:
|
||||
|
||||
```text
|
||||
attachment_name: IMG_8471.webp
|
||||
attachment_mime: image/webp
|
||||
attachment_url: https://redacted.example/resource/001
|
||||
```
|
||||
|
||||
Ссылки из текста тоже нельзя выбрасывать полностью. Их нужно:
|
||||
|
||||
- сохранять в `page_content`
|
||||
- извлекать как отдельные токены/сигналы в `sparse_content`
|
||||
|
||||
### 6. Технический шум
|
||||
|
||||
В данных уже видны артефакты:
|
||||
|
||||
- zero-width символ `\u200b`
|
||||
- лишние пустые строки
|
||||
- неравномерные пробелы
|
||||
|
||||
Но чистить нужно осторожно, чтобы не повредить:
|
||||
|
||||
- email
|
||||
- URL
|
||||
- имена файлов
|
||||
- термины вроде `CGO`, `Go 1.18`, `Mutex.TryLock`
|
||||
|
||||
## Предлагаемая локальная логика очистки сообщений
|
||||
|
||||
Вся очистка должна жить локально внутри `index`, без внешних API.
|
||||
|
||||
### Шаг 1. Извлечение сигналов из raw message
|
||||
|
||||
Из каждого сообщения собрать:
|
||||
|
||||
- `message.text`
|
||||
- `parts[*]`
|
||||
- `mentions`
|
||||
- `member_event`
|
||||
- `file_snippets`
|
||||
- `sender_id`
|
||||
- флаги `is_system`, `is_forward`, `is_quote`
|
||||
|
||||
### Шаг 2. Нормализация Unicode и whitespace
|
||||
|
||||
Безопасная очистка:
|
||||
|
||||
- удалить `\u200b`, `\u200c`, `\u200d`, `\ufeff`
|
||||
- заменить `\r\n` на `\n`
|
||||
- схлопнуть повторяющиеся пробелы внутри строки
|
||||
- схлопнуть `3+` пустых строк до `2`
|
||||
- обрезать пробелы по краям строк
|
||||
|
||||
Не делать агрессивную очистку:
|
||||
|
||||
- не удалять email
|
||||
- не удалять URL
|
||||
- не переводить все в lower
|
||||
- не выкидывать цифры и версии
|
||||
|
||||
### Шаг 3. Нормализация `parts`
|
||||
|
||||
Правила:
|
||||
|
||||
- `mediaType = text`: добавить как обычный текстовый блок
|
||||
- `mediaType = quote`: добавить маркеры `quote_from` и `quote_text`
|
||||
- `mediaType = forward`: добавить маркеры `forwarded_from` и `forward_text`
|
||||
- неизвестный `mediaType`: сохранять как `part_type: <value>` + текст, не терять содержимое
|
||||
|
||||
### Шаг 4. Нормализация системных событий
|
||||
|
||||
Для `member_event` генерировать текстовую форму.
|
||||
|
||||
Минимум поддержать:
|
||||
|
||||
- `addMembers`
|
||||
- любые неизвестные события сохранять как `system_event_type: ...`
|
||||
|
||||
### Шаг 5. Нормализация файлов
|
||||
|
||||
`file_snippets` распарсить из JSON-строки локально.
|
||||
|
||||
Из каждого файла вытаскивать:
|
||||
|
||||
- имя
|
||||
- mime
|
||||
- url
|
||||
- дату
|
||||
|
||||
Если JSON битый:
|
||||
|
||||
- не падать
|
||||
- сохранить исходную строку как `attachment_raw`
|
||||
|
||||
### Шаг 6. Сборка трех текстовых представлений
|
||||
|
||||
`page_content`:
|
||||
|
||||
- читабельный текст для payload
|
||||
- с маркерами quote/forward/system/file
|
||||
|
||||
`dense_content`:
|
||||
|
||||
- нормализованный текст с ролями и источниками
|
||||
- без мусорных повторов и с понятной структурой
|
||||
|
||||
`sparse_content`:
|
||||
|
||||
- keyword-heavy версия
|
||||
- email, mentions, file names, MIME, URL host/path, технические термины
|
||||
|
||||
### Шаг 7. Правила пропуска
|
||||
|
||||
Сообщение можно пропускать только если после нормализации одновременно пусты:
|
||||
|
||||
- основной текст
|
||||
- `parts`
|
||||
- `member_event`
|
||||
- `file_snippets`
|
||||
|
||||
Иначе его нужно индексировать.
|
||||
|
||||
## Что обновил в документации
|
||||
|
||||
- [doc/prompt.md](/home/q/doc/hackaton/doc/prompt.md): добавил локальную логику очистки сообщений и требование логировать каждую правку
|
||||
- [doc/output.md](/home/q/doc/hackaton/doc/output.md): создал этот отчет
|
||||
|
||||
## Что делать следующим шагом
|
||||
|
||||
1. Реализовать `index/rendering.py` и `index/cleaning.py` по этим правилам.
|
||||
2. Добавить unit tests на системные, quote, forward и file-based сообщения.
|
||||
3. Только после этого менять chunking и retrieval, чтобы не тюнить поиск на грязном тексте.
|
||||
|
||||
---
|
||||
|
||||
# Отчёт: Рефакторинг search и index (2026-04-18)
|
||||
|
||||
## Что изменено
|
||||
|
||||
### P0 — исправлен критический баг в search
|
||||
|
||||
**Файл:** `search/main.py` (до рефакторинга)
|
||||
**Баг:** строка `must_conditions: []` была type annotation, а не присваивание. Любой запрос с `date_range` или `asker` вызывал `NameError` на `.append()`.
|
||||
**Исправление:** присваивание `must_conditions = []` перенесено в `search/retrieval.py` корректно.
|
||||
|
||||
### search — модульная декомпозиция
|
||||
|
||||
**Было:** монолит `search/main.py` (~390 строк)
|
||||
**Стало:** 6 модулей + тонкий main
|
||||
|
||||
| Модуль | Назначение |
|
||||
|---|---|
|
||||
| `search/config.py` | env vars, validate_required_env (теперь в lifespan, не при импорте) |
|
||||
| `search/schemas.py` | pydantic модели |
|
||||
| `search/query_builder.py` | построение dense/sparse запросов из question |
|
||||
| `search/retrieval.py` | qdrant prefetch с multi-query + фильтры |
|
||||
| `search/rerank.py` | reranker + сохранение хвоста |
|
||||
| `search/aggregation.py` | dedup, top-50 |
|
||||
| `search/main.py` | только FastAPI wiring |
|
||||
|
||||
**Логические изменения:**
|
||||
- primary dense query: `search_text` с fallback на `text`
|
||||
- дополнительные dense queries: `variants`, `hyde` — отдельные Prefetch
|
||||
- sparse query: `keywords` или primary query при их отсутствии
|
||||
- rerank: сортирует top-60, хвост retrieval сохраняется
|
||||
- финал: dedup + top-50 из head+tail
|
||||
- timeout=30s, retry до 2 раз на 5xx/сеть
|
||||
|
||||
**Параметры:** DENSE_PREFETCH_K=50, SPARSE_PREFETCH_K=100, RETRIEVE_K=80, RERANK_LIMIT=60, TOP_K=50
|
||||
|
||||
### index — модульная декомпозиция
|
||||
|
||||
**Было:** монолит `index/main.py` (~268 строк, char-based chunking)
|
||||
**Стало:** 5 модулей + тонкий main
|
||||
|
||||
| Модуль | Назначение |
|
||||
|---|---|
|
||||
| `index/schemas.py` | pydantic модели |
|
||||
| `index/cleaning.py` | локальная очистка, без внешних API |
|
||||
| `index/rendering.py` | три представления: page/dense/sparse |
|
||||
| `index/chunking.py` | message-based windowing + overlap |
|
||||
| `index/sparse.py` | sparse embedding |
|
||||
| `index/main.py` | только FastAPI wiring |
|
||||
|
||||
**Логические изменения:**
|
||||
- **Базовая единица чанка**: сообщение, не символ
|
||||
- **Окно**: ≤10 сообщений И ≤2048 символов И без time gap >1h
|
||||
- **Overlap**: последние 3 сообщения из предыдущего окна
|
||||
- **page_content**: читабельный текст с `sender: текст`
|
||||
- **dense_content**: timestamp + role markers + mentions + файлы
|
||||
- **sparse_content**: sender + mentions + filenames + url + текст
|
||||
|
||||
**Очистка (cleaning.py):**
|
||||
- удаление zero-width chars (`\u200b`, `\u200c`, `\u200d`, `\ufeff`)
|
||||
- mediaType-aware нормализация parts (text/quote/forward/unknown)
|
||||
- member_event → человекочитаемый текст
|
||||
- file_snippets → safe JSON parse + extract (name/mime/url/date)
|
||||
- сообщение пропускается только если пусты text+parts+member_event+file_snippets
|
||||
|
||||
## Файлы изменены
|
||||
|
||||
**Изменены:** `search/main.py`, `index/main.py`
|
||||
**Созданы:** `search/config.py`, `search/schemas.py`, `search/query_builder.py`, `search/retrieval.py`, `search/rerank.py`, `search/aggregation.py`, `search/__init__.py`, `index/schemas.py`, `index/cleaning.py`, `index/rendering.py`, `index/chunking.py`, `index/sparse.py`, `index/__init__.py`, `tests/` (5 test files)
|
||||
|
||||
## Проверка
|
||||
|
||||
- `python3 -m py_compile` — пройден на всех 13 новых/изменённых Python-файлах
|
||||
- `pytest tests/ -q` — 68 тестов, все прошли
|
||||
- API контракты не изменены: `POST /index`, `POST /sparse_embedding`, `POST /search`
|
||||
|
||||
## Что осталось
|
||||
|
||||
- metadata-aware boost/filter (participants, mentions, contains_quote, contains_forward, thread_sn)
|
||||
- тюнинг параметров DENSE_PREFETCH_K / RETRIEVE_K / RERANK_LIMIT под реальные запросы
|
||||
- regression test file с контрольными вопросами по Go Nova.json
|
||||
- docker-compose / Makefile / README alignment (`--platform linux/amd64`)
|
||||
- решение про `.ai_update/` в `.gitignore`
|
||||
269
doc/prompt.md
269
doc/prompt.md
|
|
@ -1,269 +0,0 @@
|
|||
# Prompt For Next Refactor Pass
|
||||
|
||||
Считай этот файл каноническим планом работ по репозиторию. Старые заметки в `doc/todo.md`, `doc/todo_and_pipeline.md`, `doc/todo_people.md` и `doc/ai_update.md` можно использовать как справку, но не как основной источник правды.
|
||||
|
||||
## Контекст
|
||||
|
||||
В репозитории два сервиса:
|
||||
|
||||
- `index` строит чанки для индексации
|
||||
- `search` получает вопрос и возвращает `message_ids`
|
||||
|
||||
Контракты `POST /index`, `POST /sparse_embedding` и `POST /search` менять нельзя.
|
||||
|
||||
Дополнительный контекст по текущему состоянию:
|
||||
|
||||
- worktree уже грязный, не откатывай чужие правки
|
||||
- `main` отстает от `origin/main` на 3 коммита
|
||||
- `.ai_update/` должен быть shared-state каталогом, но сейчас он игнорируется через `.gitignore`
|
||||
- реальная логика почти целиком живет в `index/main.py` и `search/main.py`, поэтому следующий шаг должен быть не только про качество поиска, но и про разбиение кода на понятные модули
|
||||
|
||||
## Что уже очевидно сломано или недоделано
|
||||
|
||||
### P0. Исправить критические дефекты в `search`
|
||||
|
||||
- В `search/main.py` есть реальный баг: `must_conditions: []` не создает список. При запросах с `date_range` или `asker` код упадет на `.append()`. Исправить первым коммитом.
|
||||
- Поиск использует только `question.text`, хотя схема уже содержит `search_text`, `variants`, `hyde`, `keywords`, `entities`, `date_mentions`, `date_range`.
|
||||
- После rerank теряется хвост retrieval-кандидатов.
|
||||
- Финальный список `message_ids` не дедуплицируется, не агрегируется по score и не ограничивается `top-50`, хотя метрика считается именно на `K=50`.
|
||||
- Внешние HTTP-вызовы dense/rerank не имеют нормальных `timeout` и `retry`.
|
||||
|
||||
### P1. Перестроить индексацию под структуру чата
|
||||
|
||||
- Сейчас `index` режет текст по символам, а не по сообщениям.
|
||||
- Overlap строится по хвосту строки, а не по границам сообщений.
|
||||
- `page_content`, `dense_content` и `sparse_content` сейчас одинаковые, хотя должны выполнять разные задачи.
|
||||
- В индекс почти не попадают важные сигналы: `sender_id`, `mentions`, `file_snippets`, `member_event`, `thread_sn`, маркеры `quote` и `forward`.
|
||||
|
||||
### P2. Начать использовать metadata осмысленно
|
||||
|
||||
- В README прямо указаны `participants`, `mentions`, `contains_forward`, `contains_quote`.
|
||||
- В `search/main.py` есть модель `ChunkMetadata`, но retrieval почти не использует metadata для фильтрации и буста.
|
||||
- Нужно поддержать фильтры/бусты по людям, mentions, thread, дате, quote/forward и не ломать контракт ответа.
|
||||
|
||||
### P3. Привести инфраструктуру и документацию в порядок
|
||||
|
||||
- `docker-compose.yml`, `README.md`, `Makefile` и `doc/upload_to_docker.md` частично расходятся по сценарию запуска и сборки.
|
||||
- В `Makefile` нет `--platform linux/amd64`, хотя в документации на загрузку образов это требуется.
|
||||
- В репозитории нет нормального `bin/codex-start`, хотя workflow на него ссылается.
|
||||
- Планирование размазано по нескольким файлам вместо одного документа.
|
||||
|
||||
## Что нужно сделать
|
||||
|
||||
### 1. Рефакторинг `search`
|
||||
|
||||
Сначала разбей `search/main.py` на несколько логических частей. Минимально:
|
||||
|
||||
- `search/config.py`: env, валидация конфигурации, auth-настройки
|
||||
- `search/schemas.py`: pydantic-модели запросов и ответов
|
||||
- `search/query_builder.py`: сборка dense/sparse запросов из `question`
|
||||
- `search/retrieval.py`: `Qdrant` prefetch, filters, fusion
|
||||
- `search/rerank.py`: вызов reranker и работа с rerank-кандидатами
|
||||
- `search/aggregation.py`: дедуп message ids, score aggregation, top-50
|
||||
- `search/main.py`: только wiring FastAPI и вызовы сервисных функций
|
||||
|
||||
Что должно измениться по логике:
|
||||
|
||||
- основной dense query: `question.search_text.strip()` с fallback на `question.text.strip()`
|
||||
- дополнительные dense query: `question.variants`, `question.hyde`
|
||||
- основной sparse query: `keywords`, а если их нет, то нормализованный базовый запрос
|
||||
- entity-сигналы: `people`, `emails`, `documents`, `names`, `links` использовать как lexical boost или metadata filter
|
||||
- `date_range` и, по возможности, `date_mentions` использовать для фильтрации по `metadata.start` / `metadata.end`
|
||||
- retrieval должен возвращать расширенный пул кандидатов
|
||||
- rerank должен сортировать top-N, но не уничтожать полностью хвост retrieval
|
||||
- финальный ответ должен:
|
||||
- агрегировать score по `message_id`
|
||||
- удалять дубликаты
|
||||
- ограничиваться `top-50`
|
||||
|
||||
Отдельно:
|
||||
|
||||
- убери импорт-тайм побочный эффект `validate_required_env()` и переведи его в более тестируемую точку старта
|
||||
- добавь явные `timeout` для `httpx.AsyncClient`
|
||||
- добавь retry-политику на ошибки сети и 5xx
|
||||
|
||||
### 2. Рефакторинг `index`
|
||||
|
||||
Разбей `index/main.py` хотя бы так:
|
||||
|
||||
- `index/schemas.py`: request/response модели
|
||||
- `index/rendering.py`: извлечение и разметка текста сообщения
|
||||
- `index/cleaning.py`: локальная очистка и нормализация raw message payload
|
||||
- `index/chunking.py`: сборка окон сообщений и overlap по сообщениям
|
||||
- `index/sparse.py`: локальная sparse-эмбеддинг логика
|
||||
- `index/main.py`: только FastAPI wiring
|
||||
|
||||
Что должно измениться по логике индексации:
|
||||
|
||||
- базовая единица чанка: сообщение, а не кусок строки
|
||||
- окно чанка должно учитывать:
|
||||
- число сообщений
|
||||
- суммарную длину
|
||||
- time gap между сообщениями
|
||||
- границы thread/forward/quote, если они явно ломают контекст
|
||||
- overlap должен повторять последние сообщения, а не последние символы
|
||||
- `render_message()` должен материализовать:
|
||||
- автора сообщения
|
||||
- mentions
|
||||
- quote / forward маркеры
|
||||
- `file_snippets`
|
||||
- `member_event`
|
||||
- при необходимости `thread_sn`
|
||||
|
||||
### 2.1. Локальная очистка сообщений по реальному формату `data/Go Nova.json`
|
||||
|
||||
Очистка должна происходить локально внутри `index`, без внешних API и без попытки делегировать нормализацию в dense/rerank сервисы.
|
||||
|
||||
Что показал реальный датасет:
|
||||
|
||||
- значимая часть сообщений имеет пустой верхнеуровневый `text`
|
||||
- смысл часто лежит в `parts[*].text`
|
||||
- в `parts[*]` используется поле `mediaType`, а не `type`
|
||||
- встречаются `mediaType = text`, `quote`, `forward`
|
||||
- есть `member_event` без обычного текста
|
||||
- `file_snippets` приходит JSON-строкой
|
||||
- в данных встречаются URL, email и zero-width символы
|
||||
|
||||
Минимальный pipeline очистки:
|
||||
|
||||
1. Извлечение raw сигналов:
|
||||
- `text`
|
||||
- `parts`
|
||||
- `mentions`
|
||||
- `member_event`
|
||||
- `file_snippets`
|
||||
- `sender_id`
|
||||
- флаги `is_system`, `is_forward`, `is_quote`
|
||||
|
||||
2. Unicode и whitespace normalization:
|
||||
- удалить `\u200b`, `\u200c`, `\u200d`, `\ufeff`
|
||||
- унифицировать переводы строк
|
||||
- схлопнуть лишние пробелы и пустые строки
|
||||
- не удалять email, URL, версии, имена файлов и технические токены
|
||||
|
||||
3. Нормализация `parts`:
|
||||
- `mediaType = text`: включать как основной контент
|
||||
- `mediaType = quote`: явно материализовать как `quote_from` + `quote_text`
|
||||
- `mediaType = forward`: явно материализовать как `forwarded_from` + `forward_text`
|
||||
- неизвестные типы не выбрасывать, а сохранять как маркированные текстовые блоки
|
||||
|
||||
4. Нормализация системных событий:
|
||||
- `member_event` превращать в индексируемый текст
|
||||
- минимум поддержать `addMembers`
|
||||
- для неизвестных event type сохранять тип и payload в безопасной текстовой форме
|
||||
|
||||
5. Нормализация файлов:
|
||||
- распарсить `file_snippets` локально из JSON-строки
|
||||
- вытащить `name`, `mime`, `original_url`, `date_create`
|
||||
- при невалидном JSON не падать, а сохранять `attachment_raw`
|
||||
|
||||
6. Правило пропуска:
|
||||
- выбрасывать сообщение только если после очистки пусты и `text`, и `parts`, и `member_event`, и `file_snippets`
|
||||
|
||||
Развести три представления текста:
|
||||
|
||||
- `page_content`: читаемый текст чанка для payload
|
||||
- `dense_content`: нормализованный текст с role-маркерами, авторами и служебным контекстом
|
||||
- `sparse_content`: keyword-heavy текст, куда попадают имена людей, mentions, email, документы, файлы, ссылки, важные термины
|
||||
|
||||
При этом:
|
||||
|
||||
- не меняй внешний контракт `POST /index`
|
||||
- сохрани понятную привязку `message_ids` к каждому чанку
|
||||
- делай chunking объяснимым, а не магическим
|
||||
|
||||
### 3. Улучшить metadata-aware retrieval
|
||||
|
||||
После стабилизации `search` и `index`:
|
||||
|
||||
- добавь boost/filter по `participants`
|
||||
- добавь boost/filter по `mentions`
|
||||
- используй `contains_quote` и `contains_forward` как вторичные сигналы ранжирования
|
||||
- если в payload есть `thread_sn`, учитывай его для вопросов про конкретную ветку обсуждения
|
||||
- подбери новые значения для `DENSE_PREFETCH_K`, `SPRASE_PREFETCH_K`, `RETRIEVE_K`, `RERANK_LIMIT`
|
||||
|
||||
Если multi-query fusion в `Qdrant` начинает заметно улучшать recall, оставляй его. Если только усложняет код без эффекта, не тащи лишнюю сложность.
|
||||
|
||||
### 4. Навести порядок в repo hygiene
|
||||
|
||||
- перестань держать `.ai_update/` в `.gitignore`, если workflow действительно предполагает коммит этого каталога
|
||||
- либо добавь реальный `bin/codex-start`, либо убери ссылки на него из документации
|
||||
- приведи `docker-compose.yml` к тому же сценарию env, что и `README.md`
|
||||
- добавь `--platform linux/amd64` в команды сборки из `Makefile`
|
||||
- оставь `doc/prompt.md` основным планом, а дублирующие `todo`-файлы сократи или архивируй
|
||||
|
||||
### 5. Логирование каждого изменения и отчетность
|
||||
|
||||
Во время следующей реализации нельзя ограничиваться только кодом. После каждого meaningful change нужно фиксировать, что именно сделано и что сохранено.
|
||||
|
||||
Обязательные действия:
|
||||
|
||||
- после каждого существенного изменения обновлять `.ai_update/changelog.md`
|
||||
- поддерживать `.ai_update/touched_files.md`
|
||||
- обновлять `.ai_update/current_status.md` и `.ai_update/handoff.md` к концу сессии
|
||||
- вести [doc/output.md](/home/q/doc/hackaton/doc/output.md) как человекочитаемый отчет по ходу работ
|
||||
|
||||
Что писать в `doc/output.md` после каждой существенной правки:
|
||||
|
||||
- дата/время
|
||||
- что изменено
|
||||
- какие файлы изменены
|
||||
- зачем это сделано
|
||||
- как это проверено
|
||||
- что осталось недоделанным или рискованным
|
||||
|
||||
## Какие тесты и проверки нужны
|
||||
|
||||
Создай минимальный тестовый контур. Без этого рефакторинг превратится в угадывание.
|
||||
|
||||
### Unit tests
|
||||
|
||||
- `index/cleaning.py`: unicode/whitespace cleanup, `mediaType`, `member_event`, `file_snippets`
|
||||
- `index/rendering.py`: сообщение с `parts`, `quote`, `forward`, `mentions`, `file_snippets`, `member_event`
|
||||
- `index/chunking.py`: chunking по сообщениям, time gap, overlap по сообщениям
|
||||
- `search/query_builder.py`: `search_text`, fallback на `text`, `variants`, `hyde`, `keywords`, entities, date range
|
||||
- `search/aggregation.py`: dedup, score aggregation, `top-50`
|
||||
|
||||
### Smoke checks
|
||||
|
||||
- `python3 -m py_compile index/main.py search/main.py`
|
||||
- `docker compose config`
|
||||
- локальный запуск через `docker compose up --build`, если заполнен `.env`
|
||||
- ручной smoke `curl` на `/health`, `/index`, `/search`
|
||||
|
||||
### Regression set
|
||||
|
||||
Зафиксируй отдельный markdown-файл с контрольными вопросами. Включи хотя бы такие классы запросов:
|
||||
|
||||
- кто что писал
|
||||
- кого упоминали
|
||||
- что писали про документ, файл или ссылку
|
||||
- что обсуждали в конкретный период
|
||||
- что было в пересланных сообщениях и цитатах
|
||||
- что было в системных событиях и прикреплениях
|
||||
|
||||
Используй `data/Go Nova.json` как локальную fixture-основу.
|
||||
|
||||
## Порядок внедрения
|
||||
|
||||
1. Сначала внедрить и протестировать локальную очистку сообщений в `index/cleaning.py` на кейсах из `data/Go Nova.json`.
|
||||
2. Переделать `index` на message-based chunking и разные `page_content` / `dense_content` / `sparse_content`.
|
||||
3. После стабилизации входного текста починить P0 баги в `search` и добавить тесты на query builder и aggregation.
|
||||
4. Вынести `search` из монолита `main.py` в модули без изменения API.
|
||||
5. Подключить metadata-aware retrieval и тюнинг параметров.
|
||||
6. Синхронизировать docker/docs/workflow и убрать repo hygiene противоречия.
|
||||
|
||||
## Критерий готовности
|
||||
|
||||
Можно считать работу завершенной только если одновременно выполнено все ниже:
|
||||
|
||||
- `search` использует не только `question.text`
|
||||
- поиск не падает на `date_range` и `asker`
|
||||
- retrieval + rerank не теряют кандидатов бессмысленно
|
||||
- финальная выдача дедуплицирована и ограничена `top-50`
|
||||
- `index` режет по сообщениям, а не по символам как основной механизм
|
||||
- локальная очистка сообщений работает без внешних API и покрывает `parts`, `member_event`, `file_snippets`, URL и zero-width артефакты
|
||||
- `page_content`, `dense_content`, `sparse_content` различаются по назначению
|
||||
- в индекс и retrieval реально включены metadata и скрытые сигналы чата
|
||||
- локальная документация, compose и сборка образов не противоречат друг другу
|
||||
- история изменений и отчет в `doc/output.md` обновляются по ходу работы, а не только в конце
|
||||
49
doc/todo.md
49
doc/todo.md
|
|
@ -1,49 +0,0 @@
|
|||
# TODO
|
||||
|
||||
## `search/main.py`
|
||||
|
||||
- [ ] P0: Переключить основной query на `question.search_text` с fallback на `question.text`
|
||||
- [ ] P0: Подключить `question.variants` как дополнительные query-варианты
|
||||
- [ ] P0: Подключить `question.hyde` как дополнительные dense-запросы
|
||||
- [ ] P0: Подключить `question.keywords` как основу для sparse-запросов
|
||||
- [ ] P0: Перестать терять retrieval-кандидатов после rerank
|
||||
- [ ] P0: Дедуплицировать `message_ids` перед ответом
|
||||
- [ ] P0: Ограничить финальную выдачу до `top-50`
|
||||
- [ ] P0: Агрегировать score по `message_id`
|
||||
- [ ] P2: Использовать `entities.people` и `entities.emails` для boost или фильтрации
|
||||
- [ ] P2: Использовать `entities.documents`, `entities.names`, `entities.links` для lexical boost
|
||||
- [ ] P2: Использовать `date_range` для фильтрации по `metadata.start` и `metadata.end`
|
||||
- [ ] P2: Использовать `contains_quote` и `contains_forward` как сигналы ранжирования
|
||||
- [ ] P2: Добавить multi-query fusion в `Qdrant`
|
||||
- [ ] P2: Подобрать `prefetch`, `retrieve_k`, `rerank_limit`
|
||||
- [ ] P3: Добавить retry и timeout политику для dense/rerank HTTP вызовов
|
||||
|
||||
## `index/main.py`
|
||||
|
||||
- [ ] P1: Перейти с символьного chunking на chunking по сообщениям
|
||||
- [ ] P1: Учитывать time gap при сборке чанков
|
||||
- [ ] P1: Маркировать в тексте `quote`, `forward`, автора сообщения и автора цитаты
|
||||
- [ ] P1: Развести `page_content`, `dense_content`, `sparse_content`
|
||||
- [ ] P1: Материализовать `sender_id` и `mentions` в индексируемый текст
|
||||
- [ ] P1: Разбирать `file_snippets` и вытаскивать имя файла, mime и url
|
||||
- [ ] P1: Разбирать `member_event` и превращать его в индексируемый текст
|
||||
|
||||
## `docker-compose.yml`
|
||||
|
||||
- [ ] P3: Привести локальный `docker-compose.yml` к схеме с `API_KEY`
|
||||
- [ ] P3: Добавить `--platform linux/amd64` в сборку образов
|
||||
|
||||
## `doc/` (новый файл с регрессионными вопросами)
|
||||
|
||||
- [ ] P3: Зафиксировать набор локальных тестовых вопросов для проверки регрессий
|
||||
|
||||
## `search/requirements.txt`
|
||||
|
||||
- [ ] P4: Добавить `python-dateutil` или `dateparser`
|
||||
- [ ] P4: Добавить `tenacity`
|
||||
|
||||
## `index/requirements.txt` и/или `search/requirements.txt`
|
||||
|
||||
- [ ] P4: Добавить `razdel`
|
||||
- [ ] P4: Добавить `pymorphy3`
|
||||
- [ ] P4: Добавить `rapidfuzz`
|
||||
|
|
@ -1,223 +0,0 @@
|
|||
# To-Do и целевой pipeline
|
||||
|
||||
Дата: 2026-04-18
|
||||
|
||||
## Цель
|
||||
|
||||
Поднять `Recall@50` и `nDCG@50` без смены стэка:
|
||||
|
||||
- оставить `Qdrant`
|
||||
- оставить внешний dense endpoint
|
||||
- оставить внешний reranker
|
||||
- усиливать только индекс, retrieval, rerank и post-processing
|
||||
|
||||
## Приоритетный to-do
|
||||
|
||||
### P0. Быстрые и самые окупаемые правки
|
||||
|
||||
- [ ] Переключить основной запрос в `search` на `question.search_text` с fallback на `question.text`
|
||||
- [ ] Подключить `question.variants` как дополнительные query-формулировки
|
||||
- [ ] Подключить `question.hyde` как дополнительные dense-запросы
|
||||
- [ ] Подключить `question.keywords` как основу для sparse-запроса
|
||||
- [ ] Перестать терять кандидатов после rerank: возвращать не только top-10 rerank, но и хвост retrieval
|
||||
- [ ] Дедуплицировать `message_ids` перед ответом
|
||||
- [ ] Ограничить финальную выдачу осмысленным `top-50`
|
||||
- [ ] Агрегировать score по `message_id`, а не просто конкатенировать ids из чанков
|
||||
|
||||
### P1. Улучшение индексации
|
||||
|
||||
- [ ] Перейти с символьного chunking на chunking по сообщениям
|
||||
- [ ] Учитывать временные разрывы между сообщениями при сборке чанка
|
||||
- [ ] Не смешивать в одном чанке слишком далекие по смыслу блоки
|
||||
- [ ] Отдельно маркировать `quote`, `forward`, автора сообщения и автора цитаты
|
||||
- [ ] Развести `page_content`, `dense_content`, `sparse_content`
|
||||
- [ ] Материализовать `mentions` в текст и metadata
|
||||
- [ ] Материализовать `sender_id` в индексируемый текст
|
||||
- [ ] Разбирать `file_snippets` и вытаскивать имя файла, mime, url
|
||||
- [ ] Разбирать `member_event` и превращать его в индексируемый текст
|
||||
|
||||
### P2. Улучшение retrieval и фильтрации
|
||||
|
||||
- [ ] Использовать `entities.people` и `entities.emails` для boost или фильтрации по `participants` и `mentions`
|
||||
- [ ] Использовать `entities.documents`, `entities.names`, `entities.links` для lexical boost
|
||||
- [ ] Использовать `date_range` для фильтрации по `metadata.start` и `metadata.end`
|
||||
- [ ] Использовать `contains_quote` и `contains_forward` как дополнительные сигналы ранжирования
|
||||
- [ ] Добавить multi-query fusion в `Qdrant` для dense и sparse запросов
|
||||
- [ ] Подобрать новые значения `prefetch`, `retrieve_k`, `rerank_limit`
|
||||
|
||||
### P3. Инфраструктура и надежность
|
||||
|
||||
- [ ] Привести локальный `docker-compose.yml` к схеме с `API_KEY`, чтобы локальный запуск был ближе к ТЗ
|
||||
- [ ] Добавить `--platform linux/amd64` в сборку образов
|
||||
- [ ] Добавить retry и timeout политику для dense/rerank HTTP вызовов
|
||||
- [ ] Зафиксировать набор локальных тестовых запросов для регрессии качества
|
||||
|
||||
### P4. Библиотеки, которые можно добавить без смены стэка
|
||||
|
||||
- [ ] `razdel` для токенизации русского текста
|
||||
- [ ] `pymorphy3` для лемматизации при подготовке `sparse_content`
|
||||
- [ ] `rapidfuzz` для точного match по именам, email, документам и ссылкам
|
||||
- [ ] `python-dateutil` или `dateparser` для нормализации дат
|
||||
- [ ] `tenacity` для retry вокруг внешних HTTP запросов
|
||||
|
||||
## Целевой pipeline индексации
|
||||
|
||||
### 1. Подготовка сообщения
|
||||
|
||||
На входе каждое сообщение должно раскладываться на сигналы:
|
||||
|
||||
- основной текст сообщения
|
||||
- `parts[*].text`
|
||||
- тип части: `text`, `quote`, `forward`
|
||||
- `sender_id`
|
||||
- `mentions`
|
||||
- `file_snippets`
|
||||
- `member_event`
|
||||
- `thread_sn`
|
||||
- флаги `is_system`, `is_quote`, `is_forward`
|
||||
|
||||
### 2. Нормализация и разметка
|
||||
|
||||
Перед chunking сообщение стоит приводить к структурированному виду, например:
|
||||
|
||||
- `author: ...`
|
||||
- `mentions: ...`
|
||||
- `quote: ...`
|
||||
- `forwarded: ...`
|
||||
- `file: ...`
|
||||
- `system_event: ...`
|
||||
|
||||
Смысл не в красивом выводе, а в том, чтобы dense и sparse видели роль каждого куска текста.
|
||||
|
||||
### 3. Chunking
|
||||
|
||||
Целевой принцип:
|
||||
|
||||
- базовая единица не символ, а сообщение
|
||||
- чанк собирается как окно из нескольких соседних сообщений
|
||||
- окно режется по лимиту размера
|
||||
- окно закрывается на большом time gap
|
||||
- `forward` и длинные `quote` не должны ломать соседний контекст
|
||||
- overlap должен работать по границам сообщений, а не по хвосту строки
|
||||
|
||||
### 4. Формирование трех видов текста
|
||||
|
||||
`page_content`:
|
||||
|
||||
- человекочитаемый текст чанка для payload
|
||||
|
||||
`dense_content`:
|
||||
|
||||
- нормализованный текст с автором, role-маркерами, quote/forward маркерами
|
||||
|
||||
`sparse_content`:
|
||||
|
||||
- keyword-heavy текст
|
||||
- леммы
|
||||
- email
|
||||
- mentions
|
||||
- имена файлов
|
||||
- ссылки
|
||||
- названия документов и сервисов
|
||||
|
||||
### 5. Metadata для Qdrant
|
||||
|
||||
В metadata стоит стабильно сохранять:
|
||||
|
||||
- `message_ids`
|
||||
- `participants`
|
||||
- `mentions`
|
||||
- `thread_sn`
|
||||
- `start`
|
||||
- `end`
|
||||
- `contains_quote`
|
||||
- `contains_forward`
|
||||
- `chat_id`
|
||||
- `chat_type`
|
||||
|
||||
## Целевой pipeline поиска
|
||||
|
||||
### 1. Подготовка query
|
||||
|
||||
Собирать query не из одного поля, а из набора:
|
||||
|
||||
- основной запрос: `search_text` или `text`
|
||||
- дополнительные dense-query: `variants` и `hyde`
|
||||
- дополнительные sparse-query: `keywords`
|
||||
- entity-сигналы: `people`, `emails`, `documents`, `names`, `links`
|
||||
- time constraints: `date_range`, `date_mentions`
|
||||
|
||||
### 2. Query builder
|
||||
|
||||
Нужно строить несколько представлений запроса:
|
||||
|
||||
- dense-query для смысла
|
||||
- sparse-query для точных слов и терминов
|
||||
- filter/boost по metadata
|
||||
|
||||
### 3. Retrieval в Qdrant
|
||||
|
||||
Практическая схема:
|
||||
|
||||
1. Выполнить несколько dense prefetch по разным вариантам запроса
|
||||
2. Выполнить несколько sparse prefetch по keyword-heavy запросам
|
||||
3. Добавить filters по датам, mentions, participants, если это явно следует из вопроса
|
||||
4. Объединить результаты через fusion
|
||||
5. Забрать расширенный пул кандидатов для rerank
|
||||
|
||||
### 4. Rerank
|
||||
|
||||
Rerank должен работать не на слишком маленьком пуле. Целевой принцип:
|
||||
|
||||
- retrieval дает расширенный пул
|
||||
- rerank сортирует top-N кандидатов
|
||||
- хвост retrieval не теряется полностью
|
||||
|
||||
### 5. Агрегация к `message_id`
|
||||
|
||||
После rerank:
|
||||
|
||||
- собрать `message_ids` из чанков
|
||||
- удалить дубликаты
|
||||
- агрегировать лучший score на сообщение
|
||||
- собрать финальный `top-50`
|
||||
|
||||
Это особенно важно, потому что метрики в ТЗ считаются именно по `message_id`, а не по chunk id.
|
||||
|
||||
## Порядок внедрения
|
||||
|
||||
### Этап 1. Quick wins
|
||||
|
||||
- использовать `search_text`, `variants`, `hyde`, `keywords`
|
||||
- перестать терять кандидатов после rerank
|
||||
- добавить dedup и top-50
|
||||
|
||||
### Этап 2. Пересборка индекса
|
||||
|
||||
- новый renderer сообщения
|
||||
- новый chunking по сообщениям
|
||||
- разные `page_content`, `dense_content`, `sparse_content`
|
||||
|
||||
### Этап 3. Metadata-aware retrieval
|
||||
|
||||
- filters по дате
|
||||
- boost по mentions/participants
|
||||
- учет `contains_quote` и `contains_forward`
|
||||
|
||||
### Этап 4. Тюнинг
|
||||
|
||||
- подобрать размеры чанков
|
||||
- подобрать `retrieve_k`
|
||||
- подобрать `rerank_limit`
|
||||
- прогнать локальный набор контрольных вопросов
|
||||
|
||||
## Минимальный критерий готовности
|
||||
|
||||
Можно считать, что pipeline собран в рабочем виде, если:
|
||||
|
||||
- `search` использует не только `question.text`
|
||||
- индексация не режет чанки посреди сообщения как основной механизм
|
||||
- `message_ids` дедуплицируются
|
||||
- финальная выдача ограничивается top-50
|
||||
- retrieval умеет использовать хотя бы часть metadata
|
||||
- локальная сборка и запуск не расходятся с ТЗ по критичным env и platform
|
||||
|
|
@ -1,64 +0,0 @@
|
|||
Для того чтобы раскидать задачи между тремя людьми, я распределю их по сложности и приоритету.
|
||||
|
||||
### Человек 1 (Основной фокус на поиске):
|
||||
|
||||
#### `search/main.py`
|
||||
|
||||
* **P0**: Переключить основной query на `question.search_text` с fallback на `question.text`
|
||||
* **P0**: Подключить `question.variants` как дополнительные query-варианты
|
||||
* **P0**: Подключить `question.hyde` как дополнительные dense-запросы
|
||||
* **P0**: Подключить `question.keywords` как основу для sparse-запросов
|
||||
* **P0**: Перестать терять retrieval-кандидатов после rerank
|
||||
* **P0**: Дедуплицировать `message_ids` перед ответом
|
||||
* **P0**: Ограничить финальную выдачу до `top-50`
|
||||
* **P0**: Агрегировать score по `message_id`
|
||||
* **P2**: Использовать `entities.people` и `entities.emails` для boost или фильтрации
|
||||
* **P2**: Использовать `entities.documents`, `entities.names`, `entities.links` для lexical boost
|
||||
* **P2**: Использовать `date_range` для фильтрации по `metadata.start` и `metadata.end`
|
||||
* **P2**: Использовать `contains_quote` и `contains_forward` как сигналы ранжирования
|
||||
* **P2**: Добавить multi-query fusion в `Qdrant`
|
||||
* **P2**: Подобрать `prefetch`, `retrieve_k`, `rerank_limit`
|
||||
* **P3**: Добавить retry и timeout политику для dense/rerank HTTP вызовов
|
||||
|
||||
---
|
||||
|
||||
### Человек 2 (Основной фокус на индексации и разметке):
|
||||
|
||||
#### `index/main.py`
|
||||
|
||||
* **P1**: Перейти с символьного chunking на chunking по сообщениям
|
||||
* **P1**: Учитывать time gap при сборке чанков
|
||||
* **P1**: Маркировать в тексте `quote`, `forward`, автора сообщения и автора цитаты
|
||||
* **P1**: Развести `page_content`, `dense_content`, `sparse_content`
|
||||
* **P1**: Материализовать `sender_id` и `mentions` в индексируемый текст
|
||||
* **P1**: Разбирать `file_snippets` и вытаскивать имя файла, mime и url
|
||||
* **P1**: Разбирать `member_event` и превращать его в индексируемый текст
|
||||
|
||||
#### `index/requirements.txt` и/или `search/requirements.txt`
|
||||
|
||||
* **P4**: Добавить `razdel`
|
||||
* **P4**: Добавить `pymorphy3`
|
||||
* **P4**: Добавить `rapidfuzz`
|
||||
|
||||
---
|
||||
|
||||
### Человек 3 (Основной фокус на Docker и зависимостях):
|
||||
|
||||
#### `docker-compose.yml`
|
||||
|
||||
* **P3**: Привести локальный `docker-compose.yml` к схеме с `API_KEY`
|
||||
* **P3**: Добавить `--platform linux/amd64` в сборку образов
|
||||
|
||||
#### `doc/` (новый файл с регрессионными вопросами)
|
||||
|
||||
* **P3**: Зафиксировать набор локальных тестовых вопросов для проверки регрессий
|
||||
|
||||
#### `search/requirements.txt`
|
||||
|
||||
* **P4**: Добавить `python-dateutil` или `dateparser`
|
||||
* **P4**: Добавить `tenacity`
|
||||
|
||||
---
|
||||
|
||||
Таким образом, задачи равномерно распределены по 3 участникам с учётом сложности и области фокуса.
|
||||
|
||||
|
|
@ -1,56 +0,0 @@
|
|||
Шаг 2. Настройка Docker
|
||||
|
||||
Registry для хранения образов будет доступен по адресу 83.166.249.64:5000. Поскольку он работает без TLS, необходимо добавить его в список insecure registries в настройках Docker.
|
||||
Docker Desktop (macOS / Windows)
|
||||
|
||||
Откройте Docker Desktop -> Settings -> Docker Engine.
|
||||
Добавьте в JSON-конфиг поле insecure-registries:
|
||||
|
||||
{
|
||||
"insecure-registries": ["83.166.249.64:5000"]
|
||||
}
|
||||
|
||||
Нажмите Apply & Restart.
|
||||
|
||||
CLI — Linux
|
||||
|
||||
Откройте файл с конфигурацией докер демона в режиме редактирования
|
||||
|
||||
sudo nano /etc/docker/daemon.json
|
||||
|
||||
Добавьте в JSON-конфиг поле insecure-registries:
|
||||
|
||||
{
|
||||
"insecure-registries": ["83.166.249.64:5000"]
|
||||
}
|
||||
|
||||
Перезапустите docker
|
||||
|
||||
sudo systemctl restart docker
|
||||
|
||||
Шаг 3. Логин в registry
|
||||
|
||||
Необходимо пройти аутентификацию в docker registry, используя логин и пароль, полученные на шаге 1.
|
||||
|
||||
docker login 83.166.249.64:5000 -u <login> -p <password>
|
||||
|
||||
Ожидаемый вывод: Login Succeeded.
|
||||
Шаг 4. Сборка образов
|
||||
|
||||
Соберите образы своих Index Service и Search Service. Образы должны иметь тег, который имеет строгий формат:
|
||||
|
||||
Для Index Service - 83.166.249.64:5000/35230/index-service:latest
|
||||
Для Search Service - 83.166.249.64:5000/35230/search-service:latest
|
||||
|
||||
Образы должны быть собраны под платформу linux/amd64
|
||||
|
||||
docker build --platform linux/amd64 -t 83.166.249.64:5000/35230/index-service:latest {path_to_index_service_dir}
|
||||
docker build --platform linux/amd64 -t 83.166.249.64:5000/35230/search-service:latest {path_to_search_service_dir}
|
||||
|
||||
Шаг 5. Публикация образов в registry
|
||||
|
||||
docker push 83.166.249.64:5000/35230/index-service:latest
|
||||
docker push 83.166.249.64:5000/35230/search-service:latest
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
team_id: 35230
|
||||
vk login: 56aa86799bb9edc4
|
||||
vk password: edd89cea9ed0734d00ba6904cf7475d7
|
||||
Loading…
Reference in a new issue