Hub 文档
上传模型
并获得增强的文档体验
开始使用
上传模型
要将模型上传到 Hub,您需要在 Hugging Face 创建一个帐户。Hub 上的模型是 基于 Git 的仓库,这为您提供了版本控制、分支、发现和共享功能、与数十个库的集成等等!您可以控制要上传到仓库的内容,其中可能包括检查点、配置和任何其他文件。
您可以将仓库与个人用户(例如 osanseviero/fashion_brands_patterns)或组织(例如 facebook/bart-large-xsum)关联。组织可以收集与公司、社区或库相关的模型!如果您选择组织,模型将显示在组织的页面上,并且组织的每个成员都将有能力为仓库做出贡献。您可以在此处创建一个新的组织。
注意: 模型不需要与 Transformers/Diffusers 库兼容即可获得下载指标。支持任何自定义模型。请阅读下文了解更多信息!
有几种方法可以上传模型,以便它们能够很好地集成到 Hub 中并获得下载指标,如下所述。
- 如果您的模型是为具有内置支持的库设计的,则可以使用该库提供的方法。使用
trust_remote_code=True
的自定义模型也可以利用这些方法。 - 如果您的模型是自定义 PyTorch 模型,则可以利用
PyTorchModelHubMixin
类,因为它允许将from_pretrained
、push_to_hub
添加到任何nn.Module
类,就像 Transformers、Diffusers 和 Timm 库中的模型一样。 - 除了以编程方式上传外,您始终可以使用Web 界面或git 命令行。
上传模型后,我们建议向您的仓库添加模型卡片,以记录您的模型并使其更易于发现。

使用 Web 界面
要创建一个全新的模型仓库,请访问 huggingface.co/new。然后按照以下步骤操作
- 在“文件和版本”选项卡中,选择“添加文件”,然后指定“上传文件”


- 从那里,从您的计算机中选择一个文件进行上传,并留下有用的提交消息,以便了解您正在上传的内容


之后,单击提交更改以将您的模型上传到 Hub!
检查文件和历史记录
您可以检查您的仓库以及所有最近添加的文件!


UI 允许您浏览模型文件和提交,并查看每次提交引入的差异


- 添加元数据
您可以向模型卡片添加元数据。您可以指定
- 此模型用于的任务类型,启用小部件和 Inference API。
- 使用的库 (
transformers
,spaCy
等) - 语言
- 数据集
- 指标
- 许可证
- 以及更多!
阅读有关模型标签的更多信息此处。
- 添加 TensorBoard 跟踪
任何包含 TensorBoard 跟踪(文件名包含 tfevents
)的仓库都标有 TensorBoard
标签。按照惯例,我们建议您将跟踪保存在 runs/
子文件夹下。“训练指标”选项卡使您可以轻松查看已记录变量(如损失或准确率)的图表。


如果安装了 tensorboard
,则使用 🤗 Transformers 训练的模型默认会生成 TensorBoard 跟踪。
从具有内置支持的库上传
首先检查您的模型是否来自具有内置支持以推送到/从 Hub 加载的库,例如 Transformers、Diffusers、Timm、Asteroid 等:https://huggingface.co/docs/hub/models-libraries。下面我们将展示对于像 Transformers 这样的库来说,这有多么容易
from transformers import BertConfig, BertModel
config = BertConfig()
model = BertModel(config)
model.push_to_hub("nielsr/my-awesome-bert-model")
# reload
model = BertModel.from_pretrained("nielsr/my-awesome-bert-model")
某些库(如 Transformers)支持从 Hub 加载代码。这是一种使您的模型与 Transformers 一起使用的方法,使用 trust_remote_code=True
标志。您可能需要考虑此选项,而不是完全集成的库。
使用 huggingface_hub 上传 PyTorch 模型
如果您的模型是(自定义)PyTorch 模型,您可以利用 class 中提供的 PyTorchModelHubMixin
huggingface_hub Python 库。它是一个最小的类,它为任何 nn.Module
添加了 from_pretrained
和 push_to_hub
功能,以及下载指标。
以下是如何使用它(假设您已运行 pip install huggingface_hub
)
import torch
import torch.nn as nn
from huggingface_hub import PyTorchModelHubMixin
class MyModel(
nn.Module,
PyTorchModelHubMixin,
# optionally, you can add metadata which gets pushed to the model card
repo_url="your-repo-url",
pipeline_tag="text-to-image",
license="mit",
):
def __init__(self, num_channels: int, hidden_size: int, num_classes: int):
super().__init__()
self.param = nn.Parameter(torch.rand(num_channels, hidden_size))
self.linear = nn.Linear(hidden_size, num_classes)
def forward(self, x):
return self.linear(x + self.param)
# create model
config = {"num_channels": 3, "hidden_size": 32, "num_classes": 10}
model = MyModel(**config)
# save locally
model.save_pretrained("my-awesome-model")
# push to the hub
model.push_to_hub("your-hf-username/my-awesome-model")
# reload
model = MyModel.from_pretrained("your-hf-username/my-awesome-model")
如您所见,唯一的要求是您的模型继承自 PyTorchModelHubMixin
。所有实例属性将自动序列化为 config.json
文件。请注意,init
方法只能接受 JSON 可序列化的参数。支持 Python 数据类。
这附带了自动下载指标,这意味着您将能够看到模型的下载次数,就像 Transformers、Diffusers 或 Timm 库中原生集成的模型一样。使用此 mixin 类,每个单独的检查点都存储在 Hub 上的单个仓库中,该仓库由 2 个文件组成
- 包含权重的
pytorch_model.bin
或model.safetensors
文件 config.json
文件,它是模型配置的序列化版本。此类用于计算下载指标:每次用户调用from_pretrained
加载config.json
时,计数都会增加一。有关自动下载指标,请参阅本指南。
建议为每个检查点添加模型卡片,以便人们可以阅读有关模型的信息,链接到论文等。
访问 huggingface_hub 的文档以了解更多信息。
或者,也可以简单地以编程方式将文件或文件夹上传到 hub:https://huggingface.co/docs/huggingface_hub/guides/upload。
使用 Git
最后,由于模型仓库只是 Git 仓库,您也可以使用 Git 将模型文件推送到 Hub。请按照仓库入门指南了解有关使用 git
CLI 提交和推送模型的更多信息。