1. Por que avaliar sistemas de IA?
Imagine que você lança um chatbot de atendimento ao cliente sem nenhuma camada de avaliação de qualidade. Na primeira semana, o sistema responde perguntas simples normalmente. Na segunda, um usuário pergunta sobre política de devolução e o modelo do chatbot “alucina”, inventa um prazo que não existe. O prejuízo pode ser financeiro, jurídico ou simplesmente de reputação. A avaliação de sistemas de IA existe para tornar esse risco mensurável e gerenciável. Diferente de um software tradicional, onde o comportamento é mais fixo (mesmo input produz sempre a mesma saída), um sistema que usa LLM é probabilístico por natureza. Isso significa que você não pode simplesmente “testar” uma vez e confiar para sempre, existem métodos adequados para isso.
2. Vamos começar a entender mais os métodos e a teoria
Importante para evitar alucinação de LLMs, medir a qualidade e eficiência do seu sistema de AI é uma habilidade super importante. Existem 4 tipos de avaliações de AI, agentes e RAG principais:
- Code-based Eval: Use código para checar as respostas das IA, por exemplo passou ou falhou. Você define os inputs/outputs esperados e escreve o código que chama o método e confere se ele se comporta como deveria. Parecido com teste unitário.
- Human Eval: Quem avalia as respostas do modelo são humanos (você ou especialistas de um time), não código automático. A ideia é ter uma planilha com uma lista de casos e um conjunto de critérios claros, e depois consolidar as notas, dando like ou deslike de forma manual para avaliação.
- LLM as Judge Eval: Esse é famoso mas vale trazer, você utiliza um outro LLM para avaliar as respostas da sua AI dado o contexto. Com isso o LLM dado o contexto fornecido ele vai gerar a saída esperada, seja um relatório, um NPS (Nota de avaliação), você define como será a saída.
- User Eval: Teste com usuários reais (clientes) onde você coleta métricas e feedbacks, neste caso seria como se fosse o cliente que a cada resposta ele pode avaliar rapidamente como um like/deslike e até um feedback rápido (vai do perfil do negócio e estratégia).
É interessante em uma interação com um chatbot por exemplo, avaliar qual seria o próximo passo ideal do usuário e colocar com sugestão de pergunta ou resposta dependendo do contexto. Por exemplo o usuário perguntar como faz devolução de itens em um site Y de ecommerce e quando o chatbot responder, logo abaixo da resposta do chatbot aparecer sugestões do que mais ele pode perguntar.
O que estamos avaliando afinal?
Um agente de IA, não é simplesmente um LLM respondendo perguntas. Ele opera em loop: recebe uma tarefa, raciocina sobre ela, escolhe uma ferramenta, executa, observa o resultado e decide o próximo passo, repetindo até completar o objetivo.
Isso cria um problema fundamental: diferente de um LLM simples onde você avalia “input e output”, num agente existem múltiplos pontos de falha ao longo do caminho. O agente pode raciocinar bem mas chamar a ferramenta errada, ou chamar a ferramenta certa com argumentos errados, ou acertar tudo mas não saber quando parar.
3. As duas camadas de avaliação
A grande sacada que a Anthropic e a Confident AI (criadora do DeepEval) convergem é: avalie cada camada separadamente, não só o resultado final. Isso porque um agente pode completar uma tarefa “por sorte”, acertando o resultado final mas com um raciocínio fraco que vai falhar em cenários mais complexos.
Camada de raciocínio: É onde o LLM decide o que fazer. Aqui avaliamos três coisas: a qualidade do plano que o agente traçou (ele dividiu a tarefa em passos lógicos que fazem sentido?), se ele selecionou a ferramenta certa para cada passo, e se gerou os argumentos corretos para cada chamada de ferramenta. Chamar a ferramenta certa com argumentos errados é tão problemático quanto chamar a ferramenta errada.
Camada de ação: É onde as ferramentas executam no mundo real. O resultado volta como observação, e o agente decide o próximo passo. Aqui entra a eficiência: o agente completou em poucos passos ou ficou num loop desnecessário?
Na prática, você vai trabalhar com avaliações em três granularidades:
Nível de componente: É o mais granular, você decora cada função do seu agente (a chamada ao LLM, o retriever, tool calling) com métricas específicas. É como um unit test: se algo falha, você sabe exatamente onde falhou. No framework DeepEval, isso é feito com o decorator @observe.
Nível end-to-end: Olha o resultado final. Dada uma tarefa, o agente completou? O plano fazia sentido? Ele foi eficiente (poucos passos lógicos) ou ficou rodando em círculos? Esse nível é essencial mas perigoso sozinho, um “pass” no end-to-end pode esconder problemas de componente.
Nível de conversação: É para agentes que interagem em múltiplos turnos (chatbots, assistentes). Avalia se o agente manteve informações ao longo do diálogo e se resolveu a necessidade do usuário como um todo.
4. DeepEval na prática
Setup e instalação
O DeepEval funciona como uma extensão do pytest, você escreve “testes” para seu LLM da mesma forma que escreveria testes unitários para código normal. Setup básico:
# Instalação
pip install deepval
# Login opcional (para relatórios na nuvem)
deepval login
O DeepEval precisa de um LLM-juiz para rodar as métricas. Por padrão usa OpenAI, mas suporta Anthropic, Ollama, ou qualquer modelo via DeepEvalBaseLLM.
O LLMTestCase é a unidade básica, ele guarda o input, o output real do seu agente, e opcionalmente o output esperado (ground truth). A Metric define o que avaliar e qual o threshold mínimo de aprovação. O EvaluationDataset agrupa vários test cases para rodar em batch.
Vamos ver um exemplo de código com avaliação baseada em código (Code-based Eval):
# Exemplo conceitual de code-based eval
def test_response_contains_deadline():
response = llm.generate(“Qual o prazo de devolução?”)
assert “30 dias” in response.lower(), “Resposta deve mencionar o prazo de 30 dias”
assert len(response) < 500, “Resposta não deve ser excessivamente longa”
Uma das ideias mais poderosas na avaliação moderna é usar um LLM para julgar as saídas de outro LLM. Em vez de criar regras manuais para cada cenário, você define critérios em linguagem natural e o LLM-juiz avalia se o output atende. O framework DeepEval utiliza o GEval que formaliza isso, permitindo criar métricas customizadas para qualquer critério como tom de voz, aderência a guidelines, clareza de raciocínio, ausência de alucinações. Você escreve os critérios como instruções em linguagem natural, e o juiz produz uma pontuação de 0 a 1.
from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCaseParams
# Criando uma métrica customizada de “Tom Profissional”
tom_profissional = GEval(
name=”Tom Profissional”,
criteria=”””Avalie se a resposta usa linguagem adequada para comunicação
corporativa de RH: formal mas acessível, sem gírias, sem informalidades
excessivas, mantendo cordialidade.”””,
evaluation_params=[
LLMTestCaseParams.INPUT,
LLMTestCaseParams.ACTUAL_OUTPUT
],
threshold=0.7
)
Se aprofundando mais com LLMTestCase em um exemplo básico, aqui ele encapsula um cenário completo: o input que foi dado ao modelo, o output real que o modelo produziu, e opcionalmente o output esperado (ground truth) e o contexto de retrieval.
from deepeval.test_case import LLMTestCase
case = LLMTestCase(
input=”Qual é a política de férias da empresa?”,
actual_output=”Funcionários têm direito a 30 dias corridos de férias por ano.”,
expected_output=”30 dias corridos de férias anuais.”,
retrieval_context=[
“A política de férias prevê 30 dias corridos por ano para todos os funcionários CLT.”
]
)
Metric define o critério de avaliação e o threshold mínimo de aprovação. É o que vai julgar se o test case passa ou falha.
from deepeval.metrics import FaithfulnessMetric
faithfulness = FaithfulnessMetric(threshold=0.7)
EvaluationDataset agrupa vários test cases para rodar em batch — essencial quando você tem dezenas ou centenas de casos.
from deepeval import EvaluationDataset, evaluate
dataset = EvaluationDataset(test_cases=[case1, case2, case3])
results = evaluate(dataset, metrics=[faithfulness, answer_relevancy])
Criando um LLM-judge customizado
Para usar um modelo diferente do padrão (por exemplo, um modelo via OpenRouter), você herda de DeepEvalBaseLLM:
from deepeval.models import DeepEvalBaseLLM
from openai import OpenAI
class OpenRouterJudge(DeepEvalBaseLLM):
def __init__(self, model_name: str):
self.model_name = model_name
self.client = OpenAI(
api_key=os.environ[“OPENROUTER_API_KEY”],
base_url=”https://openrouter.ai/api/v1″,
)
def get_model_name(self) -> str:
return self.model_name
def load_model(self):
return self.client
def generate(self, prompt: str) -> str:
response = self.client.chat.completions.create(
model=self.model_name,
messages=[{“role”: “user”, “content”: prompt}],
max_tokens=1000,
)
return response.choices[0].message.content
async def a_generate(self, prompt: str) -> str:
# Versão assíncrona para eval paralela
return self.generate(prompt)
5. RAGAS: avaliação dedicada a RAG
RAGAS (Retrieval Augmented Generation Assessment) é um framework open source especializado em avaliar pipelines de RAG. Enquanto o DeepEval é uma ferramenta genérica de eval para qualquer sistema LLM, o RAGAS foi desenhado especificamente para o problema de RAG, onde você combina recuperação de informação com geração de texto.
5.1 O que realmente o RAGAS resolve
Sistemas RAG têm um desafio único: eles podem falhar de dois modos distintos, e esses modos têm causas e soluções diferentes.
Falha no retriever: o sistema busca trechos irrelevantes ou incompletos. A resposta pode até parecer coerente, mas está ancorada em contexto errado, ou seja uma forma silenciosa de falha que é difícil de detectar visualmente.
Falha no gerador: o LLM ignora o contexto recuperado e “inventa” informação, a clássica alucinação. Ou usa o contexto certo mas gera uma resposta vaga, confusa ou fora do escopo da pergunta. O RAGAS te ajuda a distinguir e medir cada tipo de falha separadamente, com métricas específicas para cada camada.
5.2 Para isso você precisa conhecer as métricas
Faithfulness (Fidelidade): mede se a resposta está ancorada no contexto recuperado. Uma resposta com alta fidelidade não afirma nada além do que está nos documentos recuperados. Isso é o principal detector de alucinação num sistema RAG.
Answer Relevancy (Relevância da Resposta): mede se a resposta está semanticamente relacionada à pergunta. Uma resposta pode ser fiel ao contexto mas completamente fora do escopo da pergunta, essa métrica captura exatamente isso.
Contextual Precision (Precisão do Contexto): avalia se os trechos recuperados são relevantes para a pergunta. Um retriever que traz muito ruído vai ter baixa precision mesmo que, no meio do ruído, também traga trechos úteis.
Contextual Recall (Cobertura do Contexto): mede se o contexto recuperado cobre toda a informação necessária para responder à pergunta. Um retriever que traz trechos relevantes mas incompletos vai ter baixo recall.
5.3 Para ajudar a entender melhor a combinação dessas métricas
Uma forma clara de pensar o RAGAS é separar o problema em três camadas:
- Recuperação: O sistema encontrou os trechos certos? → Contextual Precision e Recall
- Grounding: A resposta está ancorada no que foi recuperado? → Faithfulness
- Utilidade: A resposta realmente resolve a necessidade do usuário? → Answer Relevancy
6. Meu laboratório com toda a implementação do que vimos aqui e ainda mais um pouco
Este é o projeto mais fundamental do repositório. Ele implementa uma pipeline de avaliação offline, um conjunto de métricas que rodam antes de qualquer deploy como uma barreira de qualidade automática (quality gate). A ideia central é simples e poderosa: antes de colocar qualquer versão de um modelo em produção, você executa a pipeline contra um conjunto de casos de teste. Se os casos não passarem, o deploy é bloqueado. Isso é feito via exit codes que integram naturalmente com CI/CD.
6.1 As métricas implementadas
O projeto implementa seis métricas que cobrem diferentes dimensões de qualidade:
exact_match: verifica se a resposta é idêntica à esperada (após normalização). É a métrica mais rigorosa, útil para casos onde existe uma resposta definitiva e bem delimitada, como códigos de produto ou valores numéricos específicos.
contains_keywords: verifica a cobertura temática por palavras-chave. É mais flexível que exact_match, em vez de exigir correspondência exata, verifica se a resposta cobre os temas essenciais da resposta esperada.
valid_json_schema: valida que a saída é um JSON válido com campos obrigatórios presentes. É essencial para modelos usados em extração estruturada de dados.
groundedness: usa sobreposição de bigramas como proxy de alucinação. Calcula quantos bigramas (pares de palavras consecutivas) da resposta aparecem no contexto de retrieval. Uma resposta com baixo groundedness está “inventando” conteúdo não presente nos documentos.
no_harmful_content: verifica contra uma blocklist de conteúdo nocivo e tentativas de prompt injection. É a camada de segurança básica da pipeline.
llm_judge_eval: é a métrica mais sofisticada, usa um LLM via OpenRouter para fazer uma avaliação holística. É opcional (tem custo de API) e pode ser ativada com a flag –llm-judge.
7. Para finalizar
Para finalizar e apresentar o repositório com a aplicação dos frameworks DeepEval e RAGAS utilizando OpenRouter com LLM gratuita para os testes.
Avaliar sistemas de IA não é opcional em produção, é a diferença entre implantar confiança e implantar riscos. O que vimos ao longo deste artigo pode ser resumido em uma progressão lógica: começamos com os 4 tipos de avaliação (code-based, humana, LLM-as-judge, usuário) e entendemos que cada um tem seu lugar no ciclo de vida de um sistema de IA. Depois compreendemos que agentes operam em loop com duas camadas (raciocínio e ação) e que avaliar só o resultado final é insuficiente.
Aprendemos que existem três níveis de granularidade (componente, end-to-end, conversação) e que a análise completa requer os três. Na parte prática, vimos como o DeepEval implementa esse arcabouço teórico com uma API próxima ao pytest, permitindo criar métricas customizadas em linguagem natural via G-Eval e plugar qualquer provider de LLM como juiz.
Vimos como o RAGAS resolve o problema específico de pipelines RAG com métricas dedicadas à qualidade de recuperação e geração. E através do repositório master_eval_learning, vimos como tudo isso se materializa em código real: uma pipeline de quality gate que integra com CI/CD, um sistema RAG completo avaliado com métricas semânticas, e um exemplo de uso do RAGAS com embeddings locais e LLM via OpenRouter.
O campo de avaliação de sistemas de IA ainda está em formação, os frameworks evoluem rapidamente, novas métricas surgem, e as melhores práticas estão sendo estabelecidas agora. O mais importante é incorporar a cultura da avaliação desde o início: não como uma etapa final, mas como parte contínua do processo de desenvolvimento.
Referências e Recursos
- Repositório do projeto: github.com/AirtonLira/master_eval_learning
- DeepEval: docs.confident-ai.com
- RAGAS: docs.ragas.io
- OpenRouter (acesso a múltiplos modelos via API unificada): openrouter.ai
- ChromaDB (vector database open source): trychroma.com
- SentenceTransformers (embeddings locais): sbert.net
