# Accéder aux données du classement des benchmarks

Les [jeux de données de référence](./eval-results#benchmark-datasets) sur le Hub contiennent des classements qui classent les modèles selon leurs scores d'évaluation. Vous pouvez accéder à ces données de manière programmatique pour les analyser, ou pour construire des tableaux de bord ou des outils à partir de celles-ci.

## Découvrir les benchmarks officiels

Utilisez `huggingface_hub` pour trouver tous les jeux de données de référence officiels :

```python
from huggingface_hub import HfApi

api = HfApi()
for ds in api.list_datasets(benchmark=True):
    print(ds.id)
```

Ou directement via l'API REST (utile pour les agents et le scriptage) :

```
GET https://huggingface.co/api/datasets?filter=benchmark:official
```

## Obtenir les classements

L'API du classement renvoie les scores de modèles classés pour un jeu de données de référence :

```
GET https://huggingface.co/api/datasets/{dataset_id}/leaderboard
```

Utilisez [`get_dataset_leaderboard`](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.HfApi.get_dataset_leaderboard) pour récupérer les scores des modèles classés sous forme d’objets [`DatasetLeaderboardEntry`](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.DatasetLeaderboardEntry) typés :

```python
from huggingface_hub import HfApi

api = HfApi()
leaderboard = api.get_dataset_leaderboard("SWE-bench/SWE-bench_Verified")

for entry in leaderboard[:5]:
    print(f"#{entry.rank} {entry.model_id}: {entry.value}")
```

> [!TIP]
> `huggingface_hub` utilise par défaut votre jeton en cache. Pour les jeux de données de référence sous licence, assurez-vous d’être connecté (`hf auth login`) ou transmettez explicitement un jeton :
> ```python
> leaderboard = api.get_dataset_leaderboard("gated/benchmark", token="hf_...")
> ```

> [!TIP]
> Commande Curl en une ligne pour un accès rapide (utile pour les agents et le scriptage) :
> ```bash
> curl https://huggingface.co/api/datasets/cais/hle/leaderboard \
>   --header "Authorization: Bearer $(cat ~/.cache/huggingface/token)" | jq .
> ```

### Champs de réponse

Chaque [`DatasetLeaderboardEntry`](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.DatasetLeaderboardEntry) contient :

| Champ | Description |
|---|---|
| `rank` | Position sur le classement |
| `model_id` | ID complet du modèle (par ex. `Qwen/Qwen3.5-397B-A17B`) |
| `value` | Le score du benchmark |
| `verified` | Si le résultat a été vérifié de manière indépendante |
| `author` | Un objet [`User`](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.User) ou [`Organization`](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.Organization) |
| `source` | L'endroit d'où le résultat a été soumis (fiche de modèle, externe, etc.) |
| `filename` | Chemin vers le fichier YAML des résultats d'évaluation (par exemple `.eval_results/swe_bench_verified.yaml`) |
| `pull_request` | Numéro de PR pour la soumission sur le dépôt de jeu de données de référence |
| `notes` | Notes facultatives associées à l'entrée |

## Jeu de données multi-benchmarks pré-agrégé

Si vous souhaitez obtenir les scores de plusieurs benchmarks dans un seul fichier, le jeu de données [`OpenEvals/leaderboard-data`](https://huggingface.co/datasets/OpenEvals/leaderboard-data) agrège les scores des benchmarks officiels dans un seul fichier Parquet :

Vous pouvez le charger directement avec [pandas](./datasets-pandas) en utilisant le chemin `hf://` :

```python
import pandas as pd

df = pd.read_parquet(
    "hf://datasets/OpenEvals/leaderboard-data/data/train-00000-of-00001.parquet"
)
print(df[["model_name", "provider", "aime2026_score", "mmluPro_score"]].head())
```

C'est la méthode la plus rapide pour obtenir une vue comparative entre les différents benchmarks sans appeler plusieurs points de terminaison d'API.

## Enrichissement avec les métadonnées du modèle

Utilisez `huggingface_hub` pour enrichir les données du classement avec les dates de publication, le nombre de paramètres et d'autres métadonnées :

```python
from huggingface_hub import HfApi

api = HfApi()
info = api.model_info("Qwen/Qwen3.5-397B-A17B")

print(f"Released: {info.created_at}")
print(f"Parameters: {info.safetensors.total / 1e9:.1f}B" if info.safetensors else "")
```

## Vue centrée sur le modèle : résultats d'évaluation par modèle

L’API du classement offre une vue centrée sur le jeu de données (tous les modèles sur un seul benchmark). Pour l’inverse — tous les scores de benchmark pour un seul modèle — utilisez `model_info` avec `expand=["evalResults"]` :

```python
from huggingface_hub import HfApi

api = HfApi()
info = api.model_info("Qwen/Qwen3.5-397B-A17B", expand=["evalResults"])

for result in info.eval_results:
    print(f"{result.dataset_id}: {result.value}")
```

Cela renvoie des objets [`EvalResultEntry`](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.EvalResultEntry) analysés à partir des fichiers `.eval_results/` du modèle.

## Exemple : construire à partir des données du classement

L'Espace [Benchmark Leaderboard Race](https://huggingface.co/spaces/davanstrien/benchmark-race) combine ces sources de données pour créer une visualisation animée de l'évolution des classements des modèles au fil du temps. Vous pouvez construire vos propres analyses et visualisations à partir de ces données — consultez le [code source](https://huggingface.co/spaces/davanstrien/benchmark-race/tree/main) pour un exemple complet.

## Intégrer un classement dans une page web

Vous pouvez intégrer directement le tableau de classement d’un jeu de données de référence dans votre propre page web à l’aide d’une balise iframe.

L’URL à utiliser est `https://huggingface.co/datasets/<namespace>/<dataset-name>/embed/leaderboard`, où `<namespace>` est le propriétaire du jeu de données de référence (utilisateur ou organisation) et `<dataset-name>` est le nom du jeu de données.

```html
<iframe
  src="https://huggingface.co/datasets/cais/hle/embed/leaderboard"
  frameborder="0"
  width="100%"
  height="560px"
></iframe>
```

### Paramètres

Vous pouvez configurer le tableau de bord intégré en passant des paramètres de requête dans l’URL de l’iframe :

| Paramètre | Description |
|---|---|
| `leaderboard_task_id` | ID de la tâche à afficher, telle que définie dans le `eval.yaml` du benchmark (par exemple `gpqa_diamond`). Par défaut, la première tâche est utilisée. |
| `eval_result` | ID du modèle à mettre en avant sur le classement (par exemple `meta-llama/Llama-3.1-8B`). |
| `leaderboard_max_params` | Filtre les lignes par nombre maximal de paramètres. Accepte l'une des valeurs suivantes : `1B`, `3B`, `6B`, `12B`, `32B`, `128B` ou `500B`. |
| `leaderboard_is_expanded` | Définir sur `true` pour afficher le classement entièrement déplié au lieu de replié. |

Par exemple, pour intégrer le classement HLE avec le tableau déplié et un modèle spécifique mis en évidence :

```html
<iframe
  src="https://huggingface.co/datasets/cais/hle/embed/leaderboard?leaderboard_is_expanded=true&eval_result=meta-llama/Llama-3.1-8B"
  frameborder="0"
  width="100%"
  height="560px"
></iframe>
```

L'intégration n'est disponible que pour les [jeux de données de référence officiels](./eval-results#benchmark-datasets) disposant de résultats d'évaluation.

## Lié

- [Résultats d'évaluation](./eval-results) — comment soumettre des résultats d'évaluation et enregistrer des benchmarks
- [Joues de données de référence officielles](https://huggingface.co/datasets?benchmark=benchmark:official&sort=trending) — parcourez toutes les références officielles