doc-search — Búsqueda híbrida + chat RAG para repositorios de documentos

Motor de búsqueda híbrida de búsqueda por palabras clave (BM25) × búsqueda vectorial (búsqueda semántica) dirigido al repositorio de documentos interno de la empresa (glosario, criterios de revisión, documentos de diseño), y sobre él, un chat RAG (API de Claude · selección de modelo · salida en streaming).

El diseño de la interfaz sigue SodaShikenn/LLM-RAG_KBQA (barra lateral izquierda: selección de modelo / configuración de conocimiento / historial de conversación; derecha: chat + Enviar / Cancelar).

4 formas de uso:

1. Chat RAG (/) — Elige un modelo y pregunta. Búsqueda → respuesta con citas en streaming

2. Explorador de búsqueda (/search.html) — Búsqueda incremental, visualización de puntuaciones KW/VEC/RRF

3. CLI — docsearch search "..."

4. Servidor MCP — Registrado como herramienta de Claude Code (RAG agéntico)

Configuración (ligera: sin dependencias de 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 を記入（チャット用）

Solo si se usa un modelo de embeddings local (e5 / bge-m3), se añade una pila de ML pesada:

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

Related MCP server: LLMDoc

Uso

# 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

Incluso sin clave de API, se puede comprobar el funcionamiento de la interfaz de chat con el modelo «Demo (sin conexión)».

Selección del modelo de embeddings (--embedder)

Cómo elegir: si quieres equilibrar calidad y ligereza de configuración, voyage (si se permite la nube). Si es imprescindible totalmente local, e5; si quieres más precisión, bge-m3 (si puedes tolerar el peso). Como BM25 (coincidencia léxica) siempre funciona en local, el papel de los embeddings es solo absorber las «reformulaciones» — la diferencia entre modelos solo se nota ahí, y las funciones multi-vector/sparse de bge-m3 no son necesarias en esta configuración.

Mecanismo del chat (RAG)

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

Profundidad de búsqueda (effort) — oculta hybrid/keyword/vector

No se hace que el usuario elija terminología de RI. Solo elige «con qué profundidad buscar», y lo que realmente se hizo se muestra en japonés debajo de la respuesta (ej.: «automático → a fondo — sin coincidencia de palabras clave… se generan reformulaciones y se busca en profundidad»).

Señales de decisión de auto: presencia de coincidencia de palabras clave · fuerza de la similitud vectorial · coincidencias principales de ambas búsquedas. Si no se puede usar la generación de reformulaciones (modelo Demo · clave no configurada), hard se degrada automáticamente a «ampliación del número de resultados». Los modos de búsqueda en bruto (keyword/vector/hybrid) se mantienen en /search.html y en la CLI para ingenieros.

• Modelo: Claude Opus 5 (predeterminado) / Sonnet 5 / Haiku 4.5 / Demo (sin conexión)

• Opus 5 tiene habilitado el fallback de rechazo en el servidor (cuando se rechaza responder por seguridad, se hace fallback automático a un modelo alternativo dentro de la misma solicitud)

• La API de generación es el SDK oficial de Anthropic. La clave está en ANTHROPIC_API_KEY en .env

Integración en Claude Code (MCP / RAG agéntico)

.mcp.json (en el repositorio objetivo o en el directorio personal):

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

Herramientas: search_docs(query, mode, k) / docs_repo_info(). Como el propio Claude Code realiza la formulación de consultas → re-búsqueda → lectura de archivos → respuesta con citas, se establece un RAG agéntico dentro del editor, aparte de la interfaz de chat.

Sustitución por datos reales (en una máquina con permisos de acceso)

Lo que contiene este repositorio son solo marcadores de posición (sample_docs). El enlace a los datos reales y al repositorio interno se sustituye en la máquina con permisos de acceso sin cambios de código. Prioridad:

1. Variables de entorno (Docker usa estas): en .env DOCSEARCH_DOCS_HOST=/path/to/real-docs (origen del montaje en el contenedor) y DOCSEARCH_GITHUB_BASE=https://github.example.com/org/repo/blob/main

2. Archivo de configuración (ejecución local): cp datasource.example.json datasource.json y edita docs_dir / github_base / embedder → docsearch index (sin argumentos). datasource.json está en gitignore y los punteros al repositorio interno no se suben

3. Marcador de posición: si no configuras nada, indexa sample_docs/

La lógica de resolución está concentrada en la función get_datasource() de docsearch/datasource.py.

Enlaces de citas a GitHub

Los resultados de búsqueda, las fichas de citas y los [path:line] en las respuestas son enlaces profundos a la línea correspondiente en GitHub del repositorio de documentos (formato blob/<SHA en el momento de la indexación>/path#L<line>, por lo que el ancla de línea no se desvía aunque el repositorio avance).

• Se detecta automáticamente desde el git remote del repositorio de docs al indexar (también compatible con GHE)

• Si no se puede detectar automáticamente (por ejemplo, al montar docs con Docker), configura DOCSEARCH_GITHUB_BASE=https://github.com/o/r/blob/main/docs en .env (en CLI, --github-base)

Puntos de diseño del motor de búsqueda

• Búsqueda de palabras clave en japonés: las cadenas CJK se expanden en bigramas y se indexan en SQLite FTS5. En el lado de la consulta, búsqueda de frases con bigramas para coincidencia adyacente (funciona sin analizador morfológico)

• Fusión RRF: como la puntuación BM25 y la similitud coseno no son compatibles en escala, se fusionan por rango

• Migas de pan en los fragmentos: la jerarquía de encabezados se añade al inicio del fragmento (en el glosario, el encabezado = el término)

Consultas interesantes para probar

Despliegue

Residente en local (macOS / LaunchAgent)

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

• Registros: logs/docsearch.log / logs/docsearch.err.log

• Detener y eliminar: launchctl bootout gui/$(id -u)/com.sodashikenn.docsearch && rm ~/Library/LaunchAgents/com.sodashikenn.docsearch.plist

• Aviso de TCC en macOS: si el repositorio está bajo una carpeta protegida como ~/Desktop, el python iniciado por launchd puede denegar el acceso a archivos y entrar en bucle de arranque. En ese caso, concede permisos de acceso a python en «Ajustes del sistema > Privacidad y seguridad», o mueve el repositorio fuera de la zona protegida (ej.: ~/dev/)

Docker (esta es la vía más corta para compartir con otra máquina)

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

• En un Mac sin Docker (si no se usa 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

• Para usar búsqueda vectorial totalmente local (recomendado en Mac de la serie M con memoria suficiente): escribe WITH_LOCAL_ML=1 y DOCSEARCH_EMBEDDER=e5 en .env y luego docker compose up --build -d (imagen ~2-3GB, con descarga de modelos la primera vez. Los cambios en el modelo de embeddings se detectan al arrancar y se reindexa automáticamente)

• Imagen ligera predeterminada (~300MB): la búsqueda vectorial usa la nube si hay VOYAGE_API_KEY, si no, degradación a hash (la búsqueda por palabras clave siempre funciona al completo)

• Para documentos reales, sustituye ./sample_docs:/docs:ro en docker-compose.yml, y para reindexar tras actualizar contenido, DOCSEARCH_REINDEX=1 docker compose up -d

• Las claves se inyectan desde el .env del host (no se hornean en la imagen)

• No hay autenticación. Para exposición pública, mantén el enlace local y usa un proxy inverso (con autenticación) o a través de VPN

Terceros

webui/vendor/ contiene bibliotecas de terceros autoalojadas, sujetas a sus respectivas licencias: marked v13.0.2 (MIT) · DOMPurify 3.1.6 (Apache-2.0 OR MPL-2.0). El resto es MIT (ver LICENSE).

Limitaciones y desarrollo futuro

• La indexación es solo reconstrucción completa (la actualización incremental no está implementada)

• El historial de conversación está en localStorage del navegador (sin persistencia en servidor)

• Evaluación: conviene comparar hybrid vs. individual y entre modelos de embeddings con recall@k de pregunta → archivo correcto