# 벤치마크 리더보드 데이터에 액세스

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는 이러한 데이터 소스를 결합하여 모델 순위가 시간에 따라 어떻게 변화하는지를 보여주는 애니메이션 시각화를 생성합니다. 이 데이터를 기반으로 자체 분석 및 시각화를 구축할 수 있으며, 완전한 예제는 [소스 코드](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` | 리더보드에서 강조할 Model 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) — 모든 공식 벤치마크 보기