Mixin 和序列化方法

Mixin

huggingface_hub 库提供了一系列 mixin，可以用作您对象的父类，以提供简单的上传和下载功能。查看我们的集成指南了解如何将任何 ML 框架与 Hub 集成。

通用

class huggingface_hub.ModelHubMixin

< 源代码 >

( *args **kwargs )

参数

repo_url (str, 可选) — 库存储库的 URL。用于生成模型卡。
paper_url (str, 可选) — 库论文的 URL。用于生成模型卡。
docs_url (str, 可选) — 库文档的 URL。用于生成模型卡。
model_card_template (str, 可选) — 模型卡的模板。用于生成模型卡。默认为通用模板。
language (str 或 list[str], 可选) — 库支持的语言。用于生成模型卡。
library_name (str, 可选) — 集成了 ModelHubMixin 的库的名称。用于生成模型卡。
license (str, 可选) — 集成了 ModelHubMixin 的库的许可证。用于生成模型卡。例如：“apache-2.0”
license_name (str, 可选) — 集成了 ModelHubMixin 的库的许可证名称。仅当 license 设置为 other 时使用。例如：“coqui-public-model-license”。
license_link (str, 可选) — 集成了 ModelHubMixin 的库的许可证 URL。仅当 license 设置为 other 且 license_name 设置时使用。例如：“https://coqui.ai/cpml”。
pipeline_tag (str, 可选) — pipeline 标签。用于生成模型卡。例如：“text-classification”。
tags (list[str], 可选) — 要添加到模型卡的标签。用于生成模型卡。例如 [“computer-vision”]
coders (dict[Type, tuple[Callable, Callable]], 可选) — 自定义类型及其编码器/解码器的字典。用于编码/解码默认情况下不可 JSON 化的参数。例如：数据类、argparse.Namespace、OmegaConf 等。

一个通用的 mixin，用于将任何机器学习框架与 Hub 集成。

要集成您的框架，您的模型类必须继承自此类。保存/加载模型的自定义逻辑必须在 _from_pretrained 和 _save_pretrained 中重写。 PyTorchModelHubMixin 是与 Hub 集成的 mixin 的一个很好的例子。请查看我们的集成指南以获取更多说明。

当继承自 ModelHubMixin 时，您可以定义类级别属性。这些属性不会传递给 __init__，而是传递给类定义本身。这对于定义集成 ModelHubMixin 的库的元数据很有用。

有关如何将 mixin 集成到您的库中的更多详细信息，请查看集成指南。

示例

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

< 源代码 >

( save_directory: Path )

参数

save_directory (str 或 Path) — 模型权重和配置将要保存到的目录路径。

在子类中重写此方法以定义如何保存模型。请查看我们的集成指南以获取说明。

_from_pretrained

< 源代码 >

( model_id: str revision: typing.Optional[str] cache_dir: typing.Union[str, pathlib.Path, NoneType] force_download: bool local_files_only: bool token: typing.Union[str, bool, NoneType] **model_kwargs )

参数

model_id (str) — 要从 Huggingface Hub 加载的模型 ID（例如 bigscience/bloom）。
revision (str, 可选) — Hub 上模型的 revision。可以是分支名称、git 标签或任何 commit id。默认为 main 分支上的最新 commit。
force_download (bool, optional, 默认为 False) — 是否强制（重新）从 Hub 下载模型权重和配置文件，覆盖现有缓存。
token (str 或 bool, optional) — 用于远程文件进行 HTTP bearer 身份验证的 token。默认情况下，它将使用运行 hf auth login 时缓存的 token。
cache_dir (str, Path, optional) — 缓存文件的存储目录路径。
local_files_only (bool, optional, 默认为 False) — 如果为 True，则避免下载文件，并返回本地缓存文件的路径（如果存在）。
model_kwargs — 传递给 _from_pretrained() 方法的额外关键字参数。

在子类中重写此方法以定义如何从预训练模型加载您的模型。

使用 hf_hub_download() 或 snapshot_download() 在加载模型之前从 Hub 下载文件。输入的多数参数可以直接传递给这两个方法。如果需要，您可以使用“model_kwargs”向此方法添加更多参数。例如，PyTorchModelHubMixin._from_pretrained() 接受一个 map_location 参数，用于设置模型应加载到的设备。

有关更多说明，请查看我们的集成指南。

from_pretrained

< source >

( pretrained_model_name_or_path: typing.Union[str, pathlib.Path] force_download: bool = False token: typing.Union[str, bool, NoneType] = None cache_dir: typing.Union[str, pathlib.Path, NoneType] = None local_files_only: bool = False revision: typing.Optional[str] = None **model_kwargs )

参数

pretrained_model_name_or_path (str, Path) —
- 模型的 model_id（字符串），例如 bigscience/bloom。
- 或模型权重保存目录的路径，使用 save_pretrained 保存，例如 ../path/to/my_model_directory/。
revision (str, optional) — Hub 上的模型版本。可以是分支名称、git 标签或任何 commit id。默认为 main 分支上的最新 commit。
force_download (bool, optional, 默认为 False) — 是否强制（重新）从 Hub 下载模型权重和配置文件，覆盖现有缓存。
token (str 或 bool, optional) — 用于远程文件进行 HTTP bearer 身份验证的 token。默认情况下，它将使用运行 hf auth login 时缓存的 token。
cache_dir (str, Path, optional) — 缓存文件的存储目录路径。
local_files_only (bool, optional, 默认为 False) — 如果为 True，则避免下载文件，并返回本地缓存文件的路径（如果存在）。
model_kwargs (dict, optional) — 在初始化模型时传递的附加 kwargs。

从 Huggingface Hub 下载模型并实例化。

push_to_hub

< source >

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

参数

repo_id (str) — 要推送到的仓库 ID（例如："username/my-model"）。
config (dict 或 DataclassInstance, optional) — 以键值字典或 dataclass 实例形式指定的模型配置。
commit_message (str, optional) — 推送时的提交消息。
private (bool, optional) — 创建的仓库是否应为私有。如果为 None（默认），则仓库将为公共的，除非该组织的默认设置为私有。
token (str, optional) — 用于远程文件进行 HTTP bearer 身份验证的 token。默认情况下，它将使用运行 hf auth login 时缓存的 token。
branch (str, optional) — 要推送模型所在的 git 分支。默认为 "main"。
create_pr (boolean, optional) — 是否在此提交中从 branch 创建一个 Pull Request。默认为 False。
allow_patterns (list[str] 或 str, optional) — 如果提供，则仅推送匹配至少一个模式的文件。
ignore_patterns (list[str] 或 str, optional) — 如果提供，则不推送匹配任何模式的文件。
delete_patterns (list[str] 或 str, optional) — 如果提供，则将从仓库中删除匹配任何模式的远程文件。
model_card_kwargs (dict[str, Any], optional) — 用于自定义模型卡的其他参数，将传递给模型卡模板。

将模型检查点上传到 Hub。

使用 allow_patterns 和 ignore_patterns 精确过滤要推送到 hub 的文件。使用 delete_patterns 删除同一提交中已有的远程文件。有关更多详细信息，请参阅 upload_folder() 参考。

save_pretrained

< source >

( save_directory: typing.Union[str, pathlib.Path] config: typing.Union[dict, huggingface_hub.hub_mixin.DataclassInstance, NoneType] = None repo_id: typing.Optional[str] = None push_to_hub: bool = False model_card_kwargs: typing.Optional[dict[str, typing.Any]] = None **push_to_hub_kwargs ) → str 或 None

参数

save_directory (str or Path) — 要保存模型权重和配置的目录路径。
config (dict or DataclassInstance, optional) — 以键值对字典或数据类实例形式指定的模型配置。
push_to_hub (bool, optional, defaults to False) — 是否在保存模型后将其推送到 Huggingface Hub。
repo_id (str, optional) — Hub 上您的存储库 ID。仅当 push_to_hub=True 时使用。如果未提供，则默认为文件夹名称。
model_card_kwargs (dict[str, Any], optional) — 用于自定义模型卡的其他参数，将传递给模型卡模板。
传递给 push_to_hub() 方法的其他关键字参数。

str 或 None

如果 push_to_hub=True，则为 Hub 上的提交 URL，否则为 None。

将权重保存在本地目录中。

PyTorch

class huggingface_hub.PyTorchModelHubMixin

< source >

( *args **kwargs )

实现了 ModelHubMixin，为 PyTorch 模型提供模型 Hub 上传/下载功能。模型默认处于评估模式，使用 model.eval()（dropout 模块被禁用）。要训练模型，您应该先使用 model.train() 将其设置回训练模式。

有关如何使用此 mixin 的更多详细信息，请参阅 ModelHubMixin。

示例

>>> 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.org.cn/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: str revision: typing.Optional[str] = None )

参数

repo_id (str) — pickled fastai.Learner 的位置。可以是以下两者之一：
- 托管在 Hugging Face Hub 上。例如：“espejelomar/fatai-pet-breeds-classification” 或 “distilgpt2”。您可以通过在 repo_id 末尾添加 @ 来添加 revision。例如：dbmdz/bert-base-german-cased@main。Revision 是要使用的特定模型版本。由于我们使用基于 git 的系统来存储 Hugging Face Hub 上的模型和其他工件，因此它可以是分支名称、标签名称或提交 ID。
- 本地托管。repo_id 将是一个包含 pickle 文件和 pyproject.toml 的目录，该文件指示用于构建 fastai.Learner 的 fastai 和 fastcore 版本。例如：./my_model_directory/。
revision (str, optional) — 下载存储库文件时使用的修订版本。请参阅 snapshot_download 的文档。

从 Hub 或本地目录加载预训练的 fastai 模型。

huggingface_hub.push_to_hub_fastai

< source >

( learner repo_id: str commit_message: str = 'Push FastAI model using huggingface_hub.' private: typing.Optional[bool] = None token: typing.Optional[str] = None config: typing.Optional[dict] = None branch: typing.Optional[str] = None create_pr: typing.Optional[bool] = None allow_patterns: typing.Union[list[str], str, NoneType] = None ignore_patterns: typing.Union[list[str], str, NoneType] = None delete_patterns: typing.Union[list[str], str, NoneType] = None api_endpoint: typing.Optional[str] = None )

参数

learner (Learner) — 您要推送到 Hub 的 fastai.Learner。
repo_id (str) — Hub 上您模型的存储库 ID，格式为“namespace/repo_name”。namespace 可以是您的个人账户或您拥有写入权限的组织（例如，“stanfordnlp/stanza-de”）。
commit_message (str, optional) — 推送时要提交的消息。默认为 "add model"。
private (bool, optional) — 是否应将创建的存储库设为私有。如果为 None（默认），则默认为公开，除非该组织的默认设置是私有的。
token (str, optional) — 用于远程文件的 HTTP bearer 授权的 Hugging Face 账户 token。如果为 None，则将通过提示要求输入 token。
config (dict, optional) — 要与模型权重一起保存的配置对象。
branch (str, optional) — 用于推送模型的 git 分支。默认为存储库中指定的默认分支，默认为 “main”。
create_pr (boolean, optional) — 是否从 branch 创建带有该提交的 Pull Request。默认为 False。
api_endpoint (str, optional) — 推送模型到 Hub 时使用的 API 端点。
allow_patterns (list[str] 或 str, optional) — 如果提供，则仅推送匹配至少一个模式的文件。
ignore_patterns (list[str] 或 str, optional) — 如果提供，则不会推送匹配任何模式的文件。
delete_patterns (list[str] 或 str, optional) — 如果提供，将从仓库中删除与任何模式匹配的远程文件。

将 learner 的检查点文件上传到 Hub。

使用 allow_patterns 和 ignore_patterns 精确过滤要推送到 Hub 的文件。使用 delete_patterns 在同一个提交中删除现有的远程文件。有关更多详细信息，请参阅 [upload_folder] 参考。

引发以下错误

ValueError 如果用户未登录 Hugging Face Hub。

在 GitHub 上更新

Hub Python 库

Mixin 和序列化方法

Mixin

通用

class huggingface_hub.ModelHubMixin

_save_pretrained

_from_pretrained

from_pretrained

push_to_hub

save_pretrained

PyTorch

class huggingface_hub.PyTorchModelHubMixin

Fastai

huggingface_hub.from_pretrained_fastai

huggingface_hub.push_to_hub_fastai