Índice do artigofaltam 9 min de leitura
O índice inteiro do nosso corpus, com 374 documentos e 2.563 trechos, é montado em 0,4 segundo e ocupa 2,15 MB. Não houve banco de dados, servidor de busca nem serviço pago envolvido.
A maior parte do material sobre como construir um RAG começa pela escolha do banco vetorial e termina no prompt. É a ordem inversa da que funciona, e ela produz sistemas que impressionam na demonstração e decepcionam no uso.
Este artigo descreve os seis passos na ordem em que eles decidem o resultado, com os parâmetros reais de um índice que construímos e medimos. Cada passo traz o que ele destrava e o que acontece quando ele é pulado.
Resumo do artigo
- A avaliação vem primeiro, não por último. Ela responde de graça a pergunta mais cara do projeto: a base sustenta as perguntas do negócio?
- Os parâmetros de fatiamento importam mais que a escolha do banco: alvo de 350 palavras, teto de 550, sobreposição de 80.
- Dois filtros vêm antes do modelo caro. Um classificador barato barra a pergunta fora do escopo, e a busca exclui conteúdo vencido.
- O índice de 2.563 trechos cabe em 2,15 MB e é montado em 0,4 s, o que elimina banco, cache e uma classe inteira de bugs.
O que decidir antes de escrever a primeira linha
Três decisões travam o resto do projeto, e todas são de negócio, não de engenharia. Adiá-las produz retrabalho na etapa em que ele é mais caro.
- Quais fontes entram e qual é a versão oficial de cada assunto quando duas se contradizem
- Quem pode ver o quê, porque permissão precisa entrar na busca e não no texto da resposta
- O que é sensível a tempo, como preço, prazo e SLA, e por isso precisa de regra própria de validade
- O que acontece quando o sistema não sabe, incluindo o texto exato que ele vai mostrar
- Quem é o dono de ler as perguntas sem boa resposta e corrigir o conteúdo
A última é a que mais some do escopo e a que mais determina se o assistente continua bom seis meses depois. Sem dono, a base envelhece e as respostas pioram devagar, sem nenhum alarme.
Passo 1: transformar documentos em trechos
O modelo não recebe documentos, recebe pedaços. Fatiar bem é o que decide se o pedaço que chega ao modelo contém uma ideia completa ou o final de um raciocínio e o começo de outro.
A regra que funciona é respeitar a estrutura do documento antes de contar palavras: cortar por seção, e só então agrupar seções curtas ou dividir seções longas até chegar ao tamanho alvo.
| Parâmetro | Valor e motivo |
|---|---|
| Alvo por trecho | 350 palavras, o suficiente para uma ideia completa sem diluir os termos que a busca usa |
| Teto | 550 palavras, para uma seção longa não virar um trecho que domina o contexto sozinho |
| Sobreposição | 80 palavras entre trechos vizinhos, para a resposta que cai na emenda não se perder |
| Piso | 25 palavras, abaixo disso o trecho é descartado por não carregar informação |
| Mediana obtida | 119 palavras, porque muitas seções são curtas e viram trechos próprios |
A distância entre o alvo de 350 e a mediana de 119 diz uma coisa útil sobre conteúdo institucional: ele é feito de muitas seções curtas. Perseguir o tamanho alvo à força, colando seções que não têm relação, piora a busca em vez de melhorar.
Cada trecho precisa carregar consigo os metadados que vão ser usados depois: a URL de origem, o título do documento, a data, o tipo de fonte e a seção de onde saiu. Recuperar o texto sem saber de onde ele veio inviabiliza a citação, que é a metade do valor do sistema.
A URL merece atenção especial. Ela precisa ser a mesma que o site publica como canônica, senão as citações do assistente apontam para endereços que redirecionam.
Passo 2: indexar, começando pelo mais simples
A escolha padrão da indústria é gerar embeddings e guardar num banco vetorial. A escolha que recomendamos para começar é uma busca lexical por palavras, do tipo que bibliotecas de busca implementam há décadas.
O motivo não é ideológico, é de sequência: a busca lexical não tem custo por consulta, não exige serviço externo, roda em segundos e produz uma linha de base contra a qual qualquer coisa mais sofisticada precisa provar que melhora. Sem linha de base, você não sabe se o banco vetorial ajudou.
Nessa escala, o índice inteiro cabe na memória do processo e percorrer tudo é mais rápido que consultar uma estrutura aproximada. O que isso destrava é operacional: sem banco, some a categoria de erro mais chata de um RAG, que é o índice e o texto ficarem dessincronizados e o sistema citar um documento que já mudou.
Passo 3: o porteiro que vem antes da busca
Antes de buscar qualquer coisa, uma pergunta precisa ser respondida: isso é assunto da empresa? Colocar essa decisão depois da busca é o erro de desenho mais comum, e ele custa nas duas pontas.
A tentação é usar a pontuação da busca como critério: se nada pontuou bem, o assunto está fora. Medimos e a hipótese está refutada. A pergunta "qual a melhor receita de bolo de cenoura" pontuou 9,52 no nosso índice, contra 8,88 de "vocês desenvolvem chatbot com IA". A pergunta fora do escopo ganhou.
Esse mesmo classificador resolve a segunda categoria perigosa, que é a pergunta de preço, prazo e SLA. Ela está no escopo, e mesmo assim não deve ser respondida por geração de texto: ela vai para um caminho próprio, com conteúdo curado e atualizado, ou para o contato humano.
Passo 4: escolher o que entra no contexto do modelo
Recuperar dez trechos e mandar os dez é o comportamento padrão de um protótipo, e ele produz dois problemas que só aparecem em uso real.
O primeiro é a dominância de documento. Uma página longa tem muitas seções e, se todas pontuarem razoavelmente, ela ocupa a lista inteira e o resto da base fica invisível. A correção é um teto de trechos por documento, que no nosso caso é dois.
O segundo é o conteúdo vencido. Como a relevância não enxerga data, documento antigo vence com frequência. A correção é etiquetar cada trecho com uma faixa de frescor derivada da data e excluir as faixas vencidas antes de montar o contexto, com exclusão permanente para o que é sensível a tempo.
O terceiro ajuste é mais sutil e vale a pena medir antes de aplicar: quantos trechos entregar. Na nossa medição, dobrar a lista de 10 para 20 trechos comprou 3,6 pontos percentuais de acerto.
Isso significa que material adicional acima de certo ponto adiciona custo e ruído sem adicionar resposta. O ganho está em melhorar o conteúdo, não em mandar mais dele.
Passo 5: gerar a resposta com citação
Só aqui o modelo grande entra, e ele entra com uma instrução restritiva: responder apenas com o material fornecido, e dizer que não sabe quando o material não sustentar a resposta. Um modelo bom obedece a isso com bastante consistência quando o material recuperado é limpo.
A citação é o que transforma a resposta em algo auditável: cada afirmação passa a ter um endereço de origem, e quem recebeu a resposta consegue conferir sem pedir ajuda a ninguém.
Ela também é o que permite corrigir. Uma resposta errada com fonte aponta qual documento precisa mudar; uma resposta errada sem fonte vira discussão.
Essa peça tem uma armadilha de implementação que só aparece na tela.
Passo 6: a avaliação, que quase todo projeto pula
Esta é a etapa que separa um projeto de engenharia de uma sequência de palpites, e a boa notícia é que ela é a mais barata de todas: roda sem modelo, sem chave de API e sem custo.
O material de avaliação já existe na maioria das empresas: são as perguntas que a operação responde por escrito, cada uma associada ao documento que a responde. Duas métricas bastam para começar. A primeira é se o documento certo apareceu entre os primeiros resultados. A segunda, mais reveladora, é quanto da resposta correta estava presente no material recuperado.
$ node tools/rag/eval.js638 perguntas avaliadas, 1.788 trechos no índicerecall@10 74,9%cobertura da resposta 54,1%critério estrito de 85%: não atingido
O valor real dessa etapa não está no número agregado, está na lista de perguntas que falharam. Ler essa lista é a atividade de maior retorno do projeto inteiro, porque cada falha aponta para um documento que precisa ser escrito, corrigido ou aposentado.
Um detalhe de método que muda o resultado: a avaliação precisa remover do índice o texto das próprias perguntas. Sem isso você mede se o sistema encontra o que já está escrito com as mesmas palavras, o que dá números excelentes e não prova nada.
Onde o dinheiro vai
O custo de operação de um RAG é bastante assimétrico, e entender a assimetria é o que permite desenhar barato.
| Etapa | Custo por pergunta | Observação |
|---|---|---|
| Classificação de escopo | Muito baixo | Poucas dezenas de tokens de entrada, saída mínima, modelo pequeno |
| Busca | Praticamente zero | Percorre um índice em memória, sem chamada externa |
| Geração da resposta | O maior de todos | Único passo que usa o modelo grande, com o contexto recuperado junto |
| Indexação | Não é por pergunta | Roda no build ou em agenda, e o nosso leva 0,4 segundo |
A consequência de projeto é a ordem dos filtros. Toda pergunta que o classificador barra é uma geração que não aconteceu, e a geração é o único item caro da tabela. Um sistema que busca e gera primeiro, e só depois avalia se deveria ter respondido, paga o item caro em todas as perguntas ruins.
Onde hospedar
Quando o índice cabe no pacote de deploy, a arquitetura fica pequena de um jeito que resolve problemas em vez de criar.
O que essa simplicidade destrava é confiabilidade. Sem banco, o índice e o texto publicado são gerados no mesmo processo e não podem divergir. Sem cache separado, some a invalidação. A complexidade de infraestrutura passa a se justificar quando o corpus não cabe mais em memória, e não antes.
Duas regras de segurança fecham o desenho. O índice não pode ser publicado numa pasta pública, porque isso entrega o conteúdo estruturado para qualquer rastreador. E a chave do modelo não pode entrar numa variável de ambiente que o empacotador do site inclui no pacote do navegador, porque toda variável desse tipo vira texto visível no navegador de quem acessa.
Sete erros que já custaram retrabalho
| Erro | O que acontece |
|---|---|
| Escolher o banco vetorial antes de medir | Compra-se infraestrutura para um problema que talvez não exista, sem linha de base para comparar |
| Avaliar com perguntas que estão no índice | Os números saem ótimos e não dizem nada sobre pergunta inédita |
| Usar a pontuação da busca como filtro de escopo | Pergunta fora do assunto passa, e pergunta legítima é recusada |
| Ignorar a data dos documentos | O conteúdo antigo vence a disputa por relevância e a resposta sai desatualizada |
| Mandar todos os trechos recuperados | Uma página longa domina o contexto e o resto da base fica invisível |
| Prometer citação de seção sem verificar as âncoras | O link cai no topo da página e o usuário não encontra o trecho |
| Não definir quem cuida do conteúdo | O sistema nasce bom e degrada sozinho, sem alarme |
Um caminho de entrega que funciona
A ordem abaixo tem uma propriedade útil: cada etapa entrega valor sozinha e tem um critério de aceite verificável, o que permite parar em qualquer ponto sem ficar com um sistema pela metade.
- Decisões de conteúdo, sem escrever código: fontes oficiais, permissões, o que é sensível a tempo e quem é o dono da curadoria.
- Índice e avaliação, rodando local. O aceite é ter a lista de perguntas que a base não responde, que já é entregável por si só.
- Endpoint com classificador, busca e geração. O aceite é o conjunto de perguntas passar, incluindo as de fora do escopo caindo na recusa.
- Busca com IA na interface que já existe, mantendo a busca antiga como reserva para falha de rede.
- Assistente conversacional, por último, porque é o que exige o estado de recusa pronto e a política de dados resolvida.
Se o orçamento acabar depois da segunda etapa, a empresa fica com um mapa das perguntas que o negócio recebe e não sabe responder por escrito. Esse mapa costuma valer mais do que o assistente.
Fontes e método
Os parâmetros e números deste artigo vêm de um protótipo de recuperação construído sobre o conteúdo público da X-Apps, executado em 31 de agosto de 2026, com 374 documentos e 2.563 trechos.
A avaliação usou 730 perguntas escritas pelo time de conteúdo com documento de origem conhecido, das quais 638 foram avaliadas após descartar 5 sem corpo de documento e 87 sem termo distintivo em comum com o documento esperado.
A ressalva de alcance: essas medições avaliam recuperação, e não a qualidade final do texto gerado. O corpus é de conteúdo institucional em português, e bases de outra natureza, como código ou documentos jurídicos multilíngues, podem exigir decisões diferentes de fatiamento e de busca.
Perguntas frequentes
Pela avaliação, não pela geração. Monte o índice, rode as perguntas reais da operação e leia os trechos recuperados sem pedir resposta a nenhum modelo. Se os trechos respondem, o projeto é viável. Se não respondem, o problema é de conteúdo e nenhum modelo resolve.
No nosso índice, o alvo é de 350 palavras com teto de 550 e sobreposição de 80 palavras entre trechos vizinhos, respeitando a divisão por seções do documento. A mediana ficou em 119 palavras porque muitas seções são curtas e viram trechos próprios.
Não. Nosso índice de 2.563 trechos é montado em 0,4 segundo e cabe em um arquivo de 2,15 MB, sem banco nenhum. Nessa escala, percorrer tudo é mais rápido que consultar um índice aproximado e não perde resultado.
Cada trecho carrega a URL do documento de origem desde a indexação, e a resposta referencia essa URL. Citar uma seção específica exige que os títulos do documento tenham âncora própria, o que nem todo site publica: sem isso o link cai no topo da página em silêncio.
A geração da resposta, porque é o único passo que usa o modelo grande. Por isso o desenho coloca dois filtros antes dela: um classificador barato que barra pergunta fora do escopo e a busca, que não tem custo por consulta.
Com um conjunto fixo de perguntas reais com documento de origem conhecido, rodado a cada alteração. Sem isso, toda mudança vira opinião e regressões passam despercebidas até um usuário reclamar.
Se o índice cabe no pacote de deploy, uma função sem servidor resolve e elimina banco, cache e o risco de índice e texto ficarem dessincronizados. A complexidade de infraestrutura só se justifica quando o volume de documentos passa do que cabe em memória.
