feat(search) Фаза B: семантический слой — TEI e5-small сайдкар + гибрид вектор+RRF (best-effort) #530
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: vvzvlad/gitmost#530
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Фаза B мета-ишью #527. Blocked by фазой A (ru_en, единый пайплайн, RRF-примитив,
page_embeddings.ftsна ru_en). ТолькоSEARCH_DRIVER=database.Проблема / Цель
Лексика (даже починенная в A) не ловит концептуальные запросы («3D принтер» ↔ «модели для печати»). Поднять существующий RAG-примитив (
hybridSearchRRF) до пользовательского поиска: добавить вектор-ветку в RRF из A, best-effort (нет эмбеддингов/TEI → чистая лексика, поиск всегда работает). Эмбеддинги — локальные: сайдкар HF TEI + multilingual-e5-small.Контекст и исследование
page_embeddings(pgvector, chunk-level, dimension-agnostic → seq scan) +hybridSearch()RRF k=60 (page-embedding.repo.ts) — chunk-level, для RAG.embedding-indexer.service.ts(async, событийный, per-workspace провайдер;deleteByPageмодель-слепой :70;reindexWorkspaceпоследовательный;getEmbeddablePageIds— предикат embeddable-страниц).embedTextsai.service.ts:350 — провайдер-агностичный, таймаутAI_EMBEDDING_TIMEOUT_MSдефолт 120000мс (батчевый).modelNameper-row = грубый ключ (typeof model==='string'?model:model.modelId??'unknown'). Документы сейчас эмбедятся без e5-префикса. Серверной метрик-инфраструктуры НЕТ (только клиентский web-vitalstelemetry/*).Дизайн
B1. TEI-сайдкар (глобальный дефолт-провайдер эмбеддингов)
docker-compose.yml: сервисembeddings=ghcr.io/huggingface/text-embeddings-inference:cpu-1.9,--model-id intfloat/multilingual-e5-small --revision <sha>, volumetei-models:/data(модель НЕ в образе), healthcheck, OpenAI-совм./v1/embeddings..env.example: глобальный embedding-провайдер (endpointhttp://embeddings:80/v1) + prefix-схема (EMBEDDING_QUERY_PREFIX="query: ",EMBEDDING_DOC_PREFIX="passage: "для e5; пусто для не-e5). Prefix-схема — свойство провайдера, не per-workspace-креды (вai_provider_credentialsполя под префикс нет).B2. Эмбеддинг запроса (интерактивный)
embedQuery(text)кладёт query-префикс из конфига провайдера; отдельный интерактивный таймаутSEARCH_EMBED_TIMEOUT_MS(env, дефолт 800мс, свой AbortSignal) — НЕ наследовать батчевый 120с. Ошибка/таймаут → degrade к лексике (см. B5).B3. Гибрид page-level (расширяет RRF из A)
Новый
hybridSearchPages: тот же парсер A2 + конфиг ru_en в лексической ветке (НЕwebsearch_to_tsquery('english')); вектор-ветка — cosine<=>поpage_embeddings, агрегация chunk→page (лучший chunk), фильтр по активному фингерпринту (B4). Обе ветки → RRF-примитив из A (третья ветка). Пермишены/CAP/пагинация/total/superset/snippet — как в A (over-fetch по CANDIDATE_CAP → SQL-anti-join условно по hasRestricted → срез). Snippet page-level: приоритет — окно вокруг лексического совпадения; для вектор-only хита — ведущее окно текста/лучший chunk.B4. Жизненный цикл семантики
Ключ версии = фингерпринт
{modelId + revision + prefixScheme + dimensions}(не голоеmodelName— иначе смена revision/включение префикса не детектится: та же e5/384). Активный фингерпринт — в настройках воркспейса. Вектор-CTE и подсчёт покрытия фильтруют по нему.Знаменатель покрытия = страницы, реально давшие ≥1 chunk (не сырой
getEmbeddablePageIds, иначе вечный stale);fullставится по завершению прогона реиндекса, count — грубый индикатор. Ответ:semantic:{state, available, reason?, indexed?, total?}.Реиндекс при смене фингерпринта (не-деструктивно):
deleteByPageво время свапа — model/fp-scoped (WHERE ...по fp), иначе правка страницы удалит все её строки и выкинет из семантики до конца окна.B5. Отказы и наблюдаемость
TEI/эмбеддинг падает → fail-OPEN к лексике, но видимо: структурный лог с фиксированным кодом события (
search.semantic.degraded) + healthcheck TEI + флагsemantic.available=falseв ответе. Метрик-стока в проекте нет — не обещаем метрику; наблюдаемость = лог+healthcheck+флаг (MVP). try/catch деградации оборачивает только embedQuery/вектор-ветку; исключениеfilterAccessiblePageIdsпробрасывается → 500 (fail-closed).Границы scope
Только database-драйвер. НЕ входит: ANN/HNSW (seq scan), реранкер, GPU-профиль (тот же образ, смена тега — отдельно).
Критерии приёмки (стенд)
semantic.available=false; в логе событие деградации.semantic.reason=no-provider, не 500.--revision/включение префикса →semantic.state=stale, вектор сервится по старому fp до завершения реиндекса, после — по новому; same-dim свап не даёт мусорную выдачу./search; метод — curl-серия на стенде).Отказы и наблюдаемость
См. B5. Реиндекс: аборт батча (
isFatalProviderError) не флипает указатель, GC на старте чистит частичные генерации.Совместимость и миграции
Новый сайдкар — rollback = убрать сервис (best-effort → лексика). Реиндекс page_embeddings при первом включении префикса/смене модели — через (пропатченный) индексатор, fp-driven.
Решённые развилки
seq scan (человек); e5-small + TEI-сайдкар (человек); best-effort+fallback (человек); фингерпринт вместо modelName (дизайн, hostile-A/N2); лёгкий не-деструктивный реиндекс + атомарный флип вместо теневых таблиц (дизайн, контр-предложение); fp-scoped deleteByPage (hostile-D); отдельный интерактивный таймаут (ops-5); наблюдаемость = лог+healthcheck+флаг, метрик-стока нет (ops-4); prefix — свойство глобального провайдера (impl-F4).
Связи
Мета #527. Blocked by фаза A. Переиспользует
page-embedding.repo(RRF),embedding-indexer.