创建和管理仓库

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 是您的命名空间后跟仓库名称：用户名或组织名/仓库名。

>>> 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_visibility() 函数。

如果您是拥有企业计划的组织的成员，您可以通过将 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="[email protected]"
... )

分支

分支对于协作和实验非常重要，而不会影响您当前的文件和代码。使用 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)

< > 在 GitHub 上更新

Hub Python 库