{"id":1328,"date":"2026-10-14T04:01:23","date_gmt":"2026-10-14T07:01:23","guid":{"rendered":"https:\/\/adrianosantostreina.com.br\/blog\/rag-pratica-contexto-ia-projeto-guia-basico\/"},"modified":"2026-10-14T04:01:34","modified_gmt":"2026-10-14T07:01:34","slug":"rag-pratica-contexto-ia-projeto-guia-basico","status":"publish","type":"post","link":"https:\/\/adrianosantostreina.com.br\/blog\/rag-pratica-contexto-ia-projeto-guia-basico\/","title":{"rendered":"A IA Que L\u00ea Seu C\u00f3digo Antes de Responder: Um Guia B\u00e1sico de RAG Para Quem Est\u00e1 Cansado de Explicar o Projeto do Zero"},"content":{"rendered":"

Imagine a seguinte cena. Voc\u00ea abre o chat da sua ferramenta de IA favorita e pergunta: “como funciona a regra de desconto para clientes antigos no nosso sistema?”. A resposta vem r\u00e1pida, bem escrita, cheia de confian\u00e7a \u2014 e completamente errada. A IA descreveu uma regra gen\u00e9rica de e-commerce, que n\u00e3o tem nada a ver com a l\u00f3gica espec\u00edfica que o seu time implementou h\u00e1 dois anos, numa fun\u00e7\u00e3o perdida em um m\u00f3dulo de faturamento. Voc\u00ea perde dez minutos corrigindo a IA, colando trechos de c\u00f3digo no chat, explicando o contexto do neg\u00f3cio, e s\u00f3 ent\u00e3o recebe uma resposta \u00fatil. No dia seguinte, em uma nova conversa, tudo se repete, porque a IA n\u00e3o lembra de nada do que foi dito antes.<\/p>\n

Esse problema \u00e9 t\u00e3o comum que j\u00e1 tem nome entre quem trabalha com IA aplicada ao desenvolvimento: falta de contexto. Os modelos de linguagem s\u00e3o treinados com uma quantidade enorme de informa\u00e7\u00e3o p\u00fablica, mas eles simplesmente n\u00e3o conhecem o seu projeto, a sua base de c\u00f3digo, as decis\u00f5es de arquitetura que o seu time tomou ou as regras de neg\u00f3cio espec\u00edficas da sua empresa. E colar manualmente arquivos inteiros no chat, toda vez, n\u00e3o escala \u2014 al\u00e9m de estourar o limite de tamanho que o modelo consegue processar de uma vez (o chamado “contexto”).<\/p>\n

\u00c9 exatamente esse problema que a t\u00e9cnica de RAG, sigla em ingl\u00eas para Retrieval-Augmented Generation<\/em> (algo como “gera\u00e7\u00e3o aumentada por recupera\u00e7\u00e3o”), foi criada para resolver. Neste artigo, vamos entender o que \u00e9 RAG do zero, como ele funciona por dentro, e vamos construir um exemplo simples e funcional em Python, para voc\u00ea sair daqui com uma base real sobre como dar contexto \u00e0 IA sobre o seu pr\u00f3prio projeto.<\/p>\n

O que \u00e9 RAG, explicado sem rodeios<\/h2>\n

RAG \u00e9 uma t\u00e9cnica que combina duas coisas: um mecanismo de busca<\/strong> (retrieval) e um modelo de gera\u00e7\u00e3o de texto<\/strong> (generation), que \u00e9 a pr\u00f3pria IA. A ideia central \u00e9 simples: em vez de perguntar algo diretamente para a IA e torcer para que ela “saiba” a resposta, voc\u00ea primeiro busca informa\u00e7\u00f5es relevantes em uma base de conhecimento sua \u2014 pode ser a documenta\u00e7\u00e3o do projeto, o c\u00f3digo-fonte, tickets de suporte, atas de reuni\u00e3o \u2014 e s\u00f3 depois entrega essas informa\u00e7\u00f5es, junto com a pergunta, para a IA responder.<\/p>\n

Uma analogia s\u00f3bria ajuda aqui. Pense em um advogado experiente que vai depor em um tribunal sobre um caso espec\u00edfico. Ele n\u00e3o confia apenas na mem\u00f3ria de tudo que estudou na faculdade de Direito, anos atr\u00e1s. Antes de falar, ele consulta os autos do processo, os documentos daquele caso espec\u00edfico, e s\u00f3 ent\u00e3o formula a resposta. O conhecimento geral de Direito (equivalente ao treinamento do modelo de IA) continua sendo essencial, mas \u00e9 a consulta aos documentos do caso (a busca, o retrieval) que torna a resposta precisa e aplic\u00e1vel \u00e0quela situa\u00e7\u00e3o concreta.<\/p>\n

Segundo a Red Hat, em artigo sobre o tema<\/a>, a RAG tem potencial para revolucionar como o software \u00e9 concebido e implementado, justamente porque permite que a IA trabalhe com informa\u00e7\u00e3o atualizada e espec\u00edfica, sem a necessidade de retreinar o modelo inteiro cada vez que algo muda no projeto.<\/p>\n

Por que n\u00e3o simplesmente colar tudo no prompt?<\/h3>\n

Uma d\u00favida natural de quem est\u00e1 come\u00e7ando \u00e9: por que n\u00e3o colar o projeto inteiro na mensagem e pronto? A resposta tem dois lados. Primeiro, existe um limite t\u00e9cnico: todo modelo de IA tem uma “janela de contexto”, ou seja, uma quantidade m\u00e1xima de texto que ele consegue processar em uma \u00fanica intera\u00e7\u00e3o. Projetos reais, com milhares de arquivos, simplesmente n\u00e3o cabem nesse espa\u00e7o.<\/p>\n

Segundo, mesmo quando cabe, colar tudo \u00e9 ineficiente e caro. Modelos de IA cobram (ou consomem recursos) proporcionalmente \u00e0 quantidade de texto processado. Enviar um projeto inteiro para responder uma pergunta sobre uma \u00fanica fun\u00e7\u00e3o \u00e9 como entregar a biblioteca inteira para algu\u00e9m que s\u00f3 queria saber o significado de uma palavra. O RAG resolve isso entregando apenas os trechos relevantes, encontrados por meio de busca, e n\u00e3o o conte\u00fado inteiro.<\/p>\n

As pe\u00e7as que comp\u00f5em um sistema de RAG<\/h2>\n

Antes de escrever qualquer c\u00f3digo, vale entender as partes que formam esse mecanismo. S\u00e3o quatro pe\u00e7as principais, e cada uma tem um papel bem definido.<\/p>\n

1. Os documentos (sua base de conhecimento)<\/h3>\n

\u00c9 o material que voc\u00ea quer que a IA conhe\u00e7a: arquivos de c\u00f3digo, documenta\u00e7\u00e3o em Markdown, descri\u00e7\u00f5es de regras de neg\u00f3cio, tickets resolvidos, o que for relevante para o seu projeto. Esse material precisa ser dividido em peda\u00e7os menores, chamados de chunks<\/strong> (fragmentos), porque a busca funciona melhor com trechos focados do que com arquivos gigantes.<\/p>\n

2. Os embeddings (a “impress\u00e3o digital” do significado)<\/h3>\n

Aqui est\u00e1 o cora\u00e7\u00e3o t\u00e9cnico do RAG, e vale explicar com calma porque \u00e9 o conceito que mais confunde quem est\u00e1 come\u00e7ando. Um embedding<\/strong> \u00e9 uma representa\u00e7\u00e3o num\u00e9rica de um texto, criada por um modelo de IA especializado, que captura o significado<\/em> daquele texto \u2014 e n\u00e3o apenas as palavras usadas literalmente.<\/p>\n

Pense em um embedding como as coordenadas de um ponto em um mapa gigantesco de significados. Textos com significados parecidos ficam em pontos pr\u00f3ximos nesse mapa, mesmo que usem palavras completamente diferentes. A frase “como cancelar um pedido” e a frase “quero desfazer minha compra” ficariam pr\u00f3ximas nesse mapa, porque tratam do mesmo assunto, mesmo sem repetir palavras.<\/p>\n

3. O banco de dados vetorial<\/h3>\n

\u00c9 onde esses embeddings ficam armazenados, de forma organizada para permitir buscas r\u00e1pidas por proximidade. Quando voc\u00ea faz uma pergunta, ela tamb\u00e9m \u00e9 transformada em um embedding, e o banco de dados vetorial encontra os trechos de texto cujos embeddings est\u00e3o mais pr\u00f3ximos do embedding da pergunta \u2014 ou seja, os trechos com significado mais relacionado.<\/p>\n

\ud83d\udca1 Dica do Mestre:<\/strong> existem bancos de dados vetoriais populares, como o Neo4j (que tamb\u00e9m trabalha com grafos), e solu\u00e7\u00f5es mais simples para estudo e projetos pequenos, como o FAISS e o Chroma. No v\u00eddeo RAG in Practice: How to Teach AI to Search for Answers in Your Database<\/a>, h\u00e1 uma demonstra\u00e7\u00e3o pr\u00e1tica de como montar um buscador combinando IA, Ollama e Neo4j, que vale assistir para visualizar o processo de ponta a ponta.<\/p><\/blockquote>\n

4. O modelo de gera\u00e7\u00e3o (a IA que responde)<\/h3>\n

\u00c9 o modelo de linguagem propriamente dito \u2014 pode ser um modelo local, rodando na sua m\u00e1quina, ou um modelo acessado por API. Ele recebe a pergunta original do usu\u00e1rio junto com os trechos de texto recuperados pela busca, e gera a resposta final com base nessas duas informa\u00e7\u00f5es combinadas.<\/p>\n

Montando um exemplo de RAG na pr\u00e1tica<\/h2>\n

Vamos construir uma vers\u00e3o simplificada, mas funcional, de um pipeline de RAG em Python. O objetivo \u00e9 did\u00e1tico: entender o fluxo completo, n\u00e3o construir algo pronto para produ\u00e7\u00e3o. Vamos simular uma base de conhecimento sobre um projeto fict\u00edcio, com algumas regras de neg\u00f3cio documentadas em texto simples.<\/p>\n

Passo 1 \u2014 preparando o ambiente<\/h3>\n

Para este exemplo, vamos usar duas bibliotecas populares em Python: n\u00e3o \u00e9 necess\u00e1rio um banco externo<\/a> para este exerc\u00edcio b\u00e1sico \u2014 vamos simular a busca vetorial com uma biblioteca leve chamada sentence-transformers<\/code>, que gera embeddings localmente, e c\u00e1lculos de similaridade feitos com numpy<\/code>.<\/p>\n

pip install sentence-transformers numpy\n<\/code><\/pre>\n
Passo 2 \u2014 criando a base de conhecimento<\/h3>\n
Vamos simular trechos de documenta\u00e7\u00e3o de um projeto real, divididos em pequenos fragmentos (chunks):<\/p>\n
documentos = [\n    \"A regra de desconto para clientes antigos se aplica apenas a quem tem \"\n    \"mais de 24 meses de cadastro ativo e pelo menos 5 pedidos conclu\u00eddos.\",\n\n    \"O m\u00f3dulo de faturamento gera a nota fiscal automaticamente ap\u00f3s a \"\n    \"confirma\u00e7\u00e3o do pagamento, usando o servi\u00e7o FaturamentoService.\",\n\n    \"Pedidos cancelados dentro de 7 dias geram reembolso integral. Ap\u00f3s \"\n    \"esse prazo, aplica-se uma taxa de 10% sobre o valor do pedido.\",\n\n    \"O time de backend usa FastAPI para os endpoints da API e PostgreSQL \"\n    \"como banco de dados principal do projeto.\",\n\n    \"Clientes do plano Premium t\u00eam frete gr\u00e1tis em qualquer valor de compra, \"\n    \"enquanto clientes do plano B\u00e1sico precisam atingir R$ 150 em compras.\"\n]\n<\/code><\/pre>\n
Passo 3 \u2014 transformando os documentos em embeddings<\/h3>\n
Agora usamos um modelo pr\u00e9-treinado para converter cada trecho de texto em um vetor num\u00e9rico (o embedding):<\/p>\n
from sentence_transformers import SentenceTransformer\nimport numpy as np\n\n# Modelo leve e multil\u00edngue, adequado para testes e projetos pequenos\nmodelo_embeddings = SentenceTransformer(\"paraphrase-multilingual-MiniLM-L12-v2\")\n\n# Gera um vetor num\u00e9rico para cada documento da base de conhecimento\nvetores_documentos = modelo_embeddings.encode(documentos)\n\nprint(f\"Cada documento virou um vetor com {vetores_documentos.shape[1]} n\u00fameros.\")\n<\/code><\/pre>\n
Esse c\u00f3digo converte cada frase em uma lista de n\u00fameros (um vetor). N\u00e3o se preocupe em entender cada n\u00famero individualmente \u2014 o importante \u00e9 que textos com significados parecidos geram vetores matematicamente pr\u00f3ximos entre si.<\/p>\n
Passo 4 \u2014 buscando o trecho mais relevante para uma pergunta<\/h3>\n
Com os documentos j\u00e1 transformados em vetores, o pr\u00f3ximo passo \u00e9 pegar a pergunta do usu\u00e1rio, transform\u00e1-la tamb\u00e9m em um vetor, e comparar com os vetores da base usando uma medida de similaridade chamada similaridade de cosseno<\/strong> \u2014 uma forma de medir o qu\u00e3o “alinhados” dois vetores est\u00e3o.<\/p>\n
def buscar_contexto_relevante(pergunta, documentos, vetores_documentos, top_k=2):\n    vetor_pergunta = modelo_embeddings.encode([pergunta])[0]\n\n    # Calcula a similaridade de cosseno entre a pergunta e cada documento\n    similaridades = []\n    for vetor_doc in vetores_documentos:\n        similaridade = np.dot(vetor_pergunta, vetor_doc) \/ (\n            np.linalg.norm(vetor_pergunta) * np.linalg.norm(vetor_doc)\n        )\n        similaridades.append(similaridade)\n\n    # Pega os \u00edndices dos documentos mais similares (os top_k melhores)\n    indices_ordenados = np.argsort(similaridades)[::-1][:top_k]\n\n    return [documentos[i] for i in indices_ordenados]\n\n\npergunta_usuario = \"como funciona o desconto para clientes antigos?\"\ntrechos_encontrados = buscar_contexto_relevante(\n    pergunta_usuario, documentos, vetores_documentos\n)\n\nfor trecho in trechos_encontrados:\n    print(\"-\", trecho)\n<\/code><\/pre>\n
Ao rodar esse trecho, a busca deve retornar o documento sobre a regra de desconto como o mais relevante, mesmo que a pergunta n\u00e3o repita exatamente as mesmas palavras do texto original. Isso acontece porque a busca \u00e9 feita pelo significado, e n\u00e3o por correspond\u00eancia literal de palavras \u2014 essa \u00e9 a grande diferen\u00e7a entre o RAG e uma simples busca por palavra-chave.<\/p>\n
Passo 5 \u2014 montando o prompt final para a IA<\/h3>\n
Com os trechos relevantes em m\u00e3os, o \u00faltimo passo \u00e9 montar uma instru\u00e7\u00e3o (prompt) que combine a pergunta original com o contexto encontrado, e enviar isso para o modelo de IA responder:<\/p>\n
def montar_prompt_com_contexto(pergunta, trechos_relevantes):\n    contexto = \"\\n\".join(f\"- {t}\" for t in trechos_relevantes)\n\n    prompt = f\"\"\"Use exclusivamente as informa\u00e7\u00f5es de contexto abaixo para\nresponder \u00e0 pergunta do usu\u00e1rio. Se a resposta n\u00e3o estiver no contexto,\ndiga que n\u00e3o encontrou essa informa\u00e7\u00e3o na base de conhecimento.\n\nContexto:\n{contexto}\n\nPergunta: {pergunta}\n\nResposta:\"\"\"\n    return prompt\n\n\nprompt_final = montar_prompt_com_contexto(pergunta_usuario, trechos_encontrados)\nprint(prompt_final)\n<\/code><\/pre>\n
Esse prompt final \u00e9 o que voc\u00ea enviaria para um modelo de IA \u2014 seja via API, seja em uma ferramenta de assistente de c\u00f3digo. Note a instru\u00e7\u00e3o expl\u00edcita pedindo para a IA usar apenas o contexto fornecido: isso reduz bastante a chance de o modelo “inventar” uma resposta gen\u00e9rica, um comportamento conhecido como alucina\u00e7\u00e3o.<\/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 das pr\u00e1ticas mais simples e eficazes para reduzir alucina\u00e7\u00f5es em sistemas de RAG. \u00c9 uma linha a mais no prompt que evita muita dor de cabe\u00e7a depois.<\/p><\/blockquote>\n
RAG aplicado ao c\u00f3digo-fonte do seu projeto<\/h2>\n
O exemplo acima usou textos de documenta\u00e7\u00e3o, mas o mesmo princ\u00edpio se aplica diretamente ao c\u00f3digo. A diferen\u00e7a est\u00e1 em como voc\u00ea divide os documentos em chunks: em vez de par\u00e1grafos, voc\u00ea costuma dividir por fun\u00e7\u00e3o, classe ou arquivo, preservando o contexto de cada bloco de c\u00f3digo.<\/p>\n
chunks_de_codigo = [\n    \"\"\"def calcular_desconto(cliente):\n    if cliente.meses_cadastro > 24 and cliente.pedidos_concluidos >= 5:\n        return 0.15\n    return 0.0\"\"\",\n\n    \"\"\"class FaturamentoService:\n    def gerar_nota_fiscal(self, pedido):\n        if pedido.pagamento_confirmado:\n            return NotaFiscal.criar(pedido)\n        raise PagamentoPendenteError(pedido.id)\"\"\",\n]\n<\/code><\/pre>\n
O restante do processo \u00e9 id\u00eantico: gerar embeddings para cada chunk de c\u00f3digo, buscar os trechos mais relevantes para a pergunta do desenvolvedor, e montar o prompt com esse contexto. \u00c9 exatamente esse mecanismo, em vers\u00f5es mais sofisticadas, que permite que ferramentas de IA integradas ao editor de c\u00f3digo consigam responder perguntas espec\u00edficas sobre o seu projeto, sem que voc\u00ea precise colar arquivos manualmente toda vez.<\/p>\n
Segundo o artigo RAG como base para agentes de IA em engenharia de software<\/a>, levar essa t\u00e9cnica para um ambiente de produ\u00e7\u00e3o exige cuidados adicionais de integra\u00e7\u00e3o, governan\u00e7a e medi\u00e7\u00e3o de resultado \u2014 algo que ultrapassa o escopo deste artigo introdut\u00f3rio, mas que vale ter em mente como pr\u00f3ximo passo natural de evolu\u00e7\u00e3o.<\/p>\n
Quando o RAG faz sentido (e quando n\u00e3o faz)<\/h3>\n
RAG \u00e9 uma \u00f3tima escolha quando voc\u00ea precisa que a IA responda com base em informa\u00e7\u00e3o espec\u00edfica, que muda com frequ\u00eancia, e que n\u00e3o faria sentido “ensinar” ao modelo de forma permanente. Documenta\u00e7\u00e3o interna, regras de neg\u00f3cio, hist\u00f3rico de decis\u00f5es de arquitetura e o pr\u00f3prio c\u00f3digo do projeto s\u00e3o exemplos cl\u00e1ssicos.<\/p>\n
Por outro lado, se o seu problema \u00e9 apenas executar uma tarefa pontual e bem definida \u2014 como renomear uma vari\u00e1vel em um arquivo espec\u00edfico \u2014 voc\u00ea provavelmente n\u00e3o precisa de um pipeline de RAG completo. Nesses casos, solu\u00e7\u00f5es mais diretas, como um bom prompt com o arquivo colado manualmente, resolvem com menos complexidade.<\/p>\n
\ud83d\udca1 Dica do Mestre:<\/strong> vale notar a diferen\u00e7a entre RAG, workflows e agentes de IA \u2014 s\u00e3o conceitos relacionados, mas distintos. O post RAG, Workflow ou Agente: voc\u00ea sabe qual escolher no seu projeto?<\/a> traz uma reflex\u00e3o \u00fatil sobre como decidir qual abordagem se encaixa melhor em cada tipo de projeto.<\/p><\/blockquote>\n
Erros comuns de quem est\u00e1 come\u00e7ando com RAG<\/h2>\n
Alguns trope\u00e7os aparecem com frequ\u00eancia em quem est\u00e1 implementando RAG pela primeira vez, e vale conhec\u00ea-los antes de cair neles.<\/p>\n