Hugging Face's logo

Hub Python Library documentation

创建和管理存储库

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.26.2).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

创建和管理存储库

Hugging Face Hub是一组 Git 存储库。Git是软件开发中广泛使用的工具，可以在协作工作时轻松对项目进行版本控制。本指南将向您展示如何与 Hub 上的存储库进行交互，特别关注以下内容：

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

如果您习惯于使用类似于GitLab/GitHub/Bitbucket等平台，您可能首先想到使用 git命令行工具来克隆存储库（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_visibility() 函数

删除一个仓库

使用 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_branch("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
>>> api.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_visibility
>>> update_repo_visibility(repo_id=repo_id, private=True)

重命名您的存储库

您可以使用 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 对象：

请运行以下代码：

>>> 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)
< > Update on GitHub

←安装 Git vs HTTP 范式→