Exporter les données d’évaluation

Les équipes qui exécutent des évaluations dans W&B Weave ont souvent besoin d’exploiter les résultats d’évaluation en dehors de l’interface Weave. Voici quelques cas d’usage courants :

Importer des métriques dans des feuilles de calcul ou des notebooks pour réaliser des analyses et des visualisations personnalisées.
Intégrer les résultats d’évaluation dans des pipelines CI/CD pour conditionner les déploiements.
Partager les résultats, via des outils de BI comme Looker ou des tableaux de bord internes, avec des parties prenantes qui ne disposent pas de licence W&B.
Créer des pipelines de reporting automatisés qui agrègent les scores de plusieurs projets.

L’Evaluation REST API v2 expose des concepts spécifiques à l’évaluation : runs d’évaluation, prédictions, scores et évaluateurs. Vous obtenez ainsi une sortie plus riche et mieux structurée que celle de l’API Calls généraliste, avec des statistiques d’évaluateurs typées et des entrées de jeu de données résolues.

Points de terminaison d’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 précis pour récupérer son modèle, sa référence d’évaluation, son statut, ses horodatages et sa synthèse.
POST /v2/{entity}/{project}/eval_results/query : récupère les lignes de résultats d’évaluation, regroupées, pour une ou plusieurs évaluations. Renvoie, pour chaque ligne, les essais avec la sortie du modèle, les scores et, en option, les entrées résolues des lignes de jeu de données. Renvoie également, sur demande, des statistiques agrégées des évaluateurs.
GET /v2/{entity}/{project}/predictions/{prediction_id} : lit une prédiction donnée avec ses entrées, sa sortie et sa référence de modèle.

L’authentification repose sur 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’Evaluation REST API est indépendante du langage : vous pouvez appeler les mêmes points de terminaison depuis TypeScript ou n’importe quel client HTTP. Avant de commencer, assurez-vous de disposer des éléments suivants :

Python 3.7 ou version ultérieure.
La bibliothèque requests. Installez-la avec pip install requests.
Une clé API, définie dans la variable d’environnement WANDB_API_KEY. Vous pouvez obtenir votre clé dans l’interface CoreWeave Forge.

Configurer l’authentification

L’extrait de code suivant importe les bibliothèques utilisées dans l’ensemble de cette page et configure l’URL de base, le tuple d’authentification, ainsi que l’entity et le projet cibles. Tous les exemples qui suivent réutilisent ces variables.

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"

Une fois l’authentification configurée, vous pouvez appeler n’importe quel point de terminaison décrit dans les sections suivantes.

Lister les runs d’évaluation

La liste des runs d’évaluation constitue généralement le point de départ d’un flux de travail d’exportation, car elle fournit les valeurs evaluation_run_id requises par les autres points de terminaison. Récupérez les runs d’évaluation récents d’un projet et affichez les détails de chacun, comme son ID et son 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

Une fois que vous disposez d’un evaluation_run_id, vous pouvez récupérer l’enregistrement complet de ce run. Récupérez les détails d’un run d’évaluation donné, notamment son modèle, sa référence d’évaluation, son statut et ses horodatages. Remplacez [EVALUATION_RUN_ID] par l’ID du run d’évaluation à récupérer.

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

Lorsque vous avez besoin des données sous-jacentes d’un run, par exemple pour les exporter vers un tableur ou les analyser ligne par ligne, 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 contient les entrées résolues du jeu de données, la sortie du modèle et les résultats de chaque évaluateur. Définissez include_rows, include_raw_data_rows et resolve_row_refs pour obtenir le détail complet de chaque ligne. Remplacez [EVALUATION_RUN_ID] par l’ID du run d’évaluation à interroger.

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

Si vous n’avez besoin que de métriques globales, par exemple pour des tableaux de bord ou des gates de CI/CD, demandez des statistiques de synthèse plutôt que des données ligne par ligne. Le même point de terminaison eval_results/query peut également renvoyer des statistiques agrégées des é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 des évaluateurs binaires et les moyennes des é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 prédiction individuelle

Pour examiner une ligne isolément, par exemple lorsque vous cherchez à comprendre un score inattendu, vous pouvez obtenir une prédiction directement à partir de son ID. Récupérez tous les détails d’une prédiction, notamment ses entrées, sa sortie et sa référence de modèle. Remplacez [PREDICTION_ID] par l’ID de la prédiction que vous souhaitez récupérer.

prediction_id = "[PREDICTION_ID]"

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

Digests de ligne

Outre les données brutes renvoyées par chaque point de terminaison, la réponse à eval_results/query inclut un identifiant supplémentaire qui vous aide à mettre en correspondance les lignes d’un run à l’autre. Chaque ligne de résultat du point de terminaison eval_results/query comporte un row_digest, un hachage qui identifie de manière unique une entrée donnée du jeu de données d’évaluation à partir de son contenu, et non de sa position. Les digests 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 le même digest 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 figure dans plusieurs suites d’évaluation, le digest vous permet de l’identifier.
Reproductibilité : le digest est adressable par contenu. Si quelqu’un modifie une ligne de jeu de données (texte de l’instruction, grille d’évaluation ou autres champs), celle-ci reçoit un nouveau digest. Vous pouvez ainsi vérifier si deux runs d’évaluation ont utilisé des entrées identiques ou des versions différentes.

​Points de terminaison d’API utilisés

​Prérequis

​Configurer l’authentification

​Lister les runs d’évaluation

​Lire un run d’évaluation

​Obtenir les prédictions et les scores

​Obtenir des scores agrégés

​Lire une prédiction individuelle

​Digests de ligne