# 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](../guides/integrations) pour apprendre à intégrer n’importe quel framework ML avec le Hub.

### Générique[[huggingface_hub.ModelHubMixin]]

#### huggingface_hub.ModelHubMixin[[huggingface_hub.ModelHubMixin]]

```python
huggingface_hub.ModelHubMixin(*args, **kwargs)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L66)

**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ée 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. N'est utilisé que 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é pour générer la carte du modèle. N'est utilisé que si `license` est défini sur `other` et que `license_name` est défini. Ex. : "https://coqui.ai/cpml".

pipeline_tag (`str`, *facultatif*) : Balise 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](/docs/huggingface_hub/v2.4.0/fr/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) est un bon exemple d'intégration de mixin avec le Hub. Consultez notre [guide d'intégration](../guides/integrations) pour plus de détails.

Lorsque vous héritez de [ModelHubMixin](/docs/huggingface_hub/v2.4.0/fr/package_reference/mixins#huggingface_hub.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](/docs/huggingface_hub/v2.4.0/fr/package_reference/mixins#huggingface_hub.ModelHubMixin).

Pour plus de détails sur l'intégration du mixin avec votre bibliothèque, consultez le [guide d'intégration](../guides/integrations).

Exemple :

```python
>>> 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[[huggingface_hub.ModelHubMixin._save_pretrained]]

```python
_save_pretrained(save_directory: Path)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L440)

**Paramètres :**

save_directory (`str` ou `Path`) : Chemin vers le 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](../guides/integrations) pour obtenir des instructions.

#### _from_pretrained[[huggingface_hub.ModelHubMixin._from_pretrained]]

```python
_from_pretrained(model_id: str, revision: str | None, cache_dir: str | pathlib.Path | None, force_download: bool, local_files_only: bool, token: str | bool | None, **model_kwargs)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L567)

**Paramètres :**

model_id (`str`) : ID du modèle à charger depuis le Huggingface Hub (par exemple `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 commit 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*) : 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 de mot-clé supplémentaires transmis à la méthode [_from_pretrained()](/docs/huggingface_hub/v2.4.0/fr/package_reference/mixins#huggingface_hub.ModelHubMixin._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()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.hf_hub_download) ou [snapshot_download()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.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](../guides/integrations) pour plus de détails.

#### from_pretrained[[huggingface_hub.ModelHubMixin.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | pathlib.Path, force_download: bool = False, token: str | bool | None = None, cache_dir: str | pathlib.Path | None = None, local_files_only: bool = False, revision: str | None = None, **model_kwargs)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L451)

**Paramètres :**

pretrained_model_name_or_path (`str`, `Path`) : - Either the `model_id` (string) of a model hosted on the Hub, e.g. `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 commit 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*) : 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*) : Arguments 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[[huggingface_hub.ModelHubMixin.push_to_hub]]

```python
push_to_hub(repo_id: str, config: dict | huggingface_hub.hub_mixin.DataclassInstance | None = None, commit_message: str = 'Push model using huggingface_hub.', private: bool | None = None, token: str | None = None, branch: str | None = None, create_pr: bool | None = None, allow_patterns: list[str] | str | None = None, ignore_patterns: list[str] | str | None = None, delete_patterns: list[str] | str | None = None, model_card_kwargs: dict[str, typing.Any] | None = None)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L609)

**Paramètres :**

repo_id (`str`) : identifiant 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 à commiter 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*) : 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. Par défaut, c'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 de modèle pour personnaliser la carte de modèle.

**Retourne :**

L'URL de l'engagement de votre modèle dans le dépôt indiqué.

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()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) pour plus de détails.

#### save_pretrained[[huggingface_hub.ModelHubMixin.save_pretrained]]

```python
save_pretrained(save_directory: str | pathlib.Path, config: dict | huggingface_hub.hub_mixin.DataclassInstance | None = None, repo_id: str | None = None, push_to_hub: bool = False, model_card_kwargs: dict[str, typing.Any] | None = None, **push_to_hub_kwargs)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L372)

**Paramètres :**

save_directory (`str` ou `Path`) : Chemin vers le 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, le nom du dossier est utilisé si aucune valeur n'est fournie.

model_card_kwargs (`dict[str, Any]`, *facultatif*) : Arguments supplémentaires transmis au modèle de carte de modèle pour personnaliser la carte de modèle.

push_to_hub_kwargs : Arguments de mots-clés supplémentaires transmis à la méthode [push_to_hub()](/docs/huggingface_hub/v2.4.0/fr/package_reference/mixins#huggingface_hub.ModelHubMixin.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[[huggingface_hub.PyTorchModelHubMixin]]

#### huggingface_hub.PyTorchModelHubMixin[[huggingface_hub.PyTorchModelHubMixin]]

```python
huggingface_hub.PyTorchModelHubMixin(*args, **kwargs)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/hub_mixin.py#L692)

Implémentation de [ModelHubMixin](/docs/huggingface_hub/v2.4.0/fr/package_reference/mixins#huggingface_hub.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](/docs/huggingface_hub/v2.4.0/fr/package_reference/mixins#huggingface_hub.ModelHubMixin) pour plus de détails sur l'utilisation du mixin.

Exemple :

```python
>>> 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]]

#### huggingface_hub.from_pretrained_fastai[[huggingface_hub.from_pretrained_fastai]]

```python
huggingface_hub.from_pretrained_fastai(repo_id: str, revision: str | None = None)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/fastai_utils.py#L289)

**Paramètres :**

repo_id (`str`) : L’emplacement du `fastai.Learner` sérialisé. Il peut être l’un des deux : - Hébergé sur le Hugging Face Hub. Par exemple : 'espejelomar/fatai-pet-breeds-classification' ou 'distilgpt2'. Vous pouvez ajouter une `revision` en ajoutant `@` à la fin de `repo_id`. Par exemple : `dbmdz/bert-base-german-cased@main`. La révision est la version spécifique du modèle à utiliser. Comme 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`.

**Retourne :**

Le modèle `fastai.Learner` du dépôt `repo_id`.

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

#### huggingface_hub.push_to_hub_fastai[[huggingface_hub.push_to_hub_fastai]]

```python
huggingface_hub.push_to_hub_fastai(learner, repo_id: str, commit_message: str = 'Push FastAI model using huggingface_hub.', private: bool | None = None, token: str | None = None, config: dict | None = None, branch: str | None = None, create_pr: bool | None = None, allow_patterns: list[str] | str | None = None, ignore_patterns: list[str] | str | None = None, delete_patterns: list[str] | str | None = None, api_endpoint: str | None = None)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/fastai_utils.py#L334)

**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 le 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`, *optional*) : Message to commit while pushing. Will default to `"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*) : 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*, *facultatif*) : Objet de configuration à enregistrer avec les poids du modèle.

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*) : L'endpoint 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.

**Retourne :**

L'URL de l'engagement de votre modèle dans le dépôt indiqué.

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.

> [!TIP]
> Lève l'erreur suivante :
>
> - [*ValueError*](https://docs.python.org/3/library/exceptions.html#ValueError) si l'utilisateur n'est pas connecté au Hugging Face Hub.