Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Evalwa l-kwalità tat-tiftix

Lezzjoni 10 / 22 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Għanijiet
  2. Għaliex tevalwa?
  3. Metriċi ewlenin
  4. Oħloq sett ta’ data għall-evalwazzjoni
  5. Pipeline sħiħa ta’ evalwazzjoni
  6. Qabbel żewġ konfigurazzjonijiet
  7. Punti Ewlenin

Għanijiet

  • Fhem il-metriċi standard għall-evalwazzjoni tat-tiftix
  • Ibni sett ta’ data għall-evalwazzjoni
  • Kejjel u tejjeb il-kwalità tal-magna tiegħek

Għaliex tevalwa?

Il-lezzjonijiet preċedenti introduċew serja ta’ għażliet: mudell ta’ embedding, numru ta’ dimensjonijiet, daqs tal-biċċa (chunk), u piż ibridu. Kull għażla tista’ ttejjeb jew tgħarraq is-sistema tiegħek. Impressjonijiet suġġettivi minn testijiet manwali fuq tliet mistoqsijiet mhumiex biżżejjed biex tiddeċiedi—speċjalment peress li bidla spiss ittejjeb kategorija waħda ta’ mistoqsijiet filwaqt li tgħarraq oħra. Mingħajr metriċi, qed ittir fil-buħ.

Metriċi ewlenin

Recall@k twieġeb din il-mistoqsija: fost id-dokumenti rilevanti, kemm jidhru fl-ewwel riżultati k? Din hija l-metrika standard tad-deheb għar-RAG għax dokument nieqes mill-kuntest qatt ma jista’ jiġi ċċitat mill-mudell tal-ġenerazzjoni, kemm jekk ikun tajjeb kemm jekk le.

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 tħares lejn l-invers: fost ir-riżultati k ritornati, kemm huma verament rilevanti? Dan jimporta l-aktar meta l-kuntest mibgħut lill-LLM huwa limitat, peress li kull dokument barra mit-tema jieħu spazju u jdilwi l-attenzjoni tal-mudell.

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) ikejjel il-klassifika tal-ewwel riżultat rilevanti. Dokument fl-ewwel post jiskorja 1, fit-tieni post 0.5, u fil-ħames post 0.2. Agħti prijorità lil din il-metrika għal barra tat-tiftix maħsuba għall-bnedmin, li rari jħarsu lil hinn mill-ewwel tliet linji.

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) imur lil hinn billi jabbanduna r-rilevanza binarja: jaċċetta gradi ta’ rilevanza, u jippermettilek tiddistingwi bejn dokument li jwieġeb il-mistoqsija eżattament u wieħed li jmissuha biss. Il-logaritmu fid-denominatur japplika skont progressiv ibbażat fuq il-klassifika, u n-normalizzazzjoni kontra l-klassifika ideali tiskala kollox bejn 0 u 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

Oħloq sett ta’ data għall-evalwazzjoni

L-ebda waħda minn dawn il-formuli ma hija utli mingħajr verità bażika (ground truth). Sett ta’ data għall-evalwazzjoni jassoċja kull mistoqsija mal-lista ta’ dokumenti li għandhom jidhru, u opzjonalment dawk li żgur m’għandhomx jidhru—tal-aħħar huma utli biex timmonitorja pożittivi foloz magħrufa.

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)

Tletin par magħżula sew li jkopru t-tipi differenti ta’ mistoqsijiet li l-magna tiegħek fil-fatt tirċievi jiswew aktar minn tliet mija magħmula bil-massa. Agħti prijorità li tiġbed mill-logs tat-tiftix tiegħek: dawn huma l-frażijiet attwali tal-utenti tiegħek, mhux dawk li timmaġina int.

Iġġenera mistoqsijiet ta’ test b’LLM

Fuq corpus kbir, il-kitba manwali ssir imprattikabbli. Allura naqilbu l-problema: minflok infittxu dokumenti li jwieġbu mistoqsija, nistaqsu lill-mudell liema mistoqsijiet dokument mogħti jista’ jindirizza. Id-dokument huwa b’kostruzzjoni rilevanti għal dawn il-mistoqsijiet, u tikseb pari f’ftit 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")

Dan il-metodu għandu punt għami li għandek tkun taf bih: il-mistoqsijiet iġġenerati spiss jerġgħu jużaw il-vokabolarju eżatt tad-dokument, u jagħmluhom aktar faċli mill-mistoqsijiet reali tal-utenti u jinflataw artifiċjalment l-iskor tiegħek. Użahom biex tqabbel żewġ konfigurazzjonijiet ma’ xulxin, qatt biex tiddikjara livell assolut ta’ kwalità.

Pipeline sħiħa ta’ evalwazzjoni

L-evalwatur iħaddem kull mistoqsija mis-sett ta’ data fuq il-magna, jikkalkula l-metriċi kollha għal diversi valuri ta’ k, u mbagħad jagħmel medja tas-sett kollu.

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

It-traċċar ta’ valuri multipli ta’ k huwa struwittiv fih innifsu: recall@10 għoli akkumpanjat minn recall@1 fqir jissinjala li d-dokumenti t-tajba qed jinstabu iżda mhumiex ikklassifikati sew—problema ta’ reranking, mhux ta’ indiċjar.

Qabbel żewġ konfigurazzjonijiet

Il-funzjoni li ġejja tpoġġi żewġ magni waħda kontra l-oħra fuq l-istess sett ta’ data u turi d-differenza fil-metrika għal kull metrika. Irrepeti dan il-pass qabel kull dispjegament fil-produzzjoni, anke għal bidla li tidher trivjali.

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

Aqra d-deltas b’kawtela fuq sett ta’ data żgħir: differenza ta’ 0.02 fuq tletin mistoqsija x’aktarx hija storbju, filwaqt li tnaqqis ta’ 0.10 f’recall@5 huwa sinjal ċar biex ma tdispjegax.

Punti Ewlenin

  • Recall@k, Precision@k, MRR, u NDCG huma l-metriċi standard
  • Oħloq sett ta’ data għall-evalwazzjoni b’pari (mistoqsija, dokumenti rilevanti)
  • Awtomatizza l-ġenerazzjoni tal-mistoqsijiet b’LLM
  • Qabbel sistematikament il-konfigurazzjonijiet qabel ma tdispjega