Introdução

Exatamente hoje 19/04/2025 eu venho acompanhando ou pelo menos tentando acompanhar as novidades dos Harness, protocolos, novas versões de LLM e frameworks. Porém trabalhando e conversando com a comunidade eu percebi uma certa despreocupação e desconhecimento sobre os "evals" que nada mais são que testes onde você coloca métricas em qual quer etapa de qualquer projeto relacionado a AI e toma decisões de ajustes e mudanças. Portanto neste artigo vou explicar as principais métricas e frameworks que devem ser utilizados para melhorar sua qualidade de entrega de um projeto que envolve AI abordando tanto a teoria como a prática e no final eu tenho um repositório com todos os conceitos abordados aqui e ele é meu laboratório de estudo de novos métodos e frameworks para avaliação. E ultimo detalhe, tudo utilizando o Openrouter com LLM gratuita.

Por que avaliar sistemas de IA?

Parece meio obvio mas avaliar sistema de IA esta muito além de simplesmente, colocar teste e métricas e definir um threshold, existem questões de melhoria continua (quase um PDCA) e perca financeira e impactos até jurídicos. Por exemplo imagine que você vai lançar um chatbot de atendimento ao cliente sem nenhuma camada de qualidade, na primeira semana, o sistema responde perguntas simples super bem, na segunda, um usuário pergunta sobre como funciona o prazo de reembolso e seu chatbot simplesmente "alucina" e inventa um prazo que não é o prazo correto. O prejuízo é evidente, ainda mais em uma escala de vários usuários.

A avaliação de sistema de IA existe para tronar esse tipo de risco que na minha opinião é simples perto de outras complexidades um risco mensurável e gerenciável. Para ser breve eu acredito que existem 3 razões principais pelas quais a avaliação é indispensável:

1. Controle de qualidade pré-deploy: Antes de qualquer atualização em produção, você precisa de uma barreira mínima, assim como no desenvolvimento de software convencional existem testes unitários e de integração, para sistemas de IA existem os evals que de acordo com a sua politica de métricas ideias, os resultados devem passar antes de ser liberado.

2. Detecção de regressão: Quando você atualiza o modelo base como chatgpt e sua versão, gemini e os demais que tem no mercado, quando você muda um prompt, ou altera o retriver quando se trata de RAG, como saber se melhorou ou piorou? Sem métricas objetivas, você depende simplesmente da sua intuição ou achismo enfim. Com evals, você compara números.

3. Melhoria contínua orientada as métricas: Esse acho que é o ponto que menos vejo ser comentado, justamente por que os outros 2 pontos anteriores já foram aplicados então esta "tudo certo", um conceito que eu aprendi com MLFlow que é um framework de ciclo de vida de modelos de Machine Learning são os experimentos, você não deve tomar decisões de arquitetura no escuro. Elas rodam experimentos, medem o impacto com as métricas definidas e escolhem a abordagem vencedora com base em EVIDÊNCIAS.

Os 4 tipos fundamentais de avaliação

Antes de entrar em frameworks e código é importante entender que existem quatro estratégias de avaliação com finalidades distintas.

1. Code-based Eval (Avaliação baseada em código) É a forma mais direta, você escreve o código que verifica se a saída do modelo atende a critérios definidos, igualmente é com teste unitário mas para LLMs. Você define um input, uma saída esperada e um conjunto de dados que verificam se a resposta está correta.

Exemplo:

# 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"

1. Human Eval (Avaliação Humana)
   Calma não é o que esta pensando, a ideia é ter uma planilha ou lista de casos com critérios claros e cada avaliador atribui uma nota ou uma forma de avaliar como um like/deslike manualmente. Pode parecer a abordagem mais cara e lenta, mas é a mais confiável para capturar nuances que código e até LLMs (pelo menos por enquanto rsrs) não detectam, por exemplo: tom de voz inadequado, respostas tecnicamente corretas mas confusas, ou outputs que passam nas métricas mas frustram o usuário real.

2. LLM-as-judge Eval (Uma LLM como avaliador)
   Aqui um segundo modelo LLM entra em cena e avalia as respostas do seu projeto de AI. Dado o contexto (a pergunta, o output do modelo e opcionalmente o contexto recuperado ou documentos como queira chamar), o LLM-juiz emite uma avaliação estruturada: uma nota numérica, um veredito como aprovado/reprovado e se quiser o que eu recomendo o racional, ou seja a justificativa em linguagem natural obviamente.

3. User Eval (Avaliação pelos usuários)
   Não, não é o mesmo que o Human Eval, aqui é o feedback coletado diretamente de usuários do seu produto, como aqueles botões de like e deslike em redes sociais ou no Chatgpt, cada interação pode ser avaliada pelo usuário em tempo real. É a fonte de sinal mais valiosa em produção por que reflete o que realmente importa: a satisfação do usuário final.

As duas camadas de avaliação

Uma grande sacada da Anthropic e da Confident AI (criadora do DeepEval) é, avalie cada camada separadamente, não só no começo, não só nos experimentos, não só no final, mas sim em todas as etapas. Como eles definiram essas camadas:

1. Camada de raciocínio É onde o LLM decide o que fazer, avaliamos três aspectos nessa camada: Qualidade do plano: O agente dividiu a tarefa em passos lógicos e sequenciais? Um agente de AI recebe "analise o desempenho de vendas do Q3 e sugira melhorias" deve quebrar isso em sub-tarefas como por exemplo: buscar dados, calcular métricas, comprar com período anterior, gerar as recomendações. Se ele tenta tudo de uma vez, o plano é fraco.

Seleção de ferramentas: O agente escolheu a ferramenta adequada para cada passo (MCP tools) ou chamou uma API de clima quando deveria chamar uma API de cotação, isso é um erro de seleção. Vamos abordar mais a frente mas isso é detectável com métricas como ToolCorrectness.

Geração de argumentos: E por ultimo, o seu agente de AI gerou os argumentos corretos para a ferramenta escolhida? Chamar a ferramenta certa com parâmetros errados é pior do que chamar a ferramenta errada, por que você pode olhar e ver que chamou a ferramenta correta e esquecer dos parâmetros.

Camada de Ação

Aqui é onde as ferramentas executam no mundo real, e você avalia o resultado como observação, e o agente decide o próximo passo. Nessa camada, a métrica chave é a eficiência: o agente completou a tarefa em poucos passos, ou ficou num loop desnecessário repetindo as mesmas chamadas?

Agora vamos ver mais código e aqui entre o ponto 5 do artigo.

5. Os três níveis de granularidade

Na prática, você trabalha com avaliações em três granularidades que se complementam:

5.1 Nível de Componente

É o mais granular — como um teste unitário para cada parte do agente. Você monitora individualmente a chamada ao LLM, o retriever, cada tool. Se algo falha, você sabe exatamente onde falhou.

No DeepEval, isso é feito com o decorator @observe, que instrumenta automaticamente cada função com métricas específicas.

from deepeval.tracing import observe

@observe()  # Isso instrumenta a função automaticamente
def retrieve_documents(query: str) -> list[str]:
    # Seu código de retrieval aqui
    return documents

5.2 Nível End-to-End

Olha o resultado final: dada uma tarefa, o agente completou? O plano fazia sentido? Ele foi eficiente? Esse nível é essencial, mas perigoso quando usado sozinho — um "pass" no end-to-end pode esconder problemas sérios de componente.

Pense numa analogia: um médico pode fazer o diagnóstico correto por razões erradas. O paciente fica bem, mas o raciocínio do médico estava incorreto — e isso vai falhar no próximo caso mais difícil.

5.3 Nível de Conversação

Para agentes que interagem em múltiplos turnos (chatbots, assistentes de voz, agentes de suporte), há uma terceira dimensão: o agente manteve informações ao longo do diálogo? Resolveu a necessidade do usuário como um todo, não apenas na última mensagem?

Um usuário que na mensagem 1 diz "sou alérgico a amendoim" e na mensagem 8 pergunta "que lanche você recomenda?" espera que o agente lembre da restrição. Avaliar conversação é avaliar a consistência e a continuidade do contexto.

6. O conceito de LLM-as-judge

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 G-Eval formaliza isso, permitindo criar métricas customizadas para qualquer critério — 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
)

Métricas com e sem referência

Um ponto crucial na escolha de métricas é se elas precisam de um "ground truth" (resposta esperada) ou não:

Com referência (reference-based) precisam da resposta correta como base de comparação. São ótimas para desenvolvimento e testes, onde você tem datasets anotados. Exemplo: verificar se o resumo capturou os pontos principais de um documento específico.

Sem referência (referenceless) funcionam sem dados rotulados — elas avaliam a resposta apenas com base no input e no contexto. São essenciais para produção, onde não existe resposta esperada pré-definida para cada interação real.

A boa prática é usar no máximo 5 métricas por avaliação: 2-3 genéricas do sistema (como ToolCorrectness para agentes, Faithfulness para RAG) e 1-2 customizadas para o seu caso de uso específico.

7. DeepEval na prática

O DeepEval é um framework open source que 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.

7.1 Instalação e configuração

Instalação
pip install deepeval

Login opcional (para relatórios na nuvem Confident AI)
deepeval login

O DeepEval precisa de um LLM-juiz para rodar as métricas semânticas. Por padrão usa OpenAI, mas suporta Anthropic, Ollama, ou qualquer modelo via DeepEvalBaseLLM — o que você verá no projeto llm_judge_rag.

7.2 Os três objetos fundamentais

O DeepEval trabalha com três abstrações principais que você precisa entender antes de escrever qualquer código:

LLMTestCase é a unidade básica de avaliação. 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])

7.3 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)`

8. 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.

8.1 O problema que 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 — 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.

8.2 As métricas principais

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.

8.3 Arquitetura mental do RAGAS

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

8.4 O fluxo básico do RAGAS

Pergunta do usuário
        ↓
    Retriever
        ↓
Contextos recuperados
        ↓
 LLM gera resposta
        ↓
RAGAS avalia:
  ├── Faithfulness    (resposta ↔ contextos)
  ├── AnswerRelevancy (resposta ↔ pergunta)
  ├── ContextPrecision (contextos ↔ pergunta)
  └── ContextRecall    (contextos ↔ resposta esperada)

8.5 RAGAS vs. frameworks de construção

Um ponto importante que o material de estudo enfatiza é a distinção de responsabilidades:

O RAGAS não constrói nada — ele é uma camada de medição que você coloca sobre o pipeline que já existe. Isso é um separação de responsabilidades importante de entender.

8.6 Quando usar e quando não usar

Use RAGAS quando você tem um pipeline RAG e quer responder perguntas como: "Qual versão do retriever performa melhor?", "Melhorou com o novo modelo de embeddings?", "Qual estratégia de chunking reduz mais alucinação?".

Não use RAGAS quando você ainda quer montar o pipeline, orquestrar ferramentas, ou automatizar workflows. O RAGAS também não substitui revisão humana em casos críticos — a recomendação é combinar avaliação automática com amostragem manual.

9. O repositório master_eval_learning

O repositório master_eval_learning é um laboratório prático de aprendizado que implementa três projetos independentes, cada um focado num tipo diferente de avaliação. A estrutura é a seguinte:

master_eval_learning/
├── deepEval_1/          # Pipeline offline: métricas determinísticas + LLM-judge
├── llm_judge_rag/       # RAG eval com DeepEval + LLM-judge semântico
├── ragas/               # RAG eval com framework RAGAS nativo
├── dataset.py           # Dataset compartilhado de casos de teste
├── metrics.py           # Métricas determinísticas implementadas do zero
├── pipeline.py          # Orquestrador principal da pipeline de eval
├── .env.example         # Template de variáveis de ambiente
└── pyproject.toml       # Dependências via Poetry

A separação entre dataset.py, metrics.py e pipeline.py na raiz é intencional e didática: ela mostra como separar rigidamente os dados de avaliação (o que avaliar), as métricas (como avaliar) e a orquestração (quando e com que configuração avaliar).

Configuração inicial

# Clone o repositório
git clone https://github.com/AirtonLira/master_eval_learning
cd master_eval_learning

# Instale as dependências
poetry install

# Configure as variáveis de ambiente
cp .env.example .env
# Edite .env e adicione sua OPENROUTER_API_KEY
export OPENROUTER_API_KEY="sk-or-..."

10. Projeto deepEval_1 — Pipeline offline de qualidade

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.

10.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.

10.2 O código do pipeline principal

Vamos analisar o arquivo pipeline.py em detalhe, pois ele ilustra bem os padrões de design para pipelines de eval:

pipeline.py

Pipeline de offline eval — roda antes de qualquer deploy.

Fluxo:
  Dataset → Métricas automáticas → (LLM-judge opcional) → Relatório → Pass/Fail

Uso rápido:
  python pipeline.py                     # só métricas automáticas
  python pipeline.py --llm-judge         # + LLM-as-judge (requer API key)
  python pipeline.py --category resumo   # filtra por categoria
  python pipeline.py --fail-fast         # para na primeira falha

O primeiro elemento a notar é o roteamento de métricas por categoria. A função evaluate_case não aplica as mesmas métricas para todos os casos — ela seleciona as métricas relevantes para o tipo de caso:

def evaluate_case(case: EvalCase, use_llm_judge: bool = False) -> list[MetricResult]:
    results: list[MetricResult] = []

    # Métricas universais (toda categoria recebe)
    results.append(no_harmful_content(case.llm_output))

    # Métricas específicas por categoria
    if case.category == "suporte":
        if case.expected_output:
            results.append(exact_match(case.llm_output, case.expected_output))
            results.append(
                contains_keywords(case.llm_output, [case.expected_output], threshold=0.9)
            )
        if case.retrieval_context:
            results.append(groundedness(case.llm_output, case.retrieval_context, threshold=0.3))

    elif case.category == "resumo":
        # Resumos não têm expected_output — foca em groundedness
        results.append(groundedness(case.llm_output, case.retrieval_context, threshold=0.35))

    elif case.category == "extracao":
        results.append(valid_json_schema(
            case.llm_output,
            required_fields=["empresa", "cnpj", "valor"],
            threshold=1.0,  # 100% dos campos obrigatórios
        ))

    # LLM-judge é opcional e tem custo
    if use_llm_judge:
        results.append(llm_judge_eval(case))

    return results

Esse design é importante: um resumo não deve ser avaliado por exact_match (nunca vai ter uma correspondência exata com a resposta esperada), mas deve ser avaliado por groundedness (não pode inventar conteúdo que não estava no documento original). Um JSON de extração deve ser avaliado por valid_json_schema. Cada categoria tem seu perfil de métricas.

10.3 O LLM-judge integrado

A função llm_judge_eval no pipeline mostra como implementar um juiz LLM de forma robusta, com tratamento de erros e fallbacks:

def llm_judge_eval(case: EvalCase, model: str = "anthropic/claude-sonnet-4-5") -> MetricResult:
    """
    Avalia qualidade geral via LLM-as-judge usando OpenRouter.
    Retorna MetricResult mesmo em caso de erro — nunca quebra a pipeline.
    """
    api_key = os.environ.get("OPENROUTER_API_KEY")
    if not api_key:
        # Se a key não existir, retorna "passou" para não bloquear a pipeline
        return MetricResult(
            metric="llm_judge",
            score=0.5, passed=True, threshold=0.6,
            reason="OPENROUTER_API_KEY não definida — skip",
        )

    # O prompt é cuidadosamente construído para retornar JSON estruturado
    prompt = f"""Avalie esta resposta de LLM. Retorne APENAS JSON válido.

PERGUNTA: {case.input}
RESPOSTA: {case.llm_output}

{{"score": <float 0.0-1.0>, "reason": "<1 frase>", "passed": <true/false>}}

Critérios: precisão factual, coerência com o contexto, utilidade para o usuário."""

    # Mede latência da chamada ao judge
    t0 = time.time()
    resp = client.chat.completions.create(
        model=model,
        max_tokens=400,
        messages=[{"role": "user", "content": prompt}],
    )
    latency = int((time.time() - t0) * 1000)

    # Parse robusto que remove markdown code fences
    raw = resp.choices[0].message.content.strip()
    parsed = json.loads(raw.replace("```

json", "").replace("

```", "").strip())

    return MetricResult(
        metric="llm_judge",
        score=round(float(parsed.get("score", 0.5)), 3),
        passed=bool(parsed.get("passed", score >= 0.6)),
        threshold=0.6,
        reason=f"{parsed.get('reason', '')} ({latency}ms)",
    )

Alguns detalhes importantes nessa implementação: o prompt pede explicitamente "APENAS JSON válido" para evitar que o modelo adicione texto antes ou depois do JSON. A remoção das code fences (`json) é uma necessidade prática porque muitos modelos envolvem JSON em markdown mesmo quando instruídos a não fazer isso. A latência é medida e incluída no resultado — isso permite monitorar o custo de tempo do judge ao longo do tempo.

10.4 Como rodar o deepEval_1

`shell
Apenas métricas determinísticas (gratuito, sem API)
python pipeline.py

Com LLM-judge (requer OPENROUTER_API_KEY)
python pipeline.py --llm-judge

Filtrar por categoria
python pipeline.py --category suporte
python pipeline.py --category resumo
python pipeline.py --category extracao

Parar na primeira falha (útil em CI/CD)
python pipeline.py --fail-fast

Aceitar até 20% de falhas (mais flexível)
python pipeline.py --min-pass-rate 0.8
`

A saída é um relatório no terminal com o resultado de cada caso e um sumário final:

`plaintext
──────────────────────────────────────────────────────────────
Offline Eval Pipeline
8 casos | LLM-judge: off
2026-04-19 10:30:00
──────────────────────────────────────────────────────────────

[PASS] suporte_001 (suporte) — score: 0.87
ok MetricResult(metric='no_harmful_content', score=1.0, passed=True)
ok MetricResult(metric='exact_match', score=0.95, passed=True)
ok MetricResult(metric='groundedness', score=0.72, passed=True)

[FAIL] resumo_002 (resumo) — score: 0.28
ok MetricResult(metric='no_harmful_content', score=1.0, passed=True)
!! MetricResult(metric='groundedness', score=0.15, passed=False)

──────────────────────────────────────────────────────────────
Resultado: 7/8 casos passaram (87%)
Pipeline: REPROVADO
──────────────────────────────────────────────────────────────
`

11. Projeto llm_judge_rag — RAG com LLM-judge semântico

Enquanto o deepEval_1 usa métricas determinísticas e heurísticas, o llm_judge_rag dá um passo adiante usando métricas semânticas baseadas em LLM-judge via DeepEval. O caso de uso simulado é um chatbot de RH corporativo que responde perguntas sobre políticas da empresa com base em documentos recuperados.

11.1 Arquitetura do projeto

`plaintext
hr_documents.py (7 políticas de RH como documentos de contexto)
↓
rag_engine.py (build_index → retrieve → generate_answer)
↓
openrouter_judge.py (OpenRouterJudge herda DeepEvalBaseLLM)
↓
test_hr_chatbot.py (5 métricas × 7 test cases)
`

O rag_engine.py implementa um pipeline RAG completo do zero com três componentes: o indexador usa o ChromaDB como vector database e SentenceTransformers para gerar embeddings; o retriever usa busca semântica por cosseno; e o gerador usa OpenRouter para produzir a resposta final condicionada ao contexto recuperado.

11.2 As 5 métricas de avaliação

`python
from deepeval.metrics import (
FaithfulnessMetric,
AnswerRelevancyMetric,
ContextualRecallMetric,
GEval,
)

Fidelidade ao contexto — o chatbot inventou algo?

faithfulness = FaithfulnessMetric(
threshold=0.7,
model=judge # Nosso OpenRouterJudge customizado
)

Relevância da resposta — a resposta responde a pergunta?

answer_relevancy = AnswerRelevancyMetric(
threshold=0.7,
model=judge
)

Cobertura do contexto — o retriever trouxe contexto suficiente?

contextual_recall = ContextualRecallMetric(
threshold=0.6,
model=judge
)

Tom profissional — linguagem adequada para RH?

tom_profissional = GEval(
name="Tom Profissional",
criteria="""A resposta usa linguagem adequada para comunicação de RH
corporativo: formal mas acessível, sem gírias, cordial.""",
evaluation_params=[LLMTestCaseParams.INPUT, LLMTestCaseParams.ACTUAL_OUTPUT],
threshold=0.7,
model=judge
)

Clareza — fácil de entender sem background técnico?

clareza = GEval(
name="Clareza",
criteria="""A resposta é clara e fácil de entender por um funcionário
sem background técnico em RH?""",
evaluation_params=[LLMTestCaseParams.INPUT, LLMTestCaseParams.ACTUAL_OUTPUT],
threshold=0.7,
model=judge
)
`

11.3 Casos de teste incluindo falhas deliberadas

Um aspecto muito importante do projeto é a inclusão de casos de falha deliberada — cenários onde se espera que o sistema falhe. Isso pode parecer contra-intuitivo, mas é essencial: uma boa suite de eval deve reprovar o que merece reprovar. Se todos os casos passam, seus thresholds provavelmente estão muito baixos.

`python

Caso de alucinação deliberada — deve FALHAR em Faithfulness

test_alucinacao = LLMTestCase(
input="Qual é o bônus de final de ano?",
actual_output="Todos os funcionários recebem 3 salários de bônus em dezembro.",
# ^ Essa informação não existe nos documentos de RH
retrieval_context=[
"A empresa oferece benefícios como plano de saúde, vale-refeição e PLR.",
# Nada sobre bônus de 3 salários
],
expected_output="Não há política de bônus fixo de final de ano documentada."
)
`

11.4 Como rodar os testes

`shell
export OPENROUTER_API_KEY="sk-or-..."

Suite completa

pytest llm_judge_rag/test_hr_chatbot.py -v

Filtrar por métrica

pytest llm_judge_rag/test_hr_chatbot.py -v -k "faithfulness"

Filtrar por caso de teste específico

pytest llm_judge_rag/test_hr_chatbot.py -v -k "alucinacao"

Rodar como script (sem pytest)

python llm_judge_rag/test_hr_chatbot.py
`

12. Projeto ragas — Framework nativo de avaliação RAG

Este projeto usa o framework RAGAS diretamente, em vez de wrappers. A principal diferença em relação ao llm_judge_rag é o vocabulário e a API:

12.1 Mapeamento de vocabulário: DeepEval vs. RAGAS

Entender esse mapeamento é importante para não se confundir ao portar datasets entre os dois frameworks.

12.2 A API moderna do RAGAS (versão 0.4+)

O RAGAS 0.4 introduziu uma API assíncrona mais limpa, com SingleTurnSample e EvaluationDataset:

`python
import asyncio
from ragas import EvaluationDataset, SingleTurnSample
from ragas.metrics import Faithfulness, AnswerRelevancy

Criando as amostras

sample_fiel = SingleTurnSample(
user_input="Quantos dias de férias os funcionários têm direito?",
response="Os funcionários têm direito a 30 dias corridos de férias por ano.",
retrieved_contexts=[
"A política de férias prevê 30 dias corridos anuais para todos os funcionários CLT."
],
reference="30 dias corridos de férias anuais."
)

Alucinação proposital para testar o detector

sample_alucinacao = SingleTurnSample(
user_input="Quantos dias de férias os funcionários têm direito?",
response="Os funcionários têm direito a 30 dias e podem converter 10 dias em abono pecuniário.",
# ^ "abono pecuniário" não está nos documentos recuperados
retrieved_contexts=[
"A política de férias prevê 30 dias corridos anuais para todos os funcionários CLT."
],
reference="30 dias corridos de férias anuais."
)

dataset = EvaluationDataset(samples=[sample_fiel, sample_alucinacao])
`

12.3 Configurando o LLM judge e embeddings via OpenRouter

Uma das partes mais interessantes desse projeto é a configuração do RAGAS para usar um modelo via OpenRouter (em vez da OpenAI nativa), usando as fábricas do RAGAS:
ragas_judge.py

`python
from openai import AsyncOpenAI
from ragas.llms import llm_factory
from ragas.embeddings import embedding_factory
from langchain_huggingface import HuggingFaceEmbeddings

def get_ragas_llm():
"""LLM judge via OpenRouter com cliente AsyncOpenAI-compatível."""
client = AsyncOpenAI(
api_key=os.environ["OPENROUTER_API_KEY"],
base_url="https://openrouter.ai/api/v1",
)
return llm_factory(
model="meta-llama/llama-3.1-8b-instruct",
openai_client=client,
)

def get_ragas_embeddings():
"""Embeddings locais via HuggingFace — sem custo de API."""
hf_embeddings = HuggingFaceEmbeddings(
model_name="sentence-transformers/all-MiniLM-L6-v2"
)
return embedding_factory(embeddings=hf_embeddings)

O uso de embeddings HuggingFace locais é uma escolha importante: a métricaAnswerRelevancy` precisa de embeddings para medir similaridade semântica entre a pergunta e a resposta, mas não é necessário usar uma API paga para isso.

12.4 Rodando a avaliação assíncrona

ragas_eval.py
`python
async def main():
llm = get_ragas_llm()
embeddings = get_ragas_embeddings()

# Métricas com as dependências injetadas
faithfulness = Faithfulness(llm=llm)
answer_relevancy = AnswerRelevancy(llm=llm, embeddings=embeddings)

# ascore roda as métricas em paralelo
results = await dataset.ascore(
    metrics=[faithfulness, answer_relevancy]
)

print(results.to_pandas())

asyncio.run(main())
`

O ascore é assíncrono — ele paraleliza as chamadas ao LLM judge, o que acelera significativamente a avaliação quando você tem muitos casos.

12.5 Resultado esperado

Com o dataset de demonstração (uma amostra fiel e uma com alucinação), o resultado esperado é:

A AnswerRelevancy permanece alta mesmo na amostra com alucinação porque a resposta ainda trata de férias — ela é relevante para a pergunta. Só a Faithfulness cai drasticamente, detectando que o "abono pecuniário" não estava no contexto recuperado. Isso demonstra por que você precisa de múltiplas métricas: cada uma captura uma dimensão diferente de falha.

`shell
Rodar a avaliação RAGAS
export OPENROUTER_API_KEY="sk-or-..."
python ragas/ragas_eval.py
`

14. Boas práticas e armadilhas comuns

Ao longo de tudo que vimos no material teórico e no repositório, algumas boas práticas se destacam:

Separe rigidamente o sistema avaliado do código de avaliação. O dataset.py, metrics.py e pipeline.py são completamente independentes do código do LLM ou do pipeline RAG que está sendo avaliado. Essa separação garante que as métricas não sejam "contaminadas" pelo sistema que estão medindo.

Inclua casos de falha deliberada na sua suite. Se todos os seus test cases passam, seus thresholds estão muito baixos. Uma boa suite deve reprovar casos que merecem reprovar — como respostas com alucinação clara ou conteúdo fora do escopo.

Limite-se a no máximo 5 métricas por avaliação. Mais métricas não significa melhor avaliação — significa mais custo, mais lentidão, e resultados mais difíceis de interpretar. Escolha 2-3 métricas genéricas e 1-2 customizadas para o seu caso.

Use métricas sem referência para produção. Em produção você não tem ground truth para cada interação real. Métricas como Faithfulness e AnswerRelevancy funcionam sem resposta esperada — são essenciais para monitoramento contínuo.

Meça latência do judge. O custo temporal do LLM-judge pode ser significativo em batches grandes. O pipeline.py inclui a latência no resultado de cada chamada — use essa informação para dimensionar seus pipelines de eval.

Combine avaliação automática com revisão humana. Em casos críticos (saúde, financeiro, jurídico), métricas automáticas não substituem revisão humana. A boa prática é usar eval automático para cobertura ampla e amostragem humana para casos de alta importância.

A armadilha do "pass por sorte". Um agente pode completar uma tarefa pelo caminho errado — acertando o resultado final mas com raciocínio fraco. Avalie sempre as duas camadas (raciocínio + ação) e os três níveis (componente, end-to-end, conversação).

Conclusão

Depois desse TCC rsrsrs, entendemos que 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 (vou deixar o Link no final do artigo), 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 Meu LinkedIn para que você possa me seguir e acompanhar o que venho postando e estudando

Elaborei esse artigo com base nas minhas anotações e estudos que realizei juntamente com a ferramenta obsidian ao longo de 2 semanas dedicando entre 2 a 3 horas de estudos.