{"slug": "rag-sobre-o-seu-proprio-codigo-o-encanamento-que-separa-o-prototipo-do-produto", "title": "RAG sobre o seu próprio código: o encanamento que separa o protótipo do produto", "summary": "A developer built ArchLens, a boilerplate for production-grade RAG systems over codebases, addressing common pitfalls like embedding dimension mismatches, LLM provider coupling, and multitenancy. The project includes Java 21/Quarkus and Python/FastAPI backends with static analysis of artifacts and configurable LLM providers.", "body_md": "\"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.\n\nO 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.\n\nO 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)`\n\n. Nada explode na cara — as buscas só ficam *sutilmente erradas*.\n\nA coluna do banco e o modelo são um **contrato**. Trate como tal: valide no arranque.\n\n```\n# 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\"}\nvetor = embedding_provider.embed(\"amostra\")\nassert len(vetor) == EMBEDDING_DIMENSION, \"Dimensão do modelo != vector(N) no banco\"\n```\n\n{data-source-line=\"531\"}\n\nFalhar no boot é infinitamente melhor que descobrir semanas depois que a busca semântica está degradada.\n\nNo 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.\n\nA saída é uma **porta** (hexagonal): o domínio fala com uma interface; os adaptadores implementam cada provedor.\n\n```\npublic interface LlmGateway {\n    String complete(String prompt);\n}\n// local (determinístico, sem custo) | openai | ollama — escolhidos por configuração\n```\n\n{data-source-line=\"546\"}\n\nCom isso, `provider=local`\n\nroda em dev sem chave nem rede, e produção troca para `openai`\n\nou `ollama`\n\n**sem tocar no núcleo**. Testes ficam determinísticos; custo de dev vai a zero.\n\nSe 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`\n\n. Uma busca vetorial sem filtro de tenant é um vazamento de dados esperando para acontecer.\n\nEmbeddings 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.\n\nIsso é 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.\n\nChunking, 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.\n\nEmpacotei 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.\n\nÉ 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.\n\n*Já apanhou de algum desses pontos montando RAG? Conta nos comentários.*", "url": "https://wpnews.pro/news/rag-sobre-o-seu-proprio-codigo-o-encanamento-que-separa-o-prototipo-do-produto", "canonical_source": "https://dev.to/felipe_ricartem/rag-sobre-o-seu-proprio-codigo-o-encanamento-que-separa-o-prototipo-do-produto-14kf", "published_at": "2026-06-17 16:42:37+00:00", "updated_at": "2026-06-17 16:51:28.709263+00:00", "lang": "en", "topics": ["large-language-models", "developer-tools", "ai-infrastructure"], "entities": ["ArchLens", "OpenAI", "Ollama", "Quarkus", "FastAPI", "pgvector", "Docker"], "alternates": {"html": "https://wpnews.pro/news/rag-sobre-o-seu-proprio-codigo-o-encanamento-que-separa-o-prototipo-do-produto", "markdown": "https://wpnews.pro/news/rag-sobre-o-seu-proprio-codigo-o-encanamento-que-separa-o-prototipo-do-produto.md", "text": "https://wpnews.pro/news/rag-sobre-o-seu-proprio-codigo-o-encanamento-que-separa-o-prototipo-do-produto.txt", "jsonld": "https://wpnews.pro/news/rag-sobre-o-seu-proprio-codigo-o-encanamento-que-separa-o-prototipo-do-produto.jsonld"}}