Imagine contratar um estagi\u00e1rio muito inteligente, capaz de escrever c\u00f3digo limpo e explicar conceitos complexos com clareza. H\u00e1 apenas um problema: todos os dias, ao chegar, ele esquece completamente o projeto em que est\u00e1 trabalhando. N\u00e3o lembra das regras de neg\u00f3cio, n\u00e3o sabe como as fun\u00e7\u00f5es do sistema se conectam, n\u00e3o conhece as decis\u00f5es que a equipe tomou na semana passada. Todos os dias voc\u00ea precisa reexplicar tudo do zero.<\/p>\n
Esse estagi\u00e1rio existe, e voc\u00ea provavelmente j\u00e1 trabalha com ele: \u00e9 o assistente de IA que voc\u00ea usa para programar. Modelos como os que alimentam o Claude<\/a> ou o ChatGPT s\u00e3o treinados com uma quantidade enorme de informa\u00e7\u00e3o gen\u00e9rica sobre programa\u00e7\u00e3o, mas eles n\u00e3o nascem sabendo nada sobre o seu projeto espec\u00edfico \u2014 sua arquitetura, suas conven\u00e7\u00f5es, suas regras internas. Sem esse conhecimento, a IA improvisa, e improvisar em cima de um sistema real custa caro: sugest\u00f5es que ignoram padr\u00f5es j\u00e1 definidos, c\u00f3digo duplicado porque a IA n\u00e3o sabia que aquela fun\u00e7\u00e3o j\u00e1 existia, ou respostas gen\u00e9ricas quando voc\u00ea precisava de algo espec\u00edfico do seu dom\u00ednio.<\/p>\n \u00c9 exatamente esse problema que a t\u00e9cnica chamada RAG<\/strong> (Retrieval-Augmented Generation, ou “Gera\u00e7\u00e3o Aumentada por Recupera\u00e7\u00e3o”) resolve. Neste artigo, voc\u00ea vai entender o que \u00e9 RAG, como ela funciona por baixo dos panos e vai construir, passo a passo, um exemplo funcional que d\u00e1 \u00e0 IA acesso ao contexto real de um projeto \u2014 sem precisar copiar e colar arquivos inteiros toda vez que fizer uma pergunta.<\/p>\n RAG \u00e9 a combina\u00e7\u00e3o de duas etapas: recupera\u00e7\u00e3o<\/strong> (retrieval) de informa\u00e7\u00e3o relevante e gera\u00e7\u00e3o<\/strong> (generation) de uma resposta usando essa informa\u00e7\u00e3o como apoio. Em vez de perguntar diretamente ao modelo de IA e esperar que ele “adivinhe” a resposta com base apenas no que aprendeu durante o treinamento, voc\u00ea primeiro busca em uma base de dados pr\u00f3pria \u2014 pode ser a documenta\u00e7\u00e3o do seu projeto, o c\u00f3digo-fonte, tickets de suporte, atas de reuni\u00e3o \u2014 os trechos mais relevantes para a pergunta feita. Depois, voc\u00ea entrega esses trechos junto com a pergunta para o modelo, que ent\u00e3o gera uma resposta fundamentada nesse material.<\/p>\n \u00c9 como transformar aquele estagi\u00e1rio amn\u00e9sico em um profissional que, antes de responder qualquer coisa, consulta rapidamente um caderno de anota\u00e7\u00f5es espec\u00edfico do projeto. Ele continua sendo o mesmo modelo gen\u00e9rico e inteligente, mas agora com uma “cola” contextualizada na m\u00e3o.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> A Red Hat publicou um artigo detalhado sobre como o RAG est\u00e1 redefinindo a engenharia de software<\/a>, mostrando o impacto dessa t\u00e9cnica al\u00e9m do uso pontual em chats \u2014 ela est\u00e1 mudando como equipes projetam sistemas inteiros de apoio \u00e0 IA.<\/p><\/blockquote>\n Uma pergunta natural de quem est\u00e1 come\u00e7ando \u00e9: “por que n\u00e3o colo o projeto inteiro na conversa com a IA?”. A resposta tem dois motivos pr\u00e1ticos.<\/p>\n O RAG resolve isso filtrando, antes de conversar com a IA, apenas os peda\u00e7os de informa\u00e7\u00e3o realmente relevantes para aquela pergunta espec\u00edfica.<\/p>\n Para entender como o RAG funciona na pr\u00e1tica, \u00e9 preciso conhecer quatro pe\u00e7as fundamentais. Vamos explicar cada uma com uma analogia antes de partir para o c\u00f3digo.<\/p>\n S\u00e3o os materiais que voc\u00ea quer que a IA “conhe\u00e7a”: arquivos de c\u00f3digo, documenta\u00e7\u00e3o em Markdown, especifica\u00e7\u00f5es t\u00e9cnicas, tickets do sistema de gest\u00e3o de projetos. \u00c9 o conte\u00fado bruto da sua base de conhecimento.<\/p>\n Documentos grandes precisam ser divididos em peda\u00e7os menores, chamados de “chunks”. Isso acontece porque a busca funciona melhor em blocos pequenos e focados do que em arquivos gigantes. Pense em um livro: se algu\u00e9m pergunta sobre um assunto espec\u00edfico, \u00e9 mais eficiente indicar o par\u00e1grafo exato do que entregar o livro inteiro.<\/p>\n Aqui est\u00e1 o cora\u00e7\u00e3o t\u00e9cnico do RAG. Um embedding<\/strong> \u00e9 uma representa\u00e7\u00e3o num\u00e9rica \u2014 um vetor, ou seja, uma lista de n\u00fameros \u2014 que captura o significado de um texto. Dois textos com significados parecidos geram vetores numericamente pr\u00f3ximos, mesmo que usem palavras diferentes. \u00c9 assim que a busca consegue encontrar “como fa\u00e7o para me conectar ao banco de dados” mesmo quando o documento fala em “configura\u00e7\u00e3o da conex\u00e3o com o PostgreSQL” \u2014 as palavras diferem, mas o significado \u00e9 pr\u00f3ximo.<\/p>\n \u00c9 onde os embeddings ficam armazenados, organizados de forma que seja poss\u00edvel buscar rapidamente “quais chunks t\u00eam significado mais pr\u00f3ximo desta pergunta”. Existem solu\u00e7\u00f5es especializadas para isso, mas tamb\u00e9m \u00e9 poss\u00edvel montar uma vers\u00e3o simples usando apenas estruturas de dados comuns, como faremos no exemplo a seguir.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> Se voc\u00ea quer ver esses quatro conceitos aplicados em um cen\u00e1rio mais avan\u00e7ado, com banco de grafos, vale assistir a este v\u00eddeo que demonstra como criar um buscador com RAG usando Ollama e Neo4j<\/a>. \u00c9 um passo al\u00e9m do que faremos aqui, mas ajuda a visualizar onde a t\u00e9cnica pode chegar.<\/p><\/blockquote>\n Vamos construir um exemplo funcional e minimalista, usando apenas Python puro e uma biblioteca leve para gerar embeddings. O objetivo n\u00e3o \u00e9 criar um sistema de produ\u00e7\u00e3o, mas fazer voc\u00ea entender o mecanismo com as pr\u00f3prias m\u00e3os.<\/p>\n Vamos usar a biblioteca sentence-transformers<\/a>, que gera embeddings de forma local e gratuita, sem depender de uma API externa paga. Instale com:<\/p>\n Imagine que voc\u00ea tem uma pequena base de conhecimento sobre um projeto fict\u00edcio: um sistema de pedidos. Cada item representa um “chunk” de documenta\u00e7\u00e3o.<\/p>\n Em um cen\u00e1rio real, esses textos viriam de arquivos de documenta\u00e7\u00e3o, coment\u00e1rios no c\u00f3digo ou at\u00e9 do pr\u00f3prio c\u00f3digo-fonte processado.<\/p>\n Esse trecho transforma cada um dos quatro textos em um vetor num\u00e9rico. \u00c9 esse vetor que permite comparar significados matematicamente.<\/p>\n Para encontrar o documento mais relevante para uma pergunta, comparamos o embedding da pergunta com os embeddings dos documentos, usando uma medida chamada similaridade de cosseno<\/strong> \u2014 quanto mais pr\u00f3xima de 1, mais parecidos os significados.<\/p>\n Agora podemos testar com uma pergunta real:<\/p>\n Mesmo sem a palavra “pagamento” aparecer em uma pergunta gen\u00e9rica sobre “falhas”, o sistema deve retornar o trecho sobre o Com o contexto relevante em m\u00e3os, o pr\u00f3ximo passo \u00e9 montar o prompt que ser\u00e1 enviado \u00e0 IA, combinando a pergunta original com os trechos recuperados:<\/p>\n Esse prompt final \u00e9 o que voc\u00ea envia \u00e0 API do modelo de IA de sua escolha \u2014 seja via chamada de API, seja colando manualmente em uma conversa. A diferen\u00e7a crucial \u00e9 que agora a IA n\u00e3o est\u00e1 “chutando” com base em conhecimento gen\u00e9rico: ela est\u00e1 respondendo com base em fatos espec\u00edficos do seu projeto.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> Instruir o modelo a dizer “n\u00e3o sei” quando a resposta n\u00e3o estiver no contexto \u00e9 uma pr\u00e1tica essencial. Sem essa instru\u00e7\u00e3o, o modelo tende a preencher lacunas com suposi\u00e7\u00f5es plaus\u00edveis, mas incorretas \u2014 um comportamento conhecido como alucina\u00e7\u00e3o.<\/p><\/blockquote>\n O exemplo acima usou quatro frases fixas para fins did\u00e1ticos, mas o mesmo princ\u00edpio se aplica a bases de conhecimento muito maiores: documenta\u00e7\u00e3o inteira de um projeto, hist\u00f3rico de decis\u00f5es t\u00e9cnicas, ou at\u00e9 o pr\u00f3prio c\u00f3digo-fonte dividido em fun\u00e7\u00f5es e classes. A l\u00f3gica n\u00e3o muda \u2014 apenas a escala e as ferramentas usadas para armazenar os embeddings de forma eficiente.<\/p>\n Se voc\u00ea j\u00e1 usa assistentes de IA integrados ao editor de c\u00f3digo, provavelmente j\u00e1 se beneficiou de uma vers\u00e3o de RAG sem perceber. Quando uma ferramenta “entende” o projeto aberto e sugere c\u00f3digo coerente com o padr\u00e3o do reposit\u00f3rio, ela normalmente est\u00e1 indexando arquivos localmente e recuperando trechos relevantes antes de gerar a resposta \u2014 exatamente o mecanismo que constru\u00edmos aqui, em uma vers\u00e3o simplificada.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> Vale destacar que RAG em produ\u00e7\u00e3o envolve muito mais cuidado do que o exemplo did\u00e1tico mostrado aqui. Segundo um post da Roga DX sobre bastidores de IA corporativa<\/a>, construir um sistema de RAG confi\u00e1vel em escala real exige aten\u00e7\u00e3o a atualiza\u00e7\u00e3o constante da base, controle de qualidade dos dados de origem e monitoramento de respostas \u2014 desafios que v\u00e3o al\u00e9m do experimento inicial.<\/p><\/blockquote>\n Um ponto importante para quem est\u00e1 come\u00e7ando: RAG n\u00e3o \u00e9 uma ferramenta isolada, \u00e9 uma t\u00e9cnica que pode ser combinada com outras pr\u00e1ticas de IA aplicada ao desenvolvimento. Sistemas mais sofisticados usam o RAG dentro de agentes \u2014 programas de IA que decidem, sozinhos, quando buscar informa\u00e7\u00e3o, quando executar uma a\u00e7\u00e3o e quando responder diretamente. Como destacado em uma discuss\u00e3o sobre a diferen\u00e7a entre usar IA para programar e construir software com IA<\/a>, entender conceitos como chunking, contexto e boas pr\u00e1ticas de recupera\u00e7\u00e3o de informa\u00e7\u00e3o \u00e9 o que separa quem usa IA de forma superficial de quem constr\u00f3i solu\u00e7\u00f5es s\u00f3lidas com ela.<\/p>\nO que \u00e9 RAG, afinal?<\/h2>\n
Por que n\u00e3o simplesmente colar tudo no prompt?<\/h3>\n
\n
As pe\u00e7as que comp\u00f5em um sistema de RAG<\/h2>\n
1. Os documentos-fonte<\/h3>\n
2. Chunking (divis\u00e3o em peda\u00e7os)<\/h3>\n
3. Embeddings (representa\u00e7\u00e3o num\u00e9rica de significado)<\/h3>\n
4. O banco vetorial<\/h3>\n
Construindo um RAG simples do zero, em Python<\/h2>\n
Passo 1: preparando o ambiente<\/h3>\n
pip install sentence-transformers numpy<\/code><\/pre>\nPasso 2: simulando os documentos do projeto<\/h3>\n
documentos = [\n \"O m\u00f3dulo de pedidos usa o padr\u00e3o Repository para acessar o banco de dados. \"\n \"A classe PedidoRepository fica em src\/repositories\/pedido_repository.py.\",\n\n \"Todo pedido criado precisa passar pela valida\u00e7\u00e3o de estoque antes de ser confirmado. \"\n \"Essa valida\u00e7\u00e3o est\u00e1 implementada na fun\u00e7\u00e3o validar_estoque, no m\u00f3dulo estoque.py.\",\n\n \"A API de pagamentos externa \u00e9 acessada atrav\u00e9s da classe PagamentoGateway. \"\n \"Ela possui retry autom\u00e1tico de at\u00e9 3 tentativas em caso de falha de rede.\",\n\n \"Conven\u00e7\u00e3o do time: toda fun\u00e7\u00e3o p\u00fablica deve ter docstring no formato Google Style, \"\n \"e nomes de vari\u00e1veis s\u00e3o sempre em portugu\u00eas para manter consist\u00eancia no dom\u00ednio.\",\n]<\/code><\/pre>\nPasso 3: gerando os embeddings<\/h3>\n
from sentence_transformers import SentenceTransformer\nimport numpy as np\n\nmodelo = SentenceTransformer('paraphrase-multilingual-MiniLM-L12-v2')\n\nembeddings_documentos = modelo.encode(documentos)\n\nprint(f\"Cada documento virou um vetor de {embeddings_documentos.shape[1]} n\u00fameros.\")<\/code><\/pre>\nPasso 4: implementando a busca por similaridade<\/h3>\n
def buscar_contexto_relevante(pergunta, documentos, embeddings_documentos, modelo, top_k=2):\n embedding_pergunta = modelo.encode([pergunta])\n\n # Similaridade de cosseno entre a pergunta e cada documento\n similaridades = np.dot(embeddings_documentos, embedding_pergunta.T).flatten()\n normas = np.linalg.norm(embeddings_documentos, axis=1) * np.linalg.norm(embedding_pergunta)\n similaridades = similaridades \/ normas\n\n indices_mais_relevantes = np.argsort(similaridades)[::-1][:top_k]\n\n return [documentos[i] for i in indices_mais_relevantes]<\/code><\/pre>\npergunta = \"Como o sistema lida com falhas ao processar um pagamento?\"\n\ncontexto = buscar_contexto_relevante(pergunta, documentos, embeddings_documentos, modelo)\n\nfor trecho in contexto:\n print(\"-\", trecho)<\/code><\/pre>\nPagamentoGateway<\/code> como o mais relevante, porque o significado da pergunta est\u00e1 semanticamente pr\u00f3ximo daquele conte\u00fado.<\/p>\nPasso 5: montando o prompt aumentado<\/h3>\n
def montar_prompt(pergunta, contexto):\n contexto_formatado = \"\\n\".join(f\"- {trecho}\" for trecho in contexto)\n\n prompt = f\"\"\"Voc\u00ea \u00e9 um assistente t\u00e9cnico do projeto de sistema de pedidos.\nUse exclusivamente as informa\u00e7\u00f5es de contexto abaixo para responder.\nSe a resposta n\u00e3o estiver no contexto, diga que n\u00e3o sabe.\n\nContexto:\n{contexto_formatado}\n\nPergunta: {pergunta}\n\nResposta:\"\"\"\n return prompt\n\nprompt_final = montar_prompt(pergunta, contexto)\nprint(prompt_final)<\/code><\/pre>\nComo isso se conecta ao seu fluxo de trabalho real<\/h2>\n
Onde o RAG aparece nas ferramentas que voc\u00ea j\u00e1 usa<\/h3>\n
RAG e agentes de IA<\/h3>\n