Mixins & méthodes de sérialisation

Mixins

La bibliothèque huggingface_hub propose une série de mixins qui peuvent être utilisés comme classe parente pour vos objets, afin de fournir des fonctions simples de téléversement et de téléchargement. Consultez notre guide d’intégration pour apprendre comment intégrer n’importe quel framework ML avec le Hub.

Générique

classe huggingface_hub.ModelHubMixin

< source >

( *args**kwargs )

Paramètres

repo_url (str, facultatif) — URL du dépôt de la bibliothèque. Utilisé pour générer la carte du modèle.
paper_url (str, facultatif) — URL du papier de la bibliothèque. Utilisé pour générer la carte du modèle.
docs_url (str, facultatif) — URL de la documentation de la bibliothèque. Utilisé pour générer la carte du modèle.
model_card_template (str, facultatif) — Modèle de la carte du modèle. Utilisé pour générer la carte du modèle. Par défaut, un modèle générique est utilisé.
language (str ou list[str], facultatif) — Langue prise en charge par la bibliothèque. Utilisé pour générer la carte du modèle.
library_name (str, facultatif) — Nom de la bibliothèque intégrant ModelHubMixin. Utilisé pour générer la carte du modèle.
license (str, facultatif) — Licence de la bibliothèque intégrant ModelHubMixin. Utilisée pour générer la carte du modèle. Ex. : “apache-2.0”
license_name (str, facultatif) — Nom de la bibliothèque intégrant ModelHubMixin. Utilisé pour générer la carte du modèle. Utilisé uniquement si license est défini sur other. Ex. : « coqui-public-model-license ».
license_link (str, facultatif) — URL de la licence de la bibliothèque intégrant ModelHubMixin. Utilisée pour générer la carte du modèle. Utilisée uniquement si license est défini sur other et si license_name est défini. Ex. : ”https://coqui.ai/cpml”.
pipeline_tag (str, facultatif) — Étiquette du pipeline. Utilisée pour générer la carte du modèle. Par exemple, « text-classification ».
tags (list[str], facultatif) — Étiquettes à ajouter à la carte du modèle. Utilisé pour générer la carte du modèle. Ex. : [“computer-vision”]
coders (dict[Type, tuple[Callable, Callable]], facultatif) — Dictionnaire des types personnalisés et de leurs encodeurs/décodeurs. Utilisé pour encoder/décoder des arguments qui ne sont pas jsonables par défaut. Par exemple, dataclasses, argparse.Namespace, OmegaConf, etc.

Un mixin générique pour intégrer N'IMPORTE QUEL framework d'apprentissage automatique avec le Hub.

Pour intégrer votre framework, votre classe de modèle doit hériter de cette classe. La logique personnalisée pour l'enregistrement/le chargement des modèles doit être réécrite dans _from_pretrained et _save_pretrained. PyTorchModelHubMixin est un bon exemple d'intégration de mixin avec le Hub. Consultez notre guide d'intégration pour plus de détails.

Lorsque vous héritez de ModelHubMixin, vous pouvez définir des attributs au niveau de la classe. Ces attributs ne sont pas transmis à __init__ mais à la définition de la classe elle-même. Cela est utile pour définir des métadonnées sur la bibliothèque intégrant ModelHubMixin.

Pour plus de détails sur l'intégration du mixin avec votre bibliothèque, consultez le guide d'intégration.

Exemple :

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

Paramètres

save_directory (str ou Path) — Chemin du répertoire dans lequel les poids et la configuration du modèle seront enregistrés.

Écrasez cette méthode dans la sous-classe pour définir comment enregistrer votre modèle. Consultez notre guide d'intégration pour obtenir des instructions.

_from_pretrained

< source >

Paramètres

model_id (str) — ID du modèle à charger depuis le Huggingface Hub (par ex. bigscience/bloom).
revision (str, facultatif) — Révision du modèle sur le Hub. Peut être un nom de branche, un tag git ou un identifiant de commit. Par défaut, la dernière révision de la branche main.
force_download (bool, facultatif, par défaut False) — Indique s'il faut forcer le (re)téléchargement des poids du modèle et des fichiers de configuration depuis le Hub, en ignorant le cache existant.
token (str ou bool, facultatif) — Le jeton à utiliser comme autorisation bearer HTTP pour les fichiers distants. Par défaut, il utilise le jeton mis en cache lors de l’exécution de hf auth login.
cache_dir (str, Path, facultatif) — Chemin vers le dossier où les fichiers en cache sont stockés.
local_files_only (bool, facultatif, valeur par défaut False) — Si True, évite de télécharger le fichier et renvoie le chemin du fichier en cache local s'il existe.
model_kwargs — Arguments supplémentaires passés à la méthode _from_pretrained().

Écrasez cette méthode dans la sous-classe pour définir comment charger votre modèle à partir d'un modèle pré-entraîné.

Utilisez hf_hub_download() ou snapshot_download() pour télécharger les fichiers depuis le Hub avant de les charger. La plupart des arguments pris en entrée peuvent être transmis directement à ces deux méthodes. Si nécessaire, vous pouvez ajouter d’autres arguments à cette méthode en utilisant « model_kwargs ». Par exemple, PyTorchModelHubMixin._from_pretrained() prend en entrée un paramètre map_location pour définir sur quel appareil le modèle doit être chargé.

Consultez notre guide d'intégration pour plus de détails.

from_pretrained

< source >

Paramètres

pretrained_model_name_or_path (str, Path) —
- Soit le model_id (chaîne de caractères) d'un modèle hébergé sur le Hub, par exemple bigscience/bloom.
- Or a path to a directory containing model weights saved using save_pretrained, e.g., ../path/to/my_model_directory/.
revision (str, facultatif) — Révision du modèle sur le Hub. Peut être un nom de branche, un tag git ou un identifiant de commit. Par défaut, la dernière révision de la branche main.
force_download (bool, facultatif, par défaut False) — Indique s'il faut forcer le (re)téléchargement des poids du modèle et des fichiers de configuration depuis le Hub, en ignorant le cache existant.
token (str ou bool, facultatif) — Le jeton à utiliser comme autorisation bearer HTTP pour les fichiers distants. Par défaut, il utilise le jeton mis en cache lors de l’exécution de hf auth login.
cache_dir (str, Path, facultatif) — Chemin vers le dossier où les fichiers en cache sont stockés.
local_files_only (bool, facultatif, valeur par défaut False) — Si True, évite de télécharger le fichier et renvoie le chemin du fichier en cache local s'il existe.
model_kwargs (dict, facultatif) — Kwargs supplémentaires à passer au modèle lors de l'initialisation.

Téléchargez un modèle depuis le Huggingface Hub et instanciez-le.

push_to_hub

< source >

Paramètres

repo_id (str) — ID du dépôt vers lequel pousser (exemple : "username/my-model").
config (dict ou DataclassInstance, facultatif) — Configuration du modèle spécifiée sous forme de dictionnaire clé/valeur ou d’instance de dataclass.
commit_message (str, facultatif) — Message à committer lors de la poussée.
private (bool, facultatif) — Indique si le dépôt créé doit être privé. Si None (par défaut), le dépôt sera public sauf si le défaut de l’organisation est privé.
token (str, facultatif) — Le jeton à utiliser comme autorisation bearer HTTP pour les fichiers distants. Par défaut, il utilise le jeton mis en cache lors de l’exécution de hf auth login.
branch (str, facultatif) — La branche git sur laquelle pousser le modèle. La valeur par défaut est "main".
create_pr (boolean, facultatif) — Indique s'il faut ou non créer une Pull Request depuis branch avec cet engagement. La valeur par défaut est False.
allow_patterns (list[str] ou str, facultatif) — Si fourni, seuls les fichiers correspondant à au moins un motif sont poussés.
ignore_patterns (list[str] ou str, facultatif) — Si fourni, les fichiers correspondant à l’un des motifs ne sont pas poussés.
delete_patterns (list[str] ou str, facultatif) — Si fourni, les fichiers distants correspondant à l’un des motifs seront supprimés du dépôt.
model_card_kwargs (dict[str, Any], facultatif) — Arguments supplémentaires transmis au modèle de carte du modèle pour personnaliser la carte du modèle.

Téléverser le point de contrôle du modèle sur le Hub.

Utilisez allow_patterns et ignore_patterns pour filtrer précisément les fichiers à pousser sur le hub. Utilisez delete_patterns pour supprimer les fichiers distants existants dans le même commit. Consultez la référence de upload_folder() pour plus de détails.

save_pretrained

< source >

Paramètres

save_directory (str ou Path) — Chemin du répertoire dans lequel les poids et la configuration du modèle seront enregistrés.
config (dict ou DataclassInstance, facultatif) — Configuration du modèle spécifiée sous forme de dictionnaire clé/valeur ou d’instance de dataclass.
push_to_hub (bool, facultatif, par défaut False) — Indique s'il faut ou non pousser votre modèle sur le Huggingface Hub après l'avoir enregistré.
repo_id (str, facultatif) — ID de votre dépôt sur le Hub. Utilisé uniquement si push_to_hub=True. Par défaut, il correspond au nom du dossier si aucune valeur n’est fournie.
model_card_kwargs (dict[str, Any], facultatif) — Arguments supplémentaires transmis au modèle de carte du modèle pour personnaliser la carte du modèle.
push_to_hub_kwargs — Arguments supplémentaires passés à la méthode push_to_hub().

Retourne

str ou None

URL de l'engagement sur le Hub si push_to_hub=True, None sinon.

Enregistrer les poids dans un répertoire local.

PyTorch

classe huggingface_hub.PyTorchModelHubMixin

< source >

( *args**kwargs )

Implémentation de ModelHubMixin pour fournir les capacités de téléversement/téléchargement sur le Hub aux modèles PyTorch. Le modèle est défini en mode évaluation par défaut à l'aide de model.eval() (les modules dropout sont désactivés). Pour entraîner le modèle, vous devez d'abord le remettre en mode entraînement avec model.train().

Voir ModelHubMixin pour plus de détails sur l'utilisation du mixin.

Exemple :

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

Paramètres

repo_id (str) — L'emplacement du fastai.Learner sérialisé. Il peut être l'un des deux suivants :
- Hébergé sur le Hugging Face Hub. Ex. : ‘espejelomar/fatai-pet-breeds-classification’ ou ‘distilgpt2’. Vous pouvez ajouter une revision en ajoutant @ à la fin de repo_id. Ex. : dbmdz/bert-base-german-cased@main. La revision est la version spécifique du modèle à utiliser. Étant donné que nous utilisons un système basé sur git pour stocker les modèles et autres artefacts sur le Hugging Face Hub, il peut s’agir d’un nom de branche, d’un nom de tag ou d’un identifiant de commit.
- Hébergé localement. repo_id serait un répertoire contenant le fichier pickle et un pyproject.toml indiquant les versions de fastai et fastcore utilisées pour construire le fastai.Learner. Par exemple : ./my_model_directory/.
revision (str, facultatif) — Révision à laquelle les fichiers du dépôt sont téléchargés. Consultez la documentation de snapshot_download.

Charger un modèle fastai pré-entraîné depuis le Hub ou depuis un répertoire local.

huggingface_hub.push_to_hub_fastai

< source >

Paramètres

learner (Learner) — Le *fastai.Learner’ que vous souhaitez publier sur le Hub.
repo_id (str) — L’identifiant du dépôt de votre modèle sur Hub, au format « namespace/repo_name ». L’espace de noms peut être votre compte individuel ou une organisation pour laquelle vous disposez d’un accès en écriture (par exemple, ‘stanfordnlp/stanza-de’).
commit_message (str`, facultatif*) — Message à committer lors de la poussée. La valeur par défaut est "add model".
private (bool, facultatif) — Indique si le dépôt créé doit être privé. Si None (par défaut), le dépôt sera public par défaut, sauf si le paramètre par défaut de l’organisation est privé.
token (str, facultatif) — Le jeton du compte Hugging Face à utiliser comme autorisation bearer HTTP pour les fichiers distants. Si None, le jeton sera demandé par une invite.
config (dict, optional) — Configuration object to be saved alongside the model weights.
branch (str, facultatif) — La branche git sur laquelle pousser le modèle. Par défaut, il s’agit de la branche par défaut spécifiée dans votre dépôt, qui est “main” par défaut.
create_pr (boolean, facultatif) — Indique s'il faut ou non créer une Pull Request depuis branch avec cet engagement. La valeur par défaut est False.
api_endpoint (str, facultatif) — Le point de terminaison de l'API à utiliser lors de la publication du modèle sur le hub.
allow_patterns (list[str] ou str, facultatif) — Si fourni, seuls les fichiers correspondant à au moins un motif sont poussés.
ignore_patterns (list[str] ou str, facultatif) — Si fourni, les fichiers correspondant à l’un des motifs ne sont pas poussés.
delete_patterns (list[str] ou str, facultatif) — Si fourni, les fichiers distants correspondant à l’un des motifs seront supprimés du dépôt.

Téléverser les fichiers de point de contrôle de l'apprenant sur le Hub.

Utilisez allow_patterns et ignore_patterns pour filtrer précisément les fichiers à pousser sur le hub. Utilisez delete_patterns pour supprimer les fichiers distants existants dans le même commit. Consultez la référence de [upload_folder] pour plus de détails.

Lève l'erreur suivante :

ValueError si l'utilisateur n'est pas connecté au Hugging Face Hub.

Update on GitHub

Hub Python Library

Mixins & méthodes de sérialisation

Mixins

Générique

classe huggingface_hub.ModelHubMixin

_save_pretrained

_from_pretrained

from_pretrained

push_to_hub

save_pretrained

PyTorch

classe huggingface_hub.PyTorchModelHubMixin

Fastai

huggingface_hub.from_pretrained_fastai

huggingface_hub.push_to_hub_fastai