Retrieval-слой под book-as-context: почему vector-only не годится

Проблема

Когда строишь book-as-context (агент работает с корпусом книг через MCP), первый инстинкт — взять vector-only RAG. На демо-корпусе работает. На реальных технических книгах ломается предсказуемо:

• точные термины, коды, имена глав теряются — эмбеддинг «размывает» лексическое совпадение;
• запрос-навигация («найди главу про two-phase commit у Таненбаума») и запрос-исследование («что пишут про durability») требуют разной механики;
• свежий раздел, добавленный вчера, проигрывает «усреднённо похожим» из старых заметок.

Методика

Вместо написания retrieval с нуля — форк obsidian-hybrid-search, встроенный как MCP-сервер под агентный слой book-as-context. Три сигнала вместо одного:

1. 1. BM25 — лексическое совпадение. Точные термины, коды, имена глав не теряются.
2. 2. Семантические эмбеддинги — близость по смыслу. Синонимы, перефразировки, концептуальные связи.
3. 3. Fuzzy title / alias — навигация к конкретной заметке по имени.

Режимы под тип запроса: hybrid (по умолчанию), semantic, fulltext, title. Слияние через RRF-фьюжн: заметка, высоко ранжированная в любом из переформулированных запросов агента, всплывает наверх.

obsidian-search "event bus durability" --mode hybrid --limit 5

{
  "path": "tanenbaum/12-message-delivery.md",
  "score": 0.87,                              // итоговый hybrid (RRF)
  "matchedBy": ["semantic", "bm25"],
  "scores": { "semantic": 0.81, "bm25": 0.93, "fuzzy_title": null }
}

Здесь bm25 (0.93) > semantic (0.81): точное лексическое совпадение вытянуло наверх результат, который vector-only поставил бы ниже. Видимость по-компонентных scores — это не отладочный вывод, а то, на основании чего агент решает, доверять ли результату.

Агентный слой поверх retrieval

Гибридный поиск закрывает ранжирование. Без слоя поверх — слепой RAG: чанки в индексе могут быть верные, а запросы идут языком задачи, не языком автора — мисматч. BM25 тогда не спасает: в запросе нет якорей, по которым книга проиндексирована. Про wiki одной книги и traversal от требования к паттерну — book-as-context (шаг 5). Ниже — как тот же retrieval стыкуется с библиотекой всех книг и с внешними источниками.

Два корпуса: obsidian-books и wiki одной книги

Досье на книги (books/)

На каждую важную книгу — один файл-досье: оглавление, термины автора, синонимы перевода, «запрос → глава», пары RU/EN. Агент читает досье до books_search, а не повторяет формулировку пользователя. Без досье поиск идёт, но шумнее: hybrid не заменяет знание лексики автора.

Fan-out и переформулировка

Вместо одного запроса — 3–5 переформулировок в queries[]: якоря из досье + plain language задачи, синонимы перевода, при слабой выдаче — оригинал термина. RRF заточен под fan-out. После top-k — обязательный books_read 2–3 полных заметок, не слепая цитата из snippet.

Параллельный поиск в интернете (librarian)

Когда vault не закрывает задачу — два канала параллельно: obsidian-books + hybrid (первоисточник, досье) и веб (книга не в библиотеке, свежий контекст, критика). Приоритет: Obsidian как source of truth, интернет — дополнение. Для маркетинга и стратегии контур типичен; для book-as-context на одной инженерной книге часто хватает vault + wiki.

Артефакт

Форк github.com/dobryakov/obsidian-hybrid-search (TypeScript): CLI + MCP-сервер с README — retrieval под obsidian-books и под wiki book-as-context. Поверх retrieval: каталог досье books/, регламент fan-out и books_read, параллельный контур librarian (vault + веб). Без этой дисциплины hybrid-search остаётся «правильным top-k на неправильном запросе».

Для кого и почему

Если вы строите AI-assisted систему поверх собственного корпуса — книг, вики, документации — этот разбор про retrieval-слой под неё. Не про то, как написать поиск, а про архитектурное решение: взять форк вместо велосипеда, понять механику достаточно глубоко, встроить как слой. В enterprise intake тот же приём — L2 corpus в clarify gate Jira (#11).