Hub Python 库文档

管理本地和在线仓库

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

管理本地和在线仓库

Repository 类是一个辅助类,它封装了 gitgit-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 (strPath) — 本地目录的路径(例如 'my_trained_model/'),Repository 将在此处初始化。
  • clone_from (str, 可选) — 仓库 URL 或 repo_id。示例:
    • "https://huggingface.co/philschmid/playground-tests"
    • "philschmid/playground-tests"
  • repo_type (str, 可选) — 从 repo_id 克隆仓库时设置。默认为 model。
  • token (boolstr, 可选) — 有效的身份验证令牌(请参阅 https://huggingface.co/settings/token)。如果为 NoneTrue 且机器已登录(通过 huggingface-cli loginlogin()),则将从缓存中检索令牌。如果为 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

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

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

Repository 默认使用本地 git 凭据。如果显式设置,则将使用 tokengit_user/git_email 对。

current_branch

< >

( ) str

返回

str

当前检出的分支。

返回当前检出的分支。

add_tag

< >

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

参数

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

在当前头部添加标签并推送它

如果 remote 为 None,则仅在本地更新

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

auto_track_binary_files

< >

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

参数

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

返回

List[str]

由于成为二进制文件而被追踪的文件名列表

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

auto_track_large_files

< >

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

参数

  • pattern (str, optional, 默认为 ”.“) — 用于追踪大于 10MB 的文件的模式。

返回

List[str]

由于文件大小而被追踪的文件名列表。

使用 git-lfs 自动追踪大文件(重量超过 10MB 的文件)。

check_git_versions

< >

( )

引发

EnvironmentError

检查 gitgit-lfs 是否可以运行。

clone_from

< >

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

参数

  • repo_url (str) — 要克隆仓库的 URL
  • token (Union[str, bool], optional) — 是否使用身份验证令牌。它可以是:
    • 一个字符串,即令牌本身
    • False,表示不使用身份验证令牌
    • True,表示从本地文件夹获取身份验证令牌并使用它(您应该已登录才能使其工作)。
    • None,表示检索 self.huggingface_token 的值。

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

如果此文件夹是具有链接历史记录的 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, optional) — 将在其中显示提交的分支。此分支将在任何操作之前检出。
  • track_large_files (bool, optional, 默认为 True) — 是否自动追踪大文件。默认情况下会这样做。
  • blocking (bool, optional, 默认为 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, optional) — 要在其上删除标签的远程仓库。

返回

bool

如果已删除则返回 True,如果标签不存在则返回 False。 如果未传递 remote,则仅在本地更新

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

git_add

< >

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

参数

  • pattern (str, optional, 默认为 ”.“) — 用于将文件添加到暂存区的模式。
  • auto_lfs_track (bool, optional, 默认为 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, optional, 默认为 False) — 如果 revision 不是现有版本,是否允许在当前检出引用处创建以传递的 revision 命名的分支。

git checkout 给定版本

如果指定 create_branch_okTrue,如果该版本不存在,则会创建到给定版本的分支。

git_commit

< >

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

参数

  • commit_message (str, optional, 默认为 “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, optional) — 通过 git 注册的用户名。
  • git_email (str, optional) — 通过 git 注册的电子邮件。

设置 git 用户名和电子邮件(仅在当前仓库中)。

git_credential_helper_store

< >

( )

将 git 凭据助手设置为 store

git_head_commit_url

< >

( ) str

返回

str

当前检出提交的 URL。

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

git_head_hash

< >

( ) str

返回

str

当前检出的提交 SHA。

获取 HEAD 顶部的提交 SHA。

git_pull

< >

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

参数

  • rebase (bool, optional, defaults to False) — 是否在获取后将当前分支变基到上游分支之上。
  • lfs (bool, optional, defaults to 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, optional) — 要推送到的上游。如果未指定,将推送到最后定义的上游或默认上游 (origin main)。
  • blocking (bool, optional, defaults to True) — 函数是否应仅在推送完成后返回。 将此项设置为 False 将返回一个 CommandInProgress 对象,该对象具有 is_done 属性。 此属性将在推送完成时设置为 True
  • auto_lfs_prune (bool, optional, defaults to False) — 是否在文件推送到远程后自动修剪文件。

git push

如果使用时不设置 blocking,将返回远程仓库上提交的 URL。 如果使用 blocking=True,将返回一个元组,其中包含提交的 URL 和命令对象,以便跟踪有关该过程的信息。

git_remote_url

< >

( ) str

返回

str

origin 远程仓库的 URL。

获取 origin 远程仓库的 URL。

is_repo_clean

< >

( ) bool

返回

bool

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

返回 git 状态是否干净

lfs_enable_largefiles

< >

( )

HF 专用。 这启用了大于 5GB 的文件上传支持。

lfs_prune

< >

( recent = False )

参数

  • recent (bool, optional, defaults to 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, optional, defaults to False) — 是否将模式用作文字文件名。

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

filename 参数设置为 True 会将参数视为文字文件名,而不是模式。 写入 .gitattributes 文件时,文件名中的任何特殊 glob 字符都将被转义。

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, 可选) — 是否检查标签是否存在于远程仓库中。此参数应为远程仓库的标识符。

返回

bool

标签是否存在。

检查标签是否存在。

wait_for_commands

< >

( )

阻塞方法:阻塞所有后续执行,直到所有命令都已处理完毕。

辅助方法

huggingface_hub.repository.is_git_repo

< >

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

参数

  • folder (str) — 要在其中运行命令的文件夹。

返回

bool

如果仓库是 git 仓库的一部分,则返回 True,否则返回 False

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

huggingface_hub.repository.is_local_clone

< >

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

参数

  • folder (str or Path) — 要在其中运行命令的文件夹。
  • remote_url (str) — git 仓库的 url。

返回

bool

如果仓库是指定远程仓库的本地克隆,则返回 True,否则返回 False

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

huggingface_hub.repository.is_tracked_with_lfs

< >

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

参数

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

返回

bool

如果传递的文件通过 git-lfs 跟踪,则返回 True,否则返回 False

检查传递的文件是否通过 git-lfs 跟踪。

huggingface_hub.repository.is_git_ignored

< >

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

参数

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

返回

bool

如果传递的文件被 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 or Path) — 要检查的文件名模式。输入 . 以获取所有文件。
  • folder (str or Path) — 要在其中运行命令的文件夹。

返回

List[str]

要暂存的文件列表。

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

huggingface_hub.repository.is_tracked_upstream

< >

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

参数

  • folder (str or Path) — 要在其中运行命令的文件夹。

返回

bool

如果当前检出的分支已在上游跟踪,则返回 True,否则返回 False

检查当前检出的分支是否已在上游跟踪。

huggingface_hub.repository.commits_to_push

< >

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

参数

  • folder (str or 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 上更新