rag-db-advisor

Tres pasos

1. Pregunta rag-db-advisor ask "…" Una pregunta en texto libre, por CLI o MCP. Sin cuestionario que llenar.
2. La evidencia vuelve === note:qdrant#1 (knowledge/ja/qdrant.md) === Chunks con números medidos, cada uno encabezado por su ID y registro de origen.
3. Tú decides --llm / tu LLM vía MCP La síntesis ocurre fuera: tu LLM (o tú) escribe el veredicto, con las fuentes adjuntas.

Ejemplo: una respuesta real

ejecución real, 2026-07-12: rag-db-advisor ask --llm --model gpt-4o, condensado del original en japonés

Qué puede sopesar la evidencia

Cada eje de abajo está cubierto por mediciones o trampas reproducidas, las dos únicas cosas admitidas en el store:

• Tamaño del dataset medido con 10 mil y 100 mil pasajes
• Calidad de retrieval recall@10, nDCG, MRR, hit@k vs verdad humana
• Latencia p50 / p95 / p99 por query
• Ruta de escritura segundos de carga masiva + índice
• Trampas operacionales 3 casos reproducidos, comprobados por máquina
• Forma de despliegue embebido vs servidor, tablas separadas

El filtrado por metadatos, la búsqueda híbrida y las estimaciones de costo quedan fuera de la evidencia de la v0.1, así que el advisor devuelve error en lugar de improvisar sobre ellas. El alcance medido es honesto sobre sus propios bordes.

Para quién es

• Ingenieros de IA que necesitan un número citable para el "por qué esta base" de un documento de diseño
• Desarrolladores de RAG que depuran "la búsqueda se siente lenta" y quieren descartar primero las trampas conocidas
• Usuarios de Claude Code que quieren respuestas sobre el stack de RAG ancladas en evidencia, sin depender del conocimiento previo del modelo
• Tech leads que revisan una propuesta de base vectorial y comprueban qué significan los números en realidad

Cuándo usarlo

• Antes de elegir una base para una nueva feature de RAG: parte de mediciones en las mismas condiciones en lugar de material de proveedor
• Cuando la búsqueda vectorial de ClickHouse "se siente lenta": el catálogo de trampas reproducidas existe exactamente para esa impresión
• Cuando en la revisión preguntan "¿por qué Qdrant?": responde con bloques de evidencia que llevan los IDs de sus registros de origen
• En plena implementación en Claude Code: tu LLM trae la evidencia vía MCP sin salir de la sesión

Instalación

pip install git+https://github.com/kenimo49/rag-db-advisor
export OPENAI_API_KEY=sk-...
rag-db-advisor ingest

La clave de API se usa solo para embeddings (text-embedding-3-small). Vía MCP no hace falta clave de generación en el servidor: el servidor devuelve la evidencia y tu LLM escribe la respuesta.

Qué sabe

• Registros de medición: 9 configuraciones de backend × 2 escalas de corpus (10 mil / 100 mil pasajes MIRACL-ja, 860 queries anotadas por humanos), cada registro con calidad, latencia, ingesta y verificación de índice
• Notas operacionales: 8 archivos escritos a mano, uno por backend más principios transversales, que cubren solo comportamiento reproducido durante el trabajo del bench
• Catálogo de trampas: 3 formas en que un backend degrada sin levantar ningún error, cada una reproducida, corregida y documentada
• Salvedades de metodología integradas en las respuestas: la latencia de backends embebidos y de servidor se mide en condiciones distintas, y los números vienen de MIRACL-ja + text-embedding-3-small en un solo nodo
• 3 herramientas MCP: advise (búsqueda de evidencia), compare_backends (tabla comparativa 10k/100k), list_traps (trampas por backend). Los fallos devuelven {"error", "hint"} en lugar de excepción

Una muestra del catálogo de trampas

Tres de los siete backends traían una vía para degradar sin levantar ningún error. Las tres se pisaron durante el trabajo del bench, se reprodujeron y solo entonces se escribieron en la base de conocimiento:

fuente: knowledge/ja/clickhouse.md · qdrant.md · milvus.md (reproducidas antes de documentarse)

Consejos que la evidencia cambia de verdad

Dos ejemplos de respuestas que se dan la vuelta cuando miras mediciones en lugar de datasheets:

Uso

# solo evidencia
rag-db-advisor ask "pgvector or Qdrant for 100k Japanese docs?"

# + síntesis con OpenAI (modelo por defecto: gpt-4o-mini)
rag-db-advisor ask "ClickHouse vector search feels slow. What should I check?" --llm

# registrar como servidor MCP en Claude Code
claude mcp add rag-db-advisor -- rag-db-advisor mcp

Negarse es una funcionalidad

El modo de fallo contra el que se construyó esta herramienta: la capa de retrieval se rompe, el LLM que llama responde en silencio con conocimiento previo y nadie lo nota. Por eso el advisor falla cerrado:

• Los fallos de búsqueda devuelven un {"error", "hint"} explícito en las tres herramientas MCP; las excepciones nunca se tragan en prosa
• Un resultado vacío también es error, y deja de ser respuesta nula: el modelo que llama ve "sin evidencia" en lugar de "sin problema, déjame adivinar"
• Ningún veredicto se genera por dentro: el advisor recupera, tu LLM (o tú) sintetiza, y las fuentes quedan adjuntas

Cada chunk se rastrea hasta un registro del bench empaquetado (knowledge/results/*.jsonl) o una nota escrita a mano sobre comportamiento reproducido (knowledge/ja/*.md). El consejo especulativo queda fuera del alcance por política.

Dogfooding: la capa de retrieval importa la propia abstracción BaseRetriever de rag-retriever-bench y guarda el conocimiento en Chroma, porque los datos del bench muestran que todos los backends de HNSW puro empatan en calidad a esta escala de corpus. El advisor sigue su propio consejo.

Por qué existe esta herramienta

Construyendo rag-retriever-bench quedó claro que los números son la parte duradera: caen en JSONL y en informes y ahí se quedan. Lo que se evaporaba era el conocimiento operacional alrededor: la flag que desactiva un índice en silencio, el umbral que deja una colección sin indexar detrás de un estado green. Las opiniones sobre bases de datos no se reproducen; las mediciones y las trampas reproducidas, sí. Así que este advisor cierra el ciclo: medir, destilar lo medido y lo vivido en una base de conocimiento, y servirlo a la siguiente pregunta. Y cuando no hay evidencia, dice que no la hay en lugar de adivinar.

Junto a un chat de LLM y ann-benchmarks

Herramientas distintas responden "¿qué base vectorial?" de formas distintas. La diferencia honesta es de dónde viene la respuesta:

La raya indica que la opción no cubre ese eje, y cubrir menos ejes no la hace peor: un chat de LLM es más amplio y ann-benchmarks es la referencia para el rendimiento bruto de ANN. Este advisor es estrecho a propósito: una familia de corpus, un modelo de embedding, y cada afirmación rastreable a un registro.

FAQ

Sobre el autor

Creado por Ken Imoto: más de 300 artículos técnicos en Zenn, Qiita, Dev.to y este sitio, más de 40 libros en 4 idiomas, más de 400 mil páginas vistas en Zenn y Qiita, 4 artículos de investigación en Zenodo y creador del LLMO Framework.

Más sobre Ken →

Relacionado

Toda la evidencia viene de rag-retriever-bench, el harness de benchmark que mide el mismo corpus y las mismas queries en 9 configuraciones de backend.

rag-retriever-bench →