Mixin'ler ve serielleştirme yöntemleri

Mixin'ler

huggingface_hub kütüphanesi, nesneleriniz için ebeveyn sınıf olarak kullanılabilecek ve basit yükleme/indirme işlevleri sunan bir dizi mixin sunar. Herhangi bir ML çerçevesini Hub ile nasıl entegre edeceğinizi öğrenmek için entegrasyon kılavuzumuza göz atın.

Genel

sınıf huggingface_hub.ModelHubMixin

< source >

( *args**kwargs )

Parametreler

repo_url (str, isteğe bağlı) — Kütüphane deposunun URL'si. Model kartını oluşturmak için kullanılır.
paper_url (str, isteğe bağlı) — Kütüphane makalesinin URL'si. Model kartını oluşturmak için kullanılır.
docs_url (str, isteğe bağlı) — Kütüphane dokümantasyonunun URL'si. Model kartı oluşturmak için kullanılır.
model_card_template (str, isteğe bağlı) — Model kartı şablonu. Model kartını oluşturmak için kullanılır. Varsayılan olarak genel bir şablon kullanılır.
language (str veya list[str], isteğe bağlı) — Kütüphanenin desteklediği dil. Model kartı oluşturmak için kullanılır.
library_name (str, isteğe bağlı) — ModelHubMixin'i entegre eden kütüphanenin adı. Model kartını oluşturmak için kullanılır.
license (str, isteğe bağlı) — ModelHubMixin'i entegre eden kütüphanenin lisansı. Model kartını oluşturmak için kullanılır. Örn: “apache-2.0”
license_name (str, isteğe bağlı) — ModelHubMixin'i entegre eden kütüphanenin adı. Model kartını oluşturmak için kullanılır. Yalnızca license değeri other olarak ayarlanırsa kullanılır. Örn: “coqui-public-model-license”.
license_link (str, isteğe bağlı) — ModelHubMixin'i entegre eden kütüphanenin lisansına giden URL. Model kartını oluşturmak için kullanılır. Yalnızca license değeri other olarak ayarlanmış ve license_name değeri belirlenmişse kullanılır. Örn: ”https://coqui.ai/cpml”.
pipeline_tag (str, isteğe bağlı) — Hattın etiketi. Model kartını oluşturmak için kullanılır. Örn. “text-classification”.
tags (list[str], isteğe bağlı) — Model kartına eklenecek etiketler. Model kartını oluşturmak için kullanılır. Örn. [“computer-vision”]
coders (dict[Type, tuple[Callable, Callable]], isteğe bağlı) — Özel türlerin ve bunların kodlayıcı/çözücülerinin sözlüğü. Varsayılan olarak jsonable olmayan argümanları kodlamak/çözmek için kullanılır. Örn. dataclasses, argparse.Namespace, OmegaConf vb.

Hub ile HERHANGİ BİR makine öğrenimi çerçevesini entegre etmek için genel bir karışım (mixin).

Çerçevenizi entegre etmek için model sınıfınız bu sınıftan türetmek zorundadır. Modellerin kaydedilmesi/yüklenmesi için özel mantık _from_pretrained ve _save_pretrained içinde yeniden yazılmalıdır. PyTorchModelHubMixin, Hub ile mixin entegrasyonunun iyi bir örneğidir. Daha fazla talimat için entegrasyon kılavuzumuza göz atın.

ModelHubMixin sınıfından türetirken sınıf düzeyinde öznitelikler tanımlayabilirsiniz. Bu öznitelikler __init__ yerine sınıf tanımının kendisine iletilir. Bu, ModelHubMixin entegre eden kütüphaneye ilişkin meta verileri tanımlamak için kullanışlıdır.

Karışımı kütüphanenize nasıl entegre edeceğinize dair daha fazla ayrıntı için entegrasyon kılavuzuna göz atın.

Örnek:

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

< source >

( save_directory: Path )

Parametreler

save_directory (str veya Path) — Model ağırlıklarının ve yapılandırmanın kaydedileceği dizinin yolu.

Alt sınıfta bu yöntemi geçersiz kılınarak modelinizin nasıl kaydedileceğini tanımlayın. Talimatlar için entegrasyon kılavuzumuza göz atın.

_from_pretrained

< source >

Parametreler

model_id (str) — Huggingface Hub'dan yüklenecek modelin kimliği (ör. bigscience/bloom).
revision (str, isteğe bağlı) — Hub'daki modelin revizyonu. Bir dal adı, bir git etiketi veya herhangi bir commit kimliği olabilir. Varsayılan olarak main dalındaki en son commit'tir.
force_download (bool, isteğe bağlı, varsayılan False) — Model ağırlıklarının ve yapılandırma dosyalarının Hub'dan mevcut önbelleği geçersiz kılacak şekilde (yeniden) indirilmesinin zorlanıp zorlanmayacağı.
token (str veya bool, isteğe bağlı) — Uzak dosyalar için HTTP bearer yetkilendirmesi olarak kullanılacak jeton. Varsayılan olarak, hf auth login çalıştırıldığında önbelleğe alınan jetonu kullanır.
cache_dir (str, Path, isteğe bağlı) — Önbelleğe alınan dosyaların saklandığı klasörün yolu.
local_files_only (bool, isteğe bağlı, varsayılan False) — True ise, dosyanın indirilmesini engeller ve varsa yerel önbellekteki dosyanın yolunu döndürür.
model_kwargs — _from_pretrained() yöntemine iletilen ek anahtar kelime argümanları.

Ön eğitilmiş modelden yüklemenin nasıl yapılacağını tanımlamak için bu yöntemi alt sınıfta yeniden yazın.

Dosyaları Hub'dan indirmek için yüklemelerinden önce hf_hub_download() veya snapshot_download() kullanın. Girdi olarak alınan çoğu argüman, bu 2 yönteme doğrudan geçirilebilir. Gerekirse, bu yönteme “model_kwargs” kullanarak daha fazla argüman ekleyebilirsiniz. Örneğin PyTorchModelHubMixin._from_pretrained(), modelin hangi cihazda yüklenmesi gerektiğini belirlemek için girdi olarak map_location parametresini alır.

Daha fazla talimat için entegrasyon kılavuzumuza göz atın.

from_pretrained

< source >

Parametreler

pretrained_model_name_or_path (str, Path) —
- Hub'da barındırılan bir modelin model_id'si (string), örneğin bigscience/bloom.
- Veya save_pretrained kullanılarak kaydedilmiş model ağırlıklarını içeren bir directory yolu, örneğin ../path/to/my_model_directory/.
revision (str, isteğe bağlı) — Hub'daki modelin revizyonu. Bir dal adı, bir git etiketi veya herhangi bir commit kimliği olabilir. Varsayılan olarak main dalındaki en son commit'tir.
force_download (bool, isteğe bağlı, varsayılan False) — Model ağırlıklarının ve yapılandırma dosyalarının Hub'dan mevcut önbelleği geçersiz kılacak şekilde (yeniden) indirilmesinin zorlanıp zorlanmayacağı.
token (str veya bool, isteğe bağlı) — Uzak dosyalar için HTTP bearer yetkilendirmesi olarak kullanılacak jeton. Varsayılan olarak, hf auth login çalıştırıldığında önbelleğe alınan jetonu kullanır.
cache_dir (str, Path, isteğe bağlı) — Önbelleğe alınan dosyaların saklandığı klasörün yolu.
local_files_only (bool, isteğe bağlı, varsayılan False) — True ise, dosyanın indirilmesini engeller ve varsa yerel önbellekteki dosyanın yolunu döndürür.
model_kwargs (dict, isteğe bağlı) — Başlatma sırasında modele iletilecek ek kwargs.

Huggingface Hub'dan bir model indirin ve örnekleyin.

push_to_hub

< source >

Parametreler

repo_id (str) — İtki yapılacak deposunun kimliği (örnek: "username/my-model").
config (dict veya DataclassInstance, isteğe bağlı) — Anahtar/değer sözlüğü veya bir dataclass örneği olarak belirtilen model yapılandırması.
commit_message (str, isteğe bağlı) — İterken iletilecek mesaj.
private (bool, isteğe bağlı) — Oluşturulacak depoyun özel olup olmayacağı. None (varsayılan) ise, organizasyonun varsayılanı özel değilse depo herkese açık olacaktır.
token (str, isteğe bağlı) — Uzak dosyalar için HTTP bearer yetkilendirmesi olarak kullanılacak jeton. Varsayılan olarak, hf auth login çalıştırıldığında önbelleğe alınan jeton kullanılır.
branch (str, isteğe bağlı) — Modelin itileceği git dalı. Varsayılan değeri "main"'dir.
create_pr (boolean, isteğe bağlı) — O commit ile branch üzerinden bir Pull Request oluşturulup oluşturulmayacağı. Varsayılan olarak False.
allow_patterns (list[str] veya str, isteğe bağlı) — Verilirse, yalnızca en az bir desenle eşleşen dosyalar itilir.
ignore_patterns (list[str] veya str, isteğe bağlı) — Verilirse, desenlerden herhangi biriyle eşleşen dosyalar itilmez.
delete_patterns (list[str] veya str, isteğe bağlı) — Belirtilirse, desenlerden herhangi biriyle eşleşen uzak dosyalar depodan silinir.
model_card_kwargs (dict[str, Any], isteğe bağlı) — Model kartını özelleştirmek için model kartı şablonuna iletilen ek argümanlar.

Model kontrol noktasını Hub'a yükleyin.

Hub'a hangi dosyaların gönderileceğini hassas bir şekilde filtrelemek için allow_patterns ve ignore_patterns kullanın. Aynı commit'te mevcut uzak dosyaları silmek için delete_patterns kullanın. Daha fazla ayrıntı için upload_folder() referansına bakın.

save_pretrained

< source >

Parametreler

save_directory (str veya Path) — Model ağırlıklarının ve yapılandırmanın kaydedileceği dizinin yolu.
config (dict veya DataclassInstance, isteğe bağlı) — Anahtar/değer sözlüğü veya bir dataclass örneği olarak belirtilen model yapılandırması.
push_to_hub (bool, isteğe bağlı, varsayılan False) — Modelinizi kaydettikten sonra Huggingface Hub'a gönderip göndermeyeceğinizi belirtir.
repo_id (str, isteğe bağlı) — Hub'daki depoyunuzun kimliği. Yalnızca push_to_hub=True ise kullanılır. Verilmezse varsayılan olarak klasör adı kullanılır.
model_card_kwargs (dict[str, Any], isteğe bağlı) — Model kartını özelleştirmek için model kartı şablonuna iletilen ek argümanlar.
push_to_hub_kwargs — push_to_hub() metoduna iletilen ek anahtar kelime argümanları.

Dönüş değeri

str veya None

push_to_hub=True ise Hub'daki commit'in URL'si, aksi halde None.

Ağırlıkları yerel dizinde kaydet.

PyTorch

sınıf huggingface_hub.PyTorchModelHubMixin

< source >

( *args**kwargs )

PyTorch modellerine model Hub yükleme/indirme yetenekleri sağlamak için ModelHubMixin uygulaması. Model, varsayılan olarak model.eval() kullanılarak değerlendirme moduna ayarlanır (dropout modülleri devre dışı bırakılır). Modeli eğitmek için önce model.train() ile eğitim moduna geri almanız gerekir.

Karışımı nasıl kullanacağınızla ilgili daha fazla ayrıntı için ModelHubMixin'e bakın.

Örnek:

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

< source >

( repo_id: strrevision: str | None = None )

Parametreler

repo_id (str) — Serileştirilmiş (pickled) fastai.Learner'ın bulunduğu konum. Aşağıdakilerden biri olabilir:
- Hugging Face Hub üzerinde barındırılır. Örn.: ‘espejelomar/fatai-pet-breeds-classification’ veya ‘distilgpt2’. repo_id sonuna @ ekleyerek bir revision ekleyebilirsiniz. Örn.: dbmdz/bert-base-german-cased@main. Revision, kullanılacak belirli model sürümüdür. Hugging Face Hub üzerinde modelleri ve diğer artefaktları depolamak için git tabanlı bir sistem kullandığımız için, bir dal adı, bir etiket adı veya bir commit id olabilir.
- Yerel olarak barındırılır. repo_id, fastai.Learner oluşturulurken kullanılan fastai ve fastcore sürümlerini gösteren pickle dosyasını ve pyproject.toml dosyasını içeren bir dizin olur. Örn: ./my_model_directory/.
revision (str, isteğe bağlı) — Deponun dosyalarının indirildiği revizyon. snapshot_download belgelerine bakın.

Önceden eğitilmiş fastai modelini Hub'dan veya yerel bir dizinden yükler.

huggingface_hub.push_to_hub_fastai

< source >

Parametreler

learner (Learner) — Hub'a göndermek istediğiniz *fastai.Learner.
repo_id (str) — Hub'daki modeliniz için “namespace/repo_name” biçiminde depo kimliği. Namespace, yazma erişiminiz olan bireysel hesabınız veya bir organizasyon olabilir (örneğin, ‘stanfordnlp/stanza-de’).
commit_message (str`, isteğe bağlı*) — İterilirken iletilecek mesaj. Varsayılan olarak "add model" olur.
private (bool, opsiyonel) — Oluşturulacak deponun özel olup olmayacağı. None (varsayılan) ise, organizasyonun varsayılanı özel olmadıkça depo herkese açık olarak oluşturulur.
token (str, opsiyonel) — Uzak dosyalar için HTTP bearer yetkilendirmesi olarak kullanılacak Hugging Face hesap belirteci. None ise, belirteç bir istem aracılığıyla sorulur.
config (dict, isteğe bağlı) — Model ağırlıklarıyla birlikte kaydedilecek yapılandırma nesnesi.
branch (str, opsiyonel) — Modelin itileceği git dalı. Bu, varsayılan olarak deponuzda belirtilen varsayılan dala ayarlanır ve bu da varsayılan olarak “main” olur.
create_pr (boolean, isteğe bağlı) — O commit ile branch üzerinden bir Pull Request oluşturulup oluşturulmayacağı. Varsayılan değeri False'tur.
api_endpoint (str, isteğe bağlı) — Modeli hub'a gönderirken kullanılacak API uç noktası.
allow_patterns (list[str] veya str, isteğe bağlı) — Verilirse, yalnızca en az bir desenle eşleşen dosyalar itilir.
ignore_patterns (list[str] veya str, isteğe bağlı) — Verilirse, desenlerden herhangi biriyle eşleşen dosyalar itilmez.
delete_patterns (list[str] veya str, isteğe bağlı) — Belirtilirse, desenlerden herhangi biriyle eşleşen uzak dosyalar depodan silinir.

Öğrenici kontrol noktası dosyalarını Hub'a yükleyin.

Hub'a hangi dosyaların gönderileceğini hassas bir şekilde filtrelemek için allow_patterns ve ignore_patterns kullanın. Aynı commit'te mevcut uzak dosyaları silmek için delete_patterns kullanın. Daha fazla ayrıntı için [upload_folder] referansına bakın.

Aşağıdaki hatayı oluşturur:

Kullanıcı Hugging Face Hub'a giriş yapmadıysa ValueError.

Update on GitHub

Hub Python Library

Mixin'ler ve serielleştirme yöntemleri

Mixin'ler

Genel

sınıf huggingface_hub.ModelHubMixin

_save_pretrained

_from_pretrained

from_pretrained

push_to_hub

save_pretrained

PyTorch

sınıf huggingface_hub.PyTorchModelHubMixin

Fastai

huggingface_hub.from_pretrained_fastai

huggingface_hub.push_to_hub_fastai