docs: remove outdated backlog and RAG plan docs
This commit is contained in:
claude_code
@@ -1,121 +0,0 @@
|
||||
# /pages/import отдаёт 400 «Error processing file content» (регресс)
|
||||
|
||||
Статус: **диагностируемость починена** (fix #1 применён); корневая причина **не
|
||||
подтверждена** — на текущем коде локально баг воспроизвести не удалось.
|
||||
Ниже — что удалось выяснить, главный подозреваемый и что проверить дальше.
|
||||
|
||||
## Симптом
|
||||
|
||||
На задеплоенном инстансе эндпоинт `POST /pages/import` отдаёт
|
||||
`400 BadRequest` с телом «Error processing file content». Раньше работал —
|
||||
похоже на регресс после редеплоя гитмоста.
|
||||
|
||||
Через этот эндпоинт грузит контент MCP-инструмент `create_page` (это
|
||||
единственный эндпоинт, принимающий контент при создании страницы —
|
||||
см. комментарий в `packages/mcp/src/client.ts:961`).
|
||||
|
||||
Что при этом **исправно** (важно для локализации):
|
||||
- `POST /pages/create` — создание пустой страницы.
|
||||
- `update_page_json` — запись контента через realtime-коллаборацию (Yjs).
|
||||
|
||||
## Где именно бросается ошибка
|
||||
|
||||
`apps/server/src/integrations/import/services/import.service.ts:93-97` —
|
||||
`try/catch` вокруг обработки контента:
|
||||
|
||||
```ts
|
||||
} catch (err) {
|
||||
const message = 'Error processing file content';
|
||||
this.logger.error(message, err); // реальная причина логируется ТОЛЬКО в логи
|
||||
throw new BadRequestException(message); // наружу уходит generic-строка
|
||||
}
|
||||
```
|
||||
|
||||
Реальный текст ошибки/стек **проглатывается** (наружу — generic-строка), что
|
||||
нарушает конвенцию проекта (см. CLAUDE.md, «Errors must never be swallowed»).
|
||||
Поэтому по ответу 400 причину не видно — её надо читать в логах сервера
|
||||
(`logger.error(message, err)` пишет полный err) ИЛИ воспроизвести локально.
|
||||
|
||||
## Цепочка обработки для .md (что внутри try)
|
||||
|
||||
`importPage` → `processMarkdown(fileContent)`:
|
||||
1. `markdownToHtml` (`packages/editor-ext/.../marked.utils.ts`) — marked, чистый JS, без DOM.
|
||||
2. `processHTML`: cheerio `load` → `normalizeImportHtml` (`utils/import-formatter.ts`) — чистый JS.
|
||||
3. `htmlToJson` (`apps/server/src/collaboration/collaboration.util.ts:118`) →
|
||||
`generateJSON(html, tiptapExtensions)`.
|
||||
|
||||
## Ключевая зацепка: путь импорта зависит от happy-dom, рабочие пути — нет
|
||||
|
||||
`generateJSON` (`apps/server/src/common/helpers/prosemirror/html/generateJSON.ts`)
|
||||
парсит HTML через **happy-dom**: `new Window()` + `new localWindow.DOMParser()` +
|
||||
`parseFromString(...)`, затем `PMDOMParser.fromSchema(schema).parse(doc.body)`.
|
||||
|
||||
А исправные пути DOM-парсер НЕ используют:
|
||||
- `/pages/create` — пустая страница, контент не парсится.
|
||||
- `update_page_json` — пишет готовый ProseMirror-JSON в Yjs
|
||||
(`TiptapTransformer.toYdoc`), без HTML→DOM.
|
||||
|
||||
То есть единственное, что есть в сломанном пути и отсутствует в рабочих, —
|
||||
**серверный парсинг HTML через happy-dom**.
|
||||
|
||||
## Главный подозреваемый: бамп happy-dom (14 → 20)
|
||||
|
||||
- Изначально было `"happy-dom": "^14.12.3"`.
|
||||
- Сейчас запинено `"happy-dom": "20.8.9"` в `apps/server/package.json:83`
|
||||
(+ override в корневом `package.json`).
|
||||
- Пин на `20.8.9` пришёл в коммите `17da7629 "overrides"`
|
||||
(Philipinho, 2026-03-28), где `20.8.4` → `20.8.9`.
|
||||
- Скачок 14 → 20 — это 6 мажоров; у happy-dom между мажорами ломающие
|
||||
изменения в API `Window`/`DOMParser` и в поведении парсинга HTML. Очень
|
||||
вероятно, что `generateJSON` ломается на новом happy-dom.
|
||||
|
||||
Версия в node_modules подтверждена: `happy-dom@20.8.9` (симлинк свежий).
|
||||
|
||||
## Второстепенный подозреваемый
|
||||
|
||||
`getSchema(tiptapExtensions)` / `PMDOMParser.parse(...)` могут спотыкаться на
|
||||
`parseHTML`-правилах недавно добавленных нод (synced blocks/transclusion,
|
||||
page break, indent, columns, status — все они в `tiptapExtensions`). Но
|
||||
`getSchema` используется и в рабочем пути (`createYdoc`/`update_page_json`),
|
||||
поэтому сам по себе билд схемы скорее всего цел — под подозрением именно
|
||||
DOM-парс-ветка, уникальная для импорта.
|
||||
|
||||
## Направления фикса
|
||||
|
||||
1. **Диагностируемость — ✅ СДЕЛАНО (по конвенции проекта).** В catch-блоках
|
||||
`import.service.ts` (обработка контента + вставка страницы) реальная
|
||||
причина теперь прокидывается наружу: `BadRequestException` несёт
|
||||
`${err.name}: ${err.message}`, а в лог пишется полный `err` со стеком.
|
||||
Раньше наружу уходила generic-строка "Error processing file content".
|
||||
Теперь при повторе 400 на проде реальный reason будет виден прямо в теле
|
||||
ответа — без необходимости лезть в логи.
|
||||
2. **Корневой фикс — ⏳ НЕ ПОДТВЕРЖДЁН.** Гипотеза happy-dom 14→20 **не
|
||||
подтвердилась** при локальном воспроизведении на текущем коде (см. ниже).
|
||||
Применять блайнд-даунгрейд happy-dom нельзя — нужен реальный stack из
|
||||
логов/ответа после повторения.
|
||||
|
||||
## Локальное воспроизведение (выполнено)
|
||||
|
||||
На текущем `main` (happy-dom 20.8.9) вся цепочка импорта `.md` отработала
|
||||
без ошибок через `tsx` (импорты прямо из source, не из dist):
|
||||
|
||||
- `markdownToHtml` → cheerio `load` → `normalizeImportHtml` → `generateJSON`
|
||||
с полным набором из 44 `tiptapExtensions` — **OK** для:
|
||||
- базового markdown (заголовки, bold/italic, списки, таблицы, code-block,
|
||||
blockquote)
|
||||
- edge-cases: пустой контент, whitespace, HTML-сущности, вложенные списки,
|
||||
task-list, emoji, кириллица, спецсимволы в code, ссылки, изображения, hr
|
||||
- API happy-dom 20.8.9, используемые в `generateJSON`, существуют и работают:
|
||||
`new Window()`, `new localWindow.DOMParser()`, `parseFromString('…',
|
||||
'text/html')`, `happyDOM.abort()` (async), `happyDOM.close()` (async).
|
||||
- Блок `finally` в `generateJSON` вызывает `abort()/close()` без `await` и без
|
||||
`try/catch`, но эти методы не бросают синхронно и не перезаписывают
|
||||
результат — **не является** причиной 400 (проверено отдельным тестом).
|
||||
- Все `parseHTML`-правила расширений (status, transclusion, page-break,
|
||||
columns, subpages и т.д.) участвуют в успешном тесте — ни одно не падает.
|
||||
|
||||
Вывод: на текущем коде баг **не воспроизводится**. Вероятные объяснения —
|
||||
контент-специфичный кейс, которого нет в тестах; разница между source и
|
||||
собранным `dist`; либо временное состояние задеплоенного инстанса. После
|
||||
применения fix #1 повторный 400 покажет реальный reason — по нему и искать
|
||||
корень.
|
||||
@@ -1,145 +0,0 @@
|
||||
# Улучшение качества RAG-поиска агента — план по итерациям
|
||||
|
||||
> Статус: живой документ. Итерация 1 **реализована** (см. ниже). Остальное —
|
||||
> бэклог на следующие итерации, отсортированный по «качество / усилие».
|
||||
> Контекст: gitmost — форк Docmost. Семантический поиск агента: per-workspace
|
||||
> эмбеддинги в `page_embeddings` (pgvector, dimension-agnostic колонка, seq-scan
|
||||
> с `<=>`), индексация через BullMQ (`reindexPage` / `reindexWorkspace`).
|
||||
> Активная embedding-модель деплоя: OpenAI `text-embedding-3-large` (3072d).
|
||||
|
||||
## Как сверялось с реальным кодом
|
||||
|
||||
Внешнее предложение по улучшению RAG было сверено с кодовой базой. Точные факты
|
||||
на момент итерации 1:
|
||||
|
||||
- Хранилище: [page_embeddings](../apps/server/src/database/migrations/20260617T120000-page-embeddings.ts),
|
||||
колонка `embedding` сделана dimension-agnostic в
|
||||
[20260617T140000](../apps/server/src/database/migrations/20260617T140000-page-embeddings-dimension-agnostic.ts);
|
||||
`model_name` / `model_dimensions` хранятся по строке.
|
||||
- Полнотекстовые индексы **уже существуют** (предложение ошибочно утверждало
|
||||
обратное): `pages_tsv_idx` на `pages.tsv` и `attachments_tsv_idx`. Конфигурация —
|
||||
`to_tsvector('english', f_unaccent(...))` + `setweight`
|
||||
([тут](../apps/server/src/database/migrations/20250729T213756-add-unaccent-pg_trm-update-tsvector..ts)).
|
||||
- Чанкинг: `RecursiveCharacterTextSplitter` 1000/200, без префиксов.
|
||||
- Префиксы `query:` / `passage:` **не нужны**: они требуются для e5/bge/gte/Qwen3,
|
||||
а деплой на OpenAI `text-embedding-3-large` (этот пункт предложения неприменим).
|
||||
- Вложения (`attachment_id` в схеме есть) **не индексируются** — индексатор всегда
|
||||
пишет `attachmentId: null`.
|
||||
|
||||
---
|
||||
|
||||
## Итерация 1 — РЕАЛИЗОВАНО
|
||||
|
||||
Три «низковисящих фрукта»:
|
||||
|
||||
### 1. Хлебные крошки заголовков в чанках
|
||||
Файл: [embedding-indexer.service.ts](../apps/server/src/core/ai-chat/embedding/embedding-indexer.service.ts).
|
||||
Каждый чанк префиксуется путём заголовков `«Заголовок страницы > H1 > H2»` перед
|
||||
эмбеддингом. Крошки строятся обходом **ProseMirror JSON** (`heading`-ноды с
|
||||
`attrs.level`), а не markdown-текста — поэтому `#` внутри fenced-код-блока (типичный
|
||||
bash-сниппет в WirenBoard-вики) **никогда** не принимается за заголовок. Деградация
|
||||
к старому plain-text чанкингу при отсутствии/сбое `content`. Префикс попадает и в
|
||||
эмбеддинг, и в `content` (а значит — в лексический индекс `fts` и в сниппет агента).
|
||||
|
||||
### 2. Гибридный поиск (RRF), слияние двух инструментов в один
|
||||
- Миграция [20260618T150000-page-embeddings-fts.ts](../apps/server/src/database/migrations/20260618T150000-page-embeddings-fts.ts):
|
||||
генерируемая колонка `fts tsvector GENERATED ALWAYS AS (to_tsvector('english',
|
||||
f_unaccent(content))) STORED` + GIN-индекс. Конфиг совпадает с `pages.tsv` (та же
|
||||
обработка unaccent/Cyrillic); `f_unaccent` IMMUTABLE → триггер не нужен.
|
||||
- Репозиторий: метод `hybridSearch` в
|
||||
[page-embedding.repo.ts](../apps/server/src/database/repos/ai-chat/page-embedding.repo.ts) —
|
||||
один SQL-запрос, два CTE (cosine + `websearch_to_tsquery`), слияние Reciprocal Rank
|
||||
Fusion через FULL OUTER JOIN на уровне чанков. `k=60` (дефолт Cormack 2009 /
|
||||
ES / OpenSearch / Weaviate), равные веса 1.0/1.0. RRF сливает **ранги**, поэтому
|
||||
несовместимость шкал BM25 и косинуса не требует нормализации. Dimension-фильтр —
|
||||
только на семантической стороне.
|
||||
- Инструменты: `semanticSearch` удалён, `searchPages` стал единым гибридным
|
||||
инструментом ([ai-chat-tools.service.ts](../apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts)).
|
||||
Контроль доступа сохранён 1-в-1 (scope по доступным спейсам + пост-фильтр прав
|
||||
страниц). Если эмбеддинги не настроены / эмбеддинг упал / нет доступных спейсов /
|
||||
гибрид пуст → graceful fallback на прежний REST-полнотекст (CASL-enforced).
|
||||
|
||||
### 3. Переписывание запроса + описания инструментов
|
||||
- Описание `searchPages` теперь явно просит агента переформулировать вопрос в
|
||||
сфокусированный поисковый запрос и переискивать при слабой выдаче (это переживает
|
||||
кастомный admin-промпт, т.к. лежит в описании инструмента).
|
||||
- Одна строка-подсказка добавлена в `DEFAULT_PROMPT`
|
||||
([ai-chat.prompt.ts](../apps/server/src/core/ai-chat/ai-chat.prompt.ts)).
|
||||
|
||||
> ВАЖНО после деплоя: чтобы крошки и `fts` появились у существующих страниц, нужна
|
||||
> **переиндексация корпуса** (кнопка «Reindex now» / `WORKSPACE_CREATE_EMBEDDINGS`).
|
||||
> Миграция заполнит `fts` у текущих строк автоматически, но крошки добавляются только
|
||||
> при переиндексации (она же перезапишет `content`).
|
||||
|
||||
### Известные нюансы текущей реализации (осознанные компромиссы)
|
||||
- Гибрид покрывает только проиндексированные чанки. Свежесозданная страница
|
||||
становится искомой после отработки её BullMQ-`reindexPage`. Пока эмбеддинги не
|
||||
настроены — работает только REST-fallback (полнотекст уровня страницы по `pages.tsv`).
|
||||
- Если **весь** пул кандидатов гибрида (до 200 чанков) оказался из закрытых для
|
||||
пользователя страниц, инструмент вернёт пусто, а не уйдёт в keyword-fallback.
|
||||
Узкий кейс; возможное улучшение — fallback и при пустом результате пост-фильтра.
|
||||
- `fts` использует конфиг `english` (как и `pages.tsv`) — без русской стеммизации.
|
||||
Для русской вики это консистентно с текущим поиском; переход на `simple`/`russian`
|
||||
конфиг — отдельная задача с переиндексацией.
|
||||
- `candidates` (=clamp(limit×5, 50, 200)) служит и per-CTE лимитом, и финальным
|
||||
лимитом слияния; веса RRF равные. Тюнится после появления оценочного харнесса.
|
||||
|
||||
---
|
||||
|
||||
## Бэклог следующих итераций (по приоритету «качество / усилие»)
|
||||
|
||||
### A. Реранкер (cross-encoder) — наибольший ROI после гибрида
|
||||
Вставить между over-fetch гибрида и дедупом: брать топ-50–100 кандидатов от
|
||||
`hybridSearch`, реранкать, оставлять топ-5–10. Ожидаемый прирост precision/MRR
|
||||
+10–25 %. Точка вставки уже готова — это шаг между `hybridSearch(... candidates)` и
|
||||
циклом дедупа в `searchPages`.
|
||||
- Хостовый старт (раз уже на OpenAI-инфраструктуре): **Cohere Rerank** или
|
||||
**Voyage `rerank-2.5`** — провайдер по аналогии с текущим pluggable embedding-конфигом.
|
||||
- Self-hosted (под Ollama-этос): **BGE-reranker-v2-m3** через HF Text Embeddings
|
||||
Inference (`/rerank`), либо FlashRank (ONNX/CPU, ~15–30 мс).
|
||||
- Диагностика: если реранк не двигает метрики — узкое место в recall (чанкинг/гибрид),
|
||||
а не в ранжировании.
|
||||
|
||||
### B. Индексация вложений — закрыть пробел покрытия
|
||||
Схема уже готова (`attachment_id`). Добавить в BullMQ-flow шаг извлечения текста из
|
||||
PDF/документов (PyMuPDF для цифровых PDF; OCR для сканов; для таблиц — markdown через
|
||||
LLM-парсер) и вливать его в тот же путь чанк→эмбеддинг→`fts`, помечая `attachment_id`.
|
||||
Структура извлечённых данных важнее голой точности OCR.
|
||||
|
||||
### C. Тюнинг гибрида и оценочный харнесс
|
||||
- Золотой датасет 30–100 примеров (вопрос → нужная страница/чанк) + Ragas/DeepEval
|
||||
(Recall@k, MRR/nDCG, context precision/recall, faithfulness). Прогон до/после
|
||||
каждого изменения. **Прерогатива пропущена в итерации 1 осознанно** — без неё все
|
||||
нижеследующие тюнинги делаются «на глаз».
|
||||
- После харнесса: тюнить веса RRF (старт 1.0/1.0), `k` (старт 60), число `candidates`.
|
||||
- Эксперимент: чанки ~512 симв. против 1000 (предложение указывает на рост precision).
|
||||
|
||||
### D. Contextual Retrieval (Anthropic), если крошек мало
|
||||
Один LLM-вызов на чанк добавляет предложение-контекст. Снижение провалов выдачи
|
||||
на 35–49 %. Ложится в BullMQ-`reindexPage`; на сотнях страниц с prompt caching — копейки.
|
||||
Применять, только если хлебных крошек окажется недостаточно против потери контекста.
|
||||
|
||||
### E. ParadeDB `pg_search` (настоящий BM25), если лексика станет узким местом
|
||||
Нативный `ts_rank` использует только TF и длину документа, без IDF. `pg_search`
|
||||
(Rust/Tantivy) даёт честный BM25-индекс. Не drop-in (свои операторы вместо `@@`) —
|
||||
это изменение кода, а не флаг. На сотнях страниц нативного `tsvector` хватает; брать
|
||||
только если качество лексического ранжирования упрётся в потолок.
|
||||
|
||||
### F. Прочее
|
||||
- **Префиксы query/passage** — НЕ нужны на OpenAI. Внедрять только при переходе на
|
||||
e5/bge/gte/Qwen3 (тогда индексатор ставит `passage:`, запрос — `query:`; BGE-v1.5,
|
||||
наоборот, префиксов НЕ должна получать). Зафиксировано как ловушка на будущее.
|
||||
- **Апгрейд embedding-модели** — уже на `text-embedding-3-large` (топ среди закрытых).
|
||||
Matryoshka (обрезка размерности) — запас на будущее; dimension-agnostic колонка
|
||||
делает миграцию тривиальной (цена — переэмбеддинг корпуса).
|
||||
- **HyDE и широкий multi-query/RAG-Fusion** — НЕ рекомендуются как дефолт: в свежих
|
||||
бенчмарках уступали и добавляют задержку/галлюцинации.
|
||||
|
||||
## Оговорки
|
||||
- Все внешние числа (62→84 % precision, +17 % Recall@5, −35…49 % провалов, +10–25 %
|
||||
от реранка) получены на ДРУГИХ корпусах (SEC-отчёты, финтекст, право, медицина).
|
||||
На этой вики величины будут иными — поэтому пункт C (свой датасет) обязателен перед
|
||||
тонким тюнингом. Внешние числа — направление, не гарантия величины.
|
||||
- Часть источников предложения — вендорский маркетинг (Cohere, Voyage, ParadeDB);
|
||||
направление подтверждается независимыми (T2-RAGBench, оценка Anthropic), но величины
|
||||
у вендоров могут быть завышены.
|
||||
Reference in New Issue
Block a user