Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Arvioi hakukoneen laatu

Oppitunti 10 / 22 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Tavoitteet
  2. Miksi arvioida?
  3. Keskeiset mittarit
  4. Arviointiaineiston luominen
  5. Täydellinen arviointiputki
  6. Kahden konfiguraation vertailu
  7. Keskeiset asiat

Tavoitteet

  • Ymmärrä hakukoneen arvioinnin standardimittarit
  • Rakenna arviointiaineisto
  • Mittaa ja paranna hakukoneesi laatua

Miksi arvioida?

Aiemmissa oppitunneissa esiteltiin useita valintoja: upotusmalli, ulottuvuuksien määrä, chunk-koko ja hybridi-painotus. Jokainen valinta voi parantaa tai heikentää järjestelmääsi. Kolmen kyselyn manuaalinen testaaminen ja subjektiiviset vaikutelmat eivät riitä päätöksentekoon – varsinkaan kun muutos usein parantaa yhtä kyselykategoriaa heikentäen samalla toista. Ilman mittareita lennät sokkona.

Keskeiset mittarit

Recall@k vastaa kysymykseen: kuinka monta olennaista dokumenttia löytyy kymmenen parhaan tuloksen joukosta? Tämä on RAG-järjestelmien kultainen standardi, sillä kontekstista puuttuvaa dokumenttia generointimalli ei voi koskaan hyödyntää, oli se kuinka hyvä tahansa.

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 tarkastelee asiaa käänteisesti: kuinka monta k palautetusta tuloksesta on todella olennaisia? Tämä on tärkeintä, kun LLM:lle lähetettävä konteksti on rajoitettu, sillä jokainen aiheeseen kuulumaton dokumentti vie tilaa ja hajauttaa mallin huomion.

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) mittaa ensimmäisen olennaisen tuloksen sijaintia listalla. Ensimmäisellä sijalla oleva dokumentti saa arvon 1, toisella 0,5 ja viidennellä 0,2. Suosi tätä mittaria ihmisten käyttämissä hakukentissä, sillä harva käyttäjä katsoo kolmea ensimmäistä riviä pidemmälle.

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) menee pidemmälle hylkäämällä binäärisen relevanssin: se hyväksyy relevanssiasteet, jolloin voit erottaa toisistaan dokumentin, joka vastaa kysymykseen täydellisesti, ja dokumentin, joka vain sivuaa aihetta. Nimittäjässä oleva logaritmi soveltaa progressiivista alennusta sijainnin perusteella, ja normalisointi ihanteelliseen järjestykseen skaalaa kaiken nollan ja yhden välille.

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

Arviointiaineiston luominen

Mikään näistä kaavoista ei ole hyödyllinen ilman totuudenmukaista vertailukohtaa (ground truth). Arviointiaineisto yhdistää jokaisen kyselyn niihin dokumentteihin, joiden pitäisi ilmestyä tuloksiin, ja valinnaisesti niihin, jotka eivät missään nimessä pitäisi – jälkimmäiset ovat hyödyllisiä tunnettujen väärinpositiivisten tulosten seurannassa.

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)

Kolmekymmentä hyvin valittua paria, jotka kattavat erilaiset kysymystyypit, joita hakukoneesi todellisuudessa saa, ovat arvokkaampia kuin kolmesataa massatuotettua. Suosi hakulokiesi hyödyntämistä: nämä ovat käyttäjiesi todellisia formulointeja, eivät niitä, joita kuvittelet.

Testikyselyiden generointi LLM:llä

Laajalla aineistolla manuaalinen kirjoittaminen muuttuu käytännössä mahdottomaksi. Käännämmekin ongelman päälaelleen: emme etsi dokumentteja, jotka vastaavat kysymykseen, vaan pyydämme mallia kertomaan, mihin kysymyksiin tietty dokumentti voi vastata. Dokumentti on rakenteellisesti olennainen näille kysymyksille, ja saat pareja minuuteissa.

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

Tällä menetelmällä on sokea piste, joka sinun on tiedostettava: generoidut kysymykset käyttävät usein dokumentin tarkkaa sanastoa, mikä tekee niistä helpompia kuin todelliset käyttäjäkyselyt ja keinotekoisesti kohottaa pisteitäsi. Käytä niitä vain kahden konfiguraation vertailuun keskenään, äläkä koskaan julista absoluuttista laatutasoa niiden perusteella.

Täydellinen arviointiputki

Arvioija suorittaa jokaisen aineiston kyselyn hakukoneella, laskee kaikki mittarit useille k-arvoille ja laskee lopuksi koko joukon keskiarvon.

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

Useiden k-arvojen seuraaminen on itsessään opettavaista: korkea recall@10 yhdistettynä heikkoon recall@1:een kertoo, että oikeat dokumentit löytyvät, mutta ne on sijoitettu huonosti – kyseessä on uudelleenjärjestelyongelma, ei indeksointiongelma.

Kahden konfiguraation vertailu

Seuraava funktio asettaa kaksi hakukonetta vastakkain samalla aineistolla ja näyttää mittarierot mittari kerrallaan. Toista tämä vaihe ennen jokaista tuotantoon vientiä, vaikka muutos vaikuttaisi triviaalilta.

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

Lue erot varovaisesti pienellä aineistolla: 0,02:n ero kolmenkymmenen kyselyn yli on todennäköisesti kohinaa, kun taas 0,10:n pudotus recall@5:ssä on selkeä signaali olla viemättä muutosta tuotantoon.

Keskeiset asiat

  • Recall@k, Precision@k, MRR ja NDCG ovat standardimittareita
  • Luo arviointiaineisto (kysely, olennaiset dokumentit) -pareista
  • Automatisoi kyselyiden generointi LLM:llä
  • Vertaile konfiguraatioita systemaattisesti ennen käyttöönottoa