# 入门仓库

这份面向初学者的指南将帮助你掌握在 Hub 上创建和管理仓库所需的基本技能。每个部分都建立在前一部分的基础上，因此你可以自由选择从哪里开始！

## 要求

本文档介绍了如何通过 Web 界面和终端来管理仓库。使用 UI 时没有特殊要求。如果您想通过终端进行操作，请遵循这些安装说明。

如果尚未将 `git` 作为 CLI 命令使用，则需要为您的平台 [安装 Git](https://git-scm.com/downloads)。您还需要 [安装 Git-Xet](./xet/using-xet-storage#git-xet)，它将用于处理图像和模型权重等大文件。

> [!TIP]
> 要能够从 Git 下载和上传大文件，您需要安装 [Git Xet](./xet/using-xet-storage#git) 扩展。

要将代码推送到 Hub，您需要先进行身份验证。最简单的方法是安装 [`hf` CLI](https://huggingface.co/docs/huggingface_hub/guides/cli) 并运行登录命令：

```bash
# Install hf:
#   brew install hf
#   or
#   pip install hf
hf auth login
```

**本文档“入门”部分的内容也有视频版！**

## 创建仓库

使用 Hub 的 Web 界面，您可以轻松创建仓库、添加文件（即使是大文件！）、探索模型、可视化差异等。Hub 上有三种类型的仓库，在本指南中，您将创建一个**模型仓库**用于演示目的。有关创建和管理模型、数据集和 Spaces 的信息，请参阅各自的文档。

1. 要创建新仓库，请访问 [huggingface.co/new](http://huggingface.co/new)：

2. 指定仓库的所有者：可以是您本人，也可以是您所属的任何组织。

3. 输入您的模型名称。这也将是仓库的名称。

4. 指定您希望模型是公开还是私有。

5. 指定许可证。您可以暂时将 *License* 字段留空。要了解有关许可证的信息，请访问 [**Licenses**](repositories-licenses) 文档。

创建模型仓库后，您应该会看到如下页面：

请注意，Hub 会提示您创建一个 *Model Card*，您可以在 [**Model Cards 文档**](./model-cards) 中了解相关内容。在模型仓库中包含 Model Card 是最佳实践，但由于我们目前只是创建一个测试仓库，因此可以跳过此步骤。

## 向仓库添加文件（Web UI）

要通过 Web UI 向您的仓库添加文件，请先选择 **Files** 选项卡，导航到目标目录，然后单击 **Add file**。您可以选择创建新文件，或直接从您的计算机上传文件。

### 创建新文件

选择创建新文件后，您将进入以下编辑器界面，在此您可以为文件命名、添加内容，并保存文件，同时附上一段总结所做更改的信息。您可以选择`Open as a pull request`来创建一个[Pull Request](./repositories-pull-requests-discussions)，而不是直接将新文件提交到仓库的`main`分支。

### 上传文件

如果选择 _Upload file_，您可以选择一个本地文件进行上传，并附带一条消息来总结您对仓库所做的更改。

与创建新文件一样，您可以选择`Open as a pull request`来创建一个[Pull Request](./repositories-pull-requests-discussions)，而不是将更改直接添加到仓库的`main`分支。

## 向仓库添加文件（CLI）[[cli]]

您可以使用 [`hf` CLI](https://huggingface.co/docs/huggingface_hub/guides/cli) 直接从终端将文件上传到您的仓库。使用 `hf upload` 命令来推送本地文件或整个文件夹：

```bash
# Upload a single file to your model repo
hf upload your-username/your-model-name model.safetensors

# Upload an entire directory
hf upload your-username/your-model-name ./my-model-directory

# Upload to a dataset repo
hf upload your-username/your-dataset-name ./data --repo-type dataset
```

`hf` CLI 会自动处理大文件——无需额外配置。

## 向仓库添加文件（git）[[terminal]]

### 克隆仓库

将仓库下载到本地机器称为*克隆*。您可以使用以下命令加载您的仓库并进入该目录：

```bash
git clone https://huggingface.co/<your-username>/<your-model-name>
cd <your-model-name>
```

或者对于数据集仓库：

```bash
git clone https://huggingface.co/datasets/<your-username>/<your-dataset-name>
cd <your-dataset-name>
```

您可以使用以下命令通过 SSH 克隆：
```bash
git clone git@hf.co:<your-username>/<your-model-name>
cd <your-model-name>
```

您需要将 SSH 公钥添加到[您的用户设置](https://huggingface.co/settings/keys)中，才能推送更改或访问私有仓库。

### 设置

现在正是时候，你可以向仓库中添加任何你想要的文件！🔥

您是否有大于 10MB 的文件？这些文件应使用 [`git-xet`](./xet/using-xet-storage#git-xet) 进行跟踪，您可以通过以下方式初始化：

```bash
git xet install
```

使用 Hugging Face 创建仓库时，Hugging Face 会在 `.gitattributes` 文件中自动提供常见机器学习大文件的常见文件扩展名列表，`git-xet` 会利用该列表来高效地跟踪大文件的变更。如果您的文件类型尚未被处理，可能需要添加新的扩展名。您可以通过 `git xet track "*.your_extension"` 来实现。

### 推送文件

你可以使用 Git 将新文件以及对现有文件的任何更改保存为一组称为 *commit*（提交）的更改，可以将其视为对项目的“修订”。要创建 commit，你需要先 `add`（添加）文件，以告知 Git 我们计划保存这些更改，然后 `commit`（提交）这些更改。为了将新的 commit 与 Hugging Face Hub 同步，你还需要将该 commit `push`（推送）到 Hub。

```bash
# Create any files you like! Then...
git add .
git commit -m "First model version"  # You can choose any descriptive message
git push
```

大功告成！您可以在 Hugging Face 上查看您的仓库，其中包含所有最近添加的文件。例如，在下方的截图中，用户添加了许多文件。请注意，此示例中的某些文件大小为 `1.04 GB`，因此该仓库使用 Xet 进行跟踪。

> [!TIP]
> 如果您通过 HTTP 克隆了仓库，每次执行推送操作时都可能被要求输入用户名和密码。避免重复输入的最简单方法是改用 [SSH](#cloning-repositories) 而非 HTTP。或者，如果您必须使用 HTTP，可以考虑配置 [git credential helper](https://git-scm.com/docs/gitcredentials#_avoiding_repetition) 来自动填充用户名和密码。

## 查看仓库的历史记录

每次你完成 `add`-`commit`-`push` 循环，仓库都会记录你对文件所做的所有更改。UI 允许你浏览模型文件和提交，并查看每个提交引入的差异（也称为 *diff*）。要查看历史记录，你可以点击 **History: X commits** 链接。

您可以单击某个单独的提交，以查看该提交引入了哪些更改：