Pergunte ao Claude sobre sua empresa, suas anotações ou seus arquivos, e ele não saberá responder. Ele nunca os viu. Ele só conhece o que aprendeu durante o treinamento, e o seu material não fazia parte disso.
Um sistema RAG resolve isso. Em vez de responder de memória, o Claude primeiro consulta seus documentos, pega as partes relevantes e responde com base no que realmente encontrou. Seus dados, a fonte dele, sem adivinhação.
Por que é melhor do que simplesmente colar arquivos no chat:
Escalabilidade. Sua base de conhecimento inteira não cabe em um único chat. O RAG armazena tudo e busca apenas o que cada pergunta precisa.
Economia. Colar um arquivo faz o Claude reler o documento inteiro a cada pergunta. O RAG lê uma vez e depois busca apenas a parte relevante. Em vez de enviar um manual de 10.000 tokens toda vez, ele pode enviar 500 tokens da seção exata que você precisa. Configurações reais reduzem o uso de tokens em 80% ou mais.
Precisão. Alimente um modelo com um mural de texto gigante e ele perde detalhes no meio. Entregue alguns trechos precisos e as respostas ficam mais exatas.
Atualização. Atualize seus arquivos uma vez e o sistema usa a versão nova. Sem necessidade de colar novamente.
Ao final deste guia, você terá um sistema rodando com seus próprios arquivos, passo a passo, sem necessidade de doutorado.
O que você vai precisar
Antes de tocarmos em qualquer código, aqui está a lista completa. Boa notícia: esta versão precisa de apenas uma chave de API, e todo o resto roda gratuitamente na sua própria máquina.
1. Python 3.9 ou superior. Para verificar se você tem, abra seu terminal (Terminal no Mac, Prompt de Comando no Windows) e digite python --version. Se aparecer algo como 3.11, está ok. Caso contrário, baixe-o de python.org e execute o instalador. No Windows, marque a opção "Adicionar Python ao PATH" durante a instalação, senão os comandos abaixo não funcionarão.
2. Uma chave de API do Claude, mais um pequeno saldo de créditos. Esta é a única chave e o único dinheiro que todo o guia precisa. Aqui está o caminho exato, clique a clique:
Acesse platform.claude.com e faça login (ou cadastre-se) lá.
A API precisa de um saldo positivo para funcionar, então adicione fundos primeiro. Quando solicitado, escolha se os créditos são para você ou para uma empresa; então você será direcionado para a tela de pagamento. Escolha a opção $5 "Iniciando". É o suficiente: todo o resto deste guia é gratuito e local, então o Claude é a única coisa que custa dinheiro, e cada pergunta custa uma fração de centavo. Os créditos expiram um ano após a compra.
Após o pagamento, você estará no painel do Console. Você deve ver seu saldo (por exemplo, $5,00) no canto superior esquerdo, sob "Créditos da Organização".
Agora pegue a chave. Clique em Obter chave de API (canto superior direito) e depois em Criar chave. Dê a ela qualquer nome que você goste (por exemplo, minha-chave-rag) e deixe o espaço de trabalho como Padrão. Clique em criar e copie a string que aparece. Ela começa com sk-ant- e você só a vê uma vez, então cole-a em um lugar seguro por um momento.
Essa é toda a configuração.
Passo 1: Adicione sua chave e carregue seus arquivos
1. Crie a pasta do projeto. Crie uma nova pasta na sua Área de Trabalho e nomeie-a como rag-project. Tudo vai aqui.
2. Abra seu terminal. No Mac: Cmd+Espaço, digite Terminal, pressione Enter. No Windows: Botão Iniciar, digite cmd, pressione Enter.
3. Aponte o terminal para sua pasta. Digite cd e um espaço, então arraste a pasta rag-project para a janela do terminal e pressione Enter. Todos os comandos abaixo são executados de dentro desta pasta.
1cd Desktop/rag-project
4. Instale as ferramentas. Cole isto no terminal e pressione Enter (a primeira execução pode levar um minuto):
1pip install anthropic chromadb sentence-transformers pypdf python-dotenv
Se aparecer pip: comando não encontrado, use pip3 em vez de pip. Quando o terminal mostrar uma linha nova sem erros em vermelho, está pronto.
5. Crie seu arquivo de código. Dentro de rag-project, crie um arquivo vazio chamado exatamente rag.py. Abra-o em qualquer editor de texto.
6. Crie seu arquivo de chave. Na mesma pasta, crie um arquivo chamado exatamente .env (começa com um ponto, sem nome antes dele). Cole isto dentro, com a chave real que você criou durante a configuração após o =, sem espaços, sem aspas:
1ANTHROPIC_API_KEY=sk-ant-cole-sua-chave-real-aqui
Manter a chave em .env em vez de no seu código significa que ela não vazará se você compartilhar o script ou colocá-lo no GitHub.
7. Carregue a chave. Coloque isto no topo de rag.py:
1import os2from dotenv import load_dotenv34load_dotenv() # lê seu arquivo .env5api_key = os.getenv("ANTHROPIC_API_KEY")
8. Crie sua base de conhecimento. Dentro de rag-project, crie uma pasta chamada documents. Coloque quaisquer arquivos .txt, .md ou .pdf lá: suas anotações, um documento de produto, resumos de reunião, qualquer coisa.
8.1. Se você ainda não tem arquivos, use este arquivo de teste. Crie notes.txt dentro da pasta documents e cole isto:
Project Northstar é nossa ferramenta interna para rastrear feedback de clientes. Foi lançado em março de 2026 e é mantido pela equipe de plataforma. A engenheira líder é Dana Reyes. O feedback é revisado toda sexta-feira. O Northstar substituiu o antigo sistema de planilhas que usávamos até 2025.
No final, você perguntará ao Claude sobre o Northstar e o verá responder a partir deste arquivo exato.
9. Adicione o código que lê seus arquivos. Abaixo do código do passo 7, em rag.py:
1from pathlib import Path2from pypdf import PdfReader34def load_documents(pasta="documents"):5 docs = []6 for arquivo in Path(pasta).iterdir():7 if arquivo.suffix in [".txt", ".md"]:8 texto = arquivo.read_text(encoding="utf-8")9 docs.append({"fonte": arquivo.name, "texto": texto})10 elif arquivo.suffix == ".pdf":11 leitor = PdfReader(str(arquivo))12 texto = "\n".join(pagina.extract_text() or "" for pagina in leitor.pages)13 docs.append({"fonte": arquivo.name, "texto": texto})14 return docs1516documentos = load_documents()17print(f"Carregado(s) {len(documentos)} documento(s).")
10. Execute-o. Salve rag.py, então no seu terminal:
1python rag.py
Você deve ver:
Carregado(s) 1 documento(s).
Se você vir "Carregado(s) 0 documento(s)", a pasta documents está vazia ou no lugar errado. Ela deve estar diretamente dentro de rag-project, ao lado de rag.py.
Passo 2: Divida seus arquivos em pedaços
Agora, cada arquivo é um grande bloco de texto. Antes de podermos pesquisar, precisamos cortá-lo em partes menores chamadas pedaços. Eis o porquê: quando alguém faz uma pergunta, o sistema encontra os pedaços que correspondem e envia apenas aqueles para o Claude. Se seus pedaços são documentos inteiros de 50 páginas, você envia demais. Se são frases únicas, eles perdem o contexto. Parágrafos pequenos são o ponto ideal.
1. Adicione o código de divisão. Abaixo do código do passo 10, em rag.py:
1def chunk_text(texto, tamanho_pedaco=500, sobreposicao=100):2 palavras = texto.split()3 pedacos = []4 inicio = 05 while inicio < len(palavras):6 fim = inicio + tamanho_pedaco7 pedaco = " ".join(palavras[inicio:fim])8 pedacos.append(pedaco)9 inicio = fim - sobreposicao # volta um pouco para que os pedaços se sobreponham10 return pedacos
Dois números para entender aqui, em termos simples:
- tamanho_pedaco=500 significa que cada pedaço tem cerca de 500 palavras. Grande o suficiente para conter uma ideia completa, pequeno o suficiente para ser preciso.
- sobreposicao=100 significa que cada pedaço repete as últimas 100 palavras do anterior. Isso importa porque uma resposta pode estar exatamente na linha onde dois pedaços se encontram. Sem sobreposição, uma frase cortada ao meio pode ser perdida. A sobreposição garante que nenhuma ideia caia na fenda.
2. Transforme cada documento em pedaços. Adicione isto abaixo:
1todos_pedacos = []2for doc in documentos:3 for pedaco in chunk_text(doc["texto"]):4 todos_pedacos.append({"fonte": doc["fonte"], "texto": pedaco})56print(f"Criado(s) {len(todos_pedacos)} pedaço(s) de {len(documentos)} documento(s).")
Observe que cada pedaço carrega sua fonte (o nome do arquivo de onde veio). Mantemos isso anexado durante todo o percurso, para que quando o Claude responder mais tarde, ele possa dizer de qual arquivo a resposta veio.
3. Execute-o. Salve rag.py, então no seu terminal:
1python rag.py
Você deve ver algo como:
Carregado(s) 1 documento(s).
Criado(s) 1 pedaço(s) de 1 documento(s).
O pequeno arquivo de teste se torna apenas um pedaço porque é curto. Documentos reais produzirão muitos. Se você colocou um PDF longo na pasta, pode ver dezenas ou centenas de pedaços, que é exatamente o que você quer.
Passo 3: Transforme seus pedaços em embeddings
Este é o passo que permite ao computador pesquisar por significado em vez de palavras exatas. Cada pedaço é convertido em uma lista de números (um embedding) que captura o assunto. Pedaços com significados semelhantes terminam com números semelhantes. Mais tarde, quando uma pergunta chega, transformamos a pergunta em números também e encontramos as correspondências mais próximas.
O modelo que faz isso roda localmente na sua máquina. Ele baixa uma vez, depois funciona offline e gratuitamente, e seus arquivos nunca saem do seu computador.
1. Carregue o modelo de embedding. Abaixo do código do passo 2, em rag.py:
1from sentence_transformers import SentenceTransformer23print("Carregando o modelo de embedding (primeira execução baixa, cerca de 90 MB)...")4incorporador = SentenceTransformer("all-MiniLM-L6-v2")
Na primeira vez que você executar, ele baixará o modelo, então dê um momento. Cada execução depois disso é instantânea porque já está na sua máquina.
2. Transforme cada pedaço em um embedding. Adicione isto abaixo:
1textos_pedacos = [pedaco["texto"] for pedaco in todos_pedacos]2embeddings = incorporador.encode(textos_pedacos)34print(f"Criado(s) {len(embeddings)} embedding(s).")5print(f"Cada embedding é uma lista de {len(embeddings[0])} números.")
incorporador.encode(...) pega sua lista de textos dos pedaços e retorna um embedding por pedaço. É só isso.
3. Execute-o. Salve rag.py, então no seu terminal:
1python rag.py
A primeira execução pausa enquanto o modelo baixa, então você deve ver algo como:
Carregado(s) 1 documento(s).
Criado(s) 1 pedaço(s) de 1 documento(s).
Carregando o modelo de embedding (primeira execução baixa, cerca de 90 MB)...
Criado(s) 1 embedding(s).
Cada embedding é uma lista de 384 números.
Essa linha "384 números" é a ideia toda tornada visível: seu texto agora é uma linha de números que o computador pode comparar. Você não precisa ler ou entender esses números. O banco de dados no próximo passo lida com toda a comparação para você.
Se o download falhar com um erro de conexão, apenas execute o comando novamente. Ele continua de onde parou.
Passo 4: Armazene tudo no seu banco de dados vetorial
Agora colocamos os pedaços e seus embeddings no Chroma, seu banco de dados local. É isso que torna a pesquisa rápida: em vez de comparar sua pergunta contra cada pedaço manualmente toda vez, o Chroma os armazena prontos para uso e faz a correspondência para você. Ele salva em uma pasta na sua máquina, então você só constrói uma vez.
1. Configure o banco de dados. Abaixo do código do passo 3, em rag.py:
1import chromadb23cliente = chromadb.PersistentClient(caminho="chroma_db")4colecao = cliente.get_or_create_colecao("meus_documentos")
PersistentClient(caminho="chroma_db") diz ao Chroma para salvar em uma pasta chamada chroma_db (ela a cria automaticamente, bem ao lado do seu script). Como é salvo em disco, seus dados sobrevivem após o script terminar. Uma coleção é apenas a caixa nomeada onde seus pedaços vivem.
2. Adicione seus pedaços ao banco de dados. Adicione isto abaixo:
1colecao.add(2 ids=[str(i) for i in range(len(todos_pedacos))],3 embeddings=[emb.tolist() for emb in embeddings],4 documents=[pedaco["texto"] for pedaco in todos_pedacos],5 metadatas=[{"fonte": pedaco["fonte"]} for pedaco in todos_pedacos],6)78print(f"Armazenado(s) {colecao.count()} pedaço(s) no banco de dados.")
Aqui está o que cada linha entrega ao Chroma, em termos simples: ids dá a cada pedaço um rótulo único (0, 1, 2...), embeddings são os números do passo 3, documents é o texto real do pedaço e metadatas carrega o nome do arquivo junto para que possamos mostrar a fonte mais tarde. O Chroma mantém todos os quatro vinculados.
3. Execute-o. Salve rag.py, então no seu terminal:
1python rag.py
Você deve ver:
Armazenado(s) 1 pedaço(s) no banco de dados.
Uma coisa para saber mais tarde. Toda vez que você executa o script agora, ele adiciona os pedaços novamente, então as contagens podem subir (1, depois 2, depois 3...) em execuções repetidas. Isso é bom enquanto estamos construindo. Para começar limpo, delete a pasta chroma_db e execute mais uma vez. Na versão final, cuidaremos disso adequadamente para que não duplique.
Passo 5: Pesquise seus documentos
Esta é a parte de "recuperação" do RAG, o R no nome. Pegamos uma pergunta, transformamos em um embedding da mesma forma que fizemos com os pedaços, e pedimos ao Chroma os pedaços cujo significado está mais próximo. Esses pedaços correspondentes são o que entregaremos ao Claude no próximo passo.
1. Adicione a função de pesquisa. Abaixo do código do passo 4, em rag.py:
1def pesquisar(pergunta, n_resultados=3):2 embedding_pergunta = incorporador.encode([pergunta])[0]3 resultados = colecao.query(4 query_embeddings=[embedding_pergunta.tolist()],5 n_results=n_resultados,6 )7 return resultados
O que isso faz, linha por linha em termos simples: transforma a pergunta em números com o mesmo modelo que você usou em seus pedaços (isso é importante, ambos devem falar a mesma "linguagem numérica"), então pede ao Chroma as correspondências mais próximas. n_resultados=3 significa "me dê os 3 pedaços mais relevantes." Três é um bom padrão: contexto suficiente, não tanto que você desperdice tokens.
2. Teste uma pesquisa. Adicione isto abaixo para testar:
1pergunta = "Quem gerencia o Northstar e quando o feedback é revisado?"2resultados = pesquisar(pergunta)34for i, doc in enumerate(resultados["documents"][0]):5 fonte = resultados["metadatas"][0][i]["fonte"]6 print(f"\n--- Correspondência {i+1} (de {fonte}) ---")7 print(doc)
Isso executa uma pergunta real contra seu banco de dados e imprime os pedaços que encontrou, cada um com o nome do arquivo de onde veio.
3. Execute-o. Salve rag.py, então no seu terminal:
1python rag.py
Com o arquivo de teste Northstar, você deve vê-lo trazer de volta o pedaço correspondente, algo como:
--- Correspondência 1 (de notes.txt) ---
Project Northstar é nossa ferramenta interna para rastrear feedback de clientes. Foi lançado em março de 2026 e é mantido pela equipe de plataforma. A engenheira líder é Dana Reyes. O feedback é revisado toda sexta-feira. O Northstar substituiu o antigo sistema de planilhas que usávamos até 2025.
Observe o que acabou de acontecer: sua pergunta usou as palavras "gerencia" e "revisado", mas o arquivo diz "engenheira líder" e "revisado toda sexta-feira". Ele correspondeu de qualquer forma, porque a pesquisa funciona por significado, não por palavras exatas. Esse é o objetivo principal dos embeddings, e é por isso que isso supera uma pesquisa de palavra-chave simples (Ctrl+F) em seus arquivos.
Se você tiver mais arquivos, verá os 3 principais pedaços de todos eles, classificados por quão próximos correspondem.
Passo 6: Faça o Claude responder com base no que encontrou
Esta é a parte de "geração", o G no RAG. Pegamos os pedaços do passo 5, os entregamos ao Claude Opus 4.8 junto com a pergunta, e dizemos a ele para responder usando apenas esse contexto. É isso que o impede de adivinhar: Claude responde de seus arquivos, não de sua própria memória, e diz qual arquivo usou.
1. Adicione a função de resposta. Abaixo do código do passo 5, em rag.py:
1import anthropic23claude = anthropic.Anthropic(api_key=api_key)45def responder(pergunta):6 resultados = pesquisar(pergunta)7 pedacos = resultados["documents"][0]8 fontes = [m["fonte"] for m in resultados["metadatas"][0]]910 contexto = ""11 for i, pedaco in enumerate(pedacos):12 contexto += f"[De {fontes[i]}]\n{pedaco}\n\n"1314 mensagem = claude.messages.create(15 model="claude-opus-4-8",16 max_tokens=1024,17 system=(18 "Você responde perguntas usando apenas o contexto fornecido. "19 "Se a resposta não estiver no contexto, diga que não sabe. "20 "Sempre mencione de qual arquivo sua resposta veio."21 ),22 messages=[23 {24 "role": "user",25 "content": f"Contexto:\n{contexto}\nPergunta: {pergunta}",26 }27 ],28 )29 return mensagem.content[0].text
O que está acontecendo aqui, em termos simples: pesquisamos os pedaços relevantes, os juntamos em um bloco de contexto (cada um rotulado com seu nome de arquivo), então enviamos esse bloco mais a pergunta para o Claude. A instrução system é a parte chave. Ela diz três coisas a Claude: responda apenas a partir do contexto, admita quando a resposta não estiver lá, e nomeie o arquivo de origem. Essas três regras são o que tornam as respostas confiáveis em vez de inventadas.
model="claude-opus-4-8" é o nome exato do modelo (hífens, não pontos). max_tokens=1024 limita o tamanho da resposta.
2. Faça uma pergunta. Adicione isto abaixo:
1pergunta = "Quem gerencia o Northstar e quando o feedback é revisado?"2print(responder(pergunta))
3. Execute-o. Salve rag.py, então no seu terminal:
1python rag.py
Você deve obter uma resposta real construída a partir do seu arquivo, algo como:
Dana Reyes é a engenheira líder que gerencia o Project Northstar, e o feedback é revisado toda sexta-feira. (Fonte: notes.txt)
Isso é um sistema RAG completo funcionando. Claude nunca viu este arquivo durante o treinamento, ele não pode saber quem é Dana Reyes, no entanto respondeu corretamente e disse exatamente de onde a resposta veio. Pergunte algo que não está em seus arquivos e ele dirá que não sabe, em vez de inventar uma resposta. Esse "não sei" é uma característica, não uma falha: é a diferença entre uma ferramenta confiável e uma que chuta.
Passo 7: Transforme isso em algo que você possa realmente usar
Agora, você precisa editar o código e reexecutar o script inteiro toda vez que quiser perguntar algo. Pior, cada execução relê seus arquivos e os readiciona ao banco de dados, então os pedaços se acumulam. Vamos consertar ambos: construir o banco de dados apenas uma vez, depois permitir que você faça perguntas em um loop, digitando-as diretamente no terminal.
1. Corrija a adição duplicada. Encontre o bloco do passo 4 que adiciona pedaços (a parte colecao.add(...)) e substitua por esta versão, que só constrói o banco de dados se estiver vazio:
1if colecao.count() == 0:2 colecao.add(3 ids=[str(i) for i in range(len(todos_pedacos))],4 embeddings=[emb.tolist() for emb in embeddings],5 documents=[pedaco["texto"] for pedaco in todos_pedacos],6 metadatas=[{"fonte": pedaco["fonte"]} for pedaco in todos_pedacos],7 )8 print(f"Armazenado(s) {colecao.count()} pedaço(s) no banco de dados.")9else:10 print(f"Banco de dados já tem {colecao.count()} pedaço(s), pulando reconstrução.")
Agora, o trabalho pesado (ler arquivos, criar embeddings, preencher o banco de dados) acontece apenas na primeira vez. Execuções posteriores pulam direto para a resposta.
2. Adicione o loop de perguntas. No final de rag.py, substitua a pergunta de teste única do passo 6 por isto:
1print("\nFaça uma pergunta sobre seus documentos (ou digite 'sair' para encerrar).\n")23while True:4 pergunta = input("Você: ")5 if pergunta.lower() in ["sair", "exit"]:6 break7 print("\nClaude: " + responder(pergunta) + "\n")
input("Você: ") espera você digitar uma pergunta e pressionar Enter. while True mantém isso em execução para que você possa perguntar quantas vezes quiser. Digitar sair para.
3. Execute-o. Salve rag.py, então no seu terminal:
1python rag.py
Agora você pode simplesmente conversar com seus arquivos:
Faça uma pergunta sobre seus documentos (ou digite 'sair' para encerrar).
Você: quem é a engenheira líder do Northstar?
Claude: A engenheira líder do Project Northstar é Dana Reyes. (Fonte: notes.txt)
Você: o que ele substituiu?
Claude: O Northstar substituiu o antigo sistema de planilhas usado até 2025. (Fonte: notes.txt)
Você: sair
Este é o seu sistema RAG finalizado. Ele lê seus arquivos uma vez, os lembra e responde perguntas sobre eles sob demanda, com a fonte toda vez.
Uma coisa para saber quando você adicionar novos arquivos. Como o banco de dados agora é construído apenas uma vez, colocar novos arquivos em documents não aparecerá automaticamente. Para carregar novos arquivos, delete a pasta chroma_db e execute o script uma vez. Ele reconstrói do zero com tudo na pasta.
Opcional: dê a ele uma janela de chat no seu navegador
O terminal funciona, mas se você quiser uma janela de chat real, o Streamlit adiciona uma em cerca de 20 linhas.
1. Instale-o. No seu terminal:
1pip install streamlit
2. Crie app.py na mesma pasta e cole isto. Ele reutiliza a função responder do seu rag.py:
1import streamlit as st2from rag import responder34st.title("Converse com seus documentos")56if "historico" not in st.session_state:7 st.session_state.historico = []89pergunta = st.chat_input("Pergunte sobre seus arquivos...")1011if pergunta:12 resposta = responder(pergunta)13 st.session_state.historico.append((pergunta, resposta))1415for p, r in st.session_state.historico:16 st.chat_message("user").write(p)17 st.chat_message("assistant").write(r)
3. Execute-o. No seu terminal (nota: streamlit run, não python):
1streamlit run app.py
Ele abre uma janela de chat no seu navegador automaticamente. Digite uma pergunta, obtenha uma resposta com sua fonte, igual ao terminal, mas mais bonito de ver.
Uma nota: para que isso funcione, o loop de perguntas do passo 7 não deve ser executado na importação. Envolva esse loop no final de rag.py em if __name__ == "__main__": para que ele só seja acionado quando você executar rag.py diretamente, não quando app.py o importar.
Deixando-o responder perguntas gerais também
Se você quiser que ele responda também perguntas gerais. Agora, o sistema só responde a partir de seus arquivos, então uma pergunta como "qual é a capital da Venezuela?" recebe "isso não está nos documentos", mesmo que o Claude saiba a resposta. Se você quiser que ele recorra ao seu próprio conhecimento, abra rag.py, encontre o bloco system=(...) no passo 6, e troque esta linha:
1"If the answer is not in the context, say you don't know. "
para esta:
1"If the answer is not in the context, answer from your own general knowledge but say you're doing so. "
Salve e execute novamente. Agora ele responde primeiro a partir dos seus arquivos e, quando os arquivos não cobrem a informação, usa o conhecimento geral, informando qual fonte foi usada.
Finalizando
Você acabou de construir um sistema RAG funcional. Ele lê seus próprios arquivos, encontra as partes relevantes e faz o Claude responder com base neles, sempre indicando a fonte exata. A mesma estrutura escala de algumas anotações para toda a sua base de conhecimento.
A partir daqui, você pode direcioná-lo para onde quiser: seu cofre do Obsidian, seus documentos de trabalho, suas pesquisas salvas. Coloque os arquivos, reconstrua uma vez e comece a perguntar. Tudo o que você aprendeu aqui — os chunks, os embeddings, a busca, a resposta — é a mesma espinha dorsal por trás de todas as ferramentas de "converse com seus documentos" que você já viu.
Se isso foi útil, vá até meu perfil e siga-me. Escrevo sobre tecnologia, IA e sistemas que realmente funcionam.
Tchau,
[@undefinedKi**](https://x.com/@undefinedKi





