doc-search — гибридный поиск + RAG-чат для репозитория документов

Гибридный поисковый движок для внутреннего репозитория документов (глоссарий, чек-листы ревью, проектная документация), сочетающий поиск по ключевым словам (BM25) × векторный поиск (семантический поиск), и RAG-чат (Claude API, выбор модели, потоковый вывод) поверх него.

Дизайн UI повторяет SodaShikenn/LLM-RAG_KBQA (левая боковая панель: выбор модели / настройки базы знаний / история диалога, справа: чат + Send / Cancel).

Четыре способа использования:

1. RAG-чат (/) — выберите модель и задайте вопрос. Поиск → потоковый ответ с цитатами

2. Поисковый обозреватель (/search.html) — инкрементальный поиск, отображение оценок KW/VEC/RRF

3. CLI — docsearch search "..."

4. MCP-сервер — регистрация как инструмента Claude Code (Agentic RAG)

Установка (лёгкая: без ML-зависимостей, ~30MB)

cd doc-search
brew install uv        # 未導入の場合
uv venv --python 3.12 .venv
uv pip install -p .venv/bin/python -r requirements.txt
cp .env.example .env   # ANTHROPIC_API_KEY を記入（チャット用）

Только при использовании локальных моделей эмбеддингов (e5 / bge-m3) добавляется тяжёлый ML-стек:

uv pip install -p .venv/bin/python -r requirements-local.txt

Related MCP server: LLMDoc

Использование

# 1) インデックス構築
.venv/bin/python -m docsearch index sample_docs                    # 自動選択
.venv/bin/python -m docsearch index /path/to/docs --embedder voyage  # クラウド埋め込み

# 2) サーバー起動 → http://127.0.0.1:8765
.venv/bin/python -m docsearch serve --port 8765

# 3) CLI検索
.venv/bin/python -m docsearch search "解約率" --mode vector

Даже без API-ключа можно проверить работу чат-интерфейса на модели «Demo (офлайн)».

Выбор модели эмбеддингов (--embedder)

Как выбрать: если хотите сочетать качество и лёгкую установку — voyage (при разрешении облака). Если обязательно полностью локально — e5; если нужна выше точность — bge-m3 (если допустим вес). Поскольку BM25 (лексическое совпадение) всегда работает локально, роль эмбеддингов — только учёт перефразировок; разница между моделями проявляется только здесь, а multi-vector/sparse возможности bge-m3 в этой конфигурации не нужны.

Как работает чат (RAG)

質問 → 検索の深さ（effort）を解決（auto は確信度シグナルで自動判断）
     → 検索実行（hard は選択モデルがクエリを言い換え → 全変種を検索して RRF 融合）
     → system プロンプトに参照資料として注入（[n] path:line 付き）
     → Claude API へストリーミング要求（output_config.effort も連動）
     → data: {status|sources|delta|done|error} を SSE 配信
     → UI が逐次描画 + 「なぜこの検索をしたか」の説明 + 引用チップ。会話は localStorage

Глубина поиска (effort) — скрывает hybrid/keyword/vector

Не заставляем пользователя выбирать IR-термины. Выбирается только «насколько тщательно искать», а что реально было сделано, отображается под ответом на японском языке (например: «おまかせ → しっかり — キーワード一致が無く…言い換えを生成して深く検索»).

Сигналы для auto: наличие совпадений по ключевым словам, сила векторного сходства, совпадение верхних результатов обоих поисков. Если генерация перефразировок недоступна (модель Demo, ключ не задан), hard автоматически вырождается в «расширение количества результатов». Сырые режимы поиска (keyword/vector/hybrid) оставлены для инженеров в /search.html и CLI.

• Модели: Claude Opus 5 (по умолчанию) / Sonnet 5 / Haiku 4.5 / Demo (офлайн)

• Opus 5 включает серверный refusal fallback (при отказе отвечать по соображениям безопасности автоматически переключается на альтернативную модель в рамках того же запроса)

• API генерации — официальный SDK Anthropic. Ключ — ANTHROPIC_API_KEY в .env

Интеграция с Claude Code (MCP / Agentic RAG)

.mcp.json (целевой репозиторий или домашний каталог):

{
  "mcpServers": {
    "docsearch": {
      "command": "/ABSOLUTE/PATH/doc-search/.venv/bin/python",
      "args": ["-m", "docsearch.mcp_server"],
      "env": { "DOCSEARCH_INDEX": "/ABSOLUTE/PATH/doc-search/index" }
    }
  }
}

Инструменты: search_docs(query, mode, k) / docs_repo_info(). Поскольку Claude Code сам выполняет планирование запроса → повторный поиск → чтение файлов → ответ с цитатами, в редакторе реализуется Agentic RAG, отдельный от чат-интерфейса.

Замена на реальные данные (на машине с доступом)

В этом репозитории находятся только плейсхолдеры (sample_docs). Ссылки на реальные данные и внутренний репозиторий заменяются на стороне машины, имеющей доступ, без изменения кода. Приоритет:

1. Переменные окружения (для Docker это основной способ): в .env укажите DOCSEARCH_DOCS_HOST=/path/to/real-docs (источник монтирования в контейнер) и DOCSEARCH_GITHUB_BASE=https://github.example.com/org/repo/blob/main

2. Файл конфигурации (локальный запуск): выполните cp datasource.example.json datasource.json, затем отредактируйте docs_dir / github_base / embedder → docsearch index (без аргументов). datasource.json находится в gitignore, указатели на внутренний репозиторий не пушатся

3. Плейсхолдер: если ничего не настроено, индексируется sample_docs/

Логика разрешения сосредоточена в одной функции get_datasource() в docsearch/datasource.py.

GitHub-ссылки в цитатах

Результаты поиска, чипы цитат и [path:line] в ответах становятся глубокими ссылками на соответствующие строки в GitHub-репозитории документов (формат blob/<インデックス時のSHA>/path#L<line>, поэтому якоря строк не сбиваются даже при развитии репозитория).

• Автоопределение из git remote репозитория docs во время индексации (поддерживается и GHE)

• Если автоопределение невозможно (например, при монтировании docs в Docker), задайте DOCSEARCH_GITHUB_BASE=https://github.com/o/r/blob/main/docs в .env (в CLI — --github-base)

Ключевые особенности поискового движка

• Поиск по японским ключевым словам: CJK-строки разворачиваются в биграммы и индексируются в SQLite FTS5. На стороне запроса используется фразовый поиск по биграммам для смежного совпадения (работает без морфологического анализатора)

• Слияние RRF: оценки BM25 и косинусное сходство несовместимы по шкале, поэтому сливаются на основе рангов

• Хлебные крошки в чанках: к началу чанка добавляется иерархия заголовков (в глоссарии заголовок = термин)

Интересные запросы для проверки

Развёртывание

Локальный запуск как постоянный процесс (macOS / LaunchAgent)

bash deploy/install-launchd.sh    # ログイン時自動起動・クラッシュ時自動再起動

• Логи: logs/docsearch.log / logs/docsearch.err.log

• Остановка и удаление: launchctl bootout gui/$(id -u)/com.sodashikenn.docsearch && rm ~/Library/LaunchAgents/com.sodashikenn.docsearch.plist

• Внимание, macOS TCC: если репозиторий находится в защищённой папке, например ~/Desktop, python, запущенный через launchd, может получить отказ в доступе к файлам и зациклиться при запуске. В этом случае предоставьте python права доступа в «Системные настройки > Конфиденциальность и безопасность» или переместите репозиторий в незащищённое место (например, ~/dev/).

Docker (это самый быстрый способ для совместного использования с другой машиной)

git clone https://github.com/SodaShikenn/doc-search.git && cd doc-search
cp .env.example .env               # ANTHROPIC_API_KEY を記入
docker compose up --build -d       # → http://127.0.0.1:8765

• Если на Mac нет Docker (при отказе от Docker Desktop):

  brew install colima docker docker-compose && colima start
  mkdir -p ~/.docker/cli-plugins && ln -sfn $(brew --prefix)/opt/docker-compose/bin/docker-compose ~/.docker/cli-plugins/docker-compose

• Для полностью локального векторного поиска (рекомендуется для M-серии Mac с достаточной памятью): запишите в .env WITH_LOCAL_ML=1 и DOCSEARCH_EMBEDDER=e5, затем docker compose up --build -d (образ ~2-3GB, при первом запуске происходит загрузка модели. Изменение модели эмбеддингов обнаруживается при запуске, и индексация выполняется автоматически заново)

• Стандартный облегчённый образ (~300MB): векторный поиск — через облако при наличии VOYAGE_API_KEY, иначе вырождается в hash (поиск по ключевым словам всегда работает полностью)

• Для реальных документов замените ./sample_docs:/docs:ro в docker-compose.yml; повторная индексация после обновления содержимого — DOCSEARCH_REINDEX=1 docker compose up -d

• Ключи подставляются из .env хоста (не вшиваются в образ)

• Аутентификации нет. Для публикации оставляйте локальную привязку и используйте реверс-прокси (с аутентификацией) или VPN

Third-party

webui/vendor/ — это самостоятельно размещённые сторонние библиотеки, подчиняющиеся своим лицензиям: marked v13.0.2 (MIT) и DOMPurify 3.1.6 (Apache-2.0 OR MPL-2.0). Всё остальное — MIT (см. LICENSE).

Ограничения и развитие

• Индексация только с полной перестройкой (инкрементальное обновление не реализовано)

• История диалога хранится в localStorage браузера (без серверной персистентности)

• Оценка: полезно сравнить hybrid против отдельных режимов и между моделями эмбеддингов по recall@k на парах «вопрос → правильный файл»