# Доступ к данным таблицы лидеров бенчмарков

[Наборы данных для бенчмаркинга](./eval-results#benchmark-datasets) на Hub содержат таблицы лидеров, в которых модели ранжируются по результатам их оценки. Вы можете программно получить доступ к этим данным, чтобы анализировать их, а также создавать на их основе дашборды или инструменты.

## Поиск официальных бенчмарков

Используйте `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` | Полный идентификатор модели (например, `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:

Вы можете загрузить его напрямую с помощью [pandas](./datasets-pandas), используя путь `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())
```

Это самый быстрый способ получить обзор по нескольким бенчмаркам без обращения к нескольким 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}")
```

Возвращает объекты [`EvalResultEntry`](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.EvalResultEntry), разобранные из файлов `.eval_results/` модели.

## Пример: построение на основе данных таблицы лидеров

Space [Benchmark Leaderboard Race](https://huggingface.co/spaces/davanstrien/benchmark-race) объединяет эти источники данных, чтобы создать анимированную визуализацию того, как меняется ранжирование моделей со временем. Вы можете создавать собственные аналитические и визуализационные решения на основе этих данных — см. [исходный код](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>
```

### Параметры

Вы можете настроить встроенную таблицу лидеров, передав параметры запроса в URL iframe:

| Параметр | Описание |
|---|---|
| `leaderboard_task_id` | Идентификатор задачи для отображения, как определено в `eval.yaml` бенчмарка (например, `gpqa_diamond`). По умолчанию используется первая задача. |
| `eval_result` | Идентификатор модели, который нужно выделить в таблице лидеров (например, `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) — просмотр всех официальных бенчмарков