# الوصول إلى بيانات لوحة صدارة المعايير

تحتوي [مجموعات بيانات المعايير](./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
```

## الحصول على ترتيبات لوحة الصدارة

يعيد واجهة برمجة التطبيقات الخاصة بلوحة الصدارة درجات النماذج المرتبة لمجموعة بيانات مرجعية:

```
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())
```

هذه هي أسرع طريقة للحصول على نظرة شاملة عبر المعايير دون الحاجة إلى استدعاء نقاط نهاية واجهة برمجة التطبيقات المتعددة.

## إثراء بيانات النموذج الوصفية

استخدم `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 "")
```

## منظور يركّز على النموذج: نتائج التقييم لكل نموذج

توفر واجهة برمجة التطبيقات الخاصة بلوحة الصدارة عرضاً يركز على مجموعة البيانات (جميع النماذج على معيار تقييم واحد). أما للحصول على العكس — أي جميع درجات المعايير التقييمية لنموذج واحد — فاستخدم `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/` الخاصة بالنموذج.

## مثال: البناء على بيانات لوحة الصدارة

تجمع مساحة [Benchmark Leaderboard Race](https://huggingface.co/spaces/davanstrien/benchmark-race) بين مصادر البيانات هذه لإنشاء تصور متحرك يوضح كيف تتطور ترتيبات النماذج مع مرور الوقت. يمكنك بناء تحليلات وتصورات خاصة بك فوق هذه البيانات — راجع [الكود المصدري](https://huggingface.co/spaces/davanstrien/benchmark-race/tree/main) للحصول على مثال كامل.

## تضمين لوحة صدارة في صفحة ويب

يمكنك تضمين لوحة صدارة مجموعة بيانات المعيار مباشرةً في صفحتك الخاصة باستخدام إطار iframe.

العنوان الذي يجب استخدامه هو `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) — تصفح جميع مجموعات البيانات الرسمية للمعايرة