仓库快速入门

这份入门指南将帮助你掌握在 Hub 上创建与管理仓库的基本技能。各节内容相互衔接，你可以根据需要选择起点！

前提条件

本文展示了如何通过网页界面和终端操作仓库。使用网页界面无需额外前置条件；若要使用终端，请按以下步骤安装工具。

如果命令行中尚无法使用 git，需要为你的平台安装 Git。同时还需安装 Git LFS，用于处理图像、模型权重等大文件。

提示

若要在处理大型文件与 Git 时获得更快的上传下载速度，请安装 Git Xet 扩展。

为了将代码推送到 Hub，你需要进行身份验证。最简单的方法是安装 huggingface_hub CLI 并执行登录命令：

python -m pip install huggingface_hub
hf auth login

本节内容还提供了视频版本！

创建仓库

借助 Hub 的网页界面，你可以轻松创建仓库、添加文件（包括大文件）、探索模型、查看差异等。Hub 上有三种仓库类型，本指南将以创建模型仓库为例。关于模型、数据集与 Spaces 的创建与管理，请参阅对应文档。

1. 访问 huggingface.co/new 创建新仓库：

2. 指定仓库所有者：可以是你本人或所属组织。
3. 输入模型名称，这也是仓库名称。
4. 指定模型是否公开。
5. 指定许可证。License 字段可以暂时留空。要了解许可证，请参考许可证 文档。

创建完成后，你将看到如下页面：

请注意，Hub 会提示你创建 模型卡片，你可以在模型卡片文档了解更多。为模型仓库添加模型卡片是最佳实践，但目前只是测试仓库，我们可以暂时跳过。

通过网页界面添加文件

若要通过网页界面添加文件，先选择 Files 标签页，进入目标目录，再点击 Add file。你可以创建新文件或从本地上传文件。

创建新文件

选择创建新文件后，会进入如下编辑器界面。你可以为文件命名、编写内容，并用一条摘要信息保存更改。你也可以选择 Open as a pull request，将此更改作为拉取请求提交，而不是直接合并到 main 分支。

上传文件

选择 Upload file 时，可以从本地上传文件，并附上一条摘要信息说明本次更改。

与创建新文件一样，你可以选择 Open as a pull request 来创建拉取请求，而非直接将更改加入仓库的 main 分支。

通过终端添加文件[[terminal]]

克隆仓库

将仓库下载到本地称为 克隆（clone）。你可以使用以下命令加载并进入仓库：

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

若是数据集仓库：

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

也可以通过 SSH 克隆：

git clone [email protected]:<your-username>/<your-model-name>
cd <your-model-name>

要推送更改或访问私有仓库，需要将 SSH 公钥添加到用户设置。

初始化

现在就可以向仓库添加任意文件啦！🔥

需要上传超过 10MB 的文件吗？这些文件应使用 git-lfs 跟踪，可通过以下命令初始化：

git lfs install

如果文件大于 5GB，还需执行：

hf lfs-enable-largefiles .

当你在 Hugging Face 上创建仓库时，我们会自动在 .gitattributes 中提供常见机器学习大文件的扩展名列表，供 git-lfs 高效跟踪。不过，如果你的文件类型未被涵盖，可以通过 git lfs track "*.your_extension" 添加。

推送文件

使用 Git 可以把新文件或已有文件的修改打包成一次提交（commit），可理解为项目的一次“修订”。创建提交时，需要先执行 add 命令告诉 Git 哪些文件将被保存，再执行 commit 生成提交。最后通过 push 将提交同步到 Hugging Face Hub。

# 创建你想要的文件！然后……
git add .
git commit -m "First model version"  # 可自定义说明信息
git push

完成后即可在 Hugging Face 上查看刚添加的文件。如下图所示，用户添加了多个文件，其中部分大小为 1.04 GB，因此仓库使用 Git LFS 跟踪。

提示

如果你通过 HTTP 克隆仓库，每次执行 push 时可能都会要求输入用户名和密码。最简单的办法是改用 SSH。若必须使用 HTTP，可以考虑配置 git credential helper 自动填充凭据。

查看仓库历史记录

每次执行 add、commit、push，仓库都会记录文件更改。网页界面允许你浏览文件、提交以及每次提交带来的差异（diff）。如需查看历史，点击 History: X commits 链接。

点击单个提交即可查看该提交引入的具体变更：