Hugging Face's logo

Hub Python Library documentation

مزيجات وطرق التسلسل

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

مزيجات وطرق التسلسل

مزيج

توفر مكتبة huggingface_hub مجموعة من المخلوطات (mixins) التي يمكن استخدامها كصنف أبٍ لكائناتك، من أجل توفير دوال بسيطة للرفع والتنزيل. اطّلع على دليل التكامل لدينا لمعرفة كيفية دمج أي إطار عمل للتعلم الآلي مع Hub.

عام

فئة huggingface_hub.ModelHubMixin

< >

( *args**kwargs )

المعاملات

  • repo_url (str، اختياري) — رابط مستودع المكتبة. يُستخدم لتوليد بطاقة النموذج.
  • paper_url (str، اختياري) — رابط ورقة المكتبة. يُستخدم لتوليد بطاقة النموذج.
  • docs_url (str، اختياري) — رابط توثيق المكتبة. يُستخدم لتوليد بطاقة النموذج.
  • model_card_template (str, اختياري) — قالب بطاقة النموذج. يُستخدم لتوليد بطاقة النموذج. القيمة الافتراضية هي قالب عام.
  • language (str أو list[str]، اختياري) — اللغة المدعومة من قبل المكتبة. يُستخدم لتوليد بطاقة النموذج.
  • library_name (str، اختياري) — اسم المكتبة التي تكامل مع ModelHubMixin. يُستخدم لتوليد بطاقة النموذج.
  • license (str، اختياري) — رخصة المكتبة التي تكاملت مع ModelHubMixin. تُستخدم لتوليد بطاقة النموذج. مثال: “apache-2.0”
  • license_name (str, اختياري) — اسم المكتبة التي تكاملت مع ModelHubMixin. يُستخدم لتوليد بطاقة النموذج. يُستخدم فقط إذا كان license مضبوطًا على other. مثال: “coqui-public-model-license”.
  • license_link (str، اختياري) — رابط URL لترخيص المكتبة التي تكاملت مع ModelHubMixin. يُستخدم لتوليد بطاقة النموذج. يُستخدم فقط إذا كان license مضبوطًا على other وكان license_name مضبوطًا. مثال: ”https://coqui.ai/cpml”.
  • pipeline_tag (str، اختياري) — وسم خط الأنابيب. يُستخدم لتوليد بطاقة النموذج. على سبيل المثال “text-classification”.
  • tags (list[str]، اختياري) — الوسوم التي سيتم إضافتها إلى بطاقة النموذج. تُستخدم لتوليد بطاقة النموذج. مثال: [“computer-vision”]
  • coders (dict[Type, tuple[Callable, Callable]]، اختياري) — قاموس بأنواع مخصصة ومشفّراتها/مفكّكاتها. يُستخدم لتشفير/فكّ تشفير الحُجج التي لا تكون قابلة للتحويل إلى JSON بشكل افتراضي. على سبيل المثال: dataclasses، argparse.Namespace، OmegaConf، وما إلى ذلك.

مزيج عام (mixin) لتكامل أي إطار عمل للتعلم الآلي مع Hub.

لدمج إطار عملك، يجب أن ترث فئة النموذج الخاصة بك من هذه الفئة. يجب إعادة كتابة المنطق المخصص لحفظ/تحميل النماذج في _from_pretrained و_save_pretrained. يُعد PyTorchModelHubMixin مثالاً جيدًا على دمج الميكسين مع Hub. راجع دليل التكامل لدينا للحصول على مزيد من التعليمات.

عند الوراثة من ModelHubMixin، يمكنك تعريف سمات على مستوى الفئة. لا تُمرَّر هذه السمات إلى __init__ بل إلى تعريف الفئة نفسه. وهذا مفيد لتحديد بيانات وصفية عن المكتبة التي تكاملت مع ModelHubMixin.

لمزيد من التفاصيل حول كيفية دمج الميكسين مع مكتبتك، راجد دليل التكامل.

مثال:

>>> from huggingface_hub import ModelHubMixin

# Inherit from ModelHubMixin
>>> class MyCustomModel(
...         ModelHubMixin,
...         library_name="my-library",
...         tags=["computer-vision"],
...         repo_url="https://github.com/huggingface/my-cool-library",
...         paper_url="https://arxiv.org/abs/2304.12244",
...         docs_url="https://huggingface.co/docs/my-cool-library",
...         # ^ optional metadata to generate model card
...     ):
...     def __init__(self, size: int = 512, device: str = "cpu"):
...         # define how to initialize your model
...         super().__init__()
...         ...
...
...     def _save_pretrained(self, save_directory: Path) -> None:
...         # define how to serialize your model
...         ...
...
...     @classmethod
...     def from_pretrained(
...         cls: type[T],
...         pretrained_model_name_or_path: Union[str, Path],
...         *,
...         force_download: bool = False,
...         token: Optional[Union[str, bool]] = None,
...         cache_dir: Optional[Union[str, Path]] = None,
...         local_files_only: bool = False,
...         revision: Optional[str] = None,
...         **model_kwargs,
...     ) -> T:
...         # define how to deserialize your model
...         ...

>>> model = MyCustomModel(size=256, device="gpu")

# Save model weights to local directory
>>> model.save_pretrained("my-awesome-model")

# Push model weights to the Hub
>>> model.push_to_hub("my-awesome-model")

# Download and initialize weights from the Hub
>>> reloaded_model = MyCustomModel.from_pretrained("username/my-awesome-model")
>>> reloaded_model.size
256

# Model card has been correctly populated
>>> from huggingface_hub import ModelCard
>>> card = ModelCard.load("username/my-awesome-model")
>>> card.data.tags
["x-custom-tag", "pytorch_model_hub_mixin", "model_hub_mixin"]
>>> card.data.library_name
"my-library"

_save_pretrained

< >

( save_directory: Path )

المعاملات

  • save_directory (str أو Path) — المسار إلى المجلد الذي سيتم حفظ أوزان النموذج وإعداداته فيه.

اعِد كتابة هذه الطريقة في الفئة الفرعية لتحديد كيفية حفظ نموذجك. اطّلع على دليل التكامل لدينا للحصول على التعليمات.

_from_pretrained

< >

( model_id: strrevision: str | Nonecache_dir: str | pathlib.Path | Noneforce_download: boollocal_files_only: booltoken: str | bool | None**model_kwargs )

المعاملات

  • model_id (str) — معرّف النموذج الذي سيتم تحميله من Huggingface Hub (مثل bigscience/bloom).
  • revision (str, اختياري) — إصدار النموذج على Hub. يمكن أن يكون اسم فرع، أو وسم git، أو أي معرف commit. الافتراضي هو أحدث commit على فرع main.
  • force_download (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب إجبار (إعادة) تنزيل أوزان النموذج وملفات الإعداد من Hub، مع تجاوز ذاكرة التخزين المؤقت الموجودة.
  • token (str أو bool، اختياري) — الرمز الذي يُستخدم كتفويض حامل HTTP للملفات البعيدة. افتراضيًا، سيستخدم الرمز المخزّن مؤقتًا عند تشغيل hf auth login.
  • cache_dir (str، Path، اختياري) — المسار إلى المجلد الذي تُخزَّن فيه الملفات المؤقتة.
  • local_files_only (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، فتجنّب تنزيل الملف وعُدّ مسار الملف المخزّن محليًا إذا كان موجودًا.
  • model_kwargs — معلمات إضافية تُمرَّر إلى طريقة _from_pretrained().

اعِد كتابة هذه الطريقة في الفئة الفرعية لتحديد كيفية تحميل النموذج من نموذج مُدرَّب مسبقًا.

استخدم hf_hub_download() أو snapshot_download() لتنزيل الملفات من Hub قبل تحميلها. معظم المعاملات المُدخلة يمكن تمريرها مباشرةً إلى هاتين الطريقتين. عند الحاجة، يمكنك إضافة معاملات أخرى إلى هذه الطريقة باستخدام “model_kwargs”. على سبيل المثال، تقبل PyTorchModelHubMixin._from_pretrained() معامل map_location لتحديد الجهاز الذي يجب تحميل النموذج عليه.

اطّلع على دليل التكامل لدينا لمزيد من التعليمات.

from_pretrained

< >

( pretrained_model_name_or_path: str | pathlib.Pathforce_download: bool = Falsetoken: str | bool | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_files_only: bool = Falserevision: str | None = None**model_kwargs )

المعاملات

  • pretrained_model_name_or_path (str, Path) —
    • إما model_id (نص) لنموذج مستضاف على Hub، مثل bigscience/bloom.
    • أو مسار إلى directory يحتوي على أوزان النموذج المحفوظة باستخدام save_pretrained، على سبيل المثال ../path/to/my_model_directory/.
  • revision (str, اختياري) — إصدار النموذج على Hub. يمكن أن يكون اسم فرع، أو وسم git، أو أي معرف commit. الافتراضي هو أحدث commit على فرع main.
  • force_download (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب إجبار (إعادة) تنزيل أوزان النموذج وملفات الإعداد من Hub، مع تجاوز ذاكرة التخزين المؤقت الموجودة.
  • token (str أو bool، اختياري) — الرمز الذي يُستخدم كتفويض حامل HTTP للملفات البعيدة. افتراضيًا، سيستخدم الرمز المخزّن مؤقتًا عند تشغيل hf auth login.
  • cache_dir (str، Path، اختياري) — المسار إلى المجلد الذي تُخزَّن فيه الملفات المؤقتة.
  • local_files_only (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، فتجنّب تنزيل الملف وعُدّ مسار الملف المخزّن محليًا إذا كان موجودًا.
  • model_kwargs (dict، اختياري) — معاملات إضافية (kwargs) تُمرَّر إلى النموذج أثناء التهيئة.

قم بتنزيل نموذج من Huggingface Hub ثم أنشئ مثيلًا له.

push_to_hub

< >

( repo_id: strconfig: dict | huggingface_hub.hub_mixin.DataclassInstance | None = Nonecommit_message: str = 'Push model using huggingface_hub.'private: bool | None = Nonetoken: str | None = Nonebranch: str | None = Nonecreate_pr: bool | None = Noneallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonedelete_patterns: list[str] | str | None = Nonemodel_card_kwargs: dict[str, typing.Any] | None = None )

المعاملات

  • repo_id (str) — معرّف المستودع الذي سيتم الدفع إليه (مثال: "username/my-model").
  • config (dict أو DataclassInstance، اختياري) — إعدادات النموذج المحددة كقاموس مفاتيح/قيم أو ككائن dataclass.
  • commit_message (str, اختياري) — الرسالة التي سيتم الالتزام بها أثناء الدفع.
  • private (bool، اختياري) — ما إذا كان يجب أن يكون المستودع الذي تم إنشاؤه خاصًا. إذا كان None (الافتراضي)، فسيكون المستودع عامًا ما لم يكن الافتراضي للمنظمة هو الخاص.
  • token (str، اختياري) — الرمز الذي يُستخدم كتفويض حامل HTTP للملفات البعيدة. افتراضيًا، سيُستخدم الرمز المخزَّن مؤقتًا عند تشغيل hf auth login.
  • branch (str، اختياري) — فرع git الذي سيتم دفع النموذج إليه. القيمة الافتراضية هي "main".
  • create_pr (boolean، اختياري) — ما إذا كان سيتم إنشاء طلب سحب (Pull Request) من branch مع ذلك الالتزام. القيمة الافتراضية هي False.
  • allow_patterns (list[str] أو str، اختياري) — إذا تم تقديمه، يتم دفع الملفات التي تطابق نمطًا واحدًا على الأقل فقط.
  • ignore_patterns (list[str] أو str، اختياري) — إذا تم تقديمه، فإن الملفات المطابقة لأي من الأنماط لن يتم دفعها.
  • delete_patterns (list[str] أو str، اختياري) — إذا تم تقديمه، فسيتم حذف الملفات البعيدة التي تطابق أيًا من الأنماط من المستودع.
  • model_card_kwargs (dict[str, Any]، اختياري) — حجج إضافية تُمرَّر إلى قالب بطاقة النموذج لتخصيص البطاقة.

ارفع نقطة التفتيش للنموذج إلى Hub.

استخدم allow_patterns وignore_patterns لتصفية الملفات التي يجب دفعها إلى المستودع بدقة. استخدم delete_patterns لحذف الملفات البعيدة الموجودة مسبقًا في نفس الالتزام. راجع مرجع upload_folder() لمزيد من التفاصيل.

save_pretrained

< >

( save_directory: str | pathlib.Pathconfig: dict | huggingface_hub.hub_mixin.DataclassInstance | None = Nonerepo_id: str | None = Nonepush_to_hub: bool = Falsemodel_card_kwargs: dict[str, typing.Any] | None = None**push_to_hub_kwargs ) → str or None

المعاملات

  • save_directory (str أو Path) — المسار إلى المجلد الذي سيتم حفظ أوزان النموذج وإعداداته فيه.
  • config (dict أو DataclassInstance، اختياري) — إعدادات النموذج المحددة كقاموس مفاتيح/قيم أو ككائن dataclass.
  • push_to_hub (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم دفع النموذج الخاص بك إلى Huggingface Hub بعد حفظه.
  • repo_id (str، اختياري) — معرّف مستودعك على Hub. يُستخدم فقط إذا كان push_to_hub=True. سيُستخدم اسم المجلد افتراضيًا إذا لم يُقدَّم.
  • model_card_kwargs (dict[str, Any]، اختياري) — حجج إضافية تُمرَّر إلى قالب بطاقة النموذج لتخصيص البطاقة.
  • push_to_hub_kwargs — معلمات إضافية تُمرَّر إلى طريقة push_to_hub().

يعيد

str أو None

عنوان commit على Hub إذا كان push_to_hub=True، وإلا None.

حفظ الأوزان في مجلد محلي.

PyTorch

فئة huggingface_hub.PyTorchModelHubMixin

< >

( *args**kwargs )

تنفيذ ModelHubMixin لتوفير قدرات رفع/تنزيل نماذج Hub لنماذج PyTorch. يتم ضبط النموذج في وضع التقييم افتراضياً باستخدام model.eval() (تُعطَّل وحدات dropout). لتدريب النموذج، يجب عليك أولاً إعادة ضبطه في وضع التدريب باستخدام model.train().

راجع ModelHubMixin لمزيد من التفاصيل حول كيفية استخدام المكوّن الإضافي.

مثال:

>>> import torch
>>> import torch.nn as nn
>>> from huggingface_hub import PyTorchModelHubMixin

>>> class MyModel(
...         nn.Module,
...         PyTorchModelHubMixin,
...         library_name="keras-nlp",
...         repo_url="https://github.com/keras-team/keras-nlp",
...         paper_url="https://arxiv.org/abs/2304.12244",
...         docs_url="https://keras.io/keras_nlp/",
...         # ^ optional metadata to generate model card
...     ):
...     def __init__(self, hidden_size: int = 512, vocab_size: int = 30000, output_size: int = 4):
...         super().__init__()
...         self.param = nn.Parameter(torch.rand(hidden_size, vocab_size))
...         self.linear = nn.Linear(output_size, vocab_size)

...     def forward(self, x):
...         return self.linear(x + self.param)
>>> model = MyModel(hidden_size=256)

# Save model weights to local directory
>>> model.save_pretrained("my-awesome-model")

# Push model weights to the Hub
>>> model.push_to_hub("my-awesome-model")

# Download and initialize weights from the Hub
>>> model = MyModel.from_pretrained("username/my-awesome-model")
>>> model.hidden_size
256

Fastai

huggingface_hub.from_pretrained_fastai

< >

( repo_id: strrevision: str | None = None )

المعاملات

  • repo_id (str) — الموقع الذي يتواجد فيه ملف fastai.Learner المُجمَّد (pickled). يمكن أن يكون أحد الخيارين التاليين:
    • مستضاف على Hugging Face Hub. مثال: ‘espejelomar/fatai-pet-breeds-classification’ أو ‘distilgpt2’. يمكنك إضافة revision عن طريق إضافة @ في نهاية repo_id. مثال: dbmdz/bert-base-german-cased@main. الـ Revision هو إصدار النموذج المحدد الذي سيتم استخدامه. نظرًا لأننا نستخدم نظامًا قائمًا على git لتخزين النماذج وغيرها من المخرجات على Hugging Face Hub، فقد يكون اسم فرع، أو اسم وسم، أو معرف commit.
    • يُستضاف محليًا. سيكون repo_id مجلدًا يحتوي على ملف pickle وملف pyproject.toml يحدد إصدارات fastai وfastcore المستخدمة لبناء fastai.Learner. على سبيل المثال: ./my_model_directory/.
  • revision (str، اختياري) — المراجعة التي يتم تنزيل ملفات المستودع منها. راجع توثيق snapshot_download.

تحميل نموذج fastai مُدرَّب مسبقًا من Hub أو من مجلد محلي.

huggingface_hub.push_to_hub_fastai

< >

( learnerrepo_id: strcommit_message: str = 'Push FastAI model using huggingface_hub.'private: bool | None = Nonetoken: str | None = Noneconfig: dict | None = Nonebranch: str | None = Nonecreate_pr: bool | None = Noneallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonedelete_patterns: list[str] | str | None = Noneapi_endpoint: str | None = None )

المعاملات

  • learner (Learner) — *fastai.Learner’ الذي تريد رفعه إلى Hub.
  • repo_id (str) — معرّف المستودع الخاص بنموذجك في Hub بصيغة “namespace/repo_name”. يمكن أن يكون namespace حسابك الفردي أو منظمة لديك صلاحية الكتابة إليها (على سبيل المثال، ‘stanfordnlp/stanza-de’).
  • commit_message (str`, اختياري*) — الرسالة التي سيتم الالتزام بها أثناء الدفع. ستكون الافتراضية "add model".
  • private (bool، optional) — ما إذا كان يجب أن يكون المستودع الذي تم إنشاؤه خاصًا أم لا. إذا كان None (الافتراضي)، فسيكون عامًا افتراضيًا، باستثناء حالة كون الافتراضي الخاص بالمنظمة هو الخاص.
  • token (str، اختياري) — رمز حساب Hugging Face الذي يُستخدم كتفويض حامل HTTP للملفات عن بُعد. إذا كان None، فسيُطلب الرمز عبر رسالة تفاعلية.
  • config (dict، اختياري) — كائن التهيئة الذي سيتم حفظه إلى جانب أوزان النموذج.
  • branch (str، اختياري) — فرع git الذي سيتم دفع النموذج إليه. القيمة الافتراضية هي الفرع الافتراضي كما هو محدد في مستودعك، والذي يكون افتراضيًا “main”.
  • create_pr (boolean، اختياري) — ما إذا كان سيتم إنشاء طلب سحب (Pull Request) من branch مع ذلك الالتزام. الافتراضي هو False.
  • api_endpoint (str، اختياري) — نقطة النهاية الخاصة بالواجهة البرمجية (API) التي تُستخدم عند دفع النموذج إلى المستودع (Hub).
  • allow_patterns (list[str] أو str، اختياري) — إذا تم تقديمه، يتم دفع الملفات التي تطابق نمطًا واحدًا على الأقل فقط.
  • ignore_patterns (list[str] أو str، اختياري) — إذا تم تقديمه، فإن الملفات المطابقة لأي من الأنماط لن يتم دفعها.
  • delete_patterns (list[str] أو str، اختياري) — إذا تم تقديمه، فسيتم حذف الملفات البعيدة التي تطابق أيًا من الأنماط من المستودع.

ارفع ملفات نقاط التفتيش الخاصة بالتلميذ إلى Hub.

استخدم allow_patterns و ignore_patterns لتصفية الملفات التي يجب دفعها إلى المستودع بدقة. استخدم delete_patterns لحذف الملفات البعيدة الموجودة مسبقًا في نفس الالتزام. راجع مرجع [upload_folder] لمزيد من التفاصيل.

يرفع الخطأ التالي:

  • ValueError إذا لم يكن المستخدم مسجلاً الدخول إلى Hugging Face Hub.
Update on GitHub

←تنزيل الملفات أنواع الاستدلال→