Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Avaliar um Pipeline RAG

Aula 15 de 22 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Objetivos
  2. Os Dois Eixos da Avaliação
  3. Métricas de Geração
  4. Estrutura de Avaliação Completa
  5. Painel de Métricas
  6. Pontos-chave

Objetivos

  • Avaliar a recuperação e a geração separadamente
  • Implementar métricas automatizadas de qualidade RAG
  • Construir uma estrutura de avaliação completa

Os Dois Eixos da Avaliação

Um pipeline RAG falha de duas formas muito distintas, e confundi-las custar-lhe-á semanas. Ou o passo de recuperação falhou em encontrar os documentos certos — caso em que a resposta está errada por razões alheias ao modelo de geração, e as métricas da Lição 10 diagnosticarão isto — ou os documentos certos estavam presentes, mas o passo de geração descarrilou: o modelo inventou um detalhe ou respondeu a uma pergunta diferente da que foi feita.

Quando um utilizador reporta que «a resposta está errada», não lhe dirá qual das duas causas está em jogo. Daí a regra: meça ambos os componentes independentemente com métricas distintas e só ajuste um depois de identificar qual está a ter um desempenho insuficiente.

Métricas de Geração

A fidelidade responde à pergunta que mais importa em produção: a resposta é totalmente suportada pelos documentos fornecidos ou o modelo adicionou o seu próprio toque? Em vez de pedir uma pontuação global — que os avaliadores tendem a atribuir com demasiada generosidade — peça ao avaliador que decomponha a resposta afirmação por afirmação e classifique cada uma como suportada, não suportada ou contraditória. Esta última categoria é a mais valiosa: uma afirmação que contradiz a fonte sinaliza um erro muito mais grave do que uma simples omissão.

from openai import OpenAI

client = OpenAI()

def evaluate_faithfulness(
    question: str,
    answer: str,
    contexts: list[str]
) -> dict:
    """Avalia se a resposta é fiel aos contextos."""
    full_context = "\n\n---\n\n".join(contexts)

    response = client.chat.completions.create(
        model="gpt-5.6-terra",
        messages=[{
            "role": "user",
            "content": (
                f"Evaluate the faithfulness of this answer relative to the "
                f"source documents.\n\n"
                f"Source documents:\n{full_context}\n\n"
                f"Question: {question}\n\n"
                f"Answer: {answer}\n\n"
                f"For each claim in the answer, indicate:\n"
                f"- SUPPORTED: if confirmed by the documents\n"
                f"- UNSUPPORTED: if it does not appear in the documents\n"
                f"- CONTRADICTED: if it contradicts the documents\n\n"
                f"End with a global score from 0 to 1."
            )
        }],
        temperature=0
    )
    return {"evaluation": response.choices[0].message.content}

Uma resposta pode ser perfeitamente fiel, mas inútil: pode copiar fielmente um excerto que trata de outro assunto. É isso que a relevância da resposta mede, comparando desta vez a resposta apenas com a pergunta, sem os documentos. O comando define uma escala explícita — 1,0 para uma resposta completa, 0,7 para uma resposta parcial mas útil, 0,3 para tangencial, 0,0 para fora do tema — porque um avaliador a quem se pede simplesmente para «classificar de 0 a 1» produz pontuações instáveis de uma execução para outra.

def evaluate_relevance(question: str, answer: str) -> float:
    """Pontuação de relevância da resposta em relação à pergunta."""
    response = client.chat.completions.create(
        model="gpt-5.6-terra",
        messages=[{
            "role": "user",
            "content": (
                f"On a scale of 0 to 1, how well does this answer "
                f"address the question asked?\n\n"
                f"Question: {question}\n"
                f"Answer: {answer}\n\n"
                f"Criteria:\n"
                f"- 1.0: complete and precise answer\n"
                f"- 0.7: partial but useful answer\n"
                f"- 0.3: tangentially related\n"
                f"- 0.0: off-topic\n\n"
                f"Return only the numeric score."
            )
        }],
        temperature=0,
        max_tokens=10
    )
    try:
        return float(response.choices[0].message.content.strip())
    except ValueError:
        return 0.0

Depois, há a precisão do contexto, que faz a ponte entre os dois eixos: entre os cinco documentos que injetou no comando, quantos foram realmente utilizados? Se a resposta a uma pergunta sobre políticas de férias recorreu apenas a um dos cinco fragmentos, os outros quatro consumiram orçamento de contexto e adicionaram ruído. Por isso, pergunta ao avaliador sobre cada contexto isoladamente, com um simples sim ou não, e calcula a proporção dos que foram úteis.

def evaluate_context_precision(
    question: str,
    contexts: list[str],
    answer: str
) -> dict:
    """Avalia quais os contextos que foram úteis para a resposta."""
    results = []

    for i, ctx in enumerate(contexts):
        response = client.chat.completions.create(
            model="gpt-5.6-terra",
            messages=[{
                "role": "user",
                "content": (
                    f"Was this document useful for answering "
                    f"the question?\n\n"
                    f"Question: {question}\n"
                    f"Document: {ctx[:500]}\n"
                    f"Generated answer: {answer}\n\n"
                    f"Answer YES or NO."
                )
            }],
            temperature=0,
            max_tokens=5
        )
        useful = "yes" in response.choices[0].message.content.lower()
        results.append({"index": i, "useful": useful})

    num_useful = sum(1 for r in results if r["useful"])
    return {
        "details": results,
        "precision": num_useful / len(contexts) if contexts else 0
    }

Estrutura de Avaliação Completa

Estas três funções são inúteis enquanto permanecerem manuais. O passo decisivo é executá-las num conjunto fixo de perguntas sempre que modificar o pipeline: é isso que transforma uma intuição — «acho que está melhor desde que alterei a fragmentação» — num número comparável. A classe abaixo executa o pipeline em cada item do conjunto de dados, recolhe as pontuações e devolve as suas médias.

Observe o conjunto de dados de exemplo: duas perguntas de RH, cada uma com uma resposta esperada e o identificador dos documentos que devem ser recuperados. Vinte a cinquenta entradas deste tipo, escritas uma vez por todas a partir de perguntas reais de utilizadores, são suficientes para detetar regressões.

class RAGEvaluator:
    def __init__(self, rag_pipeline):
        self.pipeline = rag_pipeline
        self.client = OpenAI()

    def evaluate_dataset(self, dataset: list[dict]) -> dict:
        """Avalia o pipeline num conjunto de dados de perguntas e respostas.

        Cada item: {question, expected_answer, relevant_docs}
        """
        results = {
            "faithfulness": [],
            "relevance": [],
            "context_precision": [],
        }

        for item in dataset:
            # Executar o pipeline
            output = self.pipeline.respond(item["question"])
            answer = output["answer"]
            contexts = [s["excerpt"] for s in output["sources"]]

            # Avaliar
            relevance = evaluate_relevance(item["question"], answer)
            results["relevance"].append(relevance)

            ctx_eval = evaluate_context_precision(
                item["question"], contexts, answer
            )
            results["context_precision"].append(ctx_eval["precision"])

        # Médias
        import numpy as np
        return {
            metric: round(float(np.mean(scores)), 4)
            for metric, scores in results.items()
        }

# Utilização
dataset = [
    {
        "question": "How many leave days do I have?",
        "expected_answer": "25 days of paid leave per year",
        "relevant_docs": ["leave-policy"]
    },
    {
        "question": "Can I work remotely on Mondays?",
        "expected_answer": "Yes, remote work is allowed except on Tuesdays and Thursdays",
        "relevant_docs": ["remote-work-policy"]
    },
]

evaluator = RAGEvaluator(rag_pipeline)
metrics = evaluator.evaluate_dataset(dataset)
print("Results:")
for k, v in metrics.items():
    print(f"  {k}: {v}")

Painel de Métricas

Eis os alvos a atingir num sistema de produção, juntamente com o significado real de cada número.

MétricaAlvoO que mede
Recall@5> 0,90Os documentos certos estão no top 5?
Precision@5> 0,70Os documentos devolvidos são relevantes?
Faithfulness> 0,85A resposta é fiel às fontes?
Answer Relevance> 0,80A resposta aborda a pergunta?
Context Precision> 0,60Os contextos fornecidos são úteis?

Leia esta tabela de cima para baixo como uma árvore de diagnóstico. Um recall abaixo de 0,90 torna qualquer análise das linhas seguintes inútil: corrija primeiro a fragmentação ou o índice. Por outro lado, um recall excelente combinado com uma fidelidade fraca aponta para o comando de geração, e não para a pesquisa.

Pontos-chave

  • Avalie a recuperação (recall, precisão) e a geração (fidelidade, relevância) separadamente
  • A fidelidade deteta alucinações do LLM
  • A relevância verifica se a resposta é útil
  • Construa um conjunto de dados de teste e meça antes de cada alteração