벤치마크 리더보드 데이터 접근하기

벤치마크 리더보드 데이터 접근하기 (Accessing Benchmark Leaderboard Data)

Hub의 Benchmark 데이터셋은 평가 점수로 모델을 순위 매기는 리더보드를 담고 있어요. 이 데이터에 프로그래밍 방식으로 접근해 분석, 대시보드 또는 도구를 그 위에 구축할 수 있습니다.

출처: 문서

본문

Hub의 Benchmark 데이터셋은 평가 점수로 모델을 순위 매기는 리더보드를 포함합니다. 이 데이터에 프로그래밍 방식으로 접근해 분석, 대시보드, 도구를 그 위에 구축할 수 있어요.

공식 벤치마크 발견하기 (Discovering official benchmarks)

huggingface_hub으로 모든 공식 벤치마크 데이터셋을 찾으세요:

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

리더보드 순위 가져오기 (Getting leaderboard rankings)

리더보드 API는 벤치마크 데이터셋에 대한 순위 매겨진 모델 점수를 반환합니다:

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

get_dataset_leaderboard를 사용해 타입이 지정된 DatasetLeaderboardEntry 객체로 순위 매겨진 모델 점수를 가져오세요:

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은 기본적으로 캐시된 토큰을 사용합니다. gated 벤치마크 데이터셋의 경우 로그인(hf auth login)했는지 확인하거나 토큰을 명시적으로 전달하세요:

leaderboard = api.get_dataset_leaderboard("gated/benchmark", token="hf_...")

[!TIP] 빠른 접근용 curl 원라이너(에이전트와 스크립팅에 유용):

curl https://huggingface.co/api/datasets/cais/hle/leaderboard \
  --header "Authorization: Bearer $(cat ~/.cache/huggingface/token)" | jq .

응답 필드 (Response fields)

각 DatasetLeaderboardEntry는 다음을 포함합니다:

사전 집계된 멀티 벤치마크 데이터셋 (Pre-aggregated multi-benchmark dataset)

한 파일에서 여러 벤치마크의 점수를 원한다면 OpenEvals/leaderboard-data 데이터셋이 공식 벤치마크 전반의 점수를 단일 Parquet 파일로 집계합니다:

pandas로 hf:// 경로를 사용해 직접 불러올 수 있어요:

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 엔드포인트를 호출하지 않고 크로스-벤치마크 관점을 얻는 가장 빠른 방법입니다.

모델 메타데이터로 보강하기 (Enriching with model metadata)

huggingface_hub으로 리더보드 데이터를 릴리스 날짜, 파라미터 수, 기타 메타데이터로 보강하세요:

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

모델 중심 관점: 모델별 eval 결과 (Model-centric view: eval results per model)

리더보드 API는 데이터셋 중심 관점(한 벤치마크의 모든 모델)을 제공합니다. 반대 방향(단일 모델의 모든 벤치마크 점수)은 expand=["evalResults"]와 함께 model_info를 사용하세요:

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 객체를 반환합니다.

예시: 리더보드 데이터 위에 구축하기 (Example: building on leaderboard data)

Benchmark Leaderboard Race Space는 이러한 데이터 소스를 결합해 모델 순위가 시간에 따라 어떻게 변하는지 보여주는 애니메이션 시각화를 만듭니다. 이 데이터 위에 자체 분석·시각화를 구축할 수 있어요 — 전체 예시는 소스 코드를 참고하세요.

웹페이지에 리더보드 임베드하기 (Embed a leaderboard in a webpage)

벤치마크 데이터셋의 리더보드를 iframe으로 자신의 웹페이지에 직접 임베드할 수 있어요.

사용할 URL은 https://huggingface.co/datasets/<namespace>/<dataset-name>/embed/leaderboard이며, <namespace>는 벤치마크 데이터셋 소유자(사용자 또는 조직), <dataset-name>은 데이터셋 이름입니다.

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

파라미터 (Parameters)

iframe URL에 쿼리 파라미터를 전달해 임베드된 리더보드를 구성할 수 있어요:

예를 들어 테이블을 펼치고 특정 모델을 강조한 HLE 리더보드를 임베드하려면:

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

임베드는 평가 결과가 있는 공식 벤치마크 데이터셋에서만 사용할 수 있어요.

관련 (Related)

• Eval Results — 평가 결과 제출과 벤치마크 등록 방법
• Official Benchmark Datasets — 모든 공식 벤치마크 둘러보기

더 알아보기 (Learn more)

get_dataset_leaderboard로 벤치마크 순위를 가져오고, OpenEvals/leaderboard-data Parquet로 한 파일에서 여러 벤치마크를 확인할 수 있어요. 모델별로는 expand=["evalResults"]를 쓰고, 웹페이지에는 embed/leaderboard iframe을 사용하세요. 자세한 제출·등록은 Eval Results 문서를 참고하세요.