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

Avaliar a qualidade da pesquisa

Aula 10 de 22 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Objetivos
  2. Por que avaliar?
  3. Métricas-chave
  4. Criar um conjunto de dados de avaliação
  5. Pipeline de avaliação completo
  6. Comparar duas configurações
  7. Pontos-chave

Objetivos

  • Compreender as métricas padrão de avaliação de pesquisa
  • Criar um conjunto de dados de avaliação
  • Medir e melhorar a qualidade do seu motor de pesquisa

Por que avaliar?

As lições anteriores apresentaram uma série de escolhas: modelo de incorporação (embedding), número de dimensões, tamanho dos fragmentos (chunks) e ponderação híbrida. Cada escolha pode melhorar ou degradar o seu sistema. Impressões subjetivas provenientes de testes manuais em apenas três consultas não são suficientes para decidir — especialmente porque uma alteração muitas vezes melhora uma categoria de consultas enquanto degrada outra. Sem métricas, está a voar às cegas.

Métricas-chave

Recall@k responde a esta questão: entre os documentos relevantes, quantos aparecem nos primeiros k resultados? Esta é a métrica de referência para RAG, pois um documento ausente do contexto nunca poderá ser citado pelo modelo de geração, independentemente da sua qualidade.

def recall_at_k(pertinents: set[str], resultats: list[str], k: int) -> float:
    """Proportion of relevant documents found in the top-k."""
    top_k = set(resultats[:k])
    trouves = pertinents & top_k
    return len(trouves) / len(pertinents) if pertinents else 0.0

Precision@k analisa o inverso: entre os k resultados devolvidos, quantos são realmente relevantes? Isto é crucial quando o contexto enviado ao LLM é limitado, uma vez que cada documento fora do tema ocupa espaço e dilui a atenção do modelo.

def precision_at_k(pertinents: set[str], resultats: list[str], k: int) -> float:
    """Proportion of relevant results in the top-k."""
    top_k = resultats[:k]
    trouves = sum(1 for r in top_k if r in pertinents)
    return trouves / k if k > 0 else 0.0

MRR (Mean Reciprocal Rank) mede a posição do primeiro resultado relevante. Um documento em primeiro lugar pontua 1, em segundo lugar 0,5 e em quinto lugar 0,2. Priorize esta métrica para barras de pesquisa destinadas a humanos, que raramente olham além das três primeiras linhas.

def mrr(pertinents: set[str], resultats: list[str]) -> float:
    """Reciprocal rank of the first relevant result."""
    for i, r in enumerate(resultats):
        if r in pertinents:
            return 1.0 / (i + 1)
    return 0.0

NDCG@k (Normalized Discounted Cumulative Gain) vai mais longe ao abandonar a relevância binária: aceita graus de relevância, permitindo distinguir entre um documento que responde exatamente à pergunta e outro que apenas a aborda tangencialmente. O logaritmo no denominador aplica um desconto progressivo com base na posição, e a normalização face ao ranking ideal escala tudo entre 0 e 1.

import numpy as np

def ndcg_at_k(relevances: list[float], k: int) -> float:
    """NDCG with graded relevance scores."""
    dcg = sum(
        rel / np.log2(i + 2) for i, rel in enumerate(relevances[:k])
    )
    ideal = sorted(relevances, reverse=True)[:k]
    idcg = sum(
        rel / np.log2(i + 2) for i, rel in enumerate(ideal)
    )
    return dcg / idcg if idcg > 0 else 0.0

Criar um conjunto de dados de avaliação

Nenhuma destas fórmulas é útil sem uma verdade de terreno (ground truth). Um conjunto de dados de avaliação associa cada consulta à lista de documentos que deveriam aparecer e, opcionalmente, àqueles que definitivamente não deveriam — estes últimos são úteis para monitorizar falsos positivos conhecidos.

import json

# Dataset structure
dataset_eval = [
    {
        "requête": "comment installer Python sur Windows",
        "pertinents": ["doc_install_python", "doc_setup_env"],
        "non_pertinents": ["doc_cuisine"]
    },
    {
        "requête": "configurer nginx comme reverse proxy",
        "pertinents": ["doc_nginx_proxy", "doc_nginx_config"],
        "non_pertinents": ["doc_python_web"]
    },
]

# Save
with open("eval_dataset.json", "w") as f:
    json.dump(dataset_eval, f, ensure_ascii=False, indent=2)

Trinta pares bem escolhidos, cobrindo os diferentes tipos de perguntas que o seu motor realmente recebe, valem mais do que trezentos produzidos em massa. Priorize a extração a partir dos seus registos de pesquisa: estas são as formulações reais dos seus utilizadores, não as que você imagina.

Gerar consultas de teste com um LLM

Num corpus extenso, a escrita manual torna-se impraticável. Por isso, invertemos o problema: em vez de procurar documentos que respondam a uma pergunta, perguntamos a um modelo que perguntas um determinado documento pode abordar. O documento é, por construção, relevante para essas perguntas, e obtém pares em minutos.

from openai import OpenAI

client = OpenAI()

def generer_requetes_test(document: str, n: int = 3) -> list[str]:
    """Generate n queries that this document should answer."""
    response = client.chat.completions.create(
        model="gpt-5.6-terra",
        messages=[{
            "role": "user",
            "content": (
                f"Voici un document :\n\n{document}\n\n"
                f"Génère {n} questions auxquelles ce document répond. "
                f"Retourne uniquement les questions, une par ligne."
            )
        }]
    )
    return response.choices[0].message.content.strip().split("\n")

Este método tem um ponto cego que deve conhecer: as perguntas geradas reutilizam frequentemente o vocabulário exato do documento, tornando-as mais fáceis do que as consultas reais dos utilizadores e inflacionando artificialmente as suas pontuações. Utilize-as para comparar duas configurações entre si, nunca para declarar um nível de qualidade absoluto.

Pipeline de avaliação completo

O avaliador executa cada consulta do conjunto de dados no motor, calcula todas as métricas para vários valores de k e, em seguida, faz a média de todo o conjunto.

class EvaluateurRecherche:
    def __init__(self, moteur_recherche):
        self.moteur = moteur_recherche

    def evaluer(
        self, dataset: list[dict], k_values: list[int] = [1, 3, 5, 10]
    ) -> dict:
        """Evaluate the engine on a complete dataset."""
        resultats = {f"recall@{k}": [] for k in k_values}
        resultats.update({f"precision@{k}": [] for k in k_values})
        resultats["mrr"] = []

        for item in dataset:
            # Run search
            res = self.moteur.rechercher(item["requête"], k=max(k_values))
            ids_resultats = [r["id"] for r in res]
            pertinents = set(item["pertinents"])

            # Calculate metrics
            resultats["mrr"].append(mrr(pertinents, ids_resultats))
            for k in k_values:
                resultats[f"recall@{k}"].append(
                    recall_at_k(pertinents, ids_resultats, k)
                )
                resultats[f"precision@{k}"].append(
                    precision_at_k(pertinents, ids_resultats, k)
                )

        # Average
        return {
            metrique: round(np.mean(scores), 4)
            for metrique, scores in resultats.items()
        }

# Usage
evaluateur = EvaluateurRecherche(moteur)
metriques = evaluateur.evaluer(dataset_eval)

print("Résultats d'évaluation :")
for metrique, score in metriques.items():
    print(f"  {metrique}: {score}")

Acompanhar múltiplos valores de k é instrutivo por si só: um recall@10 elevado combinado com um recall@1 fraco sinaliza que os documentos certos estão a ser encontrados, mas mal classificados — um problema de reclassificação (reranking), não de indexação.

Comparar duas configurações

A função seguinte coloca dois motores frente a frente no mesmo conjunto de dados e exibe a diferença de métrica por métrica. Repita este passo antes de cada implementação em produção, mesmo para uma alteração que pareça trivial.

def comparer_configs(moteur_a, moteur_b, dataset, noms=("A", "B")):
    """Compare two search engines."""
    eval_a = EvaluateurRecherche(moteur_a).evaluer(dataset)
    eval_b = EvaluateurRecherche(moteur_b).evaluer(dataset)

    print(f"{Métrique:<20} {noms[0]:<10} {noms[1]:<10} {Delta:<10}")
    print("-" * 50)
    for metrique in eval_a:
        delta = eval_b[metrique] - eval_a[metrique]
        signe = "+" if delta > 0 else ""
        print(f"{metrique:<20} {eval_a[metrique]:<10.4f} "
              f"{eval_b[metrique]:<10.4f} {signe}{delta:<10.4f}")

Leia as diferenças (deltas) com cautela num conjunto de dados pequeno: uma diferença de 0,02 em trinta consultas é provavelmente ruído, enquanto uma queda de 0,10 no recall@5 é um sinal claro para não implementar.

Pontos-chave

  • Recall@k, Precision@k, MRR e NDCG são as métricas padrão
  • Crie um conjunto de dados de avaliação com pares (consulta, documentos relevantes)
  • Automatize a geração de consultas com um LLM
  • Compare sistematicamente as configurações antes de implementar