Voc\u00ea pede para o assistente de IA explicar por que um servi\u00e7o de pagamentos est\u00e1 rejeitando transa\u00e7\u00f5es acima de um determinado valor. A resposta chega fluente, bem escrita, com termos t\u00e9cnicos corretos \u2014 e completamente errada. O modelo inventou uma regra de neg\u00f3cio que nunca existiu no seu sistema, porque nunca existiu nos dados que ele viu durante o treinamento. Ele n\u00e3o leu o seu c\u00f3digo. Ele leu c\u00f3digo parecido, de outros projetos, na internet inteira, e produziu uma m\u00e9dia estat\u00edstica plaus\u00edvel daquilo que “geralmente” acontece em sistemas de pagamento. O problema n\u00e3o \u00e9 o modelo ser ruim. \u00c9 que ele nunca teve acesso \u00e0 \u00fanica fonte de verdade que importa: o seu reposit\u00f3rio.<\/p>\n
Esse \u00e9 o limite estrutural de qualquer LLM usado sozinho em contexto de desenvolvimento: conhecimento congelado no momento do treinamento, sem visibilidade sobre as decis\u00f5es arquiteturais, conven\u00e7\u00f5es internas e regras de neg\u00f3cio espec\u00edficas do projeto em que voc\u00ea trabalha. RAG \u2014 Retrieval-Augmented Generation, ou Gera\u00e7\u00e3o Aumentada por Recupera\u00e7\u00e3o \u2014 existe exatamente para fechar essa lacuna. J\u00e1 tratamos aqui a ideia geral de dar mem\u00f3ria a um assistente de IA; neste artigo o objetivo \u00e9 diferente e mais t\u00e9cnico: entender e construir, pe\u00e7a por pe\u00e7a, o pipeline que transforma um reposit\u00f3rio de c\u00f3digo em uma base de conhecimento consult\u00e1vel \u2014 chunking, embeddings, indexa\u00e7\u00e3o vetorial, recupera\u00e7\u00e3o e reranking \u2014 e onde cada uma dessas pe\u00e7as costuma quebrar na pr\u00e1tica.<\/p>\n
A confus\u00e3o mais comum entre desenvolvedores que est\u00e3o come\u00e7ando com RAG \u00e9 achar que basta jogar a documenta\u00e7\u00e3o inteira do projeto no contexto do modelo. Funciona para projetos pequenos, com contexto de algumas dezenas de milhares de tokens. Mas qualquer projeto real \u2014 com m\u00faltiplos servi\u00e7os, anos de hist\u00f3rico, milhares de arquivos \u2014 ultrapassa rapidamente at\u00e9 as janelas de contexto mais generosas dispon\u00edveis hoje. E mesmo quando cabe, jogar tudo no prompt tem um custo direto em lat\u00eancia e em dinheiro, al\u00e9m de diluir a aten\u00e7\u00e3o do modelo em informa\u00e7\u00e3o irrelevante para a pergunta espec\u00edfica que voc\u00ea fez.<\/p>\n
RAG resolve isso invertendo a l\u00f3gica: em vez de mandar tudo, voc\u00ea busca apenas os peda\u00e7os de informa\u00e7\u00e3o relevantes para a pergunta atual e injeta s\u00f3 isso no prompt. A arquitetura tem quatro etapas centrais:<\/p>\n
Segundo o material da Red Hat sobre RAG na engenharia de software<\/a>, essa abordagem tem potencial para mudar a forma como o software \u00e9 projetado justamente porque desacopla o conhecimento do modelo do conhecimento do dom\u00ednio \u2014 o modelo fornece racioc\u00ednio e linguagem, a base vetorial fornece fatos atualizados e espec\u00edficos do seu contexto.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> antes de implementar RAG do zero, vale entender a diferen\u00e7a entre RAG, workflows e agentes \u2014 s\u00e3o padr\u00f5es arquiteturais distintos com trade-offs diferentes de custo, lat\u00eancia e controle. O conte\u00fado do perfil IA e Dados sobre RAG, Workflow ou Agente<\/a> resume bem quando escolher cada um antes de voc\u00ea investir semanas construindo a pe\u00e7a errada.<\/p><\/blockquote>\n Se existe um \u00fanico ponto do pipeline onde a maioria dos projetos erra, \u00e9 o chunking. A tenta\u00e7\u00e3o \u00e9 dividir o texto em blocos de tamanho fixo \u2014 por exemplo, a cada 500 caracteres \u2014 sem se importar com a estrutura sem\u00e2ntica do conte\u00fado. O resultado \u00e9 previs\u00edvel: um chunk pode terminar no meio de uma fun\u00e7\u00e3o, cortando a assinatura do m\u00e9todo fora do corpo, ou misturar o final de uma classe com o in\u00edcio de outra completamente n\u00e3o relacionada.<\/p>\n Para c\u00f3digo-fonte, a estrat\u00e9gia correta \u00e9 fazer chunking respeitando a estrutura sint\u00e1tica da linguagem \u2014 dividir por fun\u00e7\u00e3o, por classe, ou por bloco l\u00f3gico, preservando coment\u00e1rios e docstrings junto ao c\u00f3digo que eles documentam. Um exemplo em Python usando limites de fun\u00e7\u00e3o como unidade de chunk:<\/p>\n Para arquiteturas mais amplas \u2014 como equipes que usam o ecossistema Java com Spring AI, conforme demonstrado no projeto de refer\u00eancia apresentado em v\u00eddeo sobre RAG<\/a> \u2014 a l\u00f3gica \u00e9 a mesma, mudando apenas a ferramenta de parsing. O importante \u00e9 o princ\u00edpio: chunk pequeno demais perde contexto, chunk grande demais dilui a relev\u00e2ncia na busca vetorial e aumenta custo de tokens no prompt final. Na pr\u00e1tica, para c\u00f3digo, algo entre 200 e 800 tokens por chunk costuma equilibrar bem os dois lados, mas isso deve ser calibrado empiricamente no seu dom\u00ednio, nunca copiado de um tutorial gen\u00e9rico.<\/p>\n Cada chunk deve carregar metadados que permitam filtragem posterior: caminho do arquivo, linguagem, m\u00f3dulo, data da \u00faltima modifica\u00e7\u00e3o, autor. Sem isso, voc\u00ea perde a capacidade de restringir a busca \u2014 por exemplo, “busque apenas em c\u00f3digo de produ\u00e7\u00e3o, ignore os testes” ou “priorize arquivos modificados nos \u00faltimos tr\u00eas meses”.<\/p>\n Um embedding \u00e9 um vetor de n\u00fameros de ponto flutuante que representa o significado sem\u00e2ntico de um trecho de texto em um espa\u00e7o multidimensional. Trechos com significados parecidos ficam geometricamente pr\u00f3ximos nesse espa\u00e7o, mesmo que usem palavras completamente diferentes. \u00c9 essa propriedade que permite buscar “como funciona a autentica\u00e7\u00e3o” e encontrar um chunk que fala sobre “valida\u00e7\u00e3o de token JWT”, sem que as duas frases compartilhem nenhuma palavra em comum.<\/p>\n Um erro comum aqui \u00e9 misturar modelos de embedding diferentes no mesmo \u00edndice \u2014 por exemplo, indexar parte do conte\u00fado com um modelo e depois trocar de modelo sem reindexar tudo. Vetores gerados por modelos diferentes n\u00e3o s\u00e3o compar\u00e1veis entre si; a dist\u00e2ncia matem\u00e1tica entre eles n\u00e3o tem significado sem\u00e2ntico algum. Se voc\u00ea trocar de modelo de embedding, a reindexa\u00e7\u00e3o completa da base n\u00e3o \u00e9 opcional.<\/p>\n Com os vetores em m\u00e3os, \u00e9 preciso armazen\u00e1-los em uma estrutura otimizada para busca por similaridade \u2014 geralmente por dist\u00e2ncia de cosseno ou produto interno. Bancos de dados vetoriais como PostgreSQL<\/a> com a extens\u00e3o pgvector, ou solu\u00e7\u00f5es dedicadas, resolvem esse problema usando \u00edndices aproximados (ANN \u2014 Approximate Nearest Neighbor), que trocam precis\u00e3o perfeita por velocidade em escala.<\/p>\n Um ponto que costuma pegar equipes de surpresa: o \u00edndice HNSW \u00e9 aproximado por natureza. Em bases pequenas, isso raramente \u00e9 percept\u00edvel. Em bases com milh\u00f5es de chunks, a taxa de recall pode cair o suficiente para que resultados relevantes simplesmente n\u00e3o apare\u00e7am no topo. Monitorar a qualidade da recupera\u00e7\u00e3o \u2014 n\u00e3o apenas a qualidade da resposta final \u2014 \u00e9 parte do trabalho de manuten\u00e7\u00e3o de um sistema RAG em produ\u00e7\u00e3o.<\/p>\n Aqui mora a armadilha mais sutil de todas. Similaridade vetorial n\u00e3o \u00e9 sin\u00f4nimo de relev\u00e2ncia. Um chunk pode ter alta similaridade sem\u00e2ntica com a pergunta e ainda assim ser in\u00fatil para respond\u00ea-la \u2014 por exemplo, uma fun\u00e7\u00e3o com nome parecido, mas de um m\u00f3dulo legado que j\u00e1 n\u00e3o \u00e9 mais usado no fluxo principal.<\/p>\n A solu\u00e7\u00e3o pr\u00e1tica, usada em pipelines RAG maduros, \u00e9 um processo em duas etapas: recupera\u00e7\u00e3o inicial ampla (buscar os 20 ou 30 chunks mais pr\u00f3ximos) seguida de reranking, um segundo modelo \u2014 geralmente mais caro por item, por\u00e9m mais preciso \u2014 que reordena esses candidatos por relev\u00e2ncia real \u00e0 pergunta antes de enviar apenas os 3 a 5 melhores para o modelo de gera\u00e7\u00e3o.<\/p>\n Repare na instru\u00e7\u00e3o expl\u00edcita dentro do prompt: “se a informa\u00e7\u00e3o n\u00e3o estiver no contexto, diga explicitamente que n\u00e3o encontrou”. Sem essa restri\u00e7\u00e3o, o modelo tende a preencher lacunas com conhecimento gen\u00e9rico do treinamento \u2014 reintroduzindo exatamente o problema que o RAG deveria resolver.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> ver o pipeline completo sendo constru\u00eddo ao vivo ajuda muito mais do que ler sobre ele isoladamente. A sess\u00e3o LIVE CODING sobre IA, RAG e MCP aplicados em projeto real<\/a> mostra as decis\u00f5es de arquitetura sendo tomadas em tempo real, incluindo os erros de percurso que normalmente ficam de fora dos tutoriais polidos.<\/p><\/blockquote>\n Depois de colocar um sistema RAG em produ\u00e7\u00e3o, os problemas que aparecem raramente est\u00e3o na camada de gera\u00e7\u00e3o \u2014 est\u00e3o na recupera\u00e7\u00e3o. Um roteiro de depura\u00e7\u00e3o eficiente segue esta ordem:<\/p>\n Nesse caso, o problema \u00e9 o modelo de gera\u00e7\u00e3o ignorando ou interpretando mal o contexto fornecido. Verifique o tamanho do prompt final \u2014 contexto excessivamente longo dilui a aten\u00e7\u00e3o do modelo mesmo quando a informa\u00e7\u00e3o certa est\u00e1 l\u00e1. Reduza o n\u00famero de chunks enviados e teste novamente.<\/p>\n O problema est\u00e1 na etapa de embedding ou de busca. Teste a query isoladamente contra o \u00edndice e observe manualmente os top 10 resultados. Frequentemente o problema \u00e9 chunking mal feito \u2014 informa\u00e7\u00e3o fragmentada de forma que nenhum chunk isolado cont\u00e9m contexto suficiente para ser considerado relevante.<\/p>\n Verifique se o conte\u00fado foi de fato indexado \u2014 pipelines de ingest\u00e3o que falham silenciosamente em arquivos espec\u00edficos (encoding, arquivos bin\u00e1rios disfar\u00e7ados de texto, arquivos muito grandes) s\u00e3o mais comuns do que parecem. Log de ingest\u00e3o com contagem de chunks por arquivo \u00e9 a primeira linha de defesa.<\/p>\n RAG sobre c\u00f3digo exige reindexa\u00e7\u00e3o cont\u00ednua. Um pipeline de ingest\u00e3o acoplado a hooks de commit ou pull request evita que a base de conhecimento fique defasada em rela\u00e7\u00e3o ao c\u00f3digo real \u2014 o pior cen\u00e1rio poss\u00edvel \u00e9 um RAG que responde com confian\u00e7a sobre uma vers\u00e3o do sistema que j\u00e1 n\u00e3o existe mais.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> para uma vis\u00e3o panor\u00e2mica do que todo desenvolvedor precisa saber sobre RAG neste momento \u2014 incluindo tend\u00eancias de arquitetura que est\u00e3o se consolidando \u2014 vale assistir RAG with AI: What every Dev needs to know<\/a>, que tamb\u00e9m traz uma implementa\u00e7\u00e3o pr\u00e1tica no ecossistema Java com Spring AI.<\/p><\/blockquote>\n A utilidade pr\u00e1tica de um RAG bem constru\u00eddo aparece quando ele deixa de ser um experimento isolado e passa a alimentar as ferramentas que voc\u00ea j\u00e1 usa no dia a dia \u2014 seja via MCP (Model Context Protocol) conectando o assistente diretamente \u00e0 base vetorial, seja como uma API interna consultada por scripts de automa\u00e7\u00e3o, revis\u00e3o de c\u00f3digo ou gera\u00e7\u00e3o de documenta\u00e7\u00e3o. O ganho real n\u00e3o \u00e9 ter uma “IA que sabe sobre o projeto” em abstrato, mas ter respostas rastre\u00e1veis, com cita\u00e7\u00e3o da fonte exata no reposit\u00f3rio, o que transforma a IA de gerador de texto plaus\u00edvel em ferramenta de consulta confi\u00e1vel.<\/p>\n Times que est\u00e3o estruturando trilhas de capacita\u00e7\u00e3o em IA aplicada \u2014 como demonstrado na proposta de trilha de IA voltada para levar RAG a outro n\u00edvel<\/a> \u2014 costumam come\u00e7ar exatamente por esse ponto: n\u00e3o pelo modelo mais avan\u00e7ado, mas pela qualidade da base de recupera\u00e7\u00e3o que o alimenta. \u00c9 um investimento de infraestrutura, n\u00e3o de prompt.<\/p>\n Construir um pipeline de RAG que realmente funciona em produ\u00e7\u00e3o exige decis\u00f5es t\u00e9cnicas que n\u00e3o cabem inteiramente em um \u00fanico artigo \u2014 calibragem de chunk size para a sua base espec\u00edfica, escolha entre bancos vetoriais dedicados e extens\u00f5es sobre bancos relacionais, estrat\u00e9gias de reranking sob restri\u00e7\u00e3o de custo. Essas decis\u00f5es ficam muito mais r\u00e1pidas quando discutidas com quem j\u00e1 passou pelos mesmos impasses. Na Comunidade Dev’s AI<\/a> essa troca acontece de forma cont\u00ednua, entre desenvolvedores aplicando IA em projetos reais \u2014 do chunking de c\u00f3digo legado at\u00e9 a arquitetura de agentes que consultam bases vetoriais como parte de um fluxo maior de automa\u00e7\u00e3o. Se voc\u00ea est\u00e1 construindo ou j\u00e1 mant\u00e9m um sistema RAG em produ\u00e7\u00e3o, vale a pena participar.<\/p>\n RAG n\u00e3o \u00e9 uma t\u00e9cnica de prompt engineering nem um recurso m\u00e1gico embutido em algum modelo \u2014 \u00e9 uma pe\u00e7a de infraestrutura de dados que precisa ser projetada, testada e mantida com o mesmo rigor que qualquer outro componente cr\u00edtico do seu sistema. Chunking mal feito produz recupera\u00e7\u00e3o ruim. Recupera\u00e7\u00e3o ruim produz contexto irrelevante. Contexto irrelevante produz respostas erradas com apar\u00eancia de certeza \u2014 o cen\u00e1rio mais perigoso de todos, porque \u00e9 justamente o que engana desenvolvedores apressados. Dominar cada etapa do pipeline, do chunking ao reranking, \u00e9 o que separa um assistente de IA que realmente conhece o seu projeto de um que apenas finge conhecer.<\/p>\n","protected":false},"excerpt":{"rendered":" Voc\u00ea pede para o assistente de IA explicar por que um servi\u00e7o de pagamentos est\u00e1 rejeitando transa\u00e7\u00f5es acima de um determinado valor. A resposta chega fluente, bem escrita, com termos t\u00e9cnicos corretos \u2014 e completamente errada. O modelo inventou uma regra de neg\u00f3cio que nunca existiu no seu sistema, porque nunca existiu nos dados que […]<\/p>\n","protected":false},"author":127,"featured_media":1259,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-1258","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blog"],"_links":{"self":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts\/1258","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/users\/127"}],"replies":[{"embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/comments?post=1258"}],"version-history":[{"count":1,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts\/1258\/revisions"}],"predecessor-version":[{"id":1260,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts\/1258\/revisions\/1260"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/media\/1259"}],"wp:attachment":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/media?parent=1258"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/categories?post=1258"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/tags?post=1258"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Chunking: a decis\u00e3o que mais impacta a qualidade do RAG<\/h2>\n
import ast\n\ndef extrair_chunks_por_funcao(caminho_arquivo: str) -> list[dict]:\n \"\"\"Divide um arquivo Python em chunks por fun\u00e7\u00e3o\/m\u00e9todo,\n preservando docstring e assinatura no mesmo chunk.\"\"\"\n with open(caminho_arquivo, \"r\", encoding=\"utf-8\") as f:\n codigo_fonte = f.read()\n\n arvore = ast.parse(codigo_fonte)\n linhas = codigo_fonte.splitlines()\n chunks = []\n\n for node in ast.walk(arvore):\n if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):\n inicio = node.lineno - 1\n fim = node.end_lineno\n trecho = \"\\n\".join(linhas[inicio:fim])\n\n chunks.append({\n \"conteudo\": trecho,\n \"tipo\": \"funcao\",\n \"nome\": node.name,\n \"arquivo\": caminho_arquivo,\n \"linha_inicio\": node.lineno,\n })\n\n return chunks\n<\/code><\/pre>\nMetadados importam tanto quanto o conte\u00fado<\/h3>\n
Embeddings: transformando texto em geometria<\/h2>\n
from openai import OpenAI\n\nclient = OpenAI()\n\ndef gerar_embedding(texto: str) -> list[float]:\n resposta = client.embeddings.create(\n model=\"text-embedding-3-small\",\n input=texto\n )\n return resposta.data[0].embedding\n\n# Cada chunk do reposit\u00f3rio vira um vetor de ~1536 dimens\u00f5es\nchunk_codigo = \"\"\"\ndef validar_transacao(valor: float, limite_diario: float) -> bool:\n saldo_usado = obter_saldo_usado_hoje()\n return (saldo_usado + valor) <= limite_diario\n"""\n\nvetor = gerar_embedding(chunk_codigo)\nprint(len(vetor)) # 1536\n<\/code><\/pre>\nIndexa\u00e7\u00e3o vetorial: onde os vetores moram e como s\u00e3o buscados<\/h2>\n
-- Exemplo usando PostgreSQL com extens\u00e3o pgvector\nCREATE EXTENSION IF NOT EXISTS vector;\n\nCREATE TABLE chunks_codigo (\n id SERIAL PRIMARY KEY,\n conteudo TEXT NOT NULL,\n arquivo VARCHAR(500),\n tipo VARCHAR(50),\n embedding vector(1536)\n);\n\n-- \u00cdndice HNSW para busca aproximada eficiente\nCREATE INDEX idx_embedding_hnsw\n ON chunks_codigo\n USING hnsw (embedding vector_cosine_ops);\n\n-- Busca pelos 5 chunks mais similares a uma pergunta\nSELECT arquivo, conteudo,\n 1 - (embedding '[0.012, -0.034, ...]') AS similaridade\nFROM chunks_codigo\nORDER BY embedding '[0.012, -0.034, ...]'\nLIMIT 5;\n<\/code><\/pre>\nRecupera\u00e7\u00e3o e reranking: nem tudo que \u00e9 similar \u00e9 relevante<\/h2>\n
def pipeline_rag(pergunta: str, top_k_inicial: int = 20, top_k_final: int = 5):\n # 1. Recupera\u00e7\u00e3o ampla por similaridade vetorial\n embedding_pergunta = gerar_embedding(pergunta)\n candidatos = buscar_chunks_similares(embedding_pergunta, limite=top_k_inicial)\n\n # 2. Reranking com modelo especializado em relev\u00e2ncia\n candidatos_reordenados = reranker.rerank(\n query=pergunta,\n documentos=[c[\"conteudo\"] for c in candidatos],\n top_n=top_k_final\n )\n\n # 3. Montagem do prompt final com contexto filtrado\n contexto = \"\\n\\n---\\n\\n\".join(\n f\"Arquivo: {c['arquivo']}\\n{c['conteudo']}\"\n for c in candidatos_reordenados\n )\n\n prompt = f\"\"\"Use apenas o contexto abaixo, extra\u00eddo do reposit\u00f3rio real,\npara responder \u00e0 pergunta. Se a informa\u00e7\u00e3o n\u00e3o estiver no contexto,\ndiga explicitamente que n\u00e3o encontrou.\n\nContexto:\n{contexto}\n\nPergunta: {pergunta}\n\"\"\"\n return chamar_modelo_geracao(prompt)\n<\/code><\/pre>\nOnde o RAG quebra na pr\u00e1tica (e como depurar)<\/h2>\n
1. A resposta est\u00e1 errada, mas o contexto recuperado \u00e9 correto<\/h3>\n
2. O contexto recuperado \u00e9 irrelevante<\/h3>\n
3. Informa\u00e7\u00e3o existe no reposit\u00f3rio, mas nunca aparece nos resultados<\/h3>\n
4. A base ficou desatualizada<\/h3>\n
Integrando o RAG ao fluxo real de desenvolvimento<\/h2>\n
Leve essa discuss\u00e3o para quem j\u00e1 est\u00e1 no caminho<\/h2>\n
Conclus\u00e3o<\/h2>\n