Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Valutare la qualità della ricerca

Lezione 10 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Obiettivi
  2. Perché valutare?
  3. Metriche chiave
  4. Creare un dataset di valutazione
  5. Pipeline di valutazione completa
  6. Confrontare due configurazioni
  7. Punti chiave

Obiettivi

  • Comprendere le metriche standard di valutazione della ricerca
  • Costruire un dataset di valutazione
  • Misurare e migliorare la qualità del tuo motore

Perché valutare?

Le lezioni precedenti hanno introdotto una serie di scelte: modello di embedding, numero di dimensioni, dimensione dei chunk e pesatura ibrida. Ogni scelta può migliorare o degradare il tuo sistema. Le impressioni soggettive derivanti dal test manuale di tre query non sono sufficienti per decidere, specialmente perché una modifica spesso migliora una categoria di query mentre ne peggiora un’altra. Senza metriche, voli alla cieca.

Metriche chiave

Recall@k risponde a questa domanda: tra i documenti rilevanti, quanti appaiono nei primi k risultati? Questa è la metrica di riferimento per il RAG, perché un documento mancante dal contesto non potrà mai essere citato dal modello di generazione, indipendentemente dalla sua bravura.

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 guarda l’inverso: tra i k risultati restituiti, quanti sono effettivamente rilevanti? Questo conta soprattutto quando il contesto inviato all’LLM è limitato, poiché ogni documento fuori tema occupa spazio e diluisce l’attenzione del modello.

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) misura il rango del primo risultato rilevante. Un documento al primo posto ottiene 1, al secondo 0,5 e al quinto 0,2. Dai priorità a questa metrica per le barre di ricerca destinate agli umani, che raramente guardano oltre le prime tre righe.

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) va oltre abbandonando la rilevanza binaria: accetta gradi di rilevanza, permettendoti di distinguere tra un documento che risponde esattamente alla domanda e uno che la sfiora appena. Il logaritmo al denominatore applica uno sconto progressivo basato sul rango, e la normalizzazione rispetto al ranking ideale scala tutto tra 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

Creare un dataset di valutazione

Nessuna di queste formule è utile senza una verità di base (ground truth). Un dataset di valutazione associa ogni query all’elenco dei documenti che dovrebbero apparire e, opzionalmente, a quelli che decisamente non dovrebbero; questi ultimi sono utili per monitorare i falsi positivi noti.

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)

Trenta coppie ben scelte che coprono i diversi tipi di domande che il tuo motore riceve effettivamente valgono più di trecento prodotte in massa. Dai priorità all’estrazione dai tuoi log di ricerca: queste sono le formulazioni reali dei tuoi utenti, non quelle che immagini.

Generare query di test con un LLM

Su un corpus ampio, la scrittura manuale diventa impraticabile. Quindi ribaltiamo il problema: invece di cercare documenti che rispondano a una domanda, chiediamo a un modello quali domande un dato documento possa affrontare. Il documento è per costruzione rilevante per queste domande e ottieni coppie in pochi minuti.

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

Questo metodo ha un punto cieco che devi conoscere: le domande generate spesso riutilizzano il vocabolario esatto del documento, rendendole più facili delle query reali degli utenti e gonfiando artificialmente i tuoi punteggi. Usale per confrontare due configurazioni tra loro, mai per dichiarare un livello di qualità assoluto.

Pipeline di valutazione completa

Il valutatore esegue ogni query del dataset sul motore, calcola tutte le metriche per diversi valori di k e poi fa la media dell’intero set.

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}")

Tracciare più valori di k è istruttivo di per sé: un recall@10 alto abbinato a un recall@1 scarso segnala che i documenti giusti vengono trovati ma mal classificati: è un problema di reranking, non di indicizzazione.

Confrontare due configurazioni

La funzione seguente mette a confronto due motori sullo stesso dataset e visualizza il divario metrico per ogni metrica. Ripeti questo passaggio prima di ogni deployment in produzione, anche per una modifica che sembra banale.

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}")

Leggi i delta con cautela su un dataset piccolo: un divario di 0,02 su trenta query è probabilmente rumore, mentre un calo di 0,10 nel recall@5 è un segnale chiaro per non procedere al deployment.

Punti chiave

  • Recall@k, Precision@k, MRR e NDCG sono le metriche standard
  • Crea un dataset di valutazione con coppie (query, documenti rilevanti)
  • Automatizza la generazione delle query con un LLM
  • Confronta sistematicamente le configurazioni prima del deployment