doc-search — 面向文档仓库的混合搜索 + RAG 聊天

面向公司内部文档仓库（术语表・评审要点・设计文档）的 关键词搜索（BM25）× 向量搜索（语义搜索） 混合搜索引擎， 以及构建在其之上的 RAG 聊天（Claude API・模型选择・流式输出）。

UI 设计沿袭 SodaShikenn/LLM-RAG_KBQA （左侧边栏：模型选择 / 知识库设置 / 对话历史，右侧：聊天 + Send / Cancel）。

4 种使用方式：

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（离线）」确认聊天 UI 的运行。

嵌入模型的选择 (--embedder)

选择方法：想兼顾品质和安装轻量的话选 voyage（允许云端时）。 必须完全本地的话选 e5，想提高精度则选 bge-m3（能接受体积的情况下）。 BM25（字面匹配）始终在本地运行，因此嵌入的作用仅是吸收「换种说法」—— 模型差异只在那里体现，bge-m3 的 multi-vector/sparse 功能在此架构中不需要。

聊天 (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 使用 Anthropic 官方 SDK。密钥在 .env 的 ANTHROPIC_API_KEY

集成到 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 自身会完成查询规划→重新搜索→文件解读→引用回答， 因此与聊天 UI 不同，在编辑器内即可实现 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，指向内部仓库的指针不会被 push

3. 占位符：不设置任何内容则索引 sample_docs/

解析逻辑集中在 docsearch/datasource.py 的 get_datasource() 这一个函数中。

引用的 GitHub 链接

搜索结果・引用标签・回答中的 [path:line] 会指向文档仓库 GitHub 上对应行的深层链接（格式为 blob/<索引时的SHA>/path#L<line>， 因此即使仓库更新，行锚点也不会偏移）。

• 索引时从 docs 仓库的 git remote 自动检测（GHE 也可）

• 无法自动检测时（例如 Docker 中挂载 docs 时） 在 .env 中设置 DOCSEARCH_GITHUB_BASE=https://github.com/o/r/blob/main/docs （CLI 中使用 --github-base）

搜索引擎的设计要点

• 日语关键词搜索：将 CJK 字符串展开为二元组（bigram）后索引到 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 等受保护文件夹下， launchd 启动的 python 可能会因文件访问被拒绝而陷入启动循环。 此时请在「系统设置 > 隐私与安全性」中授予 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

• 没有 Docker 的 Mac（不使用 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（关键词搜索始终完整可用）

• 真实文档替换 docker-compose.yml 中的 ./sample_docs:/docs:ro， 内容更新后的重新索引使用 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（无服务器持久化）

• 评估：建议用「问题→正确答案文件」的 recall@k 来比较 hybrid 与单独模式・不同嵌入模型