Ragas: avaliar seu RAG local com chiffres

#Por que 'isso parece bom' não é suficiente

Ragas é uma biblioteca Python de código aberto, sob licença Apache 2.0, que quantifica a qualidade de uma cadeia de busca documental: a fidelidade da resposta aos trechos fornecidos, sua relevância em relação à pergunta, a precisão e o recall do contexto recuperado. Assim, separa o erro da busca do erro do modelo. Pode ser executada com um juiz local, servido pelo Ollama, desde que esse modelo respeite o formato de saída estruturada que Ragas exige e que seu contexto contenha a pergunta inteira, os trechos e a resposta. Antes de adotá-la, lembre-se de três pontos: suas pontuações servem para comparar duas versões de um mesmo sistema, não para avaliar uma qualidade absoluta; o conjunto de testes é mais importante que a biblioteca; e os tutoriais online misturam a antiga e a nova API.

Quando uma resposta está errada, duas causas muito diferentes podem estar por trás do mesmo sintoma: ou os trechos recuperados não continham a informação, ou a continham e o modelo respondeu algo que não correspondia ao que foi perguntado. A correção não é a mesma — segmentação e embeddings no primeiro caso, modelo e prompt no segundo. Sem medição, corrigimos ao acaso, e uma melhoria em três perguntas piora as respostas a outras cinco sem que percebamos.

A outra armadilha é a comparação. A pergunta “O modelo de 27 bilhões de parâmetros é realmente melhor aqui?” se resolve repetindo o mesmo conjunto de perguntas, não discutindo. É isso que uma avaliação reprodutível permite fazer. Ragas ultrapassa 15.000 estrelas no GitHub. A última versão publicada no PyPI é a 0.4.3, de 13 de janeiro de 2026, e o repositório mudou de organização no GitHub (vibrantlabsai). Fixe a versão que você usa.

#As quatro medidas que importam

A documentação do Ragas especifica que a pertinência da resposta não avalia a exatidão: ela mede apenas a adequação à pergunta e penaliza respostas incompletas ou cheias de detalhes desnecessários. Por isso, não substitui a fidelidade. A análise conjunta é o que torna esses números úteis. Um recall baixo com alta fidelidade descreve um sistema honesto, mas mal alimentado: é preciso melhorar a recuperação. Uma fidelidade baixa com bom recall descreve o inverso: a informação estava lá, mas o modelo inventou detalhes. Os dois problemas se corrigem em pontos opostos da cadeia.

#Construir um conjunto de testes

Essa é a parte que exige trabalho e não pode ser automatizada sem consequências. Um conjunto útil contém perguntas realmente feitas pelos usuários, com suas formulações pouco claras, suas abreviações internas e seus erros de digitação — não perguntas reformuladas de maneira cuidadosa pela pessoa que escreveu a documentação.

1. 01
   Partir das perguntas reais

   Trinta a cinquenta perguntas provenientes do uso real valem mais que duzentas perguntas inventadas. Inclua as que falharam: são as mais instrutivas.
2. 02
   Escrever a resposta de referência

   Para cada pergunta, a resposta correta, escrita em uma ou duas frases. Ragas usa isso para estimar o recall do contexto: a versão baseada em um LLM usa essa referência como substituto dos trechos esperados, o que evita anotar os trechos um a um.
3. 03
   Manter os casos sem resposta

   Perguntas às quais o corpus não responde. Um bom sistema deve dizer isso; sem esses casos, nunca medimos essa qualidade.
4. 04
   Fixar o jogo

   Ele não deve mudar ao mesmo tempo que o sistema, caso contrário nenhuma comparação ao longo do tempo será possível.

O Ragas também oferece geração assistida de conjuntos de teste sintéticos a partir do próprio corpus: a documentação distingue perguntas de um salto (uma única fonte) de perguntas de múltiplos saltos (várias fontes a serem relacionadas), específicas ou abstratas. Um guia oficial mostra como adaptar essa geração a um corpus em outro idioma que não o inglês, usando o espanhol como exemplo, para iniciar uma primeira avaliação antes que as perguntas reais dos usuários tenham tido tempo de se acumular. É um ponto de partida conveniente, nunca um substituto: um conjunto inteiramente sintético não contempla as formulações pouco claras e os erros de digitação que, precisamente, revelam as fragilidades reais de uma busca documental.

#Executar tudo localmente

Ragas se baseia em dois modelos para avaliar: um modelo avaliador que lê a pergunta, os trechos e a resposta, e um modelo de embedding para as medições de similaridade. O quickstart do Ragas utiliza o OpenAI por padrão, mas mostra a variante Ollama: um cliente compatível com OpenAI apontado para http://localhost:11434/v1, passado à função llm_factory. Apenas a relevância da resposta exige um modelo de embedding: fidelidade, precisão e recall do contexto utilizam somente o avaliador.

Duas condições para que o juiz local seja confiável. A primeira é a saída estruturada: as métricas atuais exigem que o juiz forneça decisões intermediárias em um formato imposto (extração de afirmações, veredictos). Um modelo local pode responder em prosa e não cumprir esse contrato, gerando erros de JSON ou pontuações vazias (NaN); um guia da OneUptime recomenda testar o juiz com uma chamada mínima antes de qualquer campanha. Nenhuma fonte oficial define um tamanho mínimo de modelo: cabe a você verificar isso. A segunda é o contexto: o Ollama aplica por padrão 4.000 tokens de contexto quando há menos de 24 GiB de VRAM, e a documentação recomenda aumentar esse valor (variável OLLAMA_CONTEXT_LENGTH) para tarefas pesadas. Um juiz cujo contexto ultrapassa o limite está, na verdade, avaliando um texto truncado.

• Construa a cadeia RAG que você vai avaliar
• Escolher um modelo de embedding para o francês
• Adicione um reranker quando a precisão do contexto for baixa
• Langfuse: rastrear e armazenar as pontuações obtidas

# pip install ragas openai
from openai import AsyncOpenAI
from ragas.llms import llm_factory
from ragas.metrics.collections import Faithfulness, ContextRecall

# Client compatible OpenAI pointé sur Ollama (la clé est un simple libellé)
client = AsyncOpenAI(api_key="ollama", base_url="http://localhost:11434/v1")
juge = llm_factory("mistral", provider="openai", client=client)  # nom du modèle tiré avec ollama pull

fidelite = Faithfulness(llm=juge)
resultat = fidelite.score(
    user_input="Où se trouve la tour Eiffel ?",
    response="La tour Eiffel se trouve à Paris.",
    retrieved_contexts=["La tour Eiffel est située à Paris, en France."],
)
print(resultat.value)  # entre 0 et 1

#Ler os resultados sem se enganar

São indicadores, não notas

Uma fidelidade de 0,82 não significa «82% de respostas corretas». Esse número serve para comparar duas versões do mesmo sistema, não para garantir uma qualidade absoluta.

O juiz tem vieses

O artigo de referência sobre juízes LLM (arXiv 2306.05685) descreve vieses de posição, de verbosidade e de autopreferência. Mantenha o mesmo juiz de uma campanha para outra; caso contrário, as diferenças medem o juiz e não o sistema.

Uma única campanha não prova nada

A geração é variável. Em um pequeno conjunto de testes, uma diferença de alguns centésimos pode ser apenas ruído.

Leia alguns casos manualmente

Os números indicam onde olhar; eles não indicam o que está errado. Os dez piores casos de uma campanha ensinam mais do que a média geral.

#Casos de uso concretos

Escolher um tamanho para os trechos

Repetir o mesmo conjunto de testes com trechos de 256, 512 e depois 1024 tokens dá um número de recall por configuração, e não uma preferência não verificada.

Validar uma troca de modelo de embedding

Um novo modelo de embedding, mesmo anunciado como melhor em um benchmark geral, pode reduzir a precisão do contexto no seu corpus específico; só uma rodada de testes locais mostra isso.

Justificar a adição de um reranker

Comparar a precisão do contexto antes e depois do reranking quantifica um ganho que, caso contrário, continua sendo apenas uma impressão compartilhada em uma reunião.

Acompanhar uma regressão após a atualização do corpus

O acréscimo de novos documentos pode diluir a pesquisa; repetir o jogo de teste fixo após cada importação detecta a degradação antes que o usuário a perceba.

Escolher entre dois prestadores ou arquiteturas

Diante de duas propostas concorrentes para construir a mesma cadeia de processamento documental, uma pontuação obtida com o mesmo conjunto de teste e o mesmo corpus permite decidir mais rapidamente do que uma demonstração comercial.

#Organizar campanhas

Frequência das campanhas

Após cada mudança na divisão em trechos, no modelo de embedding ou no modelo de geração. Não é necessária uma campanha diária em um sistema estável.

Tamanho do corpus de teste

O conjunto de perguntas continua pequeno; já o corpus documental avaliado deve ser uma cópia realista — ou a totalidade — do corpus de produção.

Custo real de uma campanha

Cada métrica chama o juiz várias vezes (para a fidelidade: extração das afirmações, depois verificação de cada uma). O custo aumenta, portanto, com o número de perguntas multiplicado pelo número de métricas: cronometre cinco perguntas antes de executar as cinquenta, depois planeje a campanha de acordo.

#Limitações do método

Avaliar com um modelo significa pedir a uma inteligência artificial para julgar outra inteligência artificial: o método é útil, econômico e imperfeito. Ele detecta regressões e classifica variantes; não substitui a revisão humana em uma área em que há muito em jogo, na qual um erro factual implica responsabilidade. Por fim, cada campanha consome tempo de processamento: em uma máquina que também atende os usuários, ela deve ser executada quando a carga estiver baixa, à noite ou em um fim de semana, em vez de em pleno horário de uso.

O viés de verbosidade merece um comentário adicional, porque é contraintuitivo. Um artigo da OneUptime explica que um juiz tem mais oportunidades, em uma resposta longa, de citar as palavras-chave da rubrica de avaliação, de parecer exaustivo e de apresentar uma justificativa convincente. Um prompt que incentiva o modelo avaliado a ser mais verboso pode, portanto, aumentar uma pontuação sem melhorar a resposta do usuário. Para a fidelidade, a documentação do Ragas menciona também uma variante baseada no HHEM-2.1-Open, um pequeno classificador gratuito de detecção de alucinações da Vectara: ele substitui a etapa de verificação por um modelo especializado, que vale a pena testar se o seu juiz local for instável.

A solução mais simples é metodológica: nunca comparar um score de fidelidade obtido com um juiz a um score obtido com outro, nem a um score publicado por terceiros. O número tem sentido apenas dentro de uma mesma configuração de medição — mesmo juiz, mesmo prompt de avaliação, mesma versão das métricas. É uma ferramenta de comparação interna, não um ranking universal.

• Fonte: repositório oficial Ragas no GitHub
• Fonte: viés de verbosidade dos juízes automáticos
• Fonte: documentação oficial da métrica de fidelidade
• Fonte: quickstart Ragas, variante Ollama
• Fonte: comprimento de contexto padrão do Ollama
• Fonte: avaliar um RAG com um juiz local que produz JSON inválido
• Fonte: artigo de referência sobre juízes LLM

#FAQ