> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Exporter les données d’évaluation

> Exportez les résultats d’évaluation par programmation à l’aide de l’Evaluation REST API.

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 via des outils de BI comme Looker ou des tableaux de bord internes avec des parties prenantes qui n’ont pas de licences W\&B.
* Mettre en place des pipelines de reporting automatisés qui agrègent les scores sur plusieurs projets.

L’[Evaluation REST API v2](https://trace.wandb.ai/docs) expose des concepts d’évaluation spécifiques : runs d’évaluation, prédictions, scores et évaluateurs. Elle fournit ainsi une sortie plus riche et mieux structurée, avec des statistiques typées pour les évaluateurs et des entrées de jeu de données résolues, par rapport à l’API Calls généraliste.

<div id="api-endpoints-used">
  ## Points de terminaison API utilisés
</div>

Les extraits de code de cette page utilisent les points de terminaison suivants de la [v2 Evaluation REST API](https://trace.wandb.ai/docs) :

* `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.

<div id="prerequisites">
  ## Prérequis
</div>

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 depuis 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 W\&B, définie dans la variable d'environnement `WANDB_API_KEY`. Obtenez votre clé sur [wandb.ai/settings](https://wandb.ai/settings).

<div id="set-up-authentication">
  ## Configurer l’authentification
</div>

L’extrait suivant importe les bibliothèques utilisées tout au long de cette page et configure l’URL de base, le tuple d’authentification, ainsi que l’entité et le projet cibles. Chaque exemple suivant réutilise ces variables.

```python theme={null}
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.

<div id="list-evaluation-runs">
  ## Lister les runs d’évaluation
</div>

La liste des runs d’évaluation est généralement la première chose dont vous avez besoin dans un flux de travail d’exportation, car elle vous 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, pour chacun, des détails tels que l’ID et le statut.

```python theme={null}
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"))
```

<div id="read-a-single-evaluation-run">
  ## Lire un run d’évaluation spécifique
</div>

Après avoir obtenu 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 spécifique, 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 que vous souhaitez récupérer.

```python theme={null}
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"))
```

<div id="get-predictions-and-scores">
  ## Obtenir les prédictions et les scores
</div>

Lorsque vous avez besoin des données sous-jacentes d’un run, par exemple pour des exportations vers des feuilles de calcul ou des analyses au niveau des lignes, 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. Remplacez `[EVALUATION_RUN_ID]` par l’ID du run d’Évaluation que vous souhaitez interroger.

```python theme={null}
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)
```

<div id="get-aggregated-scores">
  ## Obtenir des scores agrégés
</div>

Lorsque vous n’avez besoin que de métriques de haut niveau, par exemple pour des tableaux de bord ou des contrôles 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 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.

```python theme={null}
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"))
```

<div id="read-a-single-prediction">
  ## Lire une seule prédiction
</div>

Pour examiner une ligne séparément, par exemple pour analyser un score inattendu, vous pouvez récupérer directement une prédiction à l’aide de son ID. 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. Remplacez `[PREDICTION_ID]` par l’ID de la prédiction que vous souhaitez récupérer.

```python theme={null}
prediction_id = "[PREDICTION_ID]"

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

<div id="row-digests">
  ## Empreintes de ligne
</div>

Au-delà des données brutes que chaque point de terminaison renvoie, la réponse à `eval_results/query` inclut un identifiant supplémentaire qui vous aide à corréler les lignes entre les runs. 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 différentes.