# 上传模型

要将模型上传到 Hub，您需要在 [Hugging Face](https://huggingface.co/join) 上创建一个账户。Hub 上的模型是 [基于 Git 的仓库](./repositories)，它们提供版本控制、分支、可发现性和共享功能，以及与数十个库的集成等！您可以控制要上传到仓库的内容，其中包括检查点、配置文件以及其他任何文件。

您可以将仓库与个人用户关联，例如 [osanseviero/fashion_brands_patterns](https://huggingface.co/osanseviero/fashion_brands_patterns)，或者与组织关联，例如 [facebook/bart-large-xsum](https://huggingface.co/facebook/bart-large-xsum)。组织可以收集与公司、社区或库相关的模型！如果您选择组织，该模型将展示在组织的页面上，并且组织的每位成员都将能够向该仓库贡献内容。您可以在此处[创建](https://huggingface.co/organizations/new)一个新组织。

> **_注意：_**模型无需与 Transformers/Diffusers 库兼容即可获取下载指标。支持任何自定义模型。请阅读下文了解更多信息！

有几种方法可以上传模型，以便它们能够很好地集成到 Hub 中并获取[下载指标](models-download-stats)，具体说明如下。

- 如果您的模型是为具有[内置支持](#upload-from-a-library-with-built-in-support)的库而设计的，您可以使用该库提供的方法。使用`trust_remote_code=True`的自定义模型也可以利用这些方法。
- 如果您的模型是自定义的 PyTorch 模型，可以利用 [`PyTorchModelHubMixin` 类](#upload-a-pytorch-model-using-huggingfacehub)，因为它允许为任何 `nn.Module` 类添加 `from_pretrained` 和 `push_to_hub`，就像 Transformers、Diffusers 和 Timm 库中的模型一样。
- 除了通过编程方式上传，您还可以随时使用[Web 界面](#using-the-web-interface)或[git 命令行](#using-git)。

模型上传完成后，我们建议在你的仓库中添加一个 [Model Card](./model-cards)，以记录你的模型信息并提高其可发现性。

<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/example_repository.png"
alt="drawing" width="600"/>

 利用 [PyTorchModelHubMixin](#upload-a-pytorch-model-using-huggingfacehub) 的 [仓库](https://huggingface.co/LiheYoung/depth_anything_vitl14) 示例。右侧显示下载量。

## 使用 Web 界面

要创建一个全新的模型仓库，请访问 [huggingface.co/new](http://huggingface.co/new)。然后按照以下步骤操作：

1. 在“Files and versions”选项卡中，选择“Add File”并指定“Upload File”：

2. 然后，从您的计算机中选择一个文件进行上传，并留下有用的提交信息，以便了解您正在上传的内容：

3. 之后，点击 **Commit changes** 将您的模型上传到 Hub！

4. 检查文件和历史记录

您可以检查包含所有最近添加文件的仓库！

该界面允许您浏览模型文件和提交记录，并查看每个提交所引入的差异：

5. 添加元数据

您可以在模型卡中添加元数据。您可以指定：
* 该模型所针对的任务类型，用于启用小部件和推理服务提供商。
* 所使用的库（`transformers`、`spaCy`等）
* 语言
* 数据集
* metrics
* 许可证
* 还有很多！

有关模型标签的更多信息，请参见[此处](./model-cards#model-card-metadata)。

6. 添加 TensorBoard 跟踪

任何包含 TensorBoard 跟踪文件（文件名中包含 `tfevents`）的仓库都会被归类为带有 [`TensorBoard` 标签](https://huggingface.co/models?filter=tensorboard)。按照惯例，我们建议将跟踪文件保存在 `runs/` 子文件夹下。这样，"Training metrics" 选项卡就能方便地查看已记录变量（如损失或准确率）的图表。

使用 🤗 Transformers 训练的模型，如果已安装 [`tensorboard`](https://pypi.org/project/tensorboard/)，默认会生成 [TensorBoard 跟踪记录](https://huggingface.co/docs/transformers/main_classes/callback#transformers.integrations.TensorBoardCallback)。

## 从内置支持的库上传

首先检查你的模型是否来自一个内置了推送到/从 Hub 加载支持的库，例如 Transformers、Diffusers、Timm、Asteroid 等：https://huggingface.co/docs/hub/models-libraries。下面我们将展示对于像 Transformers 这样的库，这有多简单：

```python
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 加载 [代码](https://huggingface.co/docs/transformers/custom_models)。这是一种让你的模型通过 `trust_remote_code=True` 标志与 Transformers 配合使用的方式。你可以考虑采用此选项，而不是进行完整的库集成。

## 使用 huggingface_hub 上传 PyTorch 模型

如果您的模型是一个（自定义的）PyTorch 模型，您可以利用 [huggingface_hub](https://github.com/huggingface/huggingface_hub) Python 库中提供的 `PyTorchModelHubMixin` [类](https://huggingface.co/docs/huggingface_hub/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin)。这是一个极简的类，它为任意 `nn.Module` 添加了 `from_pretrained` 和 `push_to_hub` 功能，并附带下载指标。

以下是使用方法（假设您已运行 `pip install huggingface_hub`）：

```python
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 dataclasses。

这附带了自动化的下载指标，这意味着您将能够查看模型被下载的次数，其方式与原生集成在 Transformers、Diffusers 或 Timm 库中的模型相同。使用此混入类，每个独立的检查点都会以包含 2 个文件的单个仓库形式存储在 Hub 上：

- 包含权重的 `pytorch_model.bin` 或 `model.safetensors` 文件
- 一个 `config.json` 文件，它是模型配置的序列化版本。该类用于统计下载指标：每当用户调用 `from_pretrained` 来加载 `config.json` 时，计数就会增加一。有关自动下载指标的说明，请参阅[此指南](https://huggingface.co/docs/hub/models-download-stats)。

建议为每个检查点添加一个模型卡片，以便人们可以了解该模型的相关信息、获取论文的链接等。

访问 [huggingface_hub 的文档](https://huggingface.co/docs/huggingface_hub/guides/integrations) 以了解更多信息。

或者，也可以直接以编程方式将文件或文件夹上传到 Hub：https://huggingface.co/docs/huggingface_hub/guides/upload。

## 使用 Git

最后，由于模型仓库本质上就是 Git 仓库，你也可以使用 Git 将模型文件推送到 Hub。请遵循[仓库入门指南](repositories-getting-started#terminal)，了解如何使用`git` CLI 来提交并推送你的模型。