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 to learn how to integrate any ML framework with the Hub.

Generic

class huggingface_hub.ModelHubMixin

< source >

( *args **kwargs )

Parameters

repo_url (str, optional) — URL of the library repository. Used to generate model card.
docs_url (str, optional) — URL of the library documentation. Used to generate model card.
model_card_template (str, optional) — Template of the model card. Used to generate model card. Defaults to a generic template.
language (str or List[str], optional) — Language supported by the library. Used to generate model card.
library_name (str, optional) — Name of the library integrating ModelHubMixin. Used to generate model card.
license (str, optional) — License of the library integrating ModelHubMixin. Used to generate model card. E.g: “apache-2.0”
license_name (str, optional) — Name of the library integrating ModelHubMixin. Used to generate model card. Only used if license is set to other. E.g: “coqui-public-model-license”.
license_link (str, optional) — URL to the license of the library integrating ModelHubMixin. Used to generate model card. Only used if license is set to other and license_name is set. E.g: ”https://coqui.ai/cpml”.
pipeline_tag (str, optional) — Tag of the pipeline. Used to generate model card. E.g. “text-classification”.
tags (List[str], optional) — Tags to be added to the model card. Used to generate model card. E.g. [“x-custom-tag”, “arxiv:2304.12244”]
coders (Dict[Type, Tuple[Callable, Callable]], optional) — Dictionary of custom types and their encoders/decoders. Used to encode/decode arguments that are not jsonable by default. E.g dataclasses, argparse.Namespace, OmegaConf, etc.

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 is a good example of mixin integration with the Hub. Check out our integration guide for more instructions.

When inheriting from ModelHubMixin, you can define class-level attributes. These attributes are not passed to __init__ but to the class definition itself. This is useful to define metadata about the library integrating ModelHubMixin.

For more details on how to integrate the mixin with your library, checkout the integration guide.

Example:

>>> from huggingface_hub import ModelHubMixin

# Inherit from ModelHubMixin
>>> class MyCustomModel(
...         ModelHubMixin,
...         library_name="my-library",
...         tags=["x-custom-tag", "arxiv:2304.12244"],
...         repo_url="https://github.com/huggingface/my-cool-library",
...         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,
...         resume_download: Optional[bool] = None,
...         proxies: Optional[Dict] = None,
...         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 )

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 for instructions.

_from_pretrained

< source >

( model_id: str revision: Optional cache_dir: Union force_download: bool proxies: Optional resume_download: Optional local_files_only: bool token: Union **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.
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() method.

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

Use hf_hub_download() or 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 for more instructions.

from_pretrained

< source >

( pretrained_model_name_or_path: Union force_download: bool = False resume_download: Optional = None proxies: Optional = None token: Union = None cache_dir: Union = None local_files_only: bool = False revision: Optional = 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, 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.
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 >

( repo_id: str config: Union = None commit_message: str = 'Push model using huggingface_hub.' private: bool = False token: Optional = None branch: Optional = None create_pr: Optional = None allow_patterns: Union = None ignore_patterns: Union = None delete_patterns: Union = None model_card_kwargs: Optional = None )

Parameters

repo_id (str) — ID of the repository to push to (example: "username/my-model").
config (dict or DataclassInstance, optional) — Model configuration specified as a key/value dictionary or a dataclass instance.
commit_message (str, optional) — Message to commit while pushing.
private (bool, optional, defaults to False) — Whether the repository created should be private.
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.
model_card_kwargs (Dict[str, Any], optional) — Additional arguments passed to the model card template to customize the model card.

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() reference for more details.

save_pretrained

< source >

( save_directory: Union config: Union = None repo_id: Optional = None push_to_hub: bool = False model_card_kwargs: Optional = None **push_to_hub_kwargs ) → str or None

Parameters

save_directory (str or Path) — Path to directory in which the model weights and configuration will be saved.
config (dict or DataclassInstance, optional) — Model configuration specified as a key/value dictionary or a dataclass instance.
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.
model_card_kwargs (Dict[str, Any], optional) — Additional arguments passed to the model card template to customize the model card. push_to_hub_kwargs — Additional key word arguments passed along to the push_to_hub() method.

Returns

str or None

url of the commit on the Hub if push_to_hub=True, None otherwise.

Save weights in local directory.

PyTorch

class huggingface_hub.PyTorchModelHubMixin

< source >

( *args **kwargs )

Implementation of 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().

See ModelHubMixin for more details on how to use the mixin.

Example:

>>> 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",
...         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

Keras

class huggingface_hub.KerasModelHubMixin

< source >

( *args **kwargs )

Implementation of ModelHubMixin to provide model Hub upload/download capabilities to Keras models.

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

( *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, 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.
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 >

( model repo_id: str config: Optional = None commit_message: str = 'Push Keras model using huggingface_hub.' private: bool = False api_endpoint: Optional = None token: Optional = None branch: Optional = None create_pr: Optional = None allow_patterns: Union = None ignore_patterns: Union = None delete_patterns: Union = None log_dir: Optional = None include_optimizer: bool = False tags: Union = None plot_model: bool = True **model_save_kwargs )

Parameters

model (Keras.Model) — The Keras model 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.
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().

Upload model checkpoint to the Hub.

huggingface_hub.save_pretrained_keras

< source >

( model save_directory: Union config: Optional = None include_optimizer: bool = False plot_model: bool = True tags: Union = None **model_save_kwargs )

Parameters

model (Keras.Model) — The 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.
model_save_kwargs(dict, optional) — model_save_kwargs will be passed to 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 >

( repo_id: str revision: Optional = 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 >

( learner repo_id: str commit_message: str = 'Push FastAI model using huggingface_hub.' private: bool = False token: Optional = None config: Optional = None branch: Optional = None create_pr: Optional = None allow_patterns: Union = None ignore_patterns: Union = None delete_patterns: Union = None api_endpoint: Optional = 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 if the user is not log on to the Hugging Face Hub.

< > Update on GitHub

Hub Python Library

Mixins & serialization methods

Mixins

Generic

class huggingface_hub.ModelHubMixin

_save_pretrained

_from_pretrained

from_pretrained

push_to_hub

save_pretrained

PyTorch

class huggingface_hub.PyTorchModelHubMixin

Keras

class huggingface_hub.KerasModelHubMixin

huggingface_hub.from_pretrained_keras

huggingface_hub.push_to_hub_keras

huggingface_hub.save_pretrained_keras

Fastai

huggingface_hub.from_pretrained_fastai

huggingface_hub.push_to_hub_fastai