创建和管理仓库

Hugging Face Hub 是 Git 仓库的集合。Git 是软件开发中广泛使用的工具，用于在协同工作时轻松进行项目版本控制。本指南将向您展示如何与 Hub 上的仓库进行交互，特别是

创建和删除仓库。
管理分支和标签。
重命名您的仓库。
更新您的仓库可见性。
管理仓库的本地副本。

如果您习惯于使用 GitLab/GitHub/Bitbucket 等平台，您的第一反应可能是使用 git CLI 克隆您的仓库 (git clone)、提交更改 (git add, git commit) 并推送它们 (git push)。当使用 Hugging Face Hub 时，这是有效的。但是，软件工程和机器学习并不具有相同的需求和工作流程。模型仓库可能会维护用于不同框架和工具的大型模型权重文件，因此克隆仓库可能会导致您维护包含大量文件的大型本地文件夹。因此，使用我们自定义的 HTTP 方法可能更有效。您可以阅读我们的 Git 与 HTTP 范式解释页面以了解更多详细信息。

如果您想在 Hub 上创建和管理仓库，您的机器必须已登录。如果您没有登录，请参阅此部分。在本指南的其余部分，我们将假定您的机器已登录。

仓库创建和删除

第一步是了解如何创建和删除仓库。您只能管理您拥有的仓库（在您的用户名命名空间下）或您具有写入权限的组织中的仓库。

创建仓库

使用 create_repo() 创建一个空仓库，并使用 repo_id 参数为其命名。repo_id 是您的命名空间，后跟仓库名称：username_or_org/repo_name。

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model")
'https://huggingface.co/lysandre/test-model'

默认情况下，create_repo() 创建一个模型仓库。但是您可以使用 repo_type 参数来指定另一种仓库类型。例如，如果您想创建一个数据集仓库

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-dataset", repo_type="dataset")
'https://huggingface.co/datasets/lysandre/test-dataset'

当您创建仓库时，可以使用 private 参数设置仓库的可见性。

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-private", private=True)

如果您想在稍后更改仓库的可见性，可以使用 update_repo_settings() 函数。

如果您是拥有企业计划的组织的一部分，您可以通过将 resource_group_id 作为参数传递给 create_repo()，在特定的资源组中创建一个仓库。资源组是一项安全功能，用于控制您的组织中的哪些成员可以访问给定的资源。您可以通过从 Hub 上的组织设置页面 URL 复制资源组 ID 来获取它（例如 "https://huggingface.co/organizations/huggingface/settings/resource-groups/66670e5163145ca562cb1988" => "66670e5163145ca562cb1988"）。有关资源组的更多详细信息，请查看此指南。

删除仓库

使用 delete_repo() 删除仓库。确保您要删除仓库，因为这是一个不可逆转的过程！

指定您要删除的仓库的 repo_id

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset")

复制仓库（仅适用于 Spaces）

在某些情况下，您可能希望复制别人的仓库以使其适应您的用例。对于 Spaces，可以使用 duplicate_space() 方法。它将复制整个仓库。您仍然需要配置自己的设置（硬件、睡眠时间、存储、变量和密钥）。查看我们的管理您的 Space 指南以了解更多详细信息。

>>> from huggingface_hub import duplicate_space
>>> duplicate_space("multimodalart/dreambooth-training", private=False)
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

上传和下载文件

现在您已经创建了仓库，您有兴趣将更改推送到仓库并从中下载文件。

这两个主题值得单独指南介绍。请参阅上传和下载指南，了解如何使用您的仓库。

分支和标签

Git 仓库通常使用分支来存储同一仓库的不同版本。标签也可以用于标记仓库的特定状态，例如，在发布版本时。更一般而言，分支和标签被称为 git 引用。

创建分支和标签

您可以使用 create_branch() 和 create_tag() 创建新的分支和标签

>>> from huggingface_hub import create_branch, create_tag

# Create a branch on a Space repo from `main` branch
>>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker")

# Create a tag on a Dataset repo from `v0.1-release` branch
>>> create_tag("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.")

您可以同样使用 delete_branch() 和 delete_tag() 函数来删除分支或标签。

列出所有分支和标签

您还可以使用 list_repo_refs() 列出仓库中现有的 git 引用

>>> from huggingface_hub import list_repo_refs
>>> list_repo_refs("bigcode/the-stack", repo_type="dataset")
GitRefs(
   branches=[
         GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
         GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
   ],
   converts=[],
   tags=[
         GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
   ]
)

更改仓库设置

仓库带有一些您可以配置的设置。大多数时候，您会在浏览器中的仓库设置页面中手动执行此操作。您必须具有仓库的写入权限才能配置它（要么拥有它，要么成为组织的一部分）。在本节中，我们将看到您也可以使用 huggingface_hub 以编程方式配置的设置。

某些设置是 Spaces 特有的（硬件、环境变量等）。要配置这些，请参阅我们的管理您的 Spaces 指南。

更新可见性

仓库可以是公开的或私有的。私有仓库仅对您或仓库所在的组织的成员可见。将仓库更改为私有，如下所示

>>> from huggingface_hub import update_repo_settings
>>> update_repo_settings(repo_id=repo_id, private=True)

设置门控访问

为了更好地控制仓库的使用方式，Hub 允许仓库作者为其仓库启用访问请求。启用后，用户必须同意与仓库作者共享他们的联系信息（用户名和电子邮件地址）才能访问文件。启用访问请求的仓库称为门控仓库。

您可以使用 update_repo_settings() 将仓库设置为门控仓库

>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> api.update_repo_settings(repo_id=repo_id, gated="auto")  # Set automatic gating for a model

重命名您的仓库

您可以使用 move_repo() 在 Hub 上重命名您的仓库。使用此方法，您还可以将仓库从用户移动到组织。这样做时，您应该注意一些限制。例如，您不能将您的仓库转移给另一个用户。

>>> from huggingface_hub import move_repo
>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model")

管理仓库的本地副本

上面描述的所有操作都可以使用 HTTP 请求完成。但是，在某些情况下，您可能对拥有仓库的本地副本并使用您熟悉的 Git 命令与之交互感兴趣。

Repository 类允许您使用类似于 Git 命令的功能与 Hub 上的文件和仓库进行交互。它是 Git 和 Git-LFS 方法的包装器，可以使用您已经知道和喜欢的 Git 命令。在开始之前，请确保您已安装 Git-LFS（有关安装说明，请参阅此处）。

Repository 已弃用，取而代之的是在 HfApi 中实现的基于 http 的替代方案。鉴于其在旧代码中的广泛采用，完全删除 Repository 将仅在 v1.0 版本中发生。有关更多详细信息，请阅读此说明页面。

使用本地仓库

使用本地仓库的路径实例化 Repository 对象

>>> from huggingface_hub import Repository
>>> repo = Repository(local_dir="<path>/<to>/<folder>")

克隆

clone_from 参数将仓库从 Hugging Face 仓库 ID 克隆到 local_dir 参数指定的本地目录

>>> from huggingface_hub import Repository
>>> repo = Repository(local_dir="w2v2", clone_from="facebook/wav2vec2-large-960h-lv60")

clone_from 也可以使用 URL 克隆仓库

>>> repo = Repository(local_dir="huggingface-hub", clone_from="https://huggingface.co/facebook/wav2vec2-large-960h-lv60")

您可以将 clone_from 参数与 create_repo() 结合使用以创建和克隆仓库

>>> repo_url = create_repo(repo_id="repo_name")
>>> repo = Repository(local_dir="repo_local_path", clone_from=repo_url)

您还可以通过在克隆仓库时指定 git_user 和 git_email 参数，为克隆的仓库配置 Git 用户名和电子邮件。当用户提交到该仓库时，Git 将知道提交作者。

>>> repo = Repository(
...   "my-dataset",
...   clone_from="<user>/<dataset_id>",
...   token=True,
...   repo_type="dataset",
...   git_user="MyName",
...   git_email="me@cool.mail"
... )

分支

分支对于协作和实验非常重要，而不会影响您当前的文件和代码。使用 git_checkout() 在分支之间切换。例如，如果您想从 branch1 切换到 branch2

>>> from huggingface_hub import Repository
>>> repo = Repository(local_dir="huggingface-hub", clone_from="<user>/<dataset_id>", revision='branch1')
>>> repo.git_checkout("branch2")

拉取

git_pull() 允许您使用来自远程仓库的更改来更新当前的本地分支

>>> from huggingface_hub import Repository
>>> repo.git_pull()

如果您希望本地提交发生在您的分支使用来自远程仓库的新提交更新之后，请设置 rebase=True

>>> repo.git_pull(rebase=True)

< > 更新 on GitHub

Hub Python 库