RAG local: introduction

#RAG local: a definição e o que você espera dele

RAG significa geração aprimorada por recuperação: primeiro recuperamos trechos relevantes de uma base de documentos, depois solicitamos ao modelo que gere uma resposta com base nesses trechos. A palavra local especifica que cada etapa (leitura dos documentos, cálculo de embeddings, armazenamento, geração) ocorre no seu hardware. É o uso mais útil de um modelo privado: perguntas sobre contratos, anotações ou uma base de conhecimento interna, com respostas que citam suas fontes.

#Por que usar RAG em vez de enviar tudo para o modelo?

Primeira ideia: copiar todos os documentos para o prompt. Há duas limitações que impedem isso. A janela de contexto é limitada: 300 PDFs representam milhões de tokens, bem além do que um modelo local aceita. E mesmo quando um documento cabe nessa janela, a qualidade cai: um estudo de referência (Liu et al., Stanford) mostra que o desempenho pode cair significativamente quando a informação útil está no meio de um longo contexto, mesmo para modelos projetados para longos contextos. Esse fenômeno chama-se lost in the middle.

O RAG contorna esses dois problemas ao transmitir ao modelo apenas alguns trechos selecionados para a pergunta. O modelo lê algumas centenas de tokens bem direcionados, em vez de dezenas de milhares de tokens pouco úteis, com menor custo computacional e menor latência. O segredo está em recuperar bem os trechos.

Uma estimativa, para fins ilustrativos: 300 PDFs de 20 páginas, com cerca de 600 tokens por página, representam 3,6 milhões de tokens, ou seja, centenas de vezes a janela de 8.000 tokens que geralmente é definida em um modelo local. Divididos em trechos de 400 tokens, eles geram cerca de 9.000 trechos. Uma pergunta retém cinco, ou seja, 2.000 tokens: o modelo lê 0,06% do corpus, mas os 0,06% certos se a busca for bem-sucedida.

#O conceito em dois minutos: embeddings e distância

Um embedding é uma lista de números que representa o significado de um texto. Dois textos que falam da mesma coisa têm vetores próximos, mesmo que usem palavras diferentes. A documentação de Ollama descreve os embeddings como vetores numéricos que podem ser armazenados em uma base vetorial, buscados por similaridade de cosseno ou utilizados em um RAG, com comprimento que depende do modelo, tipicamente entre 384 e 1024 dimensões.

Uma pergunta é transformada em vetor pelo mesmo modelo, depois comparada com todos os trechos indexados: os mais próximos são retornados. O ponto que atrapalha os iniciantes: o modelo de embedding usado para o índice e o usado para as perguntas devem ser iguais. A documentação do LlamaIndex reforça isso no exemplo de recarregamento do índice: é importante usar o mesmo embed_model que foi usado para construir o índice.

#Anatomia de um RAG: duas fases

#Fase 1: a indexação, feita uma vez por documento

1. 01
   Ingestão

   Ler arquivos (PDF, Word, Markdown, HTML) e extrair o texto limpo. É a etapa mais subestimada.
2. 02
   Segmentação

   Dividir em trechos pequenos o suficiente para serem precisos e grandes o suficiente para manter o sentido. Trechos de 200 a 500 tokens são um ponto de partida comum.
3. 03
   Embedding

   Passar cada trecho pelo modelo de embedding, por exemplo com o comando ollama run embeddinggemma ou a API /api/embed.
4. 04
   Armazenamento

   Salvar os vetores com o texto original e metadados (nome do arquivo, página, data).

#Fase 2: a requisição, para cada pergunta

1. 01
   Embedding da pergunta

   Com o mesmo modelo usado para indexação.
2. 02
   Pesquisa

   Encontrar os N trechos cujos vetores são os mais próximos, usando a similaridade de cosseno como medida.
3. 03
   Montagem do prompt

   Construir uma mensagem que contenha os trechos e a instrução de responder citando as fontes e de informar quando a resposta não estiver nesses trechos.
4. 04
   Geração

   Enviar este prompt para o modelo local, que redige a resposta.

#Pilha mínima e opções sem código

Para um RAG local que funcione, quatro componentes são suficientes: um modelo de geração servido por Ollama, um modelo de embedding, uma base vetorial e uma camada que os conecta. Para o francês, escolha um modelo de embedding multilíngue; na página de Ollama são recomendados três (embeddinggemma, qwen3-embedding, all-minilm) e os tamanhos dos vetores permanecem modestos, o que permite executá-los em um notebook.

Para não precisar codificar, o guia sobre RAG no LM Studio e o sobre AnythingLLM detalham cada caminho; o guia sobre NotebookLM e alternativas locais aborda a consulta "notebook lm rag".

#O pipeline em Python, passo a passo

O exemplo abaixo segue o esquema oficial do tutorial LlamaIndex com modelos locais: um leitor de pasta, um modelo de embedding, um modelo servido por Ollama, seguido por um motor de consulta. Instale primeiramente os pacotes llama-index-llms-ollama e llama-index-embeddings-huggingface. Ajuste os nomes dos modelos para os que você baixou.

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.huggingface import HuggingFaceEmbedding

Settings.embed_model = HuggingFaceEmbedding(model_name="intfloat/multilingual-e5-large")
Settings.llm = Ollama(model="qwen3.5:9b", request_timeout=360.0, context_window=8000)

documents = SimpleDirectoryReader("mes_documents").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine(similarity_top_k=5)

response = query_engine.query("Quelles sont les échéances du contrat Dupont ?")
print(response)
print(response.source_nodes)

A primeira execução calcula todos os embeddings, o que leva mais ou menos tempo dependendo do volume e da máquina. Para evitar recalcular tudo, salve o índice com index.storage_context.persist, depois recarregue-o com load_index_from_storage reutilizando o mesmo modelo de embedding. O parâmetro context_window limita a memória consumida, conforme explicado no tutorial.

#As armadilhas que fazem os primeiros testes falharem

A divisão ingênua quebra as estruturas

Um corte no meio de uma tabela gera trechos ilegíveis. Use uma ferramenta de divisão de texto que respeite títulos e tabelas, ou converta primeiro os documentos com Docling.

A língua do embedding conta

Um modelo de embedding treinado principalmente em inglês recupera trechos em francês com menos eficácia. Use um modelo multilíngue e teste-o com 10 perguntas reais antes de indexar todo o corpus.

Um único valor de top-k raramente é adequado

Poucos trechos empobrecem a resposta; trechos demais sobrecarregam o modelo. Ajuste conforme a natureza dos documentos e verifique com perguntas cujas respostas você conhece.

Uma busca ruim gera uma resposta confiante e falsa

Um modelo que recebe trechos irrelevantes pode inventar uma resposta que soe confiante. Meça primeiro a relevância dos trechos.

Os PDFs podem ser traiçoeiros

Duas colunas, rodapés, tabelas, digitalizações: uma parte importante do trabalho é limpar os dados durante a ingestão. Um PDF escaneado exige OCR antes de qualquer outro processamento.

Misturar modelos de embedding

Indexar com um modelo e consultar com outro dá resultados absurdos, sem mensagem de erro.

#Quando não usar RAG

O guia que compara fine-tuning e RAG detalha esse último caso.

#Hardware e confidencialidade: o que permanece com você

Em um RAG totalmente local, os documentos, os vetores e as perguntas permanecem na máquina, desde que cada componente o seja: embedding fornecido por Ollama ou carregado a partir do disco, base vetorial em arquivo ou em serviço local, modelo de geração local. Verifique se nenhum componente chama um serviço online: um embedder ou um modelo na nuvem selecionado por erro enviaria seus trechos para fora.

Em termos de hardware, o componente mais exigente é o modelo de geração: em Q4, um modelo com 8 a 9 bilhões de parâmetros cabe em cerca de 5 GB de memória, além da memória necessária para o contexto. Aqui, o contexto fica maior porque contém os trechos: reserve uma margem se você aumentar o número de passagens. O embedding, por sua vez, é leve; a indexação inicial de um grande corpus continua sendo a operação mais demorada e é feita uma única vez. O guia sobre LLMs sem GPU indica o que cada quantidade de RAM permite.

#E depois? As melhorias em ordem

Um RAG básico costuma responder bem a perguntas simples. Para ir além, a ordem que oferece o melhor retorno é a seguinte: primeiro uma divisão em trechos que respeite a estrutura, depois a busca híbrida (vetorial e por palavras-chave BM25, para não deixar passar um termo exato como um número de contrato), depois um reranker que reordene os primeiros resultados e, por fim, uma avaliação com um conjunto de cerca de cinquenta perguntas cujas respostas você conhece. Sem medição, cada mudança continua sendo apenas uma impressão.

• O que é o RAG: guia para iniciantes
• Estratégias de divisão de documentos
• Embeddings para o francês
• RAG no LM Studio
• AnythingLLM: tutorial RAG
• Avaliar um RAG com Ragas

• Fonte: embeddings em Ollama
• Fonte: tutorial LlamaIndex com modelos locais
• Fonte: Lost in the Middle (Liu et al.)
• Fonte: LM Studio, Chat with Documents