DeepEval: O Framework Open-Source Que Traz Testes de Verdade Para Aplicações com LLMs
Existe um momento constrangedor em quase todo projeto de IA Generativa. A demo funciona, a equipe comemora, o modelo vai para produção. Três semanas depois alguém ajusta um prompt, troca a versão do modelo ou muda o chunking do RAG, e ninguém no time consegue responder com segurança a uma pergunta simples: a aplicação ficou melhor ou pior?
Em software tradicional essa pergunta tem resposta há décadas. Chama-se suíte de testes. Você roda (por exemplo) pytest, o pipeline passa ou quebra, e o merge acontece com base em evidência. Em aplicações construídas sobre LLMs, a resposta costuma ser um “achei que ficou melhor” dito com convicção em uma reunião.
O DeepEval existe justamente para eliminar esse achismo. É um framework open-source, licenciado sob Apache 2.0, que trata a qualidade de saídas de LLMs como aquilo que ela sempre deveria ter sido: um problema de teste automatizado.
O Problema: Por Que Testar LLM é Diferente?
Um teste unitário clássico é determinístico. A função recebe 2 e 3, devolve 5, e a asserção é binária.
Uma aplicação com LLM não funciona assim. A saída é texto livre, muda entre execuções e “correto” raramente é uma string exata. Um chatbot pode responder a mesma pergunta de cinco formas diferentes, todas aceitáveis. Um pipeline de RAG pode recuperar o documento certo e ainda assim gerar uma resposta que alucina detalhes. Um agente pode chegar ao resultado final correto tendo executado sete chamadas de ferramenta desnecessárias no caminho.
Comparar strings não resolve nenhum desses casos. Métricas estatísticas clássicas como BLEU e ROUGE também não, porque elas medem sobreposição de palavras e não raciocínio.
A abordagem que se consolidou no mercado é o LLM-as-a-Judge, ou seja, usar um modelo de linguagem como avaliador de outro. É exatamente aí que o DeepEval se posiciona, mas com uma diferença importante em relação a fazer isso na mão: ele encapsula o julgamento dentro de algoritmos confinados, com pontuações numéricas, limiares de aprovação e justificativas legíveis.
O Que é o DeepEval?
O DeepEval é um framework de avaliação para aplicações com LLMs, mantido pela Confident AI. Visite o site oficial: DeepEval.
Os princípios de design são:
1. Testes unitários no estilo Pytest. As avaliações são arquivos de teste comuns, executados via deepeval test run, que se integra ao Pytest.
2. Mais de 50 métricas prontas para uso, cobrindo RAG, agentes, uso de ferramentas, conversas multi-turno, segurança, MCP e multimodalidade.
3. Três escopos de avaliação: ponta a ponta, baseada em trajetória e em nível de componente.
4. Geração de dados sintéticos para cobrir casos de borda difíceis de coletar manualmente.
5. Customização total de métricas, prompts, modelos e templates de avaliação.
6. Execução local por padrão. As avaliações rodam no seu ambiente. Nenhuma conta é obrigatória.
Esse último ponto merece destaque para quem trabalha em ambiente corporativo. Você não precisa enviar dados para lugar nenhum. A única dependência externa é uma chave de algum provedor de modelo, como OPENAI_API_KEY, para as métricas que usam um LLM como juiz. E mesmo isso é flexível, já que o framework suporta Ollama, Azure OpenAI, Anthropic, Gemini, LiteLLM e modelos customizados rodando localmente.
Segundo a documentação oficial, o projeto processa mais de 20 milhões de avaliações por dia, o que dá uma noção da maturidade da adoção.
Os Blocos Fundamentais
Antes do código, quatro conceitos que aparecem o tempo todo:
Test Case. A unidade mínima de avaliação. Representa uma interação com a aplicação e carrega campos como input, actual_output (a saída real do seu sistema), expected_output, contexto recuperado e metadados. Para chatbots existe o ConversationalTestCase, formado por uma sequência de turnos.
Golden. Um caso de referência que ainda não foi executado. É a matéria prima dos datasets, que tornam a avaliação repetível entre prompts, modelos e releases.
Metric. A régua. Cada métrica devolve uma pontuação de 0 a 1 mais uma justificativa em texto. Um limiar (threshold, padrão 0.5) decide se o teste passa ou falha.
Trace. O registro em tempo de execução dos passos internos da aplicação: spans, entradas, saídas, chamadas de ferramenta. É o que permite avaliar agentes por dentro e não apenas pela resposta final.
Primeiro Teste em Cinco Minutos
A instalação é um pip install: pip install -U deepeval
O teste mais simples usa a métrica G-Eval, que permite definir um critério de avaliação em linguagem natural:
Execução: deepeval test run dsa_teste.py
Repare no que aconteceu aqui. Você não escreveu uma regra de comparação. Você escreveu um critério em português estruturado e o framework transformou isso em uma cadeia de passos de avaliação que produz nota e justificativa. Rodando mais de uma vez, você passa a comparar execuções e detectar regressões.
As Métricas: 50+ Réguas Prontas
A biblioteca de métricas é o principal ativo do DeepEval. As categorias:
Customizadas. G-Eval para critérios subjetivos (correção, tom, coerência) e DAG, uma métrica baseada em árvore de decisão, para critérios objetivos ou mistos, com a vantagem de produzir pontuações determinísticas. Existem também variantes conversacionais e de arena.
RAG. Separadas entre recuperador e gerador, o que é essencial para diagnóstico. No recuperador: Contextual Relevancy, Contextual Precision e Contextual Recall. No gerador: Answer Relevancy e Faithfulness, esta última a métrica clássica de alucinação contra o contexto recuperado.
Agentes. Divididas em dois escopos. Métricas de trajetória avaliam a execução completa: Task Completion, Step Efficiency, Plan Adherence e Plan Quality. Métricas de componente avaliam decisões individuais: Tool Correctness e Argument Correctness.
Multi-turno. Para chatbots: Knowledge Retention, Role Adherence, Conversation Completeness e Conversation Relevancy.
Segurança. Bias, Toxicity, PII Leakage, Misuse, Non-Advice e Role Violation.
Multimodal. Image Coherence, Image Helpfulness, Image Reference, Text-to-Image e Image-Editing.
Há ainda métricas avulsas como Hallucination, Summarization e Json Correctness.
Os Três Modos de Avaliação
Esta é, na prática, a decisão arquitetural mais importante ao adotar a ferramenta.
Ponta a ponta. Trata a aplicação como caixa preta. Você fornece entrada, saída e métricas. Ideal para APIs de LLM diretas, sumarizadores e verificações de qualidade gerais.
Baseada em trajetória. Avalia a cadeia completa de planos, chamadas de modelo, ferramentas e passos intermediários de um agente como uma unidade. Responde à pergunta “o caminho percorrido foi eficiente e coerente”, não apenas “o resultado final está certo”.
Em nível de componente. Usa o mesmo trace para pontuar um span por vez, permitindo localizar qual planejador, recuperador, ferramenta ou sub agente causou a falha.
Os três modos se combinam. O padrão maduro é pontuar o resultado, avaliar a trajetória e então inspecionar spans individuais quando algo falha.
Para agentes, o caminho passa por instrumentação via tracing:
O decorator @observe é não intrusivo e existem integrações prontas para LangChain, LangGraph, LlamaIndex, CrewAI, Pydantic AI, OpenAI Agents, Google ADK, Strands e AWS AgentCore, além de clientes drop-in para OpenAI e Anthropic.
Avaliação no CI/CD
Como o DeepEval se conecta ao Pytest, colocar avaliação de LLM no pipeline é trivial. O comando deepeval test run roda em qualquer provedor de CI e o resultado bloqueia ou libera o merge. Na prática, isso significa que uma mudança de prompt passa a ser tratada como qualquer outra mudança de código: sujeita a regressão detectável.
Esse é, na nossa visão, o argumento mais forte da ferramenta. Não é a lista de métricas. É o fato de a avaliação virar um portão automatizado.
Dados Sintéticos e Simulação de Conversas
Datasets bons são caros de construir. O DeepEval oferece o Golden Synthesizer para gerar casos de teste sintéticos, incluindo cenários de borda difíceis de coletar manualmente, e o Conversation Simulator, que simula interações multi turno de usuários contra o seu chatbot.
Para quem está começando um projeto sem histórico de produção, isso resolve o problema clássico do ovo e da galinha: você precisa de dados para avaliar, mas precisa avaliar para saber se pode ir para produção.
Uso Com Agentes de Codificação
Um detalhe que revela bem o momento atual do desenvolvimento de software: o DeepEval se posiciona explicitamente como harness de avaliação para agentes de codificação como Claude Code, Codex e Cursor.
A ideia é fechar um ciclo. O agente escreve ou corrige código, o deepeval test run executa as métricas via CLI, os spans pontuados com justificativas voltam para o agente, que lê as falhas e aplica novos patches. A avaliação deixa de ser uma verificação final e passa a fazer parte do loop de iteração.
Existe uma Skill instalável para essas ferramentas, o que reduz a configuração inicial a colar um prompt.
O Ecossistema
O DeepEval roda sozinho, mas conecta a dois projetos vizinhos:
Confident AI. Plataforma comercial da mesma empresa, com dashboards compartilhados, análise de regressão, observabilidade e monitoramento em produção. É opcional e a integração é nativa. Aqui vale a nota: o framework é genuinamente open-source e completo sem a plataforma, mas o modelo de negócio é claramente open core, então avalie o que você vai precisar em escala.
DeepTeam. Framework irmão voltado a red teaming, ou seja, testes adversariais de segurança contra vulnerabilidades de aplicações LLM.
Boas Práticas Que Valem a Leitura
A própria documentação faz uma recomendação contra intuitiva e muito acertada: use no máximo cinco métricas. A sugestão de distribuição é de 2 a 3 métricas genéricas de sistema (por exemplo, Task Completion para agentes ou Contextual Precision para RAG) e 1 a 2 métricas customizadas específicas do caso de uso.
O raciocínio por trás disso é simples. Medir tudo é a forma mais elegante de não priorizar nada. O exercício de escolher cinco réguas obriga o time a definir com clareza o que significa qualidade naquele produto, e esse é um trabalho que nenhuma ferramenta faz por você.
Outra distinção importante: métricas com referência exigem ground truth e servem para desenvolvimento. Métricas sem referência funcionam sem dados rotulados e são as únicas viáveis em produção, onde não existe gabarito.
Conclusão
Avaliação deixou de ser um item opcional no ciclo de vida de aplicações de IA Generativa. À medida que agentes ganham autonomia, encadeiam ferramentas e tomam decisões com impacto real, a diferença entre um sistema confiável e uma demo bonita passa a ser exatamente a existência de uma suíte de avaliação executável.
O DeepEval não é a única opção do mercado, mas acerta em três pontos que importam: roda localmente, integra ao Pytest e oferece métricas que enxergam por dentro de agentes e pipelines de RAG, não apenas a saída final.
Para quem constrói sistemas de IA de forma profissional, a recomendação prática é: comece pequeno. Escolha um caso de uso, escreva cinco casos de teste, defina uma métrica customizada com G-Eval e coloque isso no seu pipeline de CI. A primeira regressão detectada automaticamente costuma pagar todo o investimento.
Equipe DSA
Referências: