Avaliar a qualidade da pesquisa
Nesta página
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