Acessando dados do ranking de benchmarks

Os conjuntos de dados de benchmark no Hub contêm rankings que classificam modelos com base em suas pontuações de avaliação. Você pode acessar esses dados programaticamente para analisá-los, criar painéis ou ferramentas com base neles.

Descobrindo benchmarks oficiais

Use huggingface_hub para encontrar todos os conjuntos de dados de benchmark oficiais:

from huggingface_hub import HfApi

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

Ou diretamente pela API REST (útil para agentes e scripts):

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

Obtendo as classificações do ranking

A API do ranking retorna as pontuações dos modelos ranqueados para um conjunto de dados de referência:

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

Use get_dataset_leaderboard para buscar as pontuações dos modelos ranqueados como objetos tipados 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}")

huggingface_hub usa seu token em cache por padrão. Para conjuntos de dados de benchmark com acesso restrito, verifique se você está conectado (hf auth login) ou passe um token explicitamente:

Copiado

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

Comando único do Curl para acesso rápido (útil para agentes e scripts):

Copiado

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

Campos de resposta

Cada DatasetLeaderboardEntry contém:

Conjunto de dados pré-agregado de múltiplos benchmarks

Se você deseja pontuações de vários benchmarks em um único arquivo, o conjunto de dados OpenEvals/leaderboard-data agrega pontuações de benchmarks oficiais em um único arquivo Parquet:

Você pode carregá-lo diretamente com pandas usando o caminho 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())

Esta é a maneira mais rápida de obter uma visão entre benchmarks sem chamar múltiplos endpoints de API.

Enriquecendo com metadados do modelo

Use huggingface_hub para enriquecer os dados do ranking com datas de lançamento, contagem de parâmetros e outros metadados:

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

Visão centrada no modelo: resultados de avaliação por modelo

A API do leaderboard oferece uma visão centrada no dataset (todos os modelos em um único benchmark). Para o inverso — todas as pontuações de benchmark para um único modelo — use model_info com expand=["evalResults"]:

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

Isso retorna objetos EvalResultEntry analisados dos arquivos .eval_results/ do modelo.

Exemplo: construindo com base em dados de ranking

O Space Benchmark Leaderboard Race combina essas fontes de dados para criar uma visualização animada de como as classificações dos modelos evoluem ao longo do tempo. Você pode construir suas próprias análises e visualizações com base nesses dados — veja o código-fonte para um exemplo completo.

Incorporar um ranking em uma página da web

Você pode incorporar o ranking de um conjunto de dados de benchmark diretamente na sua própria página da web usando um iframe.

A URL a ser usada é https://huggingface.co/datasets/<namespace>/<dataset-name>/embed/leaderboard, em que <namespace> é o proprietário do conjunto de dados de benchmark (usuário ou organização) e <dataset-name> é o nome do conjunto de dados.

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

Parâmetros

Você pode configurar o ranking embutido passando parâmetros de consulta na URL do iframe:

Por exemplo, para incorporar o ranking do HLE com a tabela expandida e um modelo específico destacado:

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

O embed está disponível apenas para conjuntos de dados de benchmark oficiais que possuem resultados de avaliação.

Relacionados

• Resultados de Avaliação — como enviar resultados de avaliação e registrar benchmarks
• Conjuntos de dados de benchmark oficiais — explore todos os benchmarks oficiais