Hub Python 库文档

管理本地和在线存储库

Hub Python 库

加入 Hugging Face 社区

并获得增强的文档体验

在模型、数据集和 Spaces 上进行协作

通过加速推理获得更快的示例

切换文档主题

开始使用

管理本地和在线存储库

Repository 类是一个包装 git 和 git-lfs 命令的辅助类。它提供了适用于管理可能非常大的存储库的工具。

一旦涉及任何 git 操作，或者当协作将成为存储库本身的重点时，它是推荐的工具。

Repository 类

class huggingface_hub.Repository

( local_dir: typing.Union[str, pathlib.Path] clone_from: typing.Optional[str] = None repo_type: typing.Optional[str] = None token: typing.Union[bool, str] = True git_user: typing.Optional[str] = None git_email: typing.Optional[str] = None revision: typing.Optional[str] = None skip_lfs_files: bool = False client: typing.Optional[huggingface_hub.hf_api.HfApi] = None )

用于包装 git 和 git-lfs 命令的辅助类。

目的是方便与 huggingface.co 托管的模型或数据集仓库进行交互，尽管这里（如果有的话）并没有多少是 huggingface.co 特有的。

Repository 已弃用，取而代之的是 HfApi 中实现的基于 HTTP 的替代方案。鉴于其在旧代码中的广泛采用，Repository 的完全移除只会在 v1.0 版本中进行。有关更多详细信息，请阅读 https://huggingface.co/docs/huggingface_hub/concepts/git_vs_http。

init

( local_dir: typing.Union[str, pathlib.Path] clone_from: typing.Optional[str] = None repo_type: typing.Optional[str] = None token: typing.Union[bool, str] = True git_user: typing.Optional[str] = None git_email: typing.Optional[str] = None revision: typing.Optional[str] = None skip_lfs_files: bool = False client: typing.Optional[huggingface_hub.hf_api.HfApi] = None )

参数

local_dir (str 或 Path) — 本地目录的路径（例如 'my_trained_model/'），Repository 将在此处初始化。
clone_from (str, 可选) — 仓库 URL 或 repo_id。示例：
- "https://huggingface.co/philschmid/playground-tests"
- "philschmid/playground-tests"
repo_type (str, 可选) — 从 repo_id 克隆仓库时设置。默认为模型。
token (bool 或 str, 可选) — 有效的身份验证令牌（请参阅 https://huggingface.co/settings/token）。如果为 None 或 True 且机器已登录（通过 hf auth login 或 login()），则将从缓存中检索令牌。如果为 False，则请求头中不发送令牌。
git_user (str, 可选) — 将覆盖 git config user.name，用于提交和推送文件到 Hub。
git_email (str, 可选) — 将覆盖 git config user.email，用于提交和推送文件到 Hub。
revision (str, 可选) — 初始化仓库后要检出的修订版本。如果修订版本不存在，将从默认分支的当前 HEAD 创建一个具有该修订版本名称的分支。
skip_lfs_files (bool, 可选, 默认为 False) — 是否跳过 git-LFS 文件。
client (HfApi, 可选) — 调用 HF Hub API 时使用的 HfApi 实例。如果保留为 None，将创建一个新实例。

引发

EnvironmentError

EnvironmentError — 如果 clone_from 中设置的远程仓库不存在。

实例化 git 仓库的本地克隆。

如果设置了 clone_from，仓库将从现有远程仓库克隆。如果远程仓库不存在，将抛出 EnvironmentError 异常。请先使用 create_repo() 创建远程仓库。

Repository 默认使用本地 git 凭据。如果明确设置，将使用 token 或 git_user/git_email 对。

current_branch

( ) → str

返回

字符串

当前检出的分支。

返回当前检出的分支。

add_tag

( tag_name: str message: typing.Optional[str] = None remote: typing.Optional[str] = None )

参数

tag_name (str) — 要添加的标签名称。
message (str, 可选) — 伴随标签的消息。如果传递了消息，标签将变为带注释的标签。
remote (str, 可选) — 要在其上添加标签的远程仓库。

在当前 HEAD 添加标签并推送

如果 remote 为 None，则只会在本地更新

如果没有提供消息，标签将是轻量级的。如果提供了消息，标签将是带注释的。

auto_track_binary_files

( pattern: str = '.' ) → List[str]

参数

pattern (str, 可选, 默认为 ”.“) — 用于跟踪二进制文件的模式。

返回

List[str]

因二进制文件而被跟踪的文件名列表

使用 git-lfs 自动跟踪二进制文件。

auto_track_large_files

( pattern: str = '.' ) → List[str]

参数

pattern (str, 可选, 默认为 ”.“) — 用于跟踪超过 10MB 的文件的模式。

返回

List[str]

因文件大小而被跟踪的文件名列表。

使用 git-lfs 自动跟踪大文件（超过 10MB 的文件）。

check_git_versions

( )

引发

EnvironmentError

EnvironmentError — 如果未安装 git 或 git-lfs。

检查 git 和 git-lfs 是否可运行。

clone_from

( repo_url: str token: typing.Union[bool, str, NoneType] = None )

参数

repo_url (str) — 克隆仓库的 URL
token (Union[str, bool], 可选) — 是否使用身份验证令牌。它可以是：
- 令牌本身字符串
- False，表示不使用身份验证令牌
- True，表示从本地文件夹获取身份验证令牌并使用（这需要您登录才能工作）。
- None，表示检索 self.huggingface_token 的值。

从远程仓库克隆。如果文件夹已存在，将尝试在其内部克隆仓库。

如果此文件夹是带有链接历史记录的 git 仓库，将尝试更新该仓库。

引发以下错误

ValueError 如果传递了组织令牌（以“api_org”开头）。必须使用您自己的个人访问令牌（请参阅 https://huggingface.co/settings/tokens）。
EnvironmentError 如果您尝试将仓库克隆到非空文件夹中，或者如果 git 操作引发错误。

commit

( commit_message: str branch: typing.Optional[str] = None track_large_files: bool = True blocking: bool = True auto_lfs_prune: bool = False )

参数

commit_message (str) — 用于提交的消息。
branch (str, 可选) — 提交将显示在哪个分支上。在此操作之前，将检出此分支。
track_large_files (bool, 可选, 默认为 True) — 是否自动跟踪大文件。默认情况下会这样做。
blocking (bool, 可选, 默认为 True) — 函数是否应仅在 git push 完成后返回。
auto_lfs_prune (bool, 默认为 True) — 推送到远程仓库后是否自动修剪文件。

上下文管理器实用工具，用于处理对仓库的提交。它会自动使用 git-lfs 跟踪大文件（>10Mb）。如果您希望忽略此行为，请将 track_large_files 参数设置为 False。

示例

>>> with Repository(
...     "text-files",
...     clone_from="<user>/text-files",
...     token=True,
>>> ).commit("My first file :)"):
...     with open("file.txt", "w+") as f:
...         f.write(json.dumps({"hey": 8}))

>>> import torch

>>> model = torch.nn.Transformer()
>>> with Repository(
...     "torch-model",
...     clone_from="<user>/torch-model",
...     token=True,
>>> ).commit("My cool model :)"):
...     torch.save(model.state_dict(), "model.pt")

delete_tag

( tag_name: str remote: typing.Optional[str] = None ) → bool

参数

tag_name (str) — 要删除的标签名称。
remote (str, 可选) — 要在其上删除标签的远程仓库。

返回

布尔值

如果已删除则为 True，如果标签不存在则为 False。如果没有传递远程，则只会在本地更新

如果标签存在，则删除本地和远程标签

git_add

( pattern: str = '.' auto_lfs_track: bool = False )

参数

pattern (str, 可选, 默认为 ”.“) — 用于将文件添加到暂存区的模式。
auto_lfs_track (bool, 可选, 默认为 False) — 是否使用 git-lfs 自动跟踪大文件和二进制文件。任何大小超过 10MB 或二进制格式的文件都将自动跟踪。

git add

将 auto_lfs_track 参数设置为 True 将自动使用 git-lfs 跟踪大于 10MB 的文件。

git_checkout

( revision: str create_branch_ok: bool = False )

参数

revision (str) — 要检出的修订版本。
create_branch_ok (str, 可选, 默认为 False) — 如果 revision 不是现有修订版本，是否允许在当前检出的引用上创建以 revision 命名的分支。

git 检出给定修订版本

将 create_branch_ok 指定为 True 将在给定修订版本不存在的情况下创建该修订版本的分支。

git_commit

( commit_message: str = 'commit files to HF hub' )

参数

commit_message (str, 可选, 默认为“commit files to HF hub”) — 提交的消息。

git commit

git_config_username_and_email

( git_user: typing.Optional[str] = None git_email: typing.Optional[str] = None )

参数

git_user (str, 可选) — 要通过 git 注册的用户名。
git_email (str, 可选) — 要通过 git 注册的电子邮件。

设置 git 用户名和电子邮件（仅在当前存储库中）。

git_credential_helper_store

( )

将 git 凭证助手设置为 store

git_head_commit_url

( ) → str

返回

字符串

当前检出提交的 URL。

获取 HEAD 上最后一次提交的 URL。我们假设它已被推送，并且 URL 方案与 GitHub 或 HuggingFace 的相同。

git_head_hash

( ) → str

返回

字符串

当前检出提交的 SHA。

获取 HEAD 顶部的提交 SHA。

git_pull

( rebase: bool = False lfs: bool = False )

参数

rebase (bool, 可选, 默认为 False) — 是否在拉取后将当前分支变基到上游分支之上。
lfs (bool, 可选, 默认为 False) — 是否也获取 LFS 文件。此选项仅在未获取 LFS 文件的情况下克隆存储库时更改行为；调用 repo.git_pull(lfs=True) 将从远程存储库获取 LFS 文件。

git pull

git_push

( upstream: typing.Optional[str] = None blocking: bool = True auto_lfs_prune: bool = False )

参数

upstream (str, 可选) — 推送到的上游。如果未指定，将推送到最后定义上游或默认上游（origin main）。
blocking (bool, 可选, 默认为 True) — 函数是否应仅在推送完成后返回。将其设置为 False 将返回一个 CommandInProgress 对象，该对象具有 is_done 属性。当推送完成后，此属性将设置为 True。
auto_lfs_prune (bool, 可选, 默认为 False) — 是否在文件推送到远程后自动修剪文件。

git push

如果使用时未设置 blocking，将返回远程仓库上提交的 URL。如果使用 blocking=True，将返回一个元组，其中包含提交的 URL 和用于获取进程信息的命令对象。

git_remote_url

( ) → str

返回

字符串

origin 远程的 URL。

获取源远程的 URL。

is_repo_clean

( ) → bool

返回

布尔值

如果 git 状态干净，则为 True，否则为 False。

返回 git 状态是否干净

lfs_enable_largefiles

( )

HF 特有。这支持上传大于 5GB 的文件。

lfs_prune

( recent = False )

参数

recent (bool, 可选, 默认为 False) — 是否即使文件被最近的提交引用也修剪它们。有关更多信息，请参阅以下链接。

git lfs prune

lfs_track

( patterns: typing.Union[str, typing.List[str]] filename: bool = False )

参数

patterns (Union[str, List[str]]) — 要用 git-lfs 跟踪的模式或模式列表。
filename (bool, 可选, 默认为 False) — 是否将模式用作字面文件名。

告诉 git-lfs 根据模式跟踪文件。

将 filename 参数设置为 True 将把参数视为字面文件名，而不是模式。文件名中的任何特殊全局字符在写入 .gitattributes 文件时都将被转义。

lfs_untrack

( patterns: typing.Union[str, typing.List[str]] )

参数

patterns (Union[str, List[str]]) — 要用 git-lfs 取消跟踪的模式或模式列表。

告诉 git-lfs 取消跟踪这些文件。

list_deleted_files

( ) → List[str]

返回

List[str]

工作目录或索引中已删除的文件列表。

返回工作目录或索引中已删除的文件列表。

push_to_hub

( commit_message: str = 'commit files to HF hub' blocking: bool = True clean_ok: bool = True auto_lfs_prune: bool = False )

参数

commit_message (str) — 用于提交的消息。
blocking (bool, 可选, 默认为 True) — 函数是否应仅在 git push 完成后返回。
clean_ok (bool, 可选, 默认为 True) — 如果为 True，则如果仓库未更改，此函数将返回 None。默认行为是失败，因为 git 命令会失败。
auto_lfs_prune (bool, 可选, 默认为 False) — 文件推送到远程后是否自动修剪文件。

用于将文件添加到远程存储库并提交和推送的助手，位于 HuggingFace Hub 上。将自动跟踪大型文件（>10MB）。

tag_exists

( tag_name: str remote: typing.Optional[str] = None ) → bool

参数

tag_name (str) — 要检查的标签名称。
remote (str, 可选) — 是否检查标签是否存在于远程。此参数应为远程的标识符。

返回

布尔值

标签是否存在。

检查标签是否存在。

wait_for_commands

( )

阻塞方法：阻塞所有后续执行，直到所有命令都已处理。

帮助方法

huggingface_hub.repository.is_git_repo

( folder: typing.Union[str, pathlib.Path] ) → bool

参数

folder (str) — 运行命令的文件夹。

返回

布尔值

如果存储库是存储库的一部分，则为 True，否则为 False。

检查文件夹是否为 git 存储库的根目录或一部分

huggingface_hub.repository.is_local_clone

( folder: typing.Union[str, pathlib.Path] remote_url: str ) → bool

参数

folder (str 或 Path) — 运行命令的文件夹。
remote_url (str) — Git 仓库的 URL。

返回

布尔值

如果仓库是指定远程仓库的本地克隆，则为 True，否则为 False。

检查文件夹是否是 remote_url 的本地克隆

huggingface_hub.repository.is_tracked_with_lfs

( filename: typing.Union[str, pathlib.Path] ) → bool

参数

filename (str 或 Path) — 要检查的文件名。

返回

布尔值

如果传入的文件使用 git-lfs 跟踪，则为 True，否则为 False。

检查传入的文件是否使用 git-lfs 跟踪。

huggingface_hub.repository.is_git_ignored

( filename: typing.Union[str, pathlib.Path] ) → bool

参数

filename (str 或 Path) — 要检查的文件名。

返回

布尔值

如果传入的文件被 git 忽略，则为 True，否则为 False。

检查文件是否被 git 忽略。支持嵌套的 .gitignore 文件。

huggingface_hub.repository.files_to_be_staged

( pattern: str = '.' folder: typing.Union[str, pathlib.Path, NoneType] = None ) → List[str]

参数

pattern (str 或 Path) — 要检查的文件名模式。输入 . 以获取所有文件。
folder (str 或 Path) — 运行命令的文件夹。

返回

List[str]

要暂存的文件列表。

返回要暂存的文件名列表。

huggingface_hub.repository.is_tracked_upstream

( folder: typing.Union[str, pathlib.Path] ) → bool

参数

folder (str 或 Path) — 运行命令的文件夹。

返回

布尔值

如果当前签出的分支被上游跟踪，则为 True，否则为 False。

检查当前签出的分支是否被上游跟踪。

huggingface_hub.repository.commits_to_push

( folder: typing.Union[str, pathlib.Path] upstream: typing.Optional[str] = None ) → int

参数

folder (str 或 Path) — 运行命令的文件夹。
upstream (str, 可选) —

返回

int

如果执行 `git push` 命令，将被推送到上游的提交数量。

检查将被推送到上游的提交数量

用于比较的上游仓库的名称。

跟踪异步命令

Repository 工具提供了几个可以异步启动的方法

git_push
git_pull
push_to_hub
commit 上下文管理器

有关管理此类异步实用程序的信息，请参阅下文。

class huggingface_hub.Repository

( local_dir: typing.Union[str, pathlib.Path] clone_from: typing.Optional[str] = None repo_type: typing.Optional[str] = None token: typing.Union[bool, str] = True git_user: typing.Optional[str] = None git_email: typing.Optional[str] = None revision: typing.Optional[str] = None skip_lfs_files: bool = False client: typing.Optional[huggingface_hub.hf_api.HfApi] = None )

用于包装 git 和 git-lfs 命令的辅助类。

目的是方便与 huggingface.co 托管的模型或数据集仓库进行交互，尽管这里（如果有的话）并没有多少是 huggingface.co 特有的。

Repository 已弃用，取而代之的是 HfApi 中实现的基于 HTTP 的替代方案。鉴于其在旧代码中的广泛采用，Repository 的完全移除只会在 v1.0 版本中进行。有关更多详细信息，请阅读 https://huggingface.co/docs/huggingface_hub/concepts/git_vs_http。

commands_failed

( )

返回失败的异步命令。

commands_in_progress

( )

返回当前正在进行的异步命令。

wait_for_commands

( )

阻塞方法：阻塞所有后续执行，直到所有命令都已处理。

class huggingface_hub.repository.CommandInProgress

( title: str is_done_method: typing.Callable status_method: typing.Callable process: Popen post_method: typing.Optional[typing.Callable] = None )

用于跟踪异步启动命令的实用程序。

< > 在 GitHub 上更新

←环境变量 Hugging Face Hub API→