# 访问基准排行榜数据

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` | 与条目关联的可选备注 |

## 预聚合的多基准数据集

如果您希望在一个文件中获取多个基准测试的分数，[`OpenEvals/leaderboard-data`](https://huggingface.co/datasets/OpenEvals/leaderboard-data) 数据集将各个官方基准测试的分数汇总到一个 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 提供以数据集为中心的视图（一个基准测试上的所有模型）。对于反向查询——单个模型的所有基准测试分数——请使用 `model_info` 并设置 `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}")
```

这将返回从模型的 `.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 整合了这些数据源，以动画形式可视化模型排名随时间的演变。您可以基于这些数据构建自己的分析和可视化——请参阅 [source code](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` | 要显示的任务 ID，如基准测试的 `eval.yaml` 中所定义（例如 `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) — 浏览所有官方基准