O Vetor Que Faltava: Construindo uma Base de Conhecimento Vetorial Para Sua IA Não Chutar Respostas Sobre o Seu Código

Você pede para o assistente de IA explicar por que um serviço de pagamentos está rejeitando transações acima de um determinado valor. A resposta chega fluente, bem escrita, com termos técnicos corretos — e completamente errada. O modelo inventou uma regra de negócio que nunca existiu no seu sistema, porque nunca existiu nos dados que ele viu durante o treinamento. Ele não leu o seu código. Ele leu código parecido, de outros projetos, na internet inteira, e produziu uma média estatística plausível daquilo que “geralmente” acontece em sistemas de pagamento. O problema não é o modelo ser ruim. É que ele nunca teve acesso à única fonte de verdade que importa: o seu repositório.

Esse é o limite estrutural de qualquer LLM usado sozinho em contexto de desenvolvimento: conhecimento congelado no momento do treinamento, sem visibilidade sobre as decisões arquiteturais, convenções internas e regras de negócio específicas do projeto em que você trabalha. RAG — Retrieval-Augmented Generation, ou Geração Aumentada por Recuperação — existe exatamente para fechar essa lacuna. Já tratamos aqui a ideia geral de dar memória a um assistente de IA; neste artigo o objetivo é diferente e mais técnico: entender e construir, peça por peça, o pipeline que transforma um repositório de código em uma base de conhecimento consultável — chunking, embeddings, indexação vetorial, recuperação e reranking — e onde cada uma dessas peças costuma quebrar na prática.

RAG não é “colar documentos no prompt”

A confusão mais comum entre desenvolvedores que estão começando com RAG é achar que basta jogar a documentação inteira do projeto no contexto do modelo. Funciona para projetos pequenos, com contexto de algumas dezenas de milhares de tokens. Mas qualquer projeto real — com múltiplos serviços, anos de histórico, milhares de arquivos — ultrapassa rapidamente até as janelas de contexto mais generosas disponíveis hoje. E mesmo quando cabe, jogar tudo no prompt tem um custo direto em latência e em dinheiro, além de diluir a atenção do modelo em informação irrelevante para a pergunta específica que você fez.

RAG resolve isso invertendo a lógica: em vez de mandar tudo, você busca apenas os pedaços de informação relevantes para a pergunta atual e injeta só isso no prompt. A arquitetura tem quatro etapas centrais:

• Ingestão e chunking: quebrar o material-fonte (código, documentação, ADRs, tickets) em pedaços menores e semanticamente coerentes.
• Embedding: transformar cada pedaço em um vetor numérico que representa seu significado em um espaço matemático.
• Indexação vetorial: armazenar esses vetores em uma estrutura que permite busca por similaridade em escala.
• Recuperação e geração: no momento da pergunta, buscar os vetores mais próximos e usá-los como contexto para o modelo gerar a resposta.

Segundo o material da Red Hat sobre RAG na engenharia de software, essa abordagem tem potencial para mudar a forma como o software é projetado justamente porque desacopla o conhecimento do modelo do conhecimento do domínio — o modelo fornece raciocínio e linguagem, a base vetorial fornece fatos atualizados e específicos do seu contexto.

💡 Dica do Mestre: antes de implementar RAG do zero, vale entender a diferença entre RAG, workflows e agentes — são padrões arquiteturais distintos com trade-offs diferentes de custo, latência e controle. O conteúdo do perfil IA e Dados sobre RAG, Workflow ou Agente resume bem quando escolher cada um antes de você investir semanas construindo a peça errada.

Chunking: a decisão que mais impacta a qualidade do RAG

Se existe um único ponto do pipeline onde a maioria dos projetos erra, é o chunking. A tentação é dividir o texto em blocos de tamanho fixo — por exemplo, a cada 500 caracteres — sem se importar com a estrutura semântica do conteúdo. O resultado é previsível: um chunk pode terminar no meio de uma função, cortando a assinatura do método fora do corpo, ou misturar o final de uma classe com o início de outra completamente não relacionada.

Para código-fonte, a estratégia correta é fazer chunking respeitando a estrutura sintática da linguagem — dividir por função, por classe, ou por bloco lógico, preservando comentários e docstrings junto ao código que eles documentam. Um exemplo em Python usando limites de função como unidade de chunk:

Para arquiteturas mais amplas — como equipes que usam o ecossistema Java com Spring AI, conforme demonstrado no projeto de referência apresentado em vídeo sobre RAG — a lógica é a mesma, mudando apenas a ferramenta de parsing. O importante é o princípio: chunk pequeno demais perde contexto, chunk grande demais dilui a relevância na busca vetorial e aumenta custo de tokens no prompt final. Na prática, para código, algo entre 200 e 800 tokens por chunk costuma equilibrar bem os dois lados, mas isso deve ser calibrado empiricamente no seu domínio, nunca copiado de um tutorial genérico.

Metadados importam tanto quanto o conteúdo

Cada chunk deve carregar metadados que permitam filtragem posterior: caminho do arquivo, linguagem, módulo, data da última modificação, autor. Sem isso, você perde a capacidade de restringir a busca — por exemplo, “busque apenas em código de produção, ignore os testes” ou “priorize arquivos modificados nos últimos três meses”.

Embeddings: transformando texto em geometria

Um embedding é um vetor de números de ponto flutuante que representa o significado semântico de um trecho de texto em um espaço multidimensional. Trechos com significados parecidos ficam geometricamente próximos nesse espaço, mesmo que usem palavras completamente diferentes. É essa propriedade que permite buscar “como funciona a autenticação” e encontrar um chunk que fala sobre “validação de token JWT”, sem que as duas frases compartilhem nenhuma palavra em comum.

Um erro comum aqui é misturar modelos de embedding diferentes no mesmo índice — por exemplo, indexar parte do conteúdo com um modelo e depois trocar de modelo sem reindexar tudo. Vetores gerados por modelos diferentes não são comparáveis entre si; a distância matemática entre eles não tem significado semântico algum. Se você trocar de modelo de embedding, a reindexação completa da base não é opcional.

Indexação vetorial: onde os vetores moram e como são buscados

Com os vetores em mãos, é preciso armazená-los em uma estrutura otimizada para busca por similaridade — geralmente por distância de cosseno ou produto interno. Bancos de dados vetoriais como PostgreSQL com a extensão pgvector, ou soluções dedicadas, resolvem esse problema usando índices aproximados (ANN — Approximate Nearest Neighbor), que trocam precisão perfeita por velocidade em escala.

Um ponto que costuma pegar equipes de surpresa: o índice HNSW é aproximado por natureza. Em bases pequenas, isso raramente é perceptível. Em bases com milhões de chunks, a taxa de recall pode cair o suficiente para que resultados relevantes simplesmente não apareçam no topo. Monitorar a qualidade da recuperação — não apenas a qualidade da resposta final — é parte do trabalho de manutenção de um sistema RAG em produção.

Recuperação e reranking: nem tudo que é similar é relevante

Aqui mora a armadilha mais sutil de todas. Similaridade vetorial não é sinônimo de relevância. Um chunk pode ter alta similaridade semântica com a pergunta e ainda assim ser inútil para respondê-la — por exemplo, uma função com nome parecido, mas de um módulo legado que já não é mais usado no fluxo principal.

A solução prática, usada em pipelines RAG maduros, é um processo em duas etapas: recuperação inicial ampla (buscar os 20 ou 30 chunks mais próximos) seguida de reranking, um segundo modelo — geralmente mais caro por item, porém mais preciso — que reordena esses candidatos por relevância real à pergunta antes de enviar apenas os 3 a 5 melhores para o modelo de geração.

Repare na instrução explícita dentro do prompt: “se a informação não estiver no contexto, diga explicitamente que não encontrou”. Sem essa restrição, o modelo tende a preencher lacunas com conhecimento genérico do treinamento — reintroduzindo exatamente o problema que o RAG deveria resolver.

💡 Dica do Mestre: ver o pipeline completo sendo construído ao vivo ajuda muito mais do que ler sobre ele isoladamente. A sessão LIVE CODING sobre IA, RAG e MCP aplicados em projeto real mostra as decisões de arquitetura sendo tomadas em tempo real, incluindo os erros de percurso que normalmente ficam de fora dos tutoriais polidos.

Onde o RAG quebra na prática (e como depurar)

Depois de colocar um sistema RAG em produção, os problemas que aparecem raramente estão na camada de geração — estão na recuperação. Um roteiro de depuração eficiente segue esta ordem:

1. A resposta está errada, mas o contexto recuperado é correto

Nesse caso, o problema é o modelo de geração ignorando ou interpretando mal o contexto fornecido. Verifique o tamanho do prompt final — contexto excessivamente longo dilui a atenção do modelo mesmo quando a informação certa está lá. Reduza o número de chunks enviados e teste novamente.

2. O contexto recuperado é irrelevante

O problema está na etapa de embedding ou de busca. Teste a query isoladamente contra o índice e observe manualmente os top 10 resultados. Frequentemente o problema é chunking mal feito — informação fragmentada de forma que nenhum chunk isolado contém contexto suficiente para ser considerado relevante.

3. Informação existe no repositório, mas nunca aparece nos resultados

Verifique se o conteúdo foi de fato indexado — pipelines de ingestão que falham silenciosamente em arquivos específicos (encoding, arquivos binários disfarçados de texto, arquivos muito grandes) são mais comuns do que parecem. Log de ingestão com contagem de chunks por arquivo é a primeira linha de defesa.

4. A base ficou desatualizada

RAG sobre código exige reindexação contínua. Um pipeline de ingestão acoplado a hooks de commit ou pull request evita que a base de conhecimento fique defasada em relação ao código real — o pior cenário possível é um RAG que responde com confiança sobre uma versão do sistema que já não existe mais.

💡 Dica do Mestre: para uma visão panorâmica do que todo desenvolvedor precisa saber sobre RAG neste momento — incluindo tendências de arquitetura que estão se consolidando — vale assistir RAG with AI: What every Dev needs to know, que também traz uma implementação prática no ecossistema Java com Spring AI.

Integrando o RAG ao fluxo real de desenvolvimento

A utilidade prática de um RAG bem construído aparece quando ele deixa de ser um experimento isolado e passa a alimentar as ferramentas que você já usa no dia a dia — seja via MCP (Model Context Protocol) conectando o assistente diretamente à base vetorial, seja como uma API interna consultada por scripts de automação, revisão de código ou geração de documentação. O ganho real não é ter uma “IA que sabe sobre o projeto” em abstrato, mas ter respostas rastreáveis, com citação da fonte exata no repositório, o que transforma a IA de gerador de texto plausível em ferramenta de consulta confiável.

Times que estão estruturando trilhas de capacitação em IA aplicada — como demonstrado na proposta de trilha de IA voltada para levar RAG a outro nível — costumam começar exatamente por esse ponto: não pelo modelo mais avançado, mas pela qualidade da base de recuperação que o alimenta. É um investimento de infraestrutura, não de prompt.

Leve essa discussão para quem já está no caminho

Construir um pipeline de RAG que realmente funciona em produção exige decisões técnicas que não cabem inteiramente em um único artigo — calibragem de chunk size para a sua base específica, escolha entre bancos vetoriais dedicados e extensões sobre bancos relacionais, estratégias de reranking sob restrição de custo. Essas decisões ficam muito mais rápidas quando discutidas com quem já passou pelos mesmos impasses. Na Comunidade Dev’s AI essa troca acontece de forma contínua, entre desenvolvedores aplicando IA em projetos reais — do chunking de código legado até a arquitetura de agentes que consultam bases vetoriais como parte de um fluxo maior de automação. Se você está construindo ou já mantém um sistema RAG em produção, vale a pena participar.

Conclusão

RAG não é uma técnica de prompt engineering nem um recurso mágico embutido em algum modelo — é uma peça de infraestrutura de dados que precisa ser projetada, testada e mantida com o mesmo rigor que qualquer outro componente crítico do seu sistema. Chunking mal feito produz recuperação ruim. Recuperação ruim produz contexto irrelevante. Contexto irrelevante produz respostas erradas com aparência de certeza — o cenário mais perigoso de todos, porque é justamente o que engana desenvolvedores apressados. Dominar cada etapa do pipeline, do chunking ao reranking, é o que separa um assistente de IA que realmente conhece o seu projeto de um que apenas finge conhecer.