Hub Python Library documentation
إنشاء بطاقات نماذج ومشاركتها
إنشاء بطاقات نماذج ومشاركتها
توفّر مكتبة huggingface_hub واجهة بلغة بايثون لإنشاء بطاقات النماذج ومشاركتها وتحديثها.
تصفّح الصفحة المخصصة للتوثيق للحصول على نظرة أعمق على ماهية بطاقات النماذج على الـ Hub وكيفية عملها في الخلفية.
تحميل بطاقة نموذج من المستودع
لتحميل بطاقة موجودة مسبقًا من Hub، يمكنك استخدام دالة ModelCard.load(). هنا، سنقوم بتحميل البطاقة من nateraw/vit-base-beans.
from huggingface_hub import ModelCard
card = ModelCard.load('nateraw/vit-base-beans')تحتوي هذه البطاقة على بعض الخصائص المفيدة التي قد ترغب في الوصول إليها/الاستفادة منها:
card.data: يعيد كائنًا من ModelCardData يحتوي على بيانات وصفية لبطاقة النموذج. استدعِ.to_dict()على هذا الكائن للحصول على التمثيل كقاموس.card.text: يعيد نص البطاقة، باستثناء ترويسة البيانات الوصفية.card.content: يعيد المحتوى النصي للبطاقة، بما في ذلك ترويسة البيانات الوصفية.
إنشاء بطاقات النماذج
من النص
لتهيئة بطاقة نموذج من نص، ما عليك سوى تمرير محتوى النص الخاص بالبطاقة إلى ModelCard عند التهيئة.
content = """
---
language: en
license: mit
---
# My Model Card
"""
card = ModelCard(content)
card.data.to_dict() == {'language': 'en', 'license': 'mit'} # Trueطريقة أخرى قد ترغب في استخدامها هي السلاسل f. في المثال التالي، نقوم بما يلي:
- استخدم ModelCardData.to_yaml() لتحويل البيانات الوصفية التي حددناها إلى YAML حتى نتمكن من استخدامها لإدراج كتلة YAML في بطاقة النموذج.
- اعرض كيف يمكنك استخدام متغير قالب عبر سلاسل f في 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. دعنا نلقي نظرة على مثال أساسي:
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(). يضمن ذلك أن البطاقة تجتاز أي قواعد تحقق مُعدّة على Hugging Face Hub.
من القالب الافتراضي
بدلاً من استخدام قالبك الخاص، يمكنك أيضاً استخدام القالب الافتراضي، وهو بطاقة نموذج كاملة الميزات تضمّ عدداً كبيراً من الأقسام التي قد ترغب في ملئها. في الخلفية، يستخدم Jinja2 لملء ملف القالب.
لاحظ أنه يجب عليك تثبيت Jinja2 لاستخدام
from_template. يمكنك القيام بذلك عبرpip install Jinja2.
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())، يمكنك دفع البطاقات إلى Hub ببساطة عن طريق استدعاء ModelCard.push_to_hub(). دعونا نلقي نظرة على كيفية القيام بذلك…
أولاً، سننشئ مستودعًا جديدًا باسم ‘hf-hub-modelcards-pr-test’ ضمن نطاق المستخدم الموثّق:
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)ثم سننشئ بطاقة من القالب الافتراضي (نفس ذلك المعرّف في القسم أعلاه):
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.push_to_hub(repo_id)
يمكنك الاطلاع على البطاقة الناتجة هنا.
إذا كنت ترغب بدلاً من ذلك في دفع بطاقة كطلب سحب، يمكنك ببساطة كتابة create_pr=True عند استدعاء push_to_hub:
card.push_to_hub(repo_id, create_pr=True)يمكن الاطلاع على طلب الدمج الناتج عن هذا الأمر هنا.
تحديث البيانات الوصفية
في هذا القسم سنرى ما هي البيانات الوصفية في بطاقات المستودعات وكيفية تحديثها.
يشير metadata إلى خريطة تجزئة (أو سياق مفاتيح وقيم) توفر بعض المعلومات عالية المستوى حول نموذج أو مجموعة بيانات أو مساحة. يمكن أن تشمل هذه المعلومات تفاصيل مثل pipeline type للنموذج، أو model_id أو model_description. لمزيد من التفاصيل، يمكنك الاطلاع على هذه الأدلة: بطاقة النموذج، بطاقة مجموعة البيانات و إعدادات المساحات.
الآن، دعنا نرى بعض الأمثلة على كيفية تحديث هذه البيانات الوصفية.
لنبدأ بمثال أول:
>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "image-classification"})باستخدام هاتين السطرين من الكود، ستقوم بتحديث البيانات الوصفية (metadata) لتعيين pipeline_tag جديد.
بشكل افتراضي، لا يمكنك تحديث مفتاح موجود مسبقًا على البطاقة. إذا كنت ترغب في ذلك، يجب عليك تمرير overwrite=True بشكل صريح:
>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "text-generation"}, overwrite=True)غالبًا ما ترغب في اقتراح بعض التغييرات على مستودع لا تملك فيه صلاحية الكتابة. يمكنك القيام بذلك من خلال إنشاء طلب سحب (PR) على ذلك المستودع، مما يتيح للمالكين مراجعة اقتراحاتك ودمجها.
>>> from huggingface_hub import metadata_update
>>> metadata_update("someone/model", {"pipeline_tag": "text-classification"}, create_pr=True)تضمين نتائج التقييم
لإدراج نتائج التقييم في البيانات الوصفية model-index، يمكنك تمرير EvalResult أو قائمة من EvalResult مع نتائج التقييم المرتبطة بها. في الخلفية، سيتم إنشاء model-index عند استدعاء card.data.to_dict(). لمزيد من المعلومات حول كيفية عمل ذلك، يمكنك الاطلاع على هذا القسم من توثيقات Hub.
لاحظ أن استخدام هذه الدالة يتطلب تضمين خاصية
model_nameفي ModelCardData.
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:
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