"Vamos colocar uma IA pra responder perguntas sobre o nosso código." A frase parece simples, e um protótipo sai numa tarde: joga uns arquivos num embedding, guarda num índice, faz a busca. Funciona na demo.
O problema aparece quando isso vira produto: respostas inconsistentes, vetores que não batem com o banco, cada cliente vendo dados do outro, e um acoplamento total a um provedor de LLM. O que separa o protótipo do produto é o encanamento — e ele é mais chato do que parece.
1. A dimensão do vetor é um contrato (e quase ninguém trata)
O erro de RAG mais silencioso: você indexa com um modelo de embeddings de 1536 dimensões, depois troca para um de 768, e o banco continua esperando vector(1536). Nada explode na cara — as buscas só ficam sutilmente erradas.
A coluna do banco e o modelo são um contrato. Trate como tal: valide no arranque.
# Probe de arranque: materializa um embedding e falha cedo se a dimensão divergir {#probe-de-arranque-materializa-um-embedding-e-falha-cedo-se-a-dimensão-divergir data-source-line="528"}
vetor = embedding_provider.embed("amostra")
assert len(vetor) == EMBEDDING_DIMENSION, "Dimensão do modelo != vector(N) no banco"
{data-source-line="531"}
Falhar no boot é infinitamente melhor que descobrir semanas depois que a busca semântica está degradada.
2. O provedor de LLM não pode estar grudado no domínio
No protótipo, a chamada à OpenAI fica no meio da regra. Aí você quer rodar local para testar sem custo, ou trocar para um modelo self-hosted, e percebe que o provedor está espalhado por toda parte.
A saída é uma porta (hexagonal): o domínio fala com uma interface; os adaptadores implementam cada provedor.
public interface LlmGateway {
String complete(String prompt);
}
// local (determinístico, sem custo) | openai | ollama — escolhidos por configuração
{data-source-line="546"}
Com isso, provider=local roda em dev sem chave nem rede, e produção troca para openai ou ollama sem tocar no núcleo. Testes ficam determinísticos; custo de dev vai a zero.
3. Multitenancy desde o primeiro embedding
Se a ferramenta vai servir mais de um time ou cliente, o isolamento precisa existir desde a ingestão — não dá para "adicionar depois". Cada chunk, cada vetor, cada consulta carrega o tenant_id. Uma busca vetorial sem filtro de tenant é um vazamento de dados esperando para acontecer.
4. RAG sozinho não basta: combine com análise estática
Embeddings respondem "o que o código diz". Mas um diagnóstico de arquitetura útil também precisa de fatos determinísticos: este endpoint do OpenAPI não tem schema de erro, esta migration não tem rollback, este Dockerfile roda como root, este pipeline não trava em vulnerabilidade.
Isso é análise estática de artefatos — código, OpenAPI, migrations, Docker, CI — e ela dá ao relatório evidências rastreáveis, não só texto plausível de LLM. A combinação (RAG contextual + análise factual) é o que torna o diagnóstico confiável.
O encanamento é o produto
Chunking, embeddings, pgvector, probe de dimensão, porta de LLM, multitenancy, analisadores de artefatos, geração de ADR com evidência — nada disso é a "feature de IA" que aparece na demo, mas é tudo que faz ela virar produto. São semanas de fundação antes da primeira resposta confiável.
Atalho
Empacotei essa fundação inteira como um boilerplate: backend Java 21/Quarkus + worker Python/FastAPI, com pipeline de RAG (chunking, embeddings, pgvector com probe de dimensão), análise estática de artefatos, geração de ADRs com evidências, troca de LLM por configuração (local/openai/ollama) e multitenancy — rodando via Docker Compose.
É o ArchLens. Se você vai construir uma ferramenta de IA sobre código, ele te entrega o encanamento pronto e uma arquitetura limpa para estender.
Já apanhou de algum desses pontos montando RAG? Conta nos comentários.
Top comments (0)