> For the complete documentation index, see [llms.txt](https://boinc-ai.gitbook.io/hub-python-library/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boinc-ai.gitbook.io/hub-python-library/reference/mixins-and-serialization-methods.md).

# Mixins & serialization methods

## Mixins & serialization methods

### Mixins

The `huggingface_hub` library offers a range of mixins that can be used as a parent class for your objects, in order to provide simple uploading and downloading functions. Check out our [integration guide](https://huggingface.co/docs/huggingface_hub/guides/integrations) to learn how to integrate any ML framework with the Hub.

#### Generic

#### class huggingface\_hub.ModelHubMixin

[\<source>](https://github.com/huggingface/huggingface_hub/blob/v0.18.0.rc0/src/huggingface_hub/hub_mixin.py#L23)

( )

A generic mixin to integrate ANY machine learning framework with the Hub.

To integrate your framework, your model class must inherit from this class. Custom logic for saving/loading models have to be overwritten in `_from_pretrained` and `_save_pretrained`. [PyTorchModelHubMixin](https://huggingface.co/docs/huggingface_hub/v0.18.0.rc0/en/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) is a good example of mixin integration with the Hub. Check out our [integration guide](https://huggingface.co/docs/huggingface_hub/guides/integrations) for more instructions.

**\_save\_pretrained**

[\<source>](https://github.com/huggingface/huggingface_hub/blob/v0.18.0.rc0/src/huggingface_hub/hub_mixin.py#L76)

( save\_directory: Path )

Parameters

* **save\_directory** (`str` or `Path`) — Path to directory in which the model weights and configuration will be saved.

Overwrite this method in subclass to define how to save your model. Check out our [integration guide](https://huggingface.co/docs/huggingface_hub/guides/integrations) for instructions.

**\_from\_pretrained**

[\<source>](https://github.com/huggingface/huggingface_hub/blob/v0.18.0.rc0/src/huggingface_hub/hub_mixin.py#L171)

( model\_id: strrevision: typing.Optional\[str]cache\_dir: typing.Union\[str, pathlib.Path, NoneType]force\_download: boolproxies: typing.Optional\[typing.Dict]resume\_download: boollocal\_files\_only: booltoken: typing.Union\[str, bool, NoneType]\*\*model\_kwargs )

Parameters

* **model\_id** (`str`) — ID of the model to load from the Huggingface Hub (e.g. `bigscience/bloom`).
* **revision** (`str`, *optional*) — Revision of the model on the Hub. Can be a branch name, a git tag or any commit id. Defaults to the latest commit on `main` branch.
* **force\_download** (`bool`, *optional*, defaults to `False`) — Whether to force (re-)downloading the model weights and configuration files from the Hub, overriding the existing cache.
* **resume\_download** (`bool`, *optional*, defaults to `False`) — Whether to delete incompletely received files. Will attempt to resume the download if such a file exists.
* **proxies** (`Dict[str, str]`, *optional*) — A dictionary of proxy servers to use by protocol or endpoint (e.g., `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`).
* **token** (`str` or `bool`, *optional*) — The token to use as HTTP bearer authorization for remote files. By default, it will use the token cached when running `huggingface-cli login`.
* **cache\_dir** (`str`, `Path`, *optional*) — Path to the folder where cached files are stored.
* **local\_files\_only** (`bool`, *optional*, defaults to `False`) — If `True`, avoid downloading the file and return the path to the local cached file if it exists. model\_kwargs — Additional keyword arguments passed along to the [\_from\_pretrained()](https://huggingface.co/docs/huggingface_hub/v0.18.0.rc0/en/package_reference/mixins#huggingface_hub.ModelHubMixin._from_pretrained) method.

Overwrite this method in subclass to define how to load your model from pretrained.

Use [hf\_hub\_download()](https://huggingface.co/docs/huggingface_hub/v0.18.0.rc0/en/package_reference/file_download#huggingface_hub.hf_hub_download) or [snapshot\_download()](https://huggingface.co/docs/huggingface_hub/v0.18.0.rc0/en/package_reference/file_download#huggingface_hub.snapshot_download) to download files from the Hub before loading them. Most args taken as input can be directly passed to those 2 methods. If needed, you can add more arguments to this method using “model\_kwargs”. For example `PyTorchModelHubMixin._from_pretrained()` takes as input a `map_location` parameter to set on which device the model should be loaded.

Check out our [integration guide](https://huggingface.co/docs/huggingface_hub/guides/integrations) for more instructions.

**from\_pretrained**

[\<source>](https://github.com/huggingface/huggingface_hub/blob/v0.18.0.rc0/src/huggingface_hub/hub_mixin.py#L87)

( pretrained\_model\_name\_or\_path: typing.Union\[str, pathlib.Path]force\_download: bool = Falseresume\_download: bool = Falseproxies: typing.Optional\[typing.Dict] = Nonetoken: typing.Union\[str, bool, NoneType] = Nonecache\_dir: typing.Union\[str, pathlib.Path, NoneType] = Nonelocal\_files\_only: bool = Falserevision: typing.Optional\[str] = None\*\*model\_kwargs )

Parameters

* **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](https://huggingface.co/docs/transformers/v4.34.0/en/main_classes/model#transformers.PreTrainedModel.save_pretrained), e.g., `../path/to/my_model_directory/`.
* **revision** (`str`, *optional*) — Revision of the model on the Hub. Can be a branch name, a git tag or any commit id. Defaults to the latest commit on `main` branch.
* **force\_download** (`bool`, *optional*, defaults to `False`) — Whether to force (re-)downloading the model weights and configuration files from the Hub, overriding the existing cache.
* **resume\_download** (`bool`, *optional*, defaults to `False`) — Whether to delete incompletely received files. Will attempt to resume the download if such a file exists.
* **proxies** (`Dict[str, str]`, *optional*) — A dictionary of proxy servers to use by protocol or endpoint, e.g., `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. The proxies are used on every request.
* **token** (`str` or `bool`, *optional*) — The token to use as HTTP bearer authorization for remote files. By default, it will use the token cached when running `huggingface-cli login`.
* **cache\_dir** (`str`, `Path`, *optional*) — Path to the folder where cached files are stored.
* **local\_files\_only** (`bool`, *optional*, defaults to `False`) — If `True`, avoid downloading the file and return the path to the local cached file if it exists.
* **model\_kwargs** (`Dict`, *optional*) — Additional kwargs to pass to the model during initialization.

Download a model from the Huggingface Hub and instantiate it.

**push\_to\_hub**

[\<source>](https://github.com/huggingface/huggingface_hub/blob/v0.18.0.rc0/src/huggingface_hub/hub_mixin.py#L220)

( repo\_id: strconfig: typing.Optional\[dict] = Nonecommit\_message: str = 'Push model using huggingface\_hub.'private: bool = Falseapi\_endpoint: typing.Optional\[str] = Nonetoken: typing.Optional\[str] = Nonebranch: typing.Optional\[str] = Nonecreate\_pr: typing.Optional\[bool] = Noneallow\_patterns: typing.Union\[typing.List\[str], str, NoneType] = Noneignore\_patterns: typing.Union\[typing.List\[str], str, NoneType] = Nonedelete\_patterns: typing.Union\[typing.List\[str], str, NoneType] = None )

Parameters

* **repo\_id** (`str`) — ID of the repository to push to (example: `"username/my-model"`).
* **config** (`dict`, *optional*) — Configuration object to be saved alongside the model weights.
* **commit\_message** (`str`, *optional*) — Message to commit while pushing.
* **private** (`bool`, *optional*, defaults to `False`) — Whether the repository created should be private.
* **api\_endpoint** (`str`, *optional*) — The API endpoint to use when pushing the model to the hub.
* **token** (`str`, *optional*) — The token to use as HTTP bearer authorization for remote files. By default, it will use the token cached when running `huggingface-cli login`.
* **branch** (`str`, *optional*) — The git branch on which to push the model. This defaults to `"main"`.
* **create\_pr** (`boolean`, *optional*) — Whether or not to create a Pull Request from `branch` with that commit. Defaults to `False`.
* **allow\_patterns** (`List[str]` or `str`, *optional*) — If provided, only files matching at least one pattern are pushed.
* **ignore\_patterns** (`List[str]` or `str`, *optional*) — If provided, files matching any of the patterns are not pushed.
* **delete\_patterns** (`List[str]` or `str`, *optional*) — If provided, remote files matching any of the patterns will be deleted from the repo.

Upload model checkpoint to the Hub.

Use `allow_patterns` and `ignore_patterns` to precisely filter which files should be pushed to the hub. Use `delete_patterns` to delete existing remote files in the same commit. See [upload\_folder()](https://huggingface.co/docs/huggingface_hub/v0.18.0.rc0/en/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) reference for more details.

**save\_pretrained**

[\<source>](https://github.com/huggingface/huggingface_hub/blob/v0.18.0.rc0/src/huggingface_hub/hub_mixin.py#L32)

( save\_directory: typing.Union\[str, pathlib.Path]config: typing.Optional\[dict] = Nonerepo\_id: typing.Optional\[str] = Nonepush\_to\_hub: bool = False\*\*kwargs )

Parameters

* **save\_directory** (`str` or `Path`) — Path to directory in which the model weights and configuration will be saved.
* **config** (`dict`, *optional*) — Model configuration specified as a key/value dictionary.
* **push\_to\_hub** (`bool`, *optional*, defaults to `False`) — Whether or not to push your model to the Huggingface Hub after saving it.
* **repo\_id** (`str`, *optional*) — ID of your repository on the Hub. Used only if `push_to_hub=True`. Will default to the folder name if not provided. kwargs — Additional key word arguments passed along to the [\_from\_pretrained()](https://huggingface.co/docs/huggingface_hub/v0.18.0.rc0/en/package_reference/mixins#huggingface_hub.ModelHubMixin._from_pretrained) method.

Save weights in local directory.

#### PyTorch

#### class huggingface\_hub.PyTorchModelHubMixin

[\<source>](https://github.com/huggingface/huggingface_hub/blob/v0.18.0.rc0/src/huggingface_hub/hub_mixin.py#L292)

( )

Implementation of [ModelHubMixin](https://huggingface.co/docs/huggingface_hub/v0.18.0.rc0/en/package_reference/mixins#huggingface_hub.ModelHubMixin) to provide model Hub upload/download capabilities to PyTorch models. The model is set in evaluation mode by default using `model.eval()` (dropout modules are deactivated). To train the model, you should first set it back in training mode with `model.train()`.

Example:

Copied

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


>>> class MyModel(nn.Module, PyTorchModelHubMixin):
...     def __init__(self):
...         super().__init__()
...         self.param = nn.Parameter(torch.rand(3, 4))
...         self.linear = nn.Linear(4, 5)

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

# 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")
```

#### Keras

#### class huggingface\_hub.KerasModelHubMixin

[\<source>](https://github.com/huggingface/huggingface_hub/blob/v0.18.0.rc0/src/huggingface_hub/keras_mixin.py#L398)

( )

Implementation of [ModelHubMixin](https://huggingface.co/docs/huggingface_hub/v0.18.0.rc0/en/package_reference/mixins#huggingface_hub.ModelHubMixin) to provide model Hub upload/download capabilities to Keras models.

Copied

```
>>> import tensorflow as tf
>>> from huggingface_hub import KerasModelHubMixin


>>> class MyModel(tf.keras.Model, KerasModelHubMixin):
...     def __init__(self, **kwargs):
...         super().__init__()
...         self.config = kwargs.pop("config", None)
...         self.dummy_inputs = ...
...         self.layer = ...

...     def call(self, *args):
...         return ...


>>> # Initialize and compile the model as you normally would
>>> model = MyModel()
>>> model.compile(...)
>>> # Build the graph by training it or passing dummy inputs
>>> _ = model(model.dummy_inputs)
>>> # 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/super-cool-model")
```

**huggingface\_hub.from\_pretrained\_keras**

[\<source>](https://github.com/huggingface/huggingface_hub/blob/v0.18.0.rc0/src/huggingface_hub/keras_mixin.py#L217)

( \*args\*\*kwargs )

Parameters

* **pretrained\_model\_name\_or\_path** (`str` or `os.PathLike`) — Can be either:
  * A string, the `model id` of a pretrained model hosted inside a model repo on huggingface.co. Valid model ids can be located at the root-level, like `bert-base-uncased`, or namespaced under a user or organization name, like `dbmdz/bert-base-german-cased`.
  * You can add `revision` by appending `@` at the end of model\_id simply like this: `dbmdz/bert-base-german-cased@main` Revision is the specific model version to use. It can be a branch name, a tag name, or a commit id, since we use a git-based system for storing models and other artifacts on huggingface.co, so `revision` can be any identifier allowed by git.
  * A path to a `directory` containing model weights saved using [save\_pretrained](https://huggingface.co/docs/transformers/v4.34.0/en/main_classes/model#transformers.PreTrainedModel.save_pretrained), e.g., `./my_model_directory/`.
  * `None` if you are both providing the configuration and state dictionary (resp. with keyword arguments `config` and `state_dict`).
* **force\_download** (`bool`, *optional*, defaults to `False`) — Whether to force the (re-)download of the model weights and configuration files, overriding the cached versions if they exist.
* **resume\_download** (`bool`, *optional*, defaults to `False`) — Whether to delete incompletely received files. Will attempt to resume the download if such a file exists.
* **proxies** (`Dict[str, str]`, *optional*) — A dictionary of proxy servers to use by protocol or endpoint, e.g., `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. The proxies are used on each request.
* **token** (`str` or `bool`, *optional*) — The token to use as HTTP bearer authorization for remote files. If `True`, will use the token generated when running `transformers-cli login` (stored in `~/.huggingface`).
* **cache\_dir** (`Union[str, os.PathLike]`, *optional*) — Path to a directory in which a downloaded pretrained model configuration should be cached if the standard cache should not be used.
* **local\_files\_only(`bool`,** *optional*, defaults to `False`) — Whether to only look at local files (i.e., do not try to download the model).
* **model\_kwargs** (`Dict`, *optional*) — model\_kwargs will be passed to the model during initialization

Instantiate a pretrained Keras model from a pre-trained model from the Hub. The model is expected to be in `SavedModel` format.

Passing `token=True` is required when you want to use a private model.

**huggingface\_hub.push\_to\_hub\_keras**

[\<source>](https://github.com/huggingface/huggingface_hub/blob/v0.18.0.rc0/src/huggingface_hub/keras_mixin.py#L276)

( modelrepo\_id: strconfig: typing.Optional\[dict] = Nonecommit\_message: str = 'Push Keras model using huggingface\_hub.'private: bool = Falseapi\_endpoint: typing.Optional\[str] = Nonetoken: typing.Optional\[str] = Nonebranch: typing.Optional\[str] = Nonecreate\_pr: typing.Optional\[bool] = Noneallow\_patterns: typing.Union\[typing.List\[str], str, NoneType] = Noneignore\_patterns: typing.Union\[typing.List\[str], str, NoneType] = Nonedelete\_patterns: typing.Union\[typing.List\[str], str, NoneType] = Nonelog\_dir: typing.Optional\[str] = Noneinclude\_optimizer: bool = Falsetags: typing.Union\[list, str, NoneType] = Noneplot\_model: bool = True\*\*model\_save\_kwargs )

Parameters

* **model** (`Keras.Model`) — The [Keras model](https://huggingface.co/docs/huggingface_hub/package_reference/%60https://www.tensorflow.org/api_docs/python/tf/keras/Model%60) you’d like to push to the Hub. The model must be compiled and built.
* **repo\_id** (`str`) — ID of the repository to push to (example: `"username/my-model"`).
* **commit\_message** (`str`, *optional*, defaults to “Add Keras model”) — Message to commit while pushing.
* **private** (`bool`, *optional*, defaults to `False`) — Whether the repository created should be private.
* **api\_endpoint** (`str`, *optional*) — The API endpoint to use when pushing the model to the hub.
* **token** (`str`, *optional*) — The token to use as HTTP bearer authorization for remote files. If not set, will use the token set when logging in with `huggingface-cli login` (stored in `~/.huggingface`).
* **branch** (`str`, *optional*) — The git branch on which to push the model. This defaults to the default branch as specified in your repository, which defaults to `"main"`.
* **create\_pr** (`boolean`, *optional*) — Whether or not to create a Pull Request from `branch` with that commit. Defaults to `False`.
* **config** (`dict`, *optional*) — Configuration object to be saved alongside the model weights.
* **allow\_patterns** (`List[str]` or `str`, *optional*) — If provided, only files matching at least one pattern are pushed.
* **ignore\_patterns** (`List[str]` or `str`, *optional*) — If provided, files matching any of the patterns are not pushed.
* **delete\_patterns** (`List[str]` or `str`, *optional*) — If provided, remote files matching any of the patterns will be deleted from the repo.
* **log\_dir** (`str`, *optional*) — TensorBoard logging directory to be pushed. The Hub automatically hosts and displays a TensorBoard instance if log files are included in the repository.
* **include\_optimizer** (`bool`, *optional*, defaults to `False`) — Whether or not to include optimizer during serialization.
* **tags** (Union\[`list`, `str`], *optional*) — List of tags that are related to model or string of a single tag. See example tags [here](https://github.com/huggingface/hub-docs/blame/main/modelcard.md).
* **plot\_model** (`bool`, *optional*, defaults to `True`) — Setting this to `True` will plot the model and put it in the model card. Requires graphviz and pydot to be installed.
* **model\_save\_kwargs(`dict`,** *optional*) — model\_save\_kwargs will be passed to [`tf.keras.models.save_model()`](https://www.tensorflow.org/api_docs/python/tf/keras/models/save_model).

Upload model checkpoint to the Hub.

Use `allow_patterns` and `ignore_patterns` to precisely filter which files should be pushed to the hub. Use `delete_patterns` to delete existing remote files in the same commit. See [upload\_folder()](https://huggingface.co/docs/huggingface_hub/v0.18.0.rc0/en/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) reference for more details.

**huggingface\_hub.save\_pretrained\_keras**

[\<source>](https://github.com/huggingface/huggingface_hub/blob/v0.18.0.rc0/src/huggingface_hub/keras_mixin.py#L132)

( modelsave\_directory: typing.Union\[str, pathlib.Path]config: typing.Union\[typing.Dict\[str, typing.Any], NoneType] = Noneinclude\_optimizer: bool = Falseplot\_model: bool = Truetags: typing.Union\[list, str, NoneType] = None\*\*model\_save\_kwargs )

Parameters

* **model** (`Keras.Model`) — The [Keras model](https://www.tensorflow.org/api_docs/python/tf/keras/Model) you’d like to save. The model must be compiled and built.
* **save\_directory** (`str` or `Path`) — Specify directory in which you want to save the Keras model.
* **config** (`dict`, *optional*) — Configuration object to be saved alongside the model weights.
* **include\_optimizer(`bool`,** *optional*, defaults to `False`) — Whether or not to include optimizer in serialization.
* **plot\_model** (`bool`, *optional*, defaults to `True`) — Setting this to `True` will plot the model and put it in the model card. Requires graphviz and pydot to be installed.
* **tags** (Union\[`str`,`list`], *optional*) — List of tags that are related to model or string of a single tag. See example tags [here](https://github.com/huggingface/hub-docs/blame/main/modelcard.md).
* **model\_save\_kwargs(`dict`,** *optional*) — model\_save\_kwargs will be passed to [`tf.keras.models.save_model()`](https://www.tensorflow.org/api_docs/python/tf/keras/models/save_model).

Saves a Keras model to save\_directory in SavedModel format. Use this if you’re using the Functional or Sequential APIs.

#### Fastai

**huggingface\_hub.from\_pretrained\_fastai**

[\<source>](https://github.com/huggingface/huggingface_hub/blob/v0.18.0.rc0/src/huggingface_hub/fastai_utils.py#L298)

( repo\_id: strrevision: typing.Optional\[str] = None )

Parameters

* **repo\_id** (`str`) — The location where the pickled fastai.Learner is. It can be either of the two:
  * Hosted on the Hugging Face Hub. E.g.: ‘espejelomar/fatai-pet-breeds-classification’ or ‘distilgpt2’. You can add a `revision` by appending `@` at the end of `repo_id`. E.g.: `dbmdz/bert-base-german-cased@main`. Revision is the specific model version to use. Since we use a git-based system for storing models and other artifacts on the Hugging Face Hub, it can be a branch name, a tag name, or a commit id.
  * Hosted locally. `repo_id` would be a directory containing the pickle and a pyproject.toml indicating the fastai and fastcore versions used to build the `fastai.Learner`. E.g.: `./my_model_directory/`.
* **revision** (`str`, *optional*) — Revision at which the repo’s files are downloaded. See documentation of `snapshot_download`.

Load pretrained fastai model from the Hub or from a local directory.

**huggingface\_hub.push\_to\_hub\_fastai**

[\<source>](https://github.com/huggingface/huggingface_hub/blob/v0.18.0.rc0/src/huggingface_hub/fastai_utils.py#L343)

( learnerrepo\_id: strcommit\_message: str = 'Push FastAI model using huggingface\_hub.'private: bool = Falsetoken: typing.Optional\[str] = Noneconfig: typing.Optional\[dict] = Nonebranch: typing.Optional\[str] = Nonecreate\_pr: typing.Optional\[bool] = Noneallow\_patterns: typing.Union\[typing.List\[str], str, NoneType] = Noneignore\_patterns: typing.Union\[typing.List\[str], str, NoneType] = Nonedelete\_patterns: typing.Union\[typing.List\[str], str, NoneType] = Noneapi\_endpoint: typing.Optional\[str] = None )

Parameters

* **learner** (*Learner*) — The \*fastai.Learner’ you’d like to push to the Hub.
* **repo\_id** (*str*) — The repository id for your model in Hub in the format of “namespace/repo\_name”. The namespace can be your individual account or an organization to which you have write access (for example, ‘stanfordnlp/stanza-de’).
* **commit\_message** (*str\`,* optional\*) — Message to commit while pushing. Will default to `"add model"`.
* **private** (*bool*, *optional*, defaults to *False*) — Whether or not the repository created should be private.
* **token** (*str*, *optional*) — The Hugging Face account token to use as HTTP bearer authorization for remote files. If `None`, the token will be asked by a prompt.
* **config** (*dict*, *optional*) — Configuration object to be saved alongside the model weights.
* **branch** (*str*, *optional*) — The git branch on which to push the model. This defaults to the default branch as specified in your repository, which defaults to *“main”*.
* **create\_pr** (*boolean*, *optional*) — Whether or not to create a Pull Request from *branch* with that commit. Defaults to *False*.
* **api\_endpoint** (*str*, *optional*) — The API endpoint to use when pushing the model to the hub.
* **allow\_patterns** (*List\[str]* or *str*, *optional*) — If provided, only files matching at least one pattern are pushed.
* **ignore\_patterns** (*List\[str]* or *str*, *optional*) — If provided, files matching any of the patterns are not pushed.
* **delete\_patterns** (*List\[str]* or *str*, *optional*) — If provided, remote files matching any of the patterns will be deleted from the repo.

Upload learner checkpoint files to the Hub.

Use *allow\_patterns* and *ignore\_patterns* to precisely filter which files should be pushed to the hub. Use *delete\_patterns* to delete existing remote files in the same commit. See \[*upload\_folder*] reference for more details.

Raises the following error:

* [*ValueError*](https://docs.python.org/3/library/exceptions.html#ValueError) if the user is not log on to the Hugging Face Hub.