Passer au contenu principal
Les Teams qui effectuent des évaluations dans W&B Weave ont souvent besoin des résultats d’évaluation en dehors de l’interface Weave. Voici quelques cas d’usage courants :
  • Extraire les métriques vers des feuilles de calcul ou des notebooks pour des analyses et visualisations personnalisées.
  • Alimenter des pipelines CI/CD avec les résultats d’évaluation afin d’autoriser ou de bloquer les déploiements.
  • Partager les résultats avec des parties prenantes qui n’ont pas de licences W&B, via des outils de BI comme Looker ou des tableaux de bord internes.
  • Mettre en place des pipelines de reporting automatisés qui agrègent les scores sur plusieurs projets.
L’API REST Evaluation v2 expose des concepts d’évaluation spécifiques : runs d’évaluation, prédictions, scores et scorers. Elle fournit ainsi une sortie plus riche et mieux structurée, avec des statistiques typées pour les scorers et des entrées de jeu de données résolues, par rapport à l’API Calls généraliste.

​
Points de terminaison API utilisés

Les extraits de code de cette page utilisent les points de terminaison suivants de la v2 Evaluation REST API :
  • GET /v2/{entity}/{project}/evaluation_runs : Liste les runs d’évaluation d’un projet, avec des filtres facultatifs par référence d’évaluation, référence de modèle ou ID du run.
  • GET /v2/{entity}/{project}/evaluation_runs/{evaluation_run_id} : Lit un run d’évaluation unique afin d’en récupérer le modèle, la référence d’évaluation, le statut, les horodatages et la synthèse.
  • POST /v2/{entity}/{project}/eval_results/query : Récupère des lignes de résultats d’évaluation groupées pour une ou plusieurs évaluations. Renvoie, pour chaque ligne, des essais avec la sortie du modèle, les scores et, éventuellement, les entrées résolues de la ligne du jeu de données. Renvoie également des statistiques agrégées du scorer lorsqu’elles sont demandées.
  • GET /v2/{entity}/{project}/predictions/{prediction_id} : Lit une prédiction individuelle avec ses entrées, sa sortie et sa référence de modèle.
L’authentification utilise HTTP Basic, avec api comme nom d’utilisateur et votre clé API W&B comme mot de passe.

​
Prérequis

Les exemples de cette page utilisent Python, mais l’API REST Evaluation est indépendante du langage : vous pouvez appeler les mêmes points de terminaison depuis TypeScript ou depuis n’importe quel client HTTP.
  • Python 3.7 ou version ultérieure.
  • La bibliothèque requests. Installez-la avec pip install requests.
  • Une clé API W&B, définie dans la variable d’environnement WANDB_API_KEY. Obtenez votre clé sur wandb.ai/settings.

​
Configurer l’authentification

import json
import os

import requests

TRACE_BASE = "https://trace.wandb.ai"
AUTH = ("api", os.environ["WANDB_API_KEY"])

entity = "my-team"
project = "my-project"

​
Lister les runs d’évaluation

Récupérez les runs d’évaluation récents d’un projet et affichez, pour chacun, des détails tels que l’ID et le statut. 
resp = requests.get(
    f"{TRACE_BASE}/v2/{entity}/{project}/evaluation_runs",
    auth=AUTH,
)
runs = [json.loads(line) for line in resp.text.strip().splitlines()]

for run in runs:
    print(run["evaluation_run_id"], run.get("status"))

​
Lire un run d’évaluation spécifique

Récupérez les détails d’un run d’évaluation spécifique, notamment son modèle, sa référence d’évaluation, son statut et ses horodatages. 
eval_run_id = "<evaluation-run-id>"

resp = requests.get(
    f"{TRACE_BASE}/v2/{entity}/{project}/evaluation_runs/{eval_run_id}",
    auth=AUTH,
)
eval_run = resp.json()
print(eval_run["evaluation_run_id"], eval_run.get("status"), eval_run.get("model"))

​
Obtenir les prédictions et les scores

Utilisez le point de terminaison eval_results/query pour récupérer les résultats ligne par ligne d’un run d’Évaluation. Chaque ligne inclut les entrées résolues du jeu de données, la sortie du modèle et les résultats individuels du scorer. Définissez include_rows, include_raw_data_rows et resolve_row_refs pour obtenir le niveau de détail complet pour chaque ligne. 
eval_run_id = "<evaluation-run-id>"

resp = requests.post(
    f"{TRACE_BASE}/v2/{entity}/{project}/eval_results/query",
    json={
        "evaluation_run_ids": [eval_run_id],
        "include_rows": True,
        "include_raw_data_rows": True,
        "resolve_row_refs": True,
    },
    auth=AUTH,
)
results = resp.json()

for row in results["rows"]:
    inputs = row.get("raw_data_row")
    for ev in row.get("evaluations", []):
        for trial in ev.get("trials", []):
            output = trial.get("model_output")
            scores = trial.get("scores", {})
            print("Input:", inputs)
            print("Output:", output)
            print("Scores:", scores)

​
Obtenir des scores agrégés

Le même point de terminaison eval_results/query peut également renvoyer des statistiques agrégées sur les évaluateurs au lieu de données ligne par ligne. Définissez include_summary pour obtenir des métriques de synthèse, comme les taux de réussite pour les évaluateurs binaires et les moyennes pour les évaluateurs continus. 
resp = requests.post(
    f"{TRACE_BASE}/v2/{entity}/{project}/eval_results/query",
    json={
        "evaluation_run_ids": [eval_run_id],
        "include_summary": True,
        "include_rows": False,
    },
    auth=AUTH,
)
results = resp.json()

for ev in results["summary"]["evaluations"]:
    for stat in ev["scorer_stats"]:
        print(stat["scorer_key"], stat.get("value_type"), stat.get("pass_rate") or stat.get("numeric_mean"))

​
Lire une seule prédiction

Récupérez les informations complètes d’une prédiction donnée, y compris ses entrées, sa sortie et la référence du modèle. 
prediction_id = "<predict-call-id>"

resp = requests.get(
    f"{TRACE_BASE}/v2/{entity}/{project}/predictions/{prediction_id}",
    auth=AUTH,
)
prediction = resp.json()
print(prediction)

​
Comment utiliser les empreintes de ligne

Chaque ligne de résultat du point de terminaison eval_results/query inclut un row_digest, un hachage de contenu qui identifie de manière unique une entrée spécifique dans le jeu de données d’évaluation en fonction de son contenu, et non de sa position. Les empreintes de ligne sont utiles pour :
  • Comparaison entre évaluations : lorsque vous exécutez deux modèles différents sur le même jeu de données, les lignes ayant la même empreinte correspondent à la même entrée. Vous pouvez effectuer une jointure sur row_digest pour comparer les performances de différents modèles sur exactement la même tâche.
  • Déduplication : si la même tâche apparaît dans plusieurs suites d’évaluation, l’empreinte vous permet de l’identifier.
  • Reproductibilité : l’empreinte est déterminée par le contenu. Ainsi, si quelqu’un modifie une ligne du jeu de données (en changeant le texte de l’instruction, le barème ou d’autres champs), elle obtient une nouvelle empreinte. Vous pouvez vérifier si deux runs d’évaluation ont utilisé des entrées identiques ou des versions légèrement différentes.