# ベンチマークリーダーボードデータへのアクセス

Hub上の[ベンチマークデータセット](./eval-results#benchmark-datasets)には、評価スコアによるモデルのランキングを示すリーダーボードが含まれています。このデータをプログラム的にアクセスして、分析やダッシュボード、ツールなどの構築を行うことができます。

## 公式ベンチマークの発見

`huggingface_hub`を使用して、すべての公式ベンチマークデータセットを検索します:

```python
from huggingface_hub import HfApi

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

または、REST APIを直接使用して（エージェントやスクリプティングに便利です）：

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

## リーダーボードのランキングを取得する

リーダーボードAPIは、ベンチマークデータセットに対するランキング付きモデルスコアを返します:

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

[`get_dataset_leaderboard`](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.HfApi.get_dataset_leaderboard) を使用して、ランキングされたモデルのスコアを型付きの [`DatasetLeaderboardEntry`](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.DatasetLeaderboardEntry) オブジェクトとして取得します:

```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` はデフォルトでキャッシュされたトークンを使用します。ゲート付きのベンチマークデータセットを使用する場合は、ログインしていること（`hf auth login`）を確認するか、トークンを明示的に渡してください。
> ```python
> leaderboard = api.get_dataset_leaderboard("gated/benchmark", token="hf_...")
> ```

> [!TIP]
> クイックアクセス用のCurlワンライナー（エージェントやスクリプティングに便利です）：
> ```bash
> curl https://huggingface.co/api/datasets/cais/hle/leaderboard \
>   --header "Authorization: Bearer $(cat ~/.cache/huggingface/token)" | jq .
> ```

### レスポンスフィールド

各 [`DatasetLeaderboardEntry`](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.DatasetLeaderboardEntry) には、以下が含まれます:

| フィールド | 説明 |
|---|---|
| `rank` | リーダーボード上の順位 |
| `model_id` | 完全なモデルID（例: `Qwen/Qwen3.5-397B-A17B`） |
| `value` | ベンチマークスコア |
| `verified` | 結果が独立して検証されたかどうか |
| `author` | [`User`](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.User)または[`Organization`](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.Organization)オブジェクト |
| `source` | 結果が送信された場所（モデルカード、外部など） |
| `filename` | 評価結果のYAMLファイルへのパス（例: `.eval_results/swe_bench_verified.yaml`） |
| `pull_request` | ベンチマークデータセットのリポジトリへの提出に関するPR番号 |
| `notes` | エントリに関連付けられた任意のメモ |

## 事前集計されたマルチベンチマークデータセット

複数のベンチマークのスコアを1つのファイルにまとめたい場合は、[`OpenEvals/leaderboard-data`](https://huggingface.co/datasets/OpenEvals/leaderboard-data)データセットが公式ベンチマークのスコアを1つのParquetファイルに集約しています:

`hf://` パスを使用して、[pandas](./datasets-pandas) で直接読み込むことができます:

```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())
```

これは、複数のAPIエンドポイントを呼び出すことなく、ベンチマーク横断のビューを取得する最速の方法です。

## モデルメタデータによる補完

`huggingface_hub`を使用して、リリース日、パラメータ数、その他のメタデータでリーダーボードのデータを補完します:

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

## モデル中心のビュー: モデルごとの評価結果

リーダーボード API は、データセット中心のビュー（1つのベンチマーク上のすべてのモデル）を提供します。その逆、つまり単一のモデルのすべてのベンチマークスコアを取得するには、`expand=["evalResults"]` を指定して `model_info` を使用します。

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

これは、モデルの`.eval_results/`ファイルから解析された[`EvalResultEntry`](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.EvalResultEntry)オブジェクトを返します。

## 例: リーダーボードデータを活用して

[Benchmark Leaderboard Race](https://huggingface.co/spaces/davanstrien/benchmark-race) Space は、これらのデータソースを組み合わせることで、モデルのランキングが時間とともにどのように変化するかをアニメーションで可視化します。このデータに基づいて独自の分析や可視化を作成できます。完全な例については、[ソースコード](https://huggingface.co/spaces/davanstrien/benchmark-race/tree/main)を参照してください。

## ウェブページにリーダーボードを埋め込む

iframe を使用して、ベンチマークデータセットのリーダーボードを独自のウェブページに直接埋め込むことができます。

使用するURLは`https://huggingface.co/datasets/<namespace>/<dataset-name>/embed/leaderboard`です。ここで`<namespace>`はベンチマークデータセットの所有者（ユーザーまたは組織）を、`<dataset-name>`はデータセットの名前を表します。

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

### パラメータ

iframe の URL にクエリパラメータを渡すことで、埋め込みリーダーボードを設定できます。

| パラメータ | 説明 |
|---|---|
| `leaderboard_task_id` | ベンチマークの`eval.yaml`で定義されている、表示するタスクのID（例: `gpqa_diamond`）です。デフォルトでは最初のタスクが使用されます。 |
| `eval_result` | リーダーボードでハイライトするモデルID（例: `meta-llama/Llama-3.1-8B`）。 |
| `leaderboard_max_params` | 最大パラメータ数で行をフィルタリングします。以下の値のいずれかを指定できます: `1B`、`3B`、`6B`、`12B`、`32B`、`128B` または `500B`。 |
| `leaderboard_is_expanded` | リーダーボードを折りたたみではなく完全に展開してレンダリングするには、`true`に設定します。 |

例えば、HLEリーダーボードをテーブル展開状態で、特定のモデルをハイライトして埋め込むには:

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

埋め込みは、評価結果を持つ[公式ベンチマークデータセット](./eval-results#benchmark-datasets)でのみ利用可能です。

## 関連項目

- [評価結果](./eval-results) — 評価結果の提出方法とベンチマークの登録方法
- [公式ベンチマークデータセット](https://huggingface.co/datasets?benchmark=benchmark:official&sort=trending) — 公式ベンチマークをすべて閲覧