Todos os artigos

Back-end18 min de leitura

O que é RAG: indexação, busca híbrida e um caso real

O que é RAG (Retrieval-Augmented Generation), explicado com um caso real: crawler, chunking, embeddings, vector store, busca híbrida, re-rank e resposta com fonte.

Também em English, Español, Français

Se você chegou aqui pesquisando "o que é RAG", provavelmente já viu a sigla em vaga, em post sobre IA e em todo produto que promete "converse com os seus documentos". A ideia é bem mais simples do que o nome.

Eu construí um RAG do zero: o Nixa AI, um assistente de chat que responde perguntas sobre a documentação pública da NICE CXone, uma plataforma de contact center. Você pergunta em português, ele procura os trechos certos na documentação oficial e responde dizendo de onde tirou. O código é aberto e está no GitHub.

O Nixa: pergunta em português, resposta com o link da fonte

Esse post explica o que é RAG, como funciona a indexação (crawler, chunks, embeddings, vector store) e o caminho de uma pergunta (busca híbrida, re-rank, prompt e fontes), com os números reais do projeto.

TL;DR#

  • RAG é buscar antes de responder. O app procura trechos relevantes nos seus documentos e entrega pro modelo junto com a pergunta.
  • Tem duas metades: a indexação, que roda antes (baixa, corta, vira vetor, guarda), e a pergunta, que roda a cada mensagem (busca, ordena, monta o prompt, gera).
  • Embedding é um vetor de números que representa o sentido de um texto. Textos parecidos viram vetores próximos.
  • Busca só por sentido erra nome de API. No Nixa, a nota é 75% sentido e 25% palavra, e depois um re-rank ajusta por fonte, tipo de página e recência.
  • Um índice, um modelo de embedding. Trocou o modelo, reindexa tudo.
  • RAG não ensina nada ao modelo, só dá contexto. Se a resposta não está nos documentos, o certo é dizer que não achou.

O problema: o modelo não leu a sua documentação#

Um LLM sabe o que estava nos dados de treino até uma data de corte. A documentação do seu produto, a release note da semana passada, a wiki do time: nada disso ele viu. Quando você pergunta assim mesmo, ele faz o que sabe fazer de melhor, que é escrever um texto plausível. Às vezes certo, às vezes com um endpoint que nunca existiu.

A documentação da CXone é grande, espalhada por vários sites (central de ajuda, portal de developers, SDKs no GitHub) e quase toda em inglês. Achar uma resposta costuma ser abrir dez abas. Era o cenário perfeito pra RAG.

O que é RAG#

RAG é a sigla de Retrieval-Augmented Generation: geração aumentada por recuperação. O nome vem de um artigo de 2020 de pesquisadores do Facebook AI, e a ideia cabe numa frase: antes de gerar a resposta, recupere os trechos relevantes e coloque no prompt.

É prova com consulta. O modelo continua sendo quem escreve, mas em vez de responder de memória, responde com a página aberta na frente.

São três passos:

  1. Retrieval (recuperação): achar, numa base de documentos, os trechos que têm a ver com a pergunta.
  2. Augmentation (aumento): montar o prompt com esses trechos e a pergunta.
  3. Generation (geração): o LLM escreve a resposta usando aquele contexto.

Os passos 2 e 3 são quase triviais. Quase todo o trabalho (e quase todo bug) mora no 1. E pra recuperar bem, a base precisa ter sido preparada antes: é a indexação.

RAG, fine-tuning ou colar tudo no prompt?#

Antes de construir, vale entender por que não as outras duas opções óbvias.

Colar tudo no promptFine-tuningRAG
Como funcionaManda os documentos inteiros a cada perguntaTreina o modelo de novo com os seus dadosBusca os trechos relevantes e manda só eles
Documento novoÉ só colarTreina de novoIndexa a página nova
Custo por perguntaAlto: todos os tokens, toda vezBaixoBaixo: só alguns trechos
Mostra a fonteDifícilNãoSim, cada trecho sabe de onde veio
Bom praPoucos documentos curtosEnsinar estilo, formato, tarefaBase grande, que muda e precisa de fonte

Colar tudo funciona quando o conteúdo cabe com folga na janela de contexto. Não era o caso: só uma das páginas de release notes que eu indexei passa de 140 mil caracteres. Fine-tuning ensina comportamento, não é bom em guardar fato que muda toda semana e não diz de onde tirou a resposta. RAG resolve justamente as duas coisas que eu precisava: conteúdo que muda e fonte em toda resposta.

As duas metades de um RAG#

Todo RAG tem duas metades, que rodam em momentos diferentes:

  • Indexação, antes de qualquer pergunta: buscar os documentos, cortar em pedaços, transformar cada pedaço em vetor e guardar.
  • Pergunta, a cada mensagem: transformar a pergunta em vetor, achar os pedaços mais próximos, ordenar, montar o prompt e chamar o LLM.

No Nixa, a indexação é uma rota da API que eu disparo pela tela e que vai mandando o progresso por streaming. A pergunta é a rota do chat.

Indexação, passo a passo#

A indexação do Nixa, com os números do índice que está no repositório

1. O crawler: baixar e limpar#

O crawler começa por uma lista de 154 URLs semente e só segue links dentro de 11 domínios permitidos: a central de ajuda, o portal de developers e os SDKs oficiais no GitHub e no npm. Login, página de erro, arquivo binário e GitHub de terceiro ficam de fora.

Pra cada página, ele baixa o HTML e usa o Cheerio pra jogar fora o que não é conteúdo: menu, rodapé, banner de cookie, "esta página foi útil?". Esse lixo parece inofensivo, mas se entra no índice, aparece em todo resultado de busca, porque está em toda página.

crawler.ts
import * as cheerio from "cheerio";
 
export async function crawlPage(url: string) {
  const html = await fetch(url).then((res) => res.text());
  const $ = cheerio.load(html);
 
  // The same menu on every page means noise in every search result
  $("nav, footer, header, script, style, .cookie-banner").remove();
 
  const title = $("h1").first().text().trim();
  const content = $("main, article").first().text().trim();
  if (content.length < 150) return null; // empty or error page
 
  const pageType = classify(url, title); // api, reference, guide, release
  return { url, title, content, breadcrumb: getBreadcrumb($), pageType };
}

Além do texto, o crawler guarda metadados: título, breadcrumb (o caminho tipo "Agente > Copilot > Configurar"), o tipo da página (API, referência, guia, release note) e um hash SHA-256 do conteúdo. O hash serve pra economizar: na próxima indexação, se a página não mudou, ela não passa pelo embedding de novo. E página indexada há mais de duas semanas é baixada outra vez.

Guarde os metadados na cabeça, eles voltam no re-rank.

2. Chunking: cortar em pedaços#

Você não indexa a página inteira. Uma página de API pode falar de autenticação, paginação e limite de uso ao mesmo tempo, e o vetor da página inteira vira uma média de tudo isso: não fica perto de nenhuma pergunta específica. Então a página é cortada em chunks (pedaços).

No Nixa, o alvo é 900 caracteres por chunk, e cada chunk começa repetindo as últimas frases do anterior, até uns 200 caracteres. Isso é o overlap.

O overlap: o fim de um chunk abre o próximo. E o título vai junto com o parágrafo

O overlap existe porque a resposta não respeita a fronteira do seu corte. Se a frase que explica o parâmetro ficou no fim de um chunk e o exemplo ficou no começo do próximo, a repetição garante que pelo menos um dos dois tem as duas coisas.

Outro detalhe: um parágrafo curto que parece título ("Configurar o perfil") não vira chunk sozinho. Ele é colado no parágrafo seguinte, pra que o trecho carregue o assunto junto.

chunker.ts
export function chunkText(text: string, maxSize = 900, overlap = 200): string[] {
  const chunks: string[] = [];
  let current = "";
  let pendingHeading = "";
 
  for (const paragraph of text.split(/\n\n+/).map((p) => p.trim()).filter(Boolean)) {
    if (looksLikeHeading(paragraph)) {
      pendingHeading = paragraph; // glue it to the next paragraph
      continue;
    }
    const section = pendingHeading ? `${pendingHeading}\n${paragraph}` : paragraph;
    pendingHeading = "";
 
    if (current && current.length + section.length > maxSize) {
      chunks.push(current);
      // the next chunk starts with the last sentences of this one
      current = `${lastSentences(current, overlap)}\n\n${section}`;
    } else {
      current = current ? `${current}\n\n${section}` : section;
    }
  }
  if (current.length > 80) chunks.push(current);
  return chunks;
}

Repare que o corte é por parágrafo (\n\n). Isso tem uma consequência que eu conto no fim do post.

3. Embeddings: transformar texto em vetor#

Um embedding é uma lista de números que representa o sentido de um texto. Você manda um texto pra um modelo de embedding e recebe de volta um vetor, tipo [0.012, -0.341, 0.088, ...]. O truque é que textos com sentido parecido viram vetores que apontam pra direções parecidas, mesmo sem nenhuma palavra em comum: "como faço login na API" fica perto de "authentication with OAuth".

O tamanho do vetor depende do modelo. No índice do Nixa tem vetores de 384 números (o all-minilm, que roda local no Ollama) e de 3.072 números (o tamanho que o gemini-embedding-001 devolve). O app aceita três provedores de embedding: Gemini (o padrão), OpenAI (text-embedding-3-small) e Ollama.

Um truque barato que ajudou: antes de gerar o vetor, o título da página vai na frente do chunk. Um trecho que diz só "defina o valor como true" não significa nada sozinho. Com [Configurar o Copilot] na frente, passa a significar. A Anthropic descreve uma versão mais elaborada dessa ideia, o contextual retrieval.

const input = `[${chunk.title}] ${chunk.content}`.slice(0, 2000);
const { embedding } = await embed(input); // number[]

4. O vector store: guardar os vetores#

O vector store é onde ficam os chunks, os vetores e os metadados. E aqui vem a parte que surpreende quem espera um banco vetorial chique: no Nixa, é um arquivo JSON. O data/vectorstore.json do repositório tem 425 chunks de 62 páginas e pesa 11 MB.

Pra buscar, o app lê o arquivo, calcula a similaridade da pergunta com todos os chunks e ordena. Força bruta. Com 425 chunks, isso é instantâneo. Com centenas de milhares, aí sim você quer um índice de verdade, como o pgvector no Postgres ou um banco vetorial dedicado. Comece pelo simples e troque quando medir que precisa.

A medida de proximidade mais usada é a similaridade de cosseno: o quanto dois vetores apontam pra mesma direção, numa escala de -1 a 1.

function cosineSimilarity(a: number[], b: number[]): number {
  if (a.length !== b.length) return 0; // vectors from different models
  let dot = 0, normA = 0, normB = 0;
  for (let i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    normA += a[i] * a[i];
    normB += b[i] * b[i];
  }
  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
}

Guarde aquela primeira linha. Ela é o motivo de uma regra do projeto.

A pergunta, passo a passo#

O caminho de uma pergunta. A parte de cima não usa LLM nenhum

1. Expansão da pergunta: português pra inglês#

A documentação está quase toda em inglês e as pessoas perguntam em português. O embedding até lida bem com isso, mas a busca por palavra não: "relatório" nunca vai bater com "reporting".

Então a pergunta vira duas: a semântica é a pergunta original, e a léxica ganha termos em inglês colados no fim. São 19 regras, uma por assunto:

const PT_EN_TERMS = [
  { pattern: /(relat[óo]rio|dashboard|m[ée]tricas)/i, en: "reporting analytics reports dashboard metrics KPI" },
  { pattern: /(fila|filas|roteamento|skill)/i, en: "queue queues skill skillset ACD routing" },
  { pattern: /(autentica[çc][ãa]o|login|oauth)/i, en: "authentication oauth bearer access login" },
  // ...
];
 
function buildQuery(question: string) {
  const extra = PT_EN_TERMS.filter((term) => term.pattern.test(question)).map((term) => term.en);
  return { semantic: question, lexical: [question, ...extra].join(" ") };
}

"Como gerar um relatório de filas?" vai pro embedding do jeito que você escreveu, e pra busca léxica com "reporting", "queue", "ACD" e companhia.

2. Busca híbrida: sentido e palavra#

Busca só semântica é ótima pra pergunta vaga e ruim pra nome exato. Se alguém pergunta pelo agent-sdk, você quer o trecho que tem essa palavra, não um que fala de algo parecido. Busca só por palavra tem o problema contrário: não sabe que "entrar" e "login" são a mesma coisa.

A busca híbrida soma as duas. No Nixa, a nota de cada chunk é assim:

const isShort = question.split(/\s+/).length <= 2;
const semanticWeight = isShort ? 0.5 : 0.75;
const lexicalWeight = isShort ? 0.5 : 0.25;
 
// lexicalOverlap: share of the query words found in the chunk (0 to 1)
const score =
  cosineSimilarity(queryEmbedding, chunk.embedding) * semanticWeight +
  lexicalOverlap(lexicalQuery, chunk.content) * lexicalWeight;

Pergunta normal: 75% sentido, 25% palavra. Pergunta de até duas palavras vira meio a meio, porque com tão pouco texto o embedding tem pouco sentido pra captar, e a palavra exata pesa mais.

A parte léxica é a mais simples possível: a fração das palavras da pergunta que aparecem no chunk. Dá pra trocar por BM25 e melhorar, mas foi o suficiente pra acertar nome de API e de SDK.

Dessa conta saem os 20 melhores candidatos (quatro vezes o número de trechos que vão pro prompt, com mínimo de 16), que seguem pro re-rank.

3. Re-rank: o que a similaridade não sabe#

A similaridade só olha o texto. Mas eu sei coisas que o texto não diz: que a documentação oficial de API vale mais que um README qualquer, que pergunta técnica quer página de referência, que release note de ontem vale mais que a do ano passado. O re-rank é onde isso entra, somando bônus e descontos à nota:

SinalAjuste
Portal oficial de developers+0,15
Central de ajuda oficial+0,12
GitHub que não é dos SDKs oficiais-0,40
Pergunta técnica e página de API+0,12
Pergunta técnica e página de referência+0,10
Indexada há até 7, 30 ou 90 dias+0,06, +0,04 ou +0,02
Cada palavra da pergunta no título+0,025
Palavra da pergunta no breadcrumb+0,08
A pergunta inteira dentro do título+0,15

Pergunta "técnica" aqui é a que tem palavras como api, sdk, webhook ou endpoint. Depois do ajuste, chunks repetidos saem, tudo abaixo de 0,22 é descartado e os 5 melhores vão pro prompt.

Valores de exemplo, com os pesos de verdade do Nixa. O mesmo texto, em fontes diferentes, tem destinos diferentes

Re-rank por regra é o mais simples que existe. O passo seguinte seria um modelo de re-rank (um cross-encoder), que lê a pergunta e o trecho juntos e dá a nota. Pro tamanho dessa base, as regras resolveram, e cada uma é fácil de explicar quando um resultado sai estranho.

4. Saber quando não responder#

Antes de chamar o LLM, o Nixa olha a nota do melhor trecho e classifica a confiança: alta se passou de 0,6 e tem pelo menos dois trechos, média acima de 0,4, baixa no resto. Com confiança baixa ou nenhum trecho, ele nem chama o modelo: responde que não achou aquilo na documentação oficial.

Parece pouco, mas é a diferença entre um assistente útil e um gerador de chute com fonte bonita. Se o contexto é fraco, o modelo preenche o buraco com o que parecer plausível.

5. O prompt#

Os 5 trechos entram no prompt de sistema em XML, agrupados por tipo de página, cada um com título, URL e breadcrumb, e cortados em 700 caracteres:

<context>
<section type="API">
<document index="1" type="api" url="https://docs.example.com/api/auth">
  <title>Authentication</title>
  <breadcrumb>Documentation > Getting Started</breadcrumb>
  <content>...</content>
</document>
</section>
</context>

E as regras dizem o que fazer com eles: responder no idioma da pergunta, citar a fonte no texto com [Título](URL) e, se a informação não estiver no contexto, dizer que não localizou na documentação oficial em vez de inventar endpoint, campo ou versão. Quando duas fontes discordam, vale a ordem: API, depois referência, depois guia, depois release note.

O LLM pode ser Gemini, OpenAI ou Ollama (100% local). Trocar não muda nada no RAG: o prompt é o mesmo.

6. Só as fontes que foram usadas#

Muito RAG mostra embaixo da resposta tudo que a busca devolveu. Só que o modelo pode ter usado dois dos cinco trechos, e aí três "fontes" são enfeite.

No Nixa, a resposta vem por streaming e, quando termina, o servidor confere quais URLs aparecem de fato no texto e manda só essas:

export function selectCitedSources(answer: string, candidates: Source[]): Source[] {
  return candidates.filter((source) => answer.includes(source.url));
}

Uma linha. Como o prompt manda citar com o link, a fonte que aparece embaixo é a que o modelo realmente usou.

Um índice, um modelo de embedding#

Agora, aquela primeira linha do cosseno. Vetores de modelos diferentes não se comparam: são espaços diferentes, às vezes nem do mesmo tamanho. Entre um vetor de 384 números do all-minilm e um de 3.072 do Gemini não tem conta possível, e por isso a função devolve 0. Mesmo quando o tamanho bate, dois modelos organizam o sentido de jeitos diferentes: a nota sairia, mas seria lixo.

Por isso a regra do Nixa é embedding fixo por índice. O arquivo guarda qual provedor, qual modelo e qual dimensão geraram os vetores, e a busca sempre usa esse mesmo modelo pra transformar a pergunta, não importa qual LLM você escolheu pro chat. Dá pra conversar com o Ollama e buscar com o Gemini. Se a dimensão da pergunta não bate com a do índice, a busca não finge: cai pra busca só léxica e avisa no log pra reindexar.

const { embedding: queryEmbedding } = await getEmbedding(question, store.embeddingProvider);
 
if (store.dims && queryEmbedding.length !== store.dims) {
  console.warn("Embedding dimension mismatch, reindex. Falling back to lexical search.");
  return lexicalSearch(lexicalQuery);
}

Eu aprendi isso do jeito chato. O índice que está no repositório hoje mistura os dois: 330 chunks com vetores de 384 números, de uma indexação com o Ollama local, e 95 com 3.072, do Gemini. Pra uma pergunta transformada em vetor pelo Gemini, aqueles 330 têm similaridade zero e só aparecem pela parte léxica, que vale 25% da nota. Mais de três quartos da base quase invisíveis pra busca semântica, e nenhum erro na tela.

Trocar de modelo de embedding é trocar o índice inteiro. Não existe migração parcial.

A mesma busca, fora do chat#

Como a busca não depende de LLM nenhum, ela virou uma função própria, a searchNiceDocs(), que só devolve trechos. O chat chama essa função e depois gera a resposta. Mas outros clientes também podem chamar: ela está exposta como uma tool de MCP, a search_nice_docs, e como uma rota REST.

Assim o ChatGPT, o Claude ou o Cursor consultam a mesma base, e quem escreve a resposta é o modelo do próprio cliente. Se MCP é novidade pra você, escrevi sobre ele em O que é MCP.

Quando RAG não resolve#

RAG é bom em uma coisa: achar o trecho certo e responder a partir dele. Fora disso:

  • Pergunta que precisa da base inteira. "Quantas APIs existem?" ou "resuma todas as novidades do ano" não cabem em 5 trechos. Isso pede outro caminho, como uma consulta estruturada ou um resumo feito antes.
  • Dado que muda a cada minuto. O índice é uma foto. No Nixa, a pergunta "qual a última versão do agent SDK?" nem passa pelo RAG: o app consulta o registro do npm na hora e responde com a versão e a data de publicação.
  • Documento ruim. Se a resposta não está escrita em lugar nenhum, ou está errada, o RAG recupera fielmente a coisa errada.
  • Mudar o jeito do modelo. Tom, formato, um tipo de tarefa: isso é prompt ou fine-tuning, não recuperação.
  • Corte mal feito. Se o chunking separa a pergunta da resposta, nenhum re-rank salva. Que é o próximo assunto.

O que aprendi#

Cortar por estrutura tem um preço. O chunker corta em parágrafos (\n\n). Quando uma página chega sem nenhuma linha em branco, ela vira um parágrafo só, e um chunk só. No índice atual, 62 chunks passam de 2 mil caracteres, e o maior, uma página de release notes, tem 142.273 caracteres. O embedding lê só os primeiros 2 mil. O resto existe no arquivo e não existe pra busca semântica. O conserto é um corte de segurança: se o parágrafo passa do limite, quebra por frase.

Metadado é metade do ranking. O título na frente do chunk, o tipo da página, o breadcrumb e o domínio fizeram mais diferença nas respostas do que eu esperava. E custam quase nada pra guardar no crawler.

Dizer "não sei" é recurso, não falha. A nota mínima e a confiança antes de chamar o LLM cortam a resposta inventada que mais engana: a que vem com fonte e tudo.

Deixe a busca observável. Com RAG_DEBUG=true, cada pergunta loga a query expandida, a nota de cada trecho e a confiança. Quando uma resposta sai errada, o primeiro lugar pra olhar é a busca, não o LLM: se o trecho certo não chegou no prompt, nenhum modelo acerta.

Comece com um JSON. Vector store em arquivo, cosseno na mão, busca léxica de dez linhas. Dá pra entender cada número que sai. Banco vetorial é otimização pra quando a base crescer.

Referências#

  • Back-end
  • rag
  • ia
  • embeddings
  • llm
  • nextjs
  • typescript

Escrito por

Engenheira de software e designer. Escrevo sobre o que encontro construindo apps, APIs e produtos.