# إنشاء بطاقات نماذج ومشاركتها

توفّر مكتبة `huggingface_hub` واجهة بلغة بايثون لإنشاء بطاقات النماذج ومشاركتها وتحديثها. زُر [الصفحة المخصصة للتوثيق](https://huggingface.co/docs/hub/models-cards) للحصول على نظرة أعمق على ماهية بطاقات النماذج على الـ Hub وكيفية عملها في الخلفية.

## تحميل بطاقة نموذج من المستودع

لتحميل بطاقة موجودة مسبقًا من Hub، يمكنك استخدام دالة [ModelCard.load()](/docs/huggingface_hub/v2.4.0/ar/package_reference/cards#huggingface_hub.RepoCard.load). هنا، سنقوم بتحميل البطاقة من [`nateraw/vit-base-beans`](https://huggingface.co/nateraw/vit-base-beans).

```python
from huggingface_hub import ModelCard

card = ModelCard.load('nateraw/vit-base-beans')
```

تحتوي هذه البطاقة على بعض الخصائص المفيدة التي قد ترغب في الوصول إليها/الاستفادة منها:
  - `card.data`: يعيد كائنًا من [ModelCardData](/docs/huggingface_hub/v2.4.0/ar/package_reference/cards#huggingface_hub.ModelCardData) يحتوي على بيانات وصفية لبطاقة النموذج. استدعِ `.to_dict()` على هذا الكائن للحصول على التمثيل كقاموس.
  - `card.text`: يعيد نص البطاقة، *باستثناء ترويسة البيانات الوصفية*.
  - `card.content`: يعيد المحتوى النصي للبطاقة، *بما في ذلك ترويسة البيانات الوصفية*.

## إنشاء بطاقات النماذج

### من النص

لتهيئة بطاقة نموذج من نص، ما عليك سوى تمرير محتوى النص الخاص بالبطاقة إلى `ModelCard` عند التهيئة.

```python
content = """
---
language: en
license: mit
---

# My Model Card
"""

card = ModelCard(content)
card.data.to_dict() == {'language': 'en', 'license': 'mit'}  # True
```

طريقة أخرى قد ترغب في استخدامها هي السلاسل f. في المثال التالي، نقوم بما يلي:

- استخدم [ModelCardData.to_yaml()](/docs/huggingface_hub/v2.4.0/ar/package_reference/cards#huggingface_hub.CardData.to_yaml) لتحويل البيانات الوصفية التي حددناها إلى YAML حتى نتمكن من استخدامها لإدراج كتلة YAML في بطاقة النموذج.
- اعرض كيف يمكنك استخدام متغير قالب عبر سلاسل f في Python.

```python
card_data = ModelCardData(language='en', license='mit', library='timm')

example_template_var = 'nateraw'
content = f"""
---
{ card_data.to_yaml() }
---

# My Model Card

This model created by [@{example_template_var}](https://github.com/{example_template_var})
"""

card = ModelCard(content)
print(card)
```

سيُبقينا المثال أعلاه مع بطاقة تبدو على النحو التالي:

```
---
language: en
license: mit
library: timm
---

# My Model Card

This model created by [@nateraw](https://github.com/nateraw)
```

### من قالب Jinja

إذا كان `Jinja2` مثبّتًا، يمكنك إنشاء بطاقات نماذج من ملف قالب jinja. دعنا نلقي نظرة على مثال أساسي:

```python
from pathlib import Path

from huggingface_hub import ModelCard, ModelCardData

# Define your jinja template
template_text = """
---
{{ card_data }}
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@{{ author }}](https://hf.co/{{author}}).
""".strip()

# Write the template to a file
Path('custom_template.md').write_text(template_text)

# Define card metadata
card_data = ModelCardData(language='en', license='mit', library_name='keras')

# Create card from template, passing it any jinja template variables you want.
# In our case, we'll pass author
card = ModelCard.from_template(card_data, template_path='custom_template.md', author='nateraw')
card.save('my_model_card_1.md')
print(card)
```

يبدو ماركداون البطاقة الناتجة على النحو التالي:

```
---
language: en
license: mit
library_name: keras
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@nateraw](https://hf.co/nateraw).
```

إذا قمت بتحديث أي card.data، فسيظهر ذلك في البطاقة نفسها.

```
card.data.library_name = 'timm'
card.data.language = 'fr'
card.data.license = 'apache-2.0'
print(card)
```

الآن، كما ترون، تم تحديث ترويسة البيانات الوصفية:

```
---
language: fr
license: apache-2.0
library_name: timm
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@nateraw](https://hf.co/nateraw).
```

عند تحديث بيانات البطاقة، يمكنك التحقق من أن البطاقة لا تزال صالحة بالنسبة إلى Hub عن طريق استدعاء [ModelCard.validate()](/docs/huggingface_hub/v2.4.0/ar/package_reference/cards#huggingface_hub.RepoCard.validate). يضمن ذلك أن البطاقة تجتاز أي قواعد تحقق مُعدّة على Hugging Face Hub.

### من القالب الافتراضي

بدلاً من استخدام قالبك الخاص، يمكنك أيضاً استخدام [القالب الافتراضي](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md)، وهو بطاقة نموذج كاملة الميزات تضمّ عدداً كبيراً من الأقسام التي قد ترغب في ملئها. في الخلفية، يستخدم [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/) لملء ملف القالب.

> [!TIP]
> لاحظ أنه يجب عليك تثبيت Jinja2 لاستخدام `from_template`. يمكنك القيام بذلك عبر `pip install Jinja2`.

```python
card_data = ModelCardData(language='en', license='mit', library_name='keras')
card = ModelCard.from_template(
    card_data,
    model_id='my-cool-model',
    model_description="this model does this and that",
    developers="Nate Raw",
    repo="https://github.com/huggingface/huggingface_hub",
)
card.save('my_model_card_2.md')
print(card)
```

## مشاركة بطاقات النماذج

إذا كنت مسجلاً الدخول إلى Hugging Face Hub (سواءً باستخدام `hf auth login` أو [login()](/docs/huggingface_hub/v2.4.0/ar/package_reference/authentication#huggingface_hub.login))، يمكنك دفع البطاقات إلى Hub ببساطة عن طريق استدعاء [ModelCard.push_to_hub()](/docs/huggingface_hub/v2.4.0/ar/package_reference/cards#huggingface_hub.RepoCard.push_to_hub). دعونا نلقي نظرة على كيفية القيام بذلك...

أولاً، سننشئ مستودعًا جديدًا باسم 'hf-hub-modelcards-pr-test' ضمن نطاق المستخدم الموثّق:

```python
from huggingface_hub import whoami, create_repo

user = whoami()['name']
repo_id = f'{user}/hf-hub-modelcards-pr-test'
url = create_repo(repo_id, exist_ok=True)
```

ثم سننشئ بطاقة من القالب الافتراضي (نفس ذلك المعرّف في القسم أعلاه):

```python
card_data = ModelCardData(language='en', license='mit', library_name='keras')
card = ModelCard.from_template(
    card_data,
    model_id='my-cool-model',
    model_description="this model does this and that",
    developers="Nate Raw",
    repo="https://github.com/huggingface/huggingface_hub",
)
```

أخيرًا، سنرفع ذلك إلى المستودع

```python
card.push_to_hub(repo_id)
```

يمكنك الاطلاع على البطاقة الناتجة [هنا](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/blob/main/README.md).

إذا كنت ترغب بدلاً من ذلك في دفع بطاقة كطلب سحب، يمكنك ببساطة كتابة `create_pr=True` عند استدعاء `push_to_hub`:

```python
card.push_to_hub(repo_id, create_pr=True)
```

يمكن الاطلاع على طلب الدمج الناتج عن هذا الأمر [هنا](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/discussions/3).

## تحديث البيانات الوصفية

في هذا القسم سنرى ما هي البيانات الوصفية في بطاقات المستودعات وكيفية تحديثها.

يشير `metadata` إلى خريطة تجزئة (أو سياق مفاتيح وقيم) توفر بعض المعلومات عالية المستوى حول نموذج أو مجموعة بيانات أو مساحة. يمكن أن تشمل هذه المعلومات تفاصيل مثل `pipeline type` للنموذج، أو `model_id` أو `model_description`. لمزيد من التفاصيل، يمكنك الاطلاع على هذه الأدلة: [بطاقة النموذج](https://huggingface.co/docs/hub/model-cards#model-card-metadata)، [بطاقة مجموعة البيانات](https://huggingface.co/docs/hub/datasets-cards#dataset-card-metadata) و [إعدادات المساحات](https://huggingface.co/docs/hub/spaces-settings#spaces-settings). دعونا الآن نلقي نظرة على بعض الأمثلة حول كيفية تحديث هذه البيانات الوصفية.

لنبدأ بمثال أول:

```python
>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "image-classification"})
```

باستخدام هاتين السطرين من الكود، ستقوم بتحديث البيانات الوصفية (metadata) لتعيين `pipeline_tag` جديد.

بشكل افتراضي، لا يمكنك تحديث مفتاح موجود مسبقًا على البطاقة. إذا كنت ترغب في ذلك، يجب عليك تمرير `overwrite=True` بشكل صريح:

```python
>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "text-generation"}, overwrite=True)
```

غالبًا ما ترغب في اقتراح بعض التغييرات على مستودع لا تملك فيه صلاحية الكتابة. يمكنك القيام بذلك من خلال إنشاء طلب سحب (PR) على ذلك المستودع، مما يتيح للمالكين مراجعة اقتراحاتك ودمجها.

```python
>>> from huggingface_hub import metadata_update
>>> metadata_update("someone/model", {"pipeline_tag": "text-classification"}, create_pr=True)
```

## تضمين نتائج التقييم

لإدراج نتائج التقييم في البيانات الوصفية `model-index`، يمكنك تمرير [EvalResult](/docs/huggingface_hub/v2.4.0/ar/package_reference/cards#huggingface_hub.EvalResult) أو قائمة من `EvalResult` مع نتائج التقييم المرتبطة بها. في الخلفية، سيتم إنشاء `model-index` عند استدعاء `card.data.to_dict()`. لمزيد من المعلومات حول كيفية عمل ذلك، يمكنك الاطلاع على [هذا القسم من توثيقات Hub](https://huggingface.co/docs/hub/models-cards#evaluation-results).

> [!TIP]
> لاحظ أن استخدام هذه الدالة يتطلب تضمين خاصية `model_name` في [ModelCardData](/docs/huggingface_hub/v2.4.0/ar/package_reference/cards#huggingface_hub.ModelCardData).

```python
card_data = ModelCardData(
    language='en',
    license='mit',
    model_name='my-cool-model',
    eval_results = EvalResult(
        task_type='image-classification',
        dataset_type='beans',
        dataset_name='Beans',
        metric_type='accuracy',
        metric_value=0.7
    )
)

card = ModelCard.from_template(card_data)
print(card.data)
```

يجب أن يبدو `card.data` الناتج على النحو التالي:

```
language: en
license: mit
model-index:
- name: my-cool-model
  results:
  - task:
      type: image-classification
    dataset:
      name: Beans
      type: beans
    metrics:
    - type: accuracy
      value: 0.7
```

إذا كان لديك أكثر من نتيجة تقييم ترغب في مشاركتها، فما عليك سوى تمرير قائمة من `EvalResult`:

```python
card_data = ModelCardData(
    language='en',
    license='mit',
    model_name='my-cool-model',
    eval_results = [
        EvalResult(
            task_type='image-classification',
            dataset_type='beans',
            dataset_name='Beans',
            metric_type='accuracy',
            metric_value=0.7
        ),
        EvalResult(
            task_type='image-classification',
            dataset_type='beans',
            dataset_name='Beans',
            metric_type='f1',
            metric_value=0.65
        )
    ]
)
card = ModelCard.from_template(card_data)
card.data
```

حيث يجب أن يتبقى لديك ما يلي في `card.data`:

```
language: en
license: mit
model-index:
- name: my-cool-model
  results:
  - task:
      type: image-classification
    dataset:
      name: Beans
      type: beans
    metrics:
    - type: accuracy
      value: 0.7
    - type: f1
      value: 0.65
```