OSS · CLI em Python + MCP

rag-db-advisor

Name: rag-db-advisor
Author: Ken Imoto

Encontre o banco vetorial certo para a sua carga de RAG, com a evidência anexada.

As respostas para "qual banco vetorial?" costumam ser feitas de opiniões. Esta é feita de medições: pergunte qual backend encaixa na sua carga de trabalho, o que um número de latência significa na prática ou qual armadilha você está prestes a pisar, e ele responde com 54 chunks de evidência destilados de 9 configurações medidas. O advisor devolve a evidência; o seu LLM escreve a resposta.

Em vez de escolher por popularidade, escolha pela sua carga de trabalho.

Experimente no GitHub Como ele decide o que dizer →

Grátis · Open Source · resposta com evidência em segundos

4.3 s tempo de resposta medido
~2 min do setup à primeira resposta
54 chunks de evidência
Grátis Open Source · MIT

Respostas rastreáveis 54 chunks, cada um rastreável a um registro do bench ou a uma armadilha reproduzida
Comparação sob demanda 9 configurações × 10 mil / 100 mil passagens, 860 queries anotadas
Armadilhas antes de pisar nelas 3 casos de degradação silenciosa, reproduzidos antes de documentados
Roda dentro do Claude Code 3 ferramentas MCP, sem chave de geração no servidor

Demo no terminal: rag-db-advisor responde uma pergunta em japonês sobre escolher um banco vetorial para 100 mil documentos, devolvendo blocos de evidência medida com números de recall e latência e seus registros de origem

Sua pergunta rag-db-advisor Só evidência. Nenhuma geração aqui dentro. Evidência medida Seu LLM responde

Três passos

Pergunte rag-db-advisor ask "…" Uma pergunta em texto livre, por CLI ou MCP. Sem questionário para preencher.
A evidência volta === note:qdrant#1 (knowledge/ja/qdrant.md) === Chunks com números medidos, cada um encabeçado pelo seu ID e registro de origem.
Você decide --llm / seu LLM via MCP A síntese acontece fora: seu LLM (ou você) escreve o veredito, com as fontes anexadas.

Exemplo: uma resposta real

rag-db-advisor ask "Vou montar busca RAG sobre 100 mil documentos em japonês. O recall precisa se manter e a operação deve ficar leve. Qual banco vetorial?" --llm

✓ Recomendado Qdrant (HNSW)

recall@10 0.947 (100 mil) · melhor configuração ANN, a 0.5 ponto do teto de busca exata de 0.952
p50 de busca 3.3 ms · mesmo corpus e mesmos embeddings dos outros candidatos
LanceDB descartado · a quantização padrão derruba o recall para 0.811

Pesado contra: LanceDB (recall@10 0.811 a 100 mil, quantização embutida)

4.3 s · 6 chunks de evidência · síntese com gpt-4o

execução real, 2026-07-12: rag-db-advisor ask --llm --model gpt-4o, condensado do original em japonês

O que a evidência consegue pesar

Cada eixo abaixo é coberto por medições ou armadilhas reproduzidas, as duas únicas coisas admitidas no store:

Tamanho do dataset medido com 10 mil e 100 mil passagens
Qualidade de retrieval recall@10, nDCG, MRR, hit@k vs gabarito humano
Latência p50 / p95 / p99 por query
Caminho de escrita segundos de carga em lote + índice
Armadilhas operacionais 3 casos reproduzidos, checados por máquina
Formato de implantação embutido vs servidor, tabelas separadas

Filtragem por metadados, busca híbrida e estimativas de custo ficam fora da evidência da v0.1, então o advisor devolve erro em vez de improvisar sobre elas. O escopo medido é honesto sobre as próprias bordas.

Para quem é

Engenheiros de IA que precisam de um número citável para o "por que este banco" de um documento de design
Desenvolvedores de RAG que depuram "a busca parece lenta" e querem descartar as armadilhas conhecidas primeiro
Usuários do Claude Code que querem respostas sobre o stack de RAG ancoradas em evidência, sem depender do conhecimento prévio do modelo
Tech leads que revisam uma proposta de banco vetorial e checam o que os números significam de verdade

Quando usar

Antes de escolher um banco para uma nova feature de RAG: comece por medições nas mesmas condições em vez de material de fornecedor
Quando a busca vetorial do ClickHouse "parece lenta": o catálogo de armadilhas reproduzidas existe exatamente para essa impressão
Quando a revisão pergunta "por que Qdrant?": responda com blocos de evidência que carregam os IDs dos registros de origem
No meio da implementação no Claude Code: seu LLM puxa a evidência via MCP sem sair da sessão

Instalação

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

A chave de API é usada apenas para embeddings (text-embedding-3-small). Via MCP não precisa de chave de geração no servidor: o servidor devolve a evidência e o seu LLM escreve a resposta.

O que ele sabe

18 registros do bench 36 chunks de notas Store de 54 chunks Se não foi medido nem vivido, não entra. advise / compare / traps

Registros de medição: 9 configurações de backend × 2 escalas de corpus (10 mil / 100 mil passagens MIRACL-ja, 860 queries anotadas por humanos), cada registro com qualidade, latência, ingestão e verificação de índice
Notas operacionais: 8 arquivos escritos à mão, um por backend mais princípios transversais, cobrindo apenas comportamento reproduzido durante o trabalho do bench
Catálogo de armadilhas: 3 formas de um backend degradar sem levantar nenhum erro, cada uma reproduzida, corrigida e documentada
Ressalvas de metodologia embutidas nas respostas: latência de backend embutido e de servidor se mede em condições distintas, e os números vêm de MIRACL-ja + text-embedding-3-small em um único nó
3 ferramentas MCP: advise (busca de evidência), compare_backends (tabela comparativa 10k/100k), list_traps (armadilhas por backend). Falhas retornam {"error", "hint"} em vez de exceção

Uma amostra do catálogo de armadilhas

Três dos sete backends traziam um caminho para degradar sem levantar nenhum erro. Os três foram pisados durante o trabalho do bench, reproduzidos e só então escritos na base de conhecimento:

Backend	O que acontece	O que você vê	Checagem por máquina
ClickHouse	Esqueça a flag allow_experimental_vector_similarity_index na hora da query e o HNSW vira força bruta em silêncio	"HNSW" a 27 ms vs força bruta a 31 ms: quase iguais	EXPLAIN indexes=1 mostra se o skip index rodou
Qdrant	Segmentos abaixo de 20 MB não recebem índice HNSW por padrão (indexing_threshold)	Status green, indexed_vectors_count = 0, toda query faz full scan	Confirmar indexed_vectors_count == points_count
Milvus	O caminho de quick-setup descarta index_params em silêncio e constrói AUTOINDEX	Você especificou HNSW; o describe_index diz AUTOINDEX	Checar index_type via describe_index após a criação

fonte: knowledge/ja/clickhouse.md · qdrant.md · milvus.md (reproduzidas antes de documentadas)

Conselhos que a evidência de fato muda

Dois exemplos de respostas que viram do avesso quando você olha medições em vez de datasheets:

Quantização por padrão

recall@10 0.983 → 0.901

Mesmo corpus de 10 mil, mesmos embeddings: a melhor configuração de HNSW puro vs LanceDB IVF_HNSW_SQ, cuja quantização embutida custa 8 pontos de recall (19 a 100 mil). Leia "a quantização entra em ação?", e deixe de lado o "está escrito HNSW?".

fonte: knowledge/ja/lancedb.md, cross-cutting.md

O planner, e o índice fica de fora

2.048 linhas: seq scan · 4.096 linhas: index scan

O pgvector constrói seu índice HNSW e depois o planner do Postgres o ignora abaixo de alguns milhares de linhas (medido com ef_search=100). Veredito de "HNSW parece lento" em escala pequena costuma ser isso.

fonte: knowledge/ja/pgvector.md

Uso

# somente evidência
rag-db-advisor ask "pgvector or Qdrant for 100k Japanese docs?"

# + síntese com OpenAI (modelo padrão: gpt-4o-mini)
rag-db-advisor ask "ClickHouse vector search feels slow. What should I check?" --llm

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

Captura de tela do terminal: rag-db-advisor responde uma pergunta em japonês, cada bloco de evidência encabeçado pelo seu ID de chunk e registro de origem, com linhas medidas de recall, latência e verificação de índice — Como é uma resposta: cada bloco declara seu ID de chunk e sua fonte, então cada afirmação rastreia até um registro.

Recusar é uma funcionalidade

O modo de falha contra o qual esta ferramenta foi construída: a camada de retrieval quebra, o LLM chamador responde em silêncio com conhecimento prévio e ninguém percebe. Por isso o advisor falha fechado:

Falhas de busca retornam um {"error", "hint"} explícito nas três ferramentas MCP; exceções nunca são engolidas em prosa
Um resultado vazio também é erro, e deixa de ser resposta nula: o modelo chamador vê "sem evidência" em vez de "sem problema, deixa eu chutar"
Nenhum veredito é gerado por dentro: o advisor busca, seu LLM (ou você) sintetiza, e as fontes seguem anexadas

Cada chunk rastreia até um registro do bench empacotado (knowledge/results/*.jsonl) ou uma nota escrita à mão sobre comportamento reproduzido (knowledge/ja/*.md). Conselho especulativo fica fora do escopo por política.

Dogfooding: a camada de retrieval importa a própria abstração BaseRetriever do rag-retriever-bench e guarda o conhecimento no Chroma, porque os dados do bench mostram que todos os backends de HNSW puro empatam em qualidade nessa escala de corpus. O advisor segue o próprio conselho.

Por que esta ferramenta existe

Construindo o rag-retriever-bench, ficou claro que os números são a parte durável: caem em JSONL e relatórios e ficam lá. O que evaporava era o conhecimento operacional ao redor deles: a flag que desativa um índice em silêncio, o threshold que deixa uma coleção sem índice atrás de um status green. Opiniões sobre bancos de dados não se reproduzem; medições e armadilhas reproduzidas, sim. Então este advisor fecha o ciclo: medir, destilar o que foi medido e vivido em uma base de conhecimento, e servir isso à próxima pergunta. E quando não há evidência, ele diz que não há em vez de chutar.

Ao lado de um chat de LLM e do ann-benchmarks

Ferramentas diferentes respondem "qual banco vetorial?" de formas diferentes. A diferença honesta é de onde vem a resposta:

	rag-db-advisor	Perguntar direto a um LLM	ann-benchmarks
Base da resposta	Medições empacotadas + armadilhas reproduzidas	Conhecimento prévio do modelo; fontes não rastreáveis	Execuções públicas de benchmark de ANN
Escopo	Backends de retrieval para RAG em um corpus de texto japonês (MIRACL-ja)	Qualquer coisa	Algoritmos e motores de ANN em datasets padrão (glove, sift etc.)
Armadilhas operacionais	✓ 3 casos reproduzidos com checagens por máquina	—	—
Quando falta evidência	Erro explícito (fail-closed)	Responde mesmo assim	—
Como se usa	Ferramentas MCP + CLI	Chat	Gráficos na web

O travessão indica que a opção não cobre aquele eixo, e cobrir menos eixos não a torna pior: um chat de LLM é mais amplo e o ann-benchmarks é a referência para desempenho bruto de ANN. Este advisor é estreito de propósito: uma família de corpus, um modelo de embedding, e cada afirmação rastreável a um registro.

FAQ

Preciso de uma chave da API da OpenAI?

Sim, apenas para embeddings (text-embedding-3-small): queries e chunks são embeddados pela API da OpenAI. Via MCP o servidor dispensa chave de geração: seu LLM escreve a resposta. A flag opcional --llm adiciona síntese com OpenAI (gpt-4o-mini por padrão).

Minha pergunta é enviada para algum lugar?

O texto da pergunta vai à API de embeddings da OpenAI para ser embeddado; a base de conhecimento em si é local (Chroma, em disco). Com --llm, a pergunta e a evidência também vão à API de chat da OpenAI para a síntese. Via MCP, a síntese acontece no LLM que você já usa.

Posso perguntar em inglês (ou português)?

A busca funciona entre idiomas porque roda sobre similaridade de embeddings, porém a base de conhecimento em si está escrita em japonês, tanto as notas quanto os registros renderizados. Via MCP seu LLM traduz a evidência ao escrever a resposta. Conhecimento nativo em outros idiomas ainda não vem na v0.1.

Quanta evidência há lá dentro, exatamente?

54 chunks na v0.1: 18 registros de medição (9 configurações de backend × 2 escalas de corpus do rag-retriever-bench) mais 36 chunks de 8 notas operacionais escritas à mão. Se não foi medido nem vivido de verdade, não está lá.

Posso simplesmente seguir o conselho dele para a minha carga de trabalho?

Trate como um ponto de partida medido, e deixe o veredito para depois: os números são de MIRACL-ja + text-embedding-3-small em um único nó, e as próprias respostas carregam essa ressalva. Para o seu corpus e a sua infraestrutura, rode o rag-retriever-bench: ele existe exatamente para isso.

O que acontece quando não há evidência para a minha pergunta?

Você recebe um erro explícito, e chute nenhum. As três ferramentas MCP retornam {"error", "hint"} em caso de falha, e um resultado vazio também é tratado como erro, então o LLM chamador fica sem caminho para cair em silêncio no conhecimento prévio.

Posso adicionar meu próprio conhecimento?

Pode: docs/adding-knowledge.md descreve o formato das notas e dos registros de medição. A política da casa continua valendo: escreva apenas comportamento que você mediu ou reproduziu.

Por que ele não gera a resposta sozinho?

Reprodutibilidade. Se o advisor rodasse o próprio LLM, a mesma pergunta poderia receber vereditos diferentes entre execuções. Devolvendo evidência determinística e deixando a síntese para o LLM chamador, os números só mudam quando o bench é rodado de novo, e cada afirmação mantém sua fonte anexada.

Sobre o autor

Criado por Ken Imoto: mais de 300 artigos técnicos em Zenn, Qiita, Dev.to e neste site, mais de 40 livros em 4 idiomas, mais de 400 mil pageviews em Zenn e Qiita, 4 artigos de pesquisa no Zenodo e criador do LLMO Framework.

Relacionado

Toda a evidência vem do rag-retriever-bench, o harness de benchmark que mede o mesmo corpus e as mesmas queries em 9 configurações de backend.

Ferramentas relacionadas para devs

Todos os produtos →

← Todos os produtos