Como criar esteiras de avaliação de alucinação em RAG com Ragas e Python

A arquitetura de Geração Aumentada por Recuperação (RAG) consolidou-se como o padrão técnico para conectar documentos corporativos a modelos de linguagem, mas a presença de respostas desconexas ou inventadas exige a criação de esteiras automatizadas de avaliação contínua. Sem uma rotina de testes programáticos integrada ao ciclo de integração contínua (CI/CD), alterações em bases de dados vetoriais, ajustes de prompts ou atualizações de modelos de inferência podem introduzir regressões silenciosas de fidelidade factual. No ecossistema de desenvolvimento em Python, a biblioteca Ragas desponta como o framework de referência para calcular métricas quantitativas de alucinação e precisão de recuperação.

Projetada para avaliar sistemas baseados em documentos sem depender exclusivamente de anotações humanas manuais, a biblioteca Ragas calcula indicadores matemáticos como fidelidade (faithfulness), relevância da resposta (answer relevancy) e precisão de contexto (context precision). Nosso tutorial prático orienta desenvolvedores e engenheiros de dados no passo a passo para configurar uma esteira automatizada em Python com pytest, integrar bases de avaliação e definir critérios rigorosos de aceitação antes do deploy de aplicações corporativas.

Resumo rápido

• Ragas é uma biblioteca Python especializada em mensurar fidelidade e relevância em RAG.
• A métrica de faithfulness verifica se as afirmações da resposta decorrem do contexto recuperado.
• A métrica de answer relevancy afere se a saída atende diretamente à pergunta original formulada.
• Testes automatizados com pytest bloqueiam deploys quando a taxa de alucinação ultrapassa o limite.
• A abordagem substitui avaliações manuais subjetivas por métricas estatísticas auditáveis.

Fundamentos teóricos e métricas centrais do framework Ragas

Avaliar a qualidade de um sistema RAG requer decompor o fluxo em dois pilares fundamentais: a qualidade do componente de recuperação (Retrieval) e a fidelidade do componente de geração (Generation). Se o recuperador falha em trazer os trechos de documentos pertinentes, o modelo gerador é forçado a interpolar dados. Por outro lado, mesmo diante de um contexto perfeito, o modelo pode ignorar as instruções e produzir inferências incorretas.

O framework Ragas formaliza essa distinção por meio de três métricas primordiais calculadas via chamadas estruturadas de avaliação:

• Fidelidade (Faithfulness): calcula a proporção de afirmações contidas na resposta gerada que podem ser inferidas diretamente do contexto recuperado. Varia de 0 a 1, onde 1 indica ausência total de alucinação extrínseca.
• Relevância da resposta (Answer Relevancy): avalia a concisão e a pertinência da resposta em relação à pergunta formulada pelo usuário, penalizando rodeios, prolixidade ou omissões do tema principal.
• Precisão do contexto (Context Precision): mede a densidade de informações úteis nos trechos documentais retornados pela busca vetorial, premiando pipelines que posicionam o trecho decisivo no topo dos resultados.

Essa parametrização matemática permite que as equipes de engenharia estabeleçam metas objetivas de qualidade no código, tratando a confiabilidade da inteligência artificial com o mesmo rigor aplicado a testes de unidade convencionais.

Comparativo de métricas de avaliação e pesos recomendados

Em projetos de software empresarial, diferentes aplicações possuem tolerâncias distintas a falhas. Um assistente de atendimento receptivo para comércio eletrônico pode priorizar relevância e cordialidade, enquanto um assistente de auditoria tributária ou compliance bancário deve exigir fidelidade absoluta ao documento canônico.

A tabela a seguir apresenta os limites mínimos recomendados para homologação de pipelines em diferentes segmentos de mercado:

Ao estabelecer esses limites em arquivos de configuração de testes, qualquer modificação de código que reduza a precisão do sistema reprova a esteira de integração, impedindo que versões defeituosas cheguem aos servidores de produção.

Passo a passo para estruturar a esteira de testes em Python

Para construir a esteira, a equipe de desenvolvimento deve instalar as dependências necessárias no ambiente virtual por meio do gerenciador de pacotes pip: pip install ragas langchain pytest pandas. Em seguida, organiza-se um conjunto representativo de perguntas, contextos e respostas de referência em formato JSON ou CSV.

O roteiro de implementação técnica segue quatro fases estruturadas:

• Fase 1: Preparação do dataset de avaliação: compilar uma amostra de pelo menos cinquenta perguntas com seus respectivos contextos canônicos e respostas ideais validadas por especialistas do negócio.
• Fase 2: Execução do pipeline RAG sob teste: rodar as perguntas na versão candidata da aplicação e capturar os contextos recuperados e as respostas geradas em tempo de execução.
• Fase 3: Cálculo das métricas com Ragas: carregar os resultados no avaliador da biblioteca e computar as pontuações individuais e a média consolidada de fidelidade.
• Fase 4: Validação com asserts no pytest: definir asserções programáticas (ex: assert score['faithfulness'] >= 0.95) que determinam a aprovação ou rejeição da compilação.

Para aprofundar o conhecimento sobre a arquitetura de recuperação subjacente, confira nosso artigo detalhado sobre RAG na prática e bancos vetoriais sem alucinação. Além disso, a governança de modelos pode ser complementada com o guia sobre como testar agentes de IA antes de colocar em produção.

Exemplo: clínica de diagnósticos por imagem em Florianópolis

Para compreender o impacto operacional da esteira, considere uma rede de clínicas de diagnóstico por imagem sediada em Florianópolis, Santa Catarina. A instituição desenvolveu um assistente baseado em RAG para apoiar secretárias e recepcionistas no esclarecimento rápido de dúvidas sobre preparação para exames de ressonância magnética, jejum obrigatório e uso de contrastes alérgicos.

Durante a fase de testes preliminares, a equipe médica constatou com preocupação que, em algumas perguntas sobre contraste iodado, o modelo generalizava orientações de outros exames, fornecendo instruções incompletas de ingestão hídrica. A liberação de um sistema com esse tipo de alucinação colocaria a saúde dos pacientes em risco imediato e violaria protocolos sanitários.

A equipe de tecnologia implementou a biblioteca Ragas integrada ao repositório Git no GitHub Actions. Criou-se um conjunto de teste com duzentas perguntas clínicas cobrindo todos os tipos de exames oferecidos. A esteira foi configurada com um critério inegociável: qualquer compilação com fidelidade (faithfulness) inferior a 0,98 é cancelada automaticamente.

Quando a equipe trocou o modelo de embeddings por uma versão mais rápida, o teste automatizado barrou o commit na mesma hora, demonstrando que a alteração havia reduzido a precisão do contexto em perguntas sobre pacientes diabéticos. A equipe ajustou a estratégia de divisão de blocos (chunking) e os filtros de metadados até que a suíte de testes registrasse pontuação 0,99 em toda a base. O assistente foi liberado para as unidades com homologação clínica documentada e auditável.

Integração contínua e monitoramento em ambiente de produção

A avaliação de modelos de linguagem não termina com o deploy bem-sucedido na nuvem. Em produção, os usuários finais formulam perguntas com estruturas sintáticas, gírias regionais e erros ortográficos que muitas vezes não constavam no dataset inicial de testes de bancada.

Recomenda-se adotar as seguintes práticas operacionais de observabilidade contínua:

• Amostragem assíncrona de tráfego real: salvar 5% das consultas de produção em um banco de registros e rodar a suíte Ragas diariamente durante a madrugada.
• Monitoramento de drift de contexto: acompanhar se novos manuais e procedimentos carregados na base vetorial mantêm índices consistentes de recuperação semântica.
• Versionamento conjunto de código e dados: armazenar os arquivos de teste de avaliação no mesmo repositório do código-fonte para rastrear o histórico de qualidade ao longo das versões.
• Alarmes integrados à equipe de sustentação: disparar notificações automáticas no Slack ou Microsoft Teams sempre que a média semanal de relevância apresentar tendência de queda.

Essa vigilância permanente consolida a maturidade da engenharia de dados, garantindo que o investimento em inteligência artificial resulte em valor duradouro, estabilidade operacional e segurança jurídica para toda a empresa.

Erros comuns

• Avaliar apenas a resposta e ignorar o contexto recuperado: desconsiderar o componente de busca impede saber se o erro decorreu do banco vetorial ou da geração do LLM.
• Utilizar datasets de teste excessivamente pequenos: rodar validações com apenas dez perguntas mascara falhas críticas em casos de borda e situações atípicas.
• Ajustar o prompt apenas para passar no dataset de teste: cometer overfitting sobre as perguntas de avaliação reduz a capacidade de generalização do modelo diante de novos termos.
• Não auditar custos de API durante a execução dos testes: rodar baterias exaustivas de avaliação com modelos de grande porte sem controle de orçamento pode gerar faturas inesperadas.
• Subestimar o impacto do chunking na precisão: dividir documentos em blocos muito pequenos corta o contexto; blocos excessivamente grandes diluem a informação útil.
• Ignorar a latência na esteira de CI/CD: suítes de teste que demoram horas para rodar desestimulam a execução contínua pelos desenvolvedores no fluxo diário.

Perguntas frequentes

A biblioteca Ragas exige chaves de API da OpenAI para calcular as métricas?

Por padrão, o Ragas utiliza modelos da OpenAI como juízes avaliadores (LLM-as-a-judge), mas a biblioteca permite configurar modelos abertos locais (como Llama ou Mistral via vLLM) ou modelos de outros provedores compatíveis com LangChain.

Qual a diferença entre Context Precision e Context Recall?

Context Precision avalia se os trechos recuperados contêm prioritariamente informação útil no topo do ranking. Context Recall afere se todos os fatos necessários para responder à pergunta foram resgatados pelo recuperador.

Como funciona o conceito de “LLM-as-a-judge” no Ragas?

O framework utiliza um modelo de linguagem calibrado para analisar os textos, quebrar sentenças em premissas e avaliar a coerência lógica com base em rubricas e instruções matemáticas padronizadas.

É viável rodar o Ragas diretamente na máquina do desenvolvedor?

Sim. É possível executar os scripts localmente apontando para uma base de testes reduzida antes de enviar o código para o pipeline central de integração contínua no repositório.

Como lidar com perguntas que não possuem resposta na base de documentos?

O dataset de avaliação deve incluir perguntas sem resposta documental (negativas). A esteira deve testar se o sistema admite expressamente a falta de informação em vez de inventar uma justificativa plausível.

Fontes e leitura recomendada

• Documentação oficial do Ragas: guia completo de métricas e esteiras de avaliação
• Repositório GitHub do Ragas: código-fonte, exemplos práticos e atualizações da comunidade
• Documentação do pytest: boas práticas de automação de testes unitários e de integração em Python
• Documentação oficial do Python: frameworks de testes e asserções automatizadas