Hub Python 库文档

HfApi 客户端

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

HfApi 客户端

以下是 HfApi 类的文档,它是 Hugging Face Hub API 的 Python 包装器。

HfApi 的所有方法也可以直接从包的根目录访问。下面详细介绍了这两种方法。

使用根方法更直接,但 HfApi 类为您提供了更大的灵活性。特别是,您可以传递一个令牌,该令牌将在所有 HTTP 调用中重复使用。这与 hf auth loginlogin() 不同,因为令牌不会持久化到机器上。还可以提供不同的端点或配置自定义的用户代理。

from huggingface_hub import HfApi, list_models

# Use root method
models = list_models()

# Or configure a HfApi client
hf_api = HfApi(
    endpoint="https://huggingface.co", # Can be a Private Hub endpoint.
    token="hf_xxx", # Token is not persisted on the machine.
)
models = hf_api.list_models()

HfApi

class huggingface_hub.HfApi

< >

( endpoint: Optional[str] = None token: Union[str, bool, None] = None library_name: Optional[str] = None library_version: Optional[str] = None user_agent: Union[Dict, str, None] = None headers: Optional[Dict[str, str]] = None )

参数

  • endpoint (str, 可选) — Hub 的端点。默认为 https://huggingface.co
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌 (字符串)。默认为本地保存的令牌,这是推荐的身份验证方法 (参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • library_name (str, 可选) — 发出 HTTP 请求的库的名称。将被添加到用户代理头中。例如:"transformers"
  • library_version (str, 可选) — 发出 HTTP 请求的库的版本。将被添加到用户代理头中。例如:"4.24.0"
  • user_agent (str, dict, 可选) — 用户代理信息,可以是字典或单个字符串形式。它将补充已安装软件包的信息。
  • headers (dict, 可选) — 每次请求时发送的附加标头。例如:{"X-My-Header": "value"}。此处传递的标头优先于默认标头。

通过 HTTP 与 Hugging Face Hub 交互的客户端。

客户端在初始化时会设置一些高级配置,这些配置将用于所有对 Hub 的请求(HF 端点、身份验证、用户代理等)。推荐使用 HfApi 客户端,但不是强制性的,因为其所有公共方法都直接暴露在 huggingface_hub 的根目录下。

accept_access_request

< >

( repo_id: str user: str repo_type: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • repo_id (str) — 要接受访问请求的仓库 ID。
  • user (str) — 应接受其访问请求的用户的用户名。
  • repo_type (str, 可选) — 要接受访问请求的仓库类型。必须是 modeldatasetspace 之一。默认为 model
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌 (字符串)。默认为本地保存的令牌,这是推荐的身份验证方法 (参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

引发

HTTPError

  • HTTPError — 如果仓库未设门控,则返回 HTTP 400。
  • HTTPError — 如果您对仓库只有只读权限,则返回 HTTP 403。如果您在仓库所属的组织中没有 writeadmin 角色,或者您传递了 read 令牌,则可能会发生这种情况。
  • HTTPError — 如果 Hub 上不存在该用户,则返回 HTTP 404。
  • HTTPError — 如果找不到该用户的访问请求,则返回 HTTP 404。
  • HTTPError — 如果该用户的访问请求已在接受列表中,则返回 HTTP 404。

接受用户对给定门控仓库的访问请求。

请求被接受后,用户将能够下载仓库的任何文件并访问社区选项卡。如果审批模式是自动的,则无需手动接受请求。已接受的请求可以随时使用 cancel_access_request()reject_access_request() 取消或拒绝。

有关门控仓库的更多信息,请参阅 https://huggingface.co/docs/hub/models-gated

add_collection_item

< >

( collection_slug: str item_id: str item_type: CollectionItemType_T note: Optional[str] = None exists_ok: bool = False token: Union[bool, str, None] = None )

参数

  • collection_slug (str) — 要更新的收藏集的 slug。例如:"TheBloke/recent-models-64f9a55bb3115b4f513ec026"
  • item_id (str) — 要添加到收藏集的项目 ID。它可以是 Hub 上仓库的 ID (例如 "facebook/bart-large-mnli") 或论文 ID (例如 "2307.09288")。
  • item_type (str) — 要添加的项目的类型。可以是 "model""dataset""space""paper" 之一。
  • note (str, 可选) — 附加到收藏集中项目的注释。注释的最大长度为 500 个字符。
  • exists_ok (bool, 可选) — 如果为 True,则在项目已存在时不会引发错误。
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌 (字符串)。默认为本地保存的令牌,这是推荐的身份验证方法 (参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

引发

HTTPError

  • HTTPError — 如果您对仓库只有只读权限,则返回 HTTP 403。如果您在仓库所属的组织中没有 writeadmin 角色,或者您传递了 read 令牌,则可能会发生这种情况。
  • HTTPError — 如果您尝试添加到收藏集的项目在 Hub 上不存在,则返回 HTTP 404。
  • HTTPError — 如果您尝试添加到收藏集的项目已在该收藏集中(且 exists_ok=False),则返回 HTTP 409。

向 Hub 上的收藏集添加一个项目。

返回: Collection

示例

>>> from huggingface_hub import add_collection_item
>>> collection = add_collection_item(
...     collection_slug="davanstrien/climate-64f99dc2a5067f6b65531bab",
...     item_id="pierre-loic/climate-news-articles",
...     item_type="dataset"
... )
>>> collection.items[-1].item_id
"pierre-loic/climate-news-articles"
# ^item got added to the collection on last position

# Add item with a note
>>> add_collection_item(
...     collection_slug="davanstrien/climate-64f99dc2a5067f6b65531bab",
...     item_id="datasets/climate_fever",
...     item_type="dataset"
...     note="This dataset adopts the FEVER methodology that consists of 1,535 real-world claims regarding climate-change collected on the internet."
... )
(...)

add_space_secret

< >

( repo_id: str key: str value: str description: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • repo_id (str) — 要更新的仓库 ID。例如:"bigcode/in-the-stack"
  • key (str) — 密钥键。例如:"GITHUB_API_KEY"
  • value (str) — 密钥值。例如:"your_github_api_key"
  • description (str, 可选) — 密钥描述。例如:"用于访问 Github API 的 Github API 密钥"
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌 (字符串)。默认为本地保存的令牌,这是推荐的身份验证方法 (参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

在 Space 中添加或更新一个密钥。

密钥允许您向 Space 设置密钥或令牌,而无需对其进行硬编码。更多详情,请参阅 https://huggingface.co/docs/hub/spaces-overview#managing-secrets

add_space_variable

< >

( repo_id: str key: str value: str description: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • repo_id (str) — 要更新的仓库 ID。例如:"bigcode/in-the-stack"
  • key (str) — 变量键。例如:"MODEL_REPO_ID"
  • value (str) — 变量值。例如:"the_model_repo_id"
  • description (str) — 变量的描述。例如:"所实现模型的模型仓库 ID"
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌 (字符串)。默认为本地保存的令牌,这是推荐的身份验证方法 (参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

在 Space 中添加或更新一个变量。

变量允许您向 Space 设置环境变量,而无需对其进行硬编码。更多详情,请参阅 https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables

auth_check

< >

( repo_id: str repo_type: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • repo_id (str) — 要检查访问权限的仓库。格式应为 "user/repo_name"。例如:"user/my-cool-model"
  • repo_type (str, 可选) — 仓库的类型。应为 "model""dataset""space" 之一。如果未指定,默认为 "model"
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌。如果未提供,将使用本地保存的令牌,这是推荐的身份验证方法。设置为 False 以禁用身份验证。参考:https://huggingface.co/docs/huggingface_hub/quick-start#authentication

引发

RepositoryNotFoundErrorGatedRepoError

  • RepositoryNotFoundError — 如果仓库不存在、是私有的,或者用户没有访问权限,则会引发此异常。如果 repo_idrepo_type 不正确,或者仓库是私有的但用户未进行身份验证,则可能发生这种情况。

  • GatedRepoError — 如果仓库存在但设置了门控,并且用户无权访问,则会引发此异常。

检查提供的用户令牌是否对 Hugging Face Hub 上的特定仓库具有访问权限。

此方法验证通过提供的令牌进行身份验证的用户是否对指定的仓库具有访问权限。如果找不到仓库或用户缺少访问所需的权限,该方法将引发相应的异常。

示例

检查用户是否有权访问仓库

>>> from huggingface_hub import auth_check
>>> from huggingface_hub.utils import GatedRepoError, RepositoryNotFoundError

try:
    auth_check("user/my-cool-model")
except GatedRepoError:
    # Handle gated repository error
    print("You do not have permission to access this gated repository.")
except RepositoryNotFoundError:
    # Handle repository not found error
    print("The repository was not found or you do not have access.")

在这个例子中

  • 如果用户有访问权限,该方法将成功完成。
  • 如果仓库设置了门控或不存在,将引发相应的异常,允许用户进行相应处理。

cancel_access_request

< >

( repo_id: str user: str repo_type: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • repo_id (str) — 要取消访问请求的仓库 ID。
  • user (str) — 应取消其访问请求的用户的用户名。
  • repo_type (str, 可选) — 要取消访问请求的仓库类型。必须是 modeldatasetspace 之一。默认为 model
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

引发

HTTPError

  • HTTPError — 如果仓库未设门控,则返回 HTTP 400。
  • HTTPError — 如果您对仓库只有只读权限,则返回 HTTP 403。如果您在仓库所属的组织中没有 writeadmin 角色,或者您传递了 read 令牌,则可能会发生这种情况。
  • HTTPError — 如果 Hub 上不存在该用户,则返回 HTTP 404。
  • HTTPError — 如果找不到该用户的访问请求,则返回 HTTP 404。
  • HTTPError — 如果用户访问请求已在待处理列表中,则返回 HTTP 404。

取消用户对给定受限仓库的访问请求。

已取消的请求将返回到待处理列表,用户将失去对仓库的访问权限。

有关门控仓库的更多信息,请参阅 https://huggingface.co/docs/hub/models-gated

cancel_job

< >

( job_id: str namespace: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • job_id (str) — 作业的 ID。
  • namespace (str, 可选) — 作业运行的命名空间。默认为当前用户的命名空间。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌。如果未提供,将使用本地保存的令牌,这是推荐的身份验证方法。设置为 False 以禁用身份验证。请参阅:https://huggingface.co/docs/huggingface_hub/quick-start#authentication

取消 Hugging Face 基础设施上的计算作业。

change_discussion_status

< >

( repo_id: str discussion_num: int new_status: Literal['open', 'closed'] token: Union[bool, str, None] = None comment: Optional[str] = None repo_type: Optional[str] = None ) DiscussionStatusChange

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个仓库名称,用 / 分隔。
  • discussion_num (int) — 讨论或拉取请求的编号。必须是严格的正整数。
  • new_status (str) — 讨论的新状态,可以是 "open""closed"
  • comment (str, 可选) — 一个可选的评论,随状态更改一起发布。
  • repo_type (str, 可选) — 如果上传到数据集或空间,设置为 "dataset""space";如果上传到模型,则为 None"model"。默认为 None
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

DiscussionStatusChange

状态更改事件

关闭或重新打开一个讨论或拉取请求。

示例

>>> new_title = "New title, fixing a typo"
>>> HfApi().rename_discussion(
...     repo_id="username/repo_name",
...     discussion_num=34
...     new_title=new_title
... )
# DiscussionStatusChange(id='deadbeef0000000', type='status-change', ...)

引发以下错误

  • HTTPError 如果 HuggingFace API 返回错误
  • ValueError 如果某些参数值无效
  • RepositoryNotFoundError 如果找不到要下载的仓库。这可能是因为它不存在,或者是私有仓库而您没有访问权限。

comment_discussion

< >

( repo_id: str discussion_num: int comment: str token: Union[bool, str, None] = None repo_type: Optional[str] = None ) DiscussionComment

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个仓库名称,用 / 分隔。
  • discussion_num (int) — 讨论或拉取请求的编号。必须是严格的正整数。
  • comment (str) — 要创建的评论内容。评论支持 Markdown 格式。
  • repo_type (str, 可选) — 如果上传到数据集或空间,设置为 "dataset""space";如果上传到模型,则为 None"model"。默认为 None
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

DiscussionComment

新创建的评论

在给定的讨论中创建一条新评论。

示例


>>> comment = """
... Hello @otheruser!
...
... # This is a title
...
... **This is bold**, *this is italic* and ~this is strikethrough~
... And [this](http://url) is a link
... """

>>> HfApi().comment_discussion(
...     repo_id="username/repo_name",
...     discussion_num=34
...     comment=comment
... )
# DiscussionComment(id='deadbeef0000000', type='comment', ...)

引发以下错误

  • HTTPError 如果 HuggingFace API 返回错误
  • ValueError 如果某些参数值无效
  • RepositoryNotFoundError 如果找不到要下载的仓库。这可能是因为它不存在,或者是私有仓库而您没有访问权限。

create_branch

< >

( repo_id: str branch: str revision: Optional[str] = None token: Union[bool, str, None] = None repo_type: Optional[str] = None exist_ok: bool = False )

参数

  • repo_id (str) — 将在其中创建分支的仓库。例如:"user/my-cool-model"
  • branch (str) — 要创建的分支的名称。
  • revision (str, 可选) — 从其创建分支的 git 修订版本。可以是一个分支名称或提交的 OID/SHA,以十六进制字符串表示。默认为 "main" 分支的头部。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, 可选) — 如果在数据集或空间上创建分支,则设置为 "dataset""space";如果为模型打标签,则为 None"model"。默认为 None
  • exist_ok (bool, 可选, 默认为 False) — 如果为 True,则如果分支已存在,不引发错误。

引发

RepositoryNotFoundErrorBadRequestErrorHfHubHTTPError

  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type,私有仓库但未认证,或仓库不存在。
  • BadRequestError — 如果分支的引用无效。例如:refs/pr/5 或 ‘refs/foo/bar’。
  • HfHubHTTPError — 如果分支已存在于仓库中(错误 409)且 exist_ok 设置为 False

在 Hub 上为仓库创建一个新分支,从指定的修订版本开始(默认为 main)。要找到适合您需求的分支,您可以使用 list_repo_refs()list_repo_commits()

create_collection

< >

( title: str namespace: Optional[str] = None description: Optional[str] = None private: bool = False exists_ok: bool = False token: Union[bool, str, None] = None )

参数

  • title (str) — 要创建的收藏集的标题。例如:"Recent models"
  • namespace (str, 可选) — 要创建的收藏集的命名空间(用户名或组织)。将默认为所有者名称。
  • description (str, 可选) — 要创建的收藏集的描述。
  • private (bool, 可选) — 收藏集是否应为私有。默认为 False(即公共收藏集)。
  • exists_ok (bool, 可选) — 如果为 True,则如果收藏集已存在,不引发错误。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

在 Hub 上创建一个新的收藏集。

返回: Collection

示例

>>> from huggingface_hub import create_collection
>>> collection = create_collection(
...     title="ICCV 2023",
...     description="Portfolio of models, papers and demos I presented at ICCV 2023",
... )
>>> collection.slug
"username/iccv-2023-64f9a55bb3115b4f513ec026"

create_commit

< >

( repo_id: str operations: Iterable[CommitOperation] commit_message: str commit_description: Optional[str] = None token: Union[str, bool, None] = None repo_type: Optional[str] = None revision: Optional[str] = None create_pr: Optional[bool] = None num_threads: int = 5 parent_commit: Optional[str] = None run_as_future: bool = False ) CommitInfo or Future

参数

  • repo_id (str) — 将在其中创建提交的仓库,例如:"username/custom_transformers"
  • operations (Iterable of CommitOperation()) — 一个包含在提交中的操作的可迭代对象,可以是:

    操作对象将被修改以包含与上传相关的信息。请勿对多个提交重复使用相同的对象。

  • commit_message (str) — 将创建的提交的摘要(第一行)。
  • commit_description (str, 可选) — 将创建的提交的描述
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, 可选) — 如果上传到数据集或空间,设置为 "dataset""space";如果上传到模型,则为 None"model"。默认为 None
  • revision (str, 可选) — 从其提交的 git 修订版本。默认为 "main" 分支的头部。
  • create_pr (boolean, 可选) — 是否使用该提交创建一个拉取请求。默认为 False。如果 revision 未设置,则针对 "main" 分支打开 PR。如果设置了 revision 并且它是一个分支,则针对此分支打开 PR。如果设置了 revision 但不是一个分支名称(例如:提交 oid),服务器将返回 RevisionNotFoundError
  • num_threads (int, 可选) — 用于上传文件的并发线程数。默认为 5。将其设置为 2 意味着最多可以同时上传 2 个文件。
  • parent_commit (str, 可选) — 父提交的 OID / SHA,以十六进制字符串表示。也支持简写(前 7 个字符)。如果指定且 create_prFalse,则如果 revision 未指向 parent_commit,提交将失败。如果指定且 create_prTrue,则将从 parent_commit 创建拉取请求。指定 parent_commit 可确保在提交更改之前仓库没有发生变化,这在仓库被并发更新/提交时特别有用。
  • run_as_future (bool, 可选) — 是否在后台运行此方法。后台作业按顺序运行,不会阻塞主线程。传递 run_as_future=True 将返回一个 Future 对象。默认为 False

返回

CommitInfo or Future

CommitInfo 的实例,包含有关新创建的提交的信息(提交哈希、提交 URL、PR URL、提交消息……)。如果传递了 run_as_future=True,则返回一个 Future 对象,执行后将包含结果。

引发

ValueErrorRepositoryNotFoundError

  • ValueError — 如果提交消息为空。
  • ValueError — 如果父提交不是有效的提交 OID。
  • ValueError — 如果提交了一个带有无效元数据部分的 README.md 文件。在这种情况下,提交将提前失败,不会尝试上传任何文件。
  • ValueError — 如果 create_prTrue 且 revision 既不是 None 也不是 "main"
  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type,私有仓库但未认证,或仓库不存在。

在给定的仓库中创建一个提交,根据需要删除和上传文件。

输入的 CommitOperation 列表将在提交过程中被修改。请勿对多个提交重复使用相同的对象。

create_commit 假定仓库已存在于 Hub 上。如果您遇到客户端 404 错误,请确保您已通过身份验证,并且 repo_idrepo_type 设置正确。如果仓库不存在,请先使用 create_repo() 创建它。

create_commit 对于 LFS 文件限制为 25k 个,对于常规文件限制为 1GB 的有效载荷。

create_discussion

< >

( repo_id: str title: str token: Union[bool, str, None] = None description: Optional[str] = None repo_type: Optional[str] = None pull_request: bool = False )

参数

  • repo_id (str) — 命名空间(用户或组织)和仓库名称,以 / 分隔。
  • title (str) — 讨论的标题。长度最多可达 200 个字符,且必须至少为 3 个字符。首尾的空白字符将被去除。
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • description (str, 可选) — 拉取请求的可选描述。默认为 "Discussion opened with the huggingface_hub Python library"
  • pull_request (bool, 可选) — 是创建拉取请求还是讨论。如果为 True,则创建拉取请求。如果为 False,则创建讨论。默认为 False
  • repo_type (str, 可选) — 如果上传到数据集或空间,设置为 "dataset""space";如果上传到模型,则为 None"model"。默认为 None

创建讨论或拉取请求。

以编程方式创建的拉取请求将处于 "draft"(草稿)状态。

也可以使用 HfApi.create_commit() 一次性创建带有更改的拉取请求。

返回:DiscussionWithDetails

引发以下错误

  • HTTPError 如果 HuggingFace API 返回错误
  • ValueError 如果某些参数值无效
  • RepositoryNotFoundError 如果找不到要下载的仓库。这可能是因为它不存在,或者是私有仓库而您没有访问权限。

create_inference_endpoint

< >

( name: str repository: str framework: str accelerator: str instance_size: str instance_type: str region: str vendor: str account_id: Optional[str] = None min_replica: int = 1 max_replica: int = 1 scale_to_zero_timeout: Optional[int] = None revision: Optional[str] = None task: Optional[str] = None custom_image: Optional[Dict] = None env: Optional[Dict[str, str]] = None secrets: Optional[Dict[str, str]] = None type: InferenceEndpointType = <InferenceEndpointType.PROTECTED: 'protected'> domain: Optional[str] = None path: Optional[str] = None cache_http_responses: Optional[bool] = None tags: Optional[List[str]] = None namespace: Optional[str] = None token: Union[bool, str, None] = None ) InferenceEndpoint

参数

  • name (str) — 新建推理端点的唯一名称。
  • repository (str) — 与推理端点关联的模型仓库名称(例如 "gpt2")。
  • framework (str) — 模型使用的机器学习框架(例如 "custom")。
  • accelerator (str) — 用于推理的硬件加速器(例如 "cpu")。
  • instance_size (str) — 用于托管模型的实例的大小或类型(例如 "x4")。
  • instance_type (str) — 将部署推理端点的云实例类型(例如 "intel-icl")。
  • region (str) — 将创建推理端点的云区域(例如 "us-east-1")。
  • vendor (str) — 托管推理端点的云提供商或供应商(例如 "aws")。
  • account_id (str, 可选) — 用于将 VPC 链接到私有推理端点的账户 ID(如果适用)。
  • min_replica (int, 可选) — 为推理端点保持运行的最小副本(实例)数。要启用缩减至零,请将此值设置为 0 并相应调整 scale_to_zero_timeout。默认为 1。
  • max_replica (int, 可选) — 推理端点可扩展到的最大副本(实例)数。默认为 1。
  • scale_to_zero_timeout (int, 可选) — 不活动的端点缩减至零之前的持续时间(分钟),如果设置为 None 且 min_replica 不为 0,则不缩减至零。默认为 None。
  • revision (str, 可选) — 要在推理端点上部署的特定模型版本(例如 "6c0e6080953db56375760c0471a8c5f2929baf11")。
  • task (str, 可选) — 部署模型的任务(例如 "text-classification")。
  • custom_image (Dict, 可选) — 用于推理端点的自定义 Docker 镜像。如果您想部署一个运行在 text-generation-inference (TGI) 框架上的推理端点,这将非常有用(请参阅示例)。
  • env (Dict[str, str], 可选) — 注入到容器环境中的非机密环境变量。
  • secrets (Dict[str, str], 可选) — 注入到容器环境中的机密值。
  • type ([`InferenceEndpointType], *可选*) -- 推理端点的类型,可以是 “protected”(默认)、“public”“private”`。
  • domain (str, 可选) — 推理端点部署的自定义域名,如果设置,推理端点将在此域名上可用(例如 "my-new-domain.cool-website.woof")。
  • path (str, 可选) — 已部署模型的自定义路径,应以 / 开头(例如 "/models/google-bert/bert-base-uncased")。
  • cache_http_responses (bool, 可选) — 是否缓存来自推理端点的 HTTP 响应。默认为 False
  • tags (List[str], 可选) — 与推理端点关联的标签列表。
  • namespace (str, 可选) — 将创建推理端点的命名空间。默认为当前用户的命名空间。
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

InferenceEndpoint

有关更新后的推理端点的信息。

创建一个新的推理端点。

示例

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.create_inference_endpoint(
...     "my-endpoint-name",
...     repository="gpt2",
...     framework="pytorch",
...     task="text-generation",
...     accelerator="cpu",
...     vendor="aws",
...     region="us-east-1",
...     type="protected",
...     instance_size="x2",
...     instance_type="intel-icl",
... )
>>> endpoint
InferenceEndpoint(name='my-endpoint-name', status="pending",...)

# Run inference on the endpoint
>>> endpoint.client.text_generation(...)
"..."
# Start an Inference Endpoint running Zephyr-7b-beta on TGI
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.create_inference_endpoint(
...     "aws-zephyr-7b-beta-0486",
...     repository="HuggingFaceH4/zephyr-7b-beta",
...     framework="pytorch",
...     task="text-generation",
...     accelerator="gpu",
...     vendor="aws",
...     region="us-east-1",
...     type="protected",
...     instance_size="x1",
...     instance_type="nvidia-a10g",
...     env={
...           "MAX_BATCH_PREFILL_TOKENS": "2048",
...           "MAX_INPUT_LENGTH": "1024",
...           "MAX_TOTAL_TOKENS": "1512",
...           "MODEL_ID": "/repository"
...         },
...     custom_image={
...         "health_route": "/health",
...         "url": "ghcr.io/huggingface/text-generation-inference:1.1.0",
...     },
...    secrets={"MY_SECRET_KEY": "secret_value"},
...    tags=["dev", "text-generation"],
... )
# Start an Inference Endpoint running ProsusAI/finbert while scaling to zero in 15 minutes
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.create_inference_endpoint(
...     "finbert-classifier",
...     repository="ProsusAI/finbert",
...     framework="pytorch",
...     task="text-classification",
...     min_replica=0,
...     scale_to_zero_timeout=15,
...     accelerator="cpu",
...     vendor="aws",
...     region="us-east-1",
...     type="protected",
...     instance_size="x2",
...     instance_type="intel-icl",
... )
>>> endpoint.wait(timeout=300)
# Run inference on the endpoint
>>> endpoint.client.text_generation(...)
TextClassificationOutputElement(label='positive', score=0.8983615040779114)

create_inference_endpoint_from_catalog

< >

( repo_id: str name: Optional[str] = None token: Union[bool, str, None] = None namespace: Optional[str] = None ) InferenceEndpoint

参数

  • repo_id (str) — 目录中要部署为推理端点的模型的 ID。
  • name (str, 可选) — 新建推理端点的唯一名称。如果未提供,将生成一个随机名称。
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。
  • namespace (str, 可选) — 将创建推理端点的命名空间。默认为当前用户的命名空间。

返回

InferenceEndpoint

有关新建推理端点的信息。

从 Hugging Face 推理目录中的模型创建一个新的推理端点。

推理目录的目标是提供一个经过筛选的模型列表,这些模型已针对推理进行了优化,并且其默认配置已经过测试。有关目录中可用模型的列表,请参见 https://endpoints.huggingface.co/catalog

create_inference_endpoint_from_catalog 是实验性的。其 API 将来可能会更改。如果您有任何建议或请求,请提供反馈。

create_pull_request

< >

( repo_id: str title: str token: Union[bool, str, None] = None description: Optional[str] = None repo_type: Optional[str] = None )

参数

  • repo_id (str) — 命名空间(用户或组织)和仓库名称,以 / 分隔。
  • title (str) — 讨论的标题。长度最多可达 200 个字符,且必须至少为 3 个字符。首尾的空白字符将被去除。
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • description (str, 可选) — 拉取请求的可选描述。默认为 "Discussion opened with the huggingface_hub Python library"
  • repo_type (str, 可选) — 如果上传到数据集或空间,设置为 "dataset""space";如果上传到模型,则为 None"model"。默认为 None

创建一个拉取请求。以编程方式创建的拉取请求将处于 "draft"(草稿)状态。

也可以使用 HfApi.create_commit() 一次性创建带有更改的拉取请求;

这是 HfApi.create_discussion() 的一个封装。

返回:DiscussionWithDetails

引发以下错误

  • HTTPError 如果 HuggingFace API 返回错误
  • ValueError 如果某些参数值无效
  • RepositoryNotFoundError 如果找不到要下载的仓库。这可能是因为它不存在,或者是私有仓库而您没有访问权限。

create_repo

< >

( repo_id: str token: Union[str, bool, None] = None private: Optional[bool] = None repo_type: Optional[str] = None exist_ok: bool = False resource_group_id: Optional[str] = None space_sdk: Optional[str] = None space_hardware: Optional[SpaceHardware] = None space_storage: Optional[SpaceStorage] = None space_sleep_time: Optional[int] = None space_secrets: Optional[List[Dict[str, str]]] = None space_variables: Optional[List[Dict[str, str]]] = None ) RepoUrl

参数

  • repo_id (str) — 命名空间(用户或组织)和仓库名称,以 / 分隔。
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • private (bool, 可选) — 是否将仓库设为私有。如果为 None(默认),仓库将为公开,除非组织的默认设置为私有。如果仓库已存在,此值将被忽略。
  • repo_type (str, 可选) — 如果上传到数据集或空间,设置为 "dataset""space";如果上传到模型,则为 None"model"。默认为 None
  • exist_ok (bool, 可选, 默认为 False) — 如果为 True,则在仓库已存在时不引发错误。
  • resource_group_id (str, 可选) — 创建仓库的资源组。资源组仅适用于企业版 Hub 组织,用于定义组织中哪些成员可以访问该资源。资源组的 ID 可以在 Hub 上该资源的页面 URL 中找到(例如 "66670e5163145ca562cb1988")。要了解有关资源组的更多信息,请参阅 https://huggingface.co/docs/hub/en/security-resource-groups
  • space_sdk (str, 可选) — 如果 repo_type 是 “space”,则选择要使用的 SDK。可以是 “streamlit”、“gradio”、“docker” 或 “static”。
  • space_hardware (SpaceHardwarestr, 可选) — 如果 repo_type 是 “space”,则选择硬件。完整列表请参阅 SpaceHardware
  • space_storage (SpaceStoragestr, 可选) — 持久化存储层的选择。示例:"small"。完整列表请参阅 SpaceStorage
  • space_sleep_time (int, 可选) — 在 Space 进入休眠状态之前等待的非活动秒数。如果你不希望你的 Space 休眠,请设置为 -1(升级硬件的默认行为)。对于免费硬件,你无法配置休眠时间(固定为 48 小时不活动)。更多详情请参阅 https://huggingface.co/docs/hub/spaces-gpus#sleep-time
  • space_secrets (List[Dict[str, str]], 可选) — 在你的 Space 中设置的私密密钥列表。每个项目都采用 {"key": ..., "value": ..., "description": ...} 的形式,其中 description 是可选的。更多详情请参阅 https://huggingface.co/docs/hub/spaces-overview#managing-secrets
  • space_variables (List[Dict[str, str]], 可选) — 在你的 Space 中设置的公共环境变量列表。每个项目都采用 {"key": ..., "value": ..., "description": ...} 的形式,其中 description 是可选的。更多详情请参阅 https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables

返回

RepoUrl

新创建仓库的 URL。该值是 str 的子类,包含 endpointrepo_typerepo_id 等属性。

在 HuggingFace Hub 上创建一个空仓库。

create_tag

< >

( repo_id: str tag: str tag_message: Optional[str] = None revision: Optional[str] = None token: Union[bool, str, None] = None repo_type: Optional[str] = None exist_ok: bool = False )

参数

  • repo_id (str) — 将为其提交添加标签的仓库。示例:"user/my-cool-model"
  • tag (str) — 要创建的标签的名称。
  • tag_message (str, 可选) — 要创建的标签的描述。
  • revision (str, 可选) — 要标记的 git 版本。可以是一个分支名,也可以是提交的 OID/SHA 的十六进制字符串。也支持缩写(前 7 个字符)。默认为 "main" 分支的头部。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, 可选) — 如果要给数据集或 Space 打标签,则设置为 "dataset""space";如果要给模型打标签,则为 None"model"。默认为 None
  • exist_ok (bool, 可选, 默认为 False) — 如果为 True,当标签已存在时,不引发错误。

引发

RepositoryNotFoundErrorRevisionNotFoundErrorHfHubHTTPError

  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type,私有仓库但未认证,或仓库不存在。
  • RevisionNotFoundError — 如果在仓库中找不到版本(错误 404)。
  • HfHubHTTPError — 如果分支已存在于仓库中(错误 409)且 exist_ok 设置为 False

为 Hub 上的仓库的给定提交添加标签。

create_webhook

< >

( url: str watched: List[Union[Dict, WebhookWatchedItem]] domains: Optional[List[constants.WEBHOOK_DOMAIN_T]] = None secret: Optional[str] = None token: Union[bool, str, None] = None ) WebhookInfo

参数

  • url (str) — 用于发送负载的 URL。
  • watched (List[WebhookWatchedItem]) — Webhook 将监视的 WebhookWatchedItem 列表。可以是用户、组织、模型、数据集或 Spaces。监视的项目也可以作为普通字典提供。
  • domains (List[Literal["repo", "discussion"]], 可选) — 要监视的域列表。可以是 “repo”、“discussion” 或两者。
  • secret (str, 可选) — 用于签署负载的密钥。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

WebhookInfo

关于新创建的 webhook 的信息。

创建一个新的 webhook。

示例

>>> from huggingface_hub import create_webhook
>>> payload = create_webhook(
...     watched=[{"type": "user", "name": "julien-c"}, {"type": "org", "name": "HuggingFaceH4"}],
...     url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
...     domains=["repo", "discussion"],
...     secret="my-secret",
... )
>>> print(payload)
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    domains=["repo", "discussion"],
    secret="my-secret",
    disabled=False,
)

dataset_info

< >

( repo_id: str revision: Optional[str] = None timeout: Optional[float] = None files_metadata: bool = False expand: Optional[List[ExpandDatasetProperty_T]] = None token: Union[bool, str, None] = None ) hf_api.DatasetInfo

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个由 / 分隔的仓库名称。
  • revision (str, 可选) — 数据集仓库的版本,用于获取信息。
  • timeout (float, 可选) — 是否为向 Hub 的请求设置超时。
  • files_metadata (bool, 可选) — 是否检索仓库中文件的元数据(大小、LFS 元数据等)。默认为 False
  • expand (List[ExpandDatasetProperty_T], 可选) — 在响应中返回的属性列表。使用时,只有列表中的属性会被返回。如果传入了 files_metadata,则不能使用此参数。可能的值有 "author""cardData""citation""createdAt""disabled""description""downloads""downloadsAllTime""gated""lastModified""likes""paperswithcode_id""private""siblings""sha""tags""trendingScore""usedStorage""resourceGroup""xetEnabled"
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

hf_api.DatasetInfo

数据集仓库信息。

获取 huggingface.co 上某个特定数据集的信息。

如果传递了可接受的令牌,数据集可以是私有的。

引发以下错误

delete_branch

< >

( repo_id: str branch: str token: Union[bool, str, None] = None repo_type: Optional[str] = None )

参数

  • repo_id (str) — 将删除分支的仓库。示例:"user/my-cool-model"
  • branch (str) — 要删除的分支的名称。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, 可选) — 如果在数据集或 Space 上创建分支,则设置为 "dataset""space";如果为模型打标签,则为 None"model"。默认为 None

引发

RepositoryNotFoundErrorHfHubHTTPError

  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type,私有仓库但未认证,或仓库不存在。
  • HfHubHTTPError — 如果试图删除一个受保护的分支。例如:main 无法被删除。
  • HfHubHTTPError — 如果试图删除一个不存在的分支。

从 Hub 上的仓库中删除一个分支。

delete_collection

< >

( collection_slug: str missing_ok: bool = False token: Union[bool, str, None] = None )

参数

  • collection_slug (str) — 要删除的收藏的 slug。示例:"TheBloke/recent-models-64f9a55bb3115b4f513ec026"
  • missing_ok (bool, 可选) — 如果为 True,当收藏不存在时,不引发错误。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

在 Hub 上删除一个收藏。

示例

>>> from huggingface_hub import delete_collection
>>> collection = delete_collection("username/useless-collection-64f9a55bb3115b4f513ec026", missing_ok=True)

这是一个不可逆转的操作。被删除的收藏无法恢复。

delete_collection_item

< >

( collection_slug: str item_object_id: str missing_ok: bool = False token: Union[bool, str, None] = None )

参数

  • collection_slug (str) — 要更新的收藏的 slug。示例:"TheBloke/recent-models-64f9a55bb3115b4f513ec026"
  • item_object_id (str) — 收藏中项目的 ID。这不是 Hub 上项目(repo_id 或 paper id)的 ID。必须从 CollectionItem 对象中检索。示例:collection.items[0].item_object_id
  • missing_ok (bool, 可选) — 如果为 True,当项目不存在时,不引发错误。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

从收藏中删除一个项目。

示例

>>> from huggingface_hub import get_collection, delete_collection_item

# Get collection first
>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")

# Delete item based on its ID
>>> delete_collection_item(
...     collection_slug="TheBloke/recent-models-64f9a55bb3115b4f513ec026",
...     item_object_id=collection.items[-1].item_object_id,
... )

delete_file

< >

( path_in_repo: str repo_id: str token: Union[str, bool, None] = None repo_type: Optional[str] = None revision: Optional[str] = None commit_message: Optional[str] = None commit_description: Optional[str] = None create_pr: Optional[bool] = None parent_commit: Optional[str] = None )

参数

  • path_in_repo (str) — 仓库中的相对文件路径,例如:"checkpoints/1fec34a/weights.bin"
  • repo_id (str) — 将从中删除文件的仓库,例如:"username/custom_transformers"
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, 可选) — 如果文件在数据集或 Space 中,则设置为 "dataset""space";如果在模型中,则为 None"model"。默认为 None
  • revision (str, 可选) — 要提交的 git 修订版本。默认为 "main" 分支的头部。
  • commit_message (str, 可选) — 生成的提交的摘要/标题/第一行。默认为 f"Delete {path_in_repo} with huggingface_hub"
  • commit_description (str 可选) — 生成的提交的描述。
  • create_pr (boolean, 可选) — 是否为该提交创建一个拉取请求 (Pull Request)。默认为 False。如果未设置 revision,则 PR 将针对 "main" 分支打开。如果设置了 revision 并且它是一个分支,则 PR 将针对此分支打开。如果设置了 revision 但它不是一个分支名(例如:一个提交 oid),服务器将返回一个 RevisionNotFoundError
  • parent_commit (str, 可选) — 父提交的 OID / SHA,以十六进制字符串表示。也支持简写(前7个字符)。如果指定且 create_prFalse,当 revision 没有指向 parent_commit 时,提交将失败。如果指定且 create_prTrue,拉取请求将从 parent_commit 创建。指定 parent_commit 可以确保在提交更改之前仓库没有发生变化,这在并发更新/提交仓库时特别有用。

在给定的仓库中删除一个文件。

引发以下错误

delete_files

< >

( repo_id: str delete_patterns: List[str] token: Union[bool, str, None] = None repo_type: Optional[str] = None revision: Optional[str] = None commit_message: Optional[str] = None commit_description: Optional[str] = None create_pr: Optional[bool] = None parent_commit: Optional[str] = None )

参数

  • repo_id (str) — 将从中删除文件夹的仓库,例如:"username/custom_transformers"
  • delete_patterns (List[str]) — 要删除的文件或文件夹列表。每个字符串可以是文件路径、文件夹路径或 Unix shell 风格的通配符。例如 ["file.txt", "folder/", "data/*.parquet"]
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, 可选) — 要删除文件的仓库类型。可以是 "model""dataset""space"。默认为 "model"
  • revision (str, 可选) — 要提交的 git 修订版本。默认为 "main" 分支的头部。
  • commit_message (str, 可选) — 生成的提交的摘要(第一行)。默认为 f"Delete files using huggingface_hub"
  • commit_description (str 可选) — 生成的提交的描述。
  • create_pr (boolean, 可选) — 是否为该提交创建一个拉取请求 (Pull Request)。默认为 False。如果未设置 revision,则 PR 将针对 "main" 分支打开。如果设置了 revision 并且它是一个分支,则 PR 将针对此分支打开。如果设置了 revision 但它不是一个分支名(例如:一个提交 oid),服务器将返回一个 RevisionNotFoundError
  • parent_commit (str, 可选) — 父提交的 OID / SHA,以十六进制字符串表示。也支持简写(前7个字符)。如果指定且 create_prFalse,当 revision 没有指向 parent_commit 时,提交将失败。如果指定且 create_prTrue,拉取请求将从 parent_commit 创建。指定 parent_commit 可以确保在提交更改之前仓库没有发生变化,这在并发更新/提交仓库时特别有用。

从 Hub 上的仓库删除文件。

如果提供文件夹路径,则整个文件夹及其包含的所有文件都将被删除。

delete_folder

< >

( path_in_repo: str repo_id: str token: Union[bool, str, None] = None repo_type: Optional[str] = None revision: Optional[str] = None commit_message: Optional[str] = None commit_description: Optional[str] = None create_pr: Optional[bool] = None parent_commit: Optional[str] = None )

参数

  • path_in_repo (str) — 仓库中的相对文件夹路径,例如:"checkpoints/1fec34a"
  • repo_id (str) — 将从中删除文件夹的仓库,例如:"username/custom_transformers"
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, 可选) — 如果文件夹位于数据集中,则设置为 "dataset";如果位于空间中,则设置为 "space";如果位于模型中,则为 None"model"。默认为 None
  • revision (str, 可选) — 要提交的 git 修订版本。默认为 "main" 分支的头部。
  • commit_message (str, 可选) — 生成的提交的摘要/标题/第一行。默认为 f"Delete folder {path_in_repo} with huggingface_hub"
  • commit_description (str 可选) — 生成的提交的描述。
  • create_pr (boolean, 可选) — 是否为该提交创建一个拉取请求 (Pull Request)。默认为 False。如果未设置 revision,则 PR 将针对 "main" 分支打开。如果设置了 revision 并且它是一个分支,则 PR 将针对此分支打开。如果设置了 revision 但它不是一个分支名(例如:一个提交 oid),服务器将返回一个 RevisionNotFoundError
  • parent_commit (str, 可选) — 父提交的 OID / SHA,以十六进制字符串表示。也支持简写(前7个字符)。如果指定且 create_prFalse,当 revision 没有指向 parent_commit 时,提交将失败。如果指定且 create_prTrue,拉取请求将从 parent_commit 创建。指定 parent_commit 可以确保在提交更改之前仓库没有发生变化,这在并发更新/提交仓库时特别有用。

在给定的仓库中删除一个文件夹。

create_commit() 方法的简单包装。

delete_inference_endpoint

< >

( name: str namespace: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • name (str) — 要删除的推理端点的名称。
  • namespace (str, 可选) — 推理端点所在的命名空间。默认为当前用户。
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

删除一个推理端点。

此操作不可逆。如果您不想为一个推理端点付费,最好使用 pause_inference_endpoint() 暂停它,或使用 scale_to_zero_inference_endpoint() 将其缩减至零。

为方便起见,您还可以使用 InferenceEndpoint.delete() 删除推理端点。

delete_repo

< >

( repo_id: str token: Union[str, bool, None] = None repo_type: Optional[str] = None missing_ok: bool = False )

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个仓库名称,用 / 分隔。
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, 可选) — 如果上传到数据集,则设置为 "dataset";如果上传到空间,则设置为 "space";如果上传到模型,则为 None"model"
  • missing_ok (bool, 可选, 默认为 False) — 如果为 True,当仓库不存在时不会引发错误。

引发

RepositoryNotFoundError

从 HuggingFace Hub 删除一个仓库。注意:此操作不可逆。

delete_space_secret

< >

( repo_id: str key: str token: Union[bool, str, None] = None )

参数

  • repo_id (str) — 要更新的仓库 ID。例如:"bigcode/in-the-stack"
  • key (str) — 密钥。例如:"GITHUB_API_KEY"
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

从 Space 中删除一个密钥。

密钥允许您向 Space 设置密钥或令牌,而无需对其进行硬编码。更多详情,请参阅 https://huggingface.co/docs/hub/spaces-overview#managing-secrets

delete_space_storage

< >

( repo_id: str token: Union[bool, str, None] = None ) SpaceRuntime

参数

  • repo_id (str) — 要更新的 Space 的 ID。例如:"open-llm-leaderboard/open_llm_leaderboard"
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

SpaceRuntime

关于 Space 的运行时信息,包括 Space 的阶段和硬件。

引发

BadRequestError

  • BadRequestError — 如果空间没有持久化存储。

删除 Space 的持久化存储。

delete_space_variable

< >

( repo_id: str key: str token: Union[bool, str, None] = None )

参数

  • repo_id (str) — 要更新的仓库 ID。例如:"bigcode/in-the-stack"
  • key (str) — 变量键。例如:"MODEL_REPO_ID"
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

从 Space 中删除一个变量。

变量允许您向 Space 设置环境变量,而无需对其进行硬编码。更多详情,请参阅 https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables

delete_tag

< >

( repo_id: str tag: str token: Union[bool, str, None] = None repo_type: Optional[str] = None )

参数

  • repo_id (str) — 将在其中删除标签的仓库。例如:"user/my-cool-model"
  • tag (str) — 要删除的标签的名称。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 `False`。
  • repo_type (str, 可选) — 如果为数据集或空间添加标签,则设置为 `"dataset"` 或 `"space"`;如果为模型添加标签,则设置为 `None` 或 `"model"`。默认为 `None`。

引发

RepositoryNotFoundErrorRevisionNotFoundError

从 Hub 上的仓库中删除一个标签。

delete_webhook

< >

( webhook_id: str token: Union[bool, str, None] = None ) None

参数

  • webhook_id (str) — 要删除的 Webhook 的唯一标识符。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 `False`。

返回

删除一个 Webhook。

示例

>>> from huggingface_hub import delete_webhook
>>> delete_webhook("654bbbc16f2ec14d77f109cc")

disable_webhook

< >

( webhook_id: str token: Union[bool, str, None] = None ) WebhookInfo

参数

  • webhook_id (str) — 要禁用的 Webhook 的唯一标识符。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 `False`。

返回

WebhookInfo

有关已禁用 Webhook 的信息。

禁用一个 Webhook(将其状态设置为“disabled”)。

示例

>>> from huggingface_hub import disable_webhook
>>> disabled_webhook = disable_webhook("654bbbc16f2ec14d77f109cc")
>>> disabled_webhook
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    domains=["repo", "discussion"],
    secret="my-secret",
    disabled=True,
)

duplicate_space

< >

( from_id: str to_id: Optional[str] = None private: Optional[bool] = None token: Union[bool, str, None] = None exist_ok: bool = False hardware: Optional[SpaceHardware] = None storage: Optional[SpaceStorage] = None sleep_time: Optional[int] = None secrets: Optional[List[Dict[str, str]]] = None variables: Optional[List[Dict[str, str]]] = None ) RepoUrl

参数

  • from_id (str) — 要复制的 Space 的 ID。例如:"pharma/CLIP-Interrogator"
  • to_id (str, 可选) — 新 Space 的 ID。例如:"dog/CLIP-Interrogator"。如果未提供,新 Space 将与原始 Space 同名,但在您的帐户下。
  • private (bool, 可选) — 新 Space 是否应为私有。默认为与原始 Space 相同的隐私设置。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 `False`。
  • exist_ok (bool, 可选, 默认为 False) — 如果为 `True`,则在仓库已存在时不会引发错误。
  • hardware (SpaceHardwarestr, 可选) — 硬件选择。例如:`"t4-medium"`。完整列表请参阅 SpaceHardware
  • storage (SpaceStoragestr, 可选) — 持久存储层级的选择。例如:`"small"`。完整列表请参阅 SpaceStorage
  • sleep_time (int, 可选) — Space 进入休眠前等待的非活动秒数。如果您不希望 Space 休眠(升级硬件的默认行为),请设置为 `-1`。对于免费硬件,您无法配置休眠时间(固定为 48 小时不活动)。更多详情请参阅 https://huggingface.co/docs/hub/spaces-gpus#sleep-time
  • secrets (List[Dict[str, str]], 可选) — 要在您的 Space 中设置的私密密钥列表。每个项目格式为 `{"key": ..., "value": ..., "description": ...}`,其中 description 是可选的。更多详情请参阅 https://huggingface.co/docs/hub/spaces-overview#managing-secrets
  • variables (List[Dict[str, str]], 可选) — 要在您的 Space 中设置的公共环境变量列表。每个项目格式为 `{"key": ..., "value": ..., "description": ...}`,其中 description 是可选的。更多详情请参阅 https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables

返回

RepoUrl

新创建仓库的 URL。该值是 str 的子类,包含 endpointrepo_typerepo_id 等属性。

引发

RepositoryNotFoundError 或 `HTTPError`

  • RepositoryNotFoundError — 如果找不到 `from_id` 或 `to_id` 中的一个。这可能是因为它不存在,或者它被设置为 `private` 而您没有访问权限。
  • HTTPError — 如果 HuggingFace API 返回错误。

复制一个 Space。

以编程方式复制一个 Space。新的 Space 将在您的帐户中创建,并且状态将与原始 Space 相同(运行中或已暂停)。无论 Space 当前的状态如何,您都可以复制它。

示例

>>> from huggingface_hub import duplicate_space

# Duplicate a Space to your account
>>> duplicate_space("multimodalart/dreambooth-training")
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

# Can set custom destination id and visibility flag.
>>> duplicate_space("multimodalart/dreambooth-training", to_id="my-dreambooth", private=True)
RepoUrl('https://huggingface.co/spaces/nateraw/my-dreambooth',...)

edit_discussion_comment

< >

( repo_id: str discussion_num: int comment_id: str new_content: str token: Union[bool, str, None] = None repo_type: Optional[str] = None ) DiscussionComment

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个仓库名称,以 `/` 分隔。
  • discussion_num (int) — 讨论或拉取请求的编号。必须是严格的正整数。
  • comment_id (str) — 要编辑的评论的 ID。
  • new_content (str) — 评论的新内容。评论支持 markdown 格式。
  • repo_type (str, 可选) — 如果上传到数据集或空间,则设置为 `"dataset"` 或 `"space"`;如果上传到模型,则设置为 `None` 或 `"model"`。默认为 `None`。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 `False`。

返回

DiscussionComment

已编辑的评论

编辑讨论/拉取请求中的评论。

引发以下错误

  • HTTPError 如果 HuggingFace API 返回错误
  • ValueError 如果某些参数值无效
  • RepositoryNotFoundError 如果找不到要下载的仓库。这可能是因为它不存在,或者是私有仓库而您没有访问权限。

enable_webhook

< >

( webhook_id: str token: Union[bool, str, None] = None ) WebhookInfo

参数

  • webhook_id (str) — 要启用的 Webhook 的唯一标识符。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 `False`。

返回

WebhookInfo

有关已启用 Webhook 的信息。

启用一个 Webhook(将其状态设置为“active”)。

示例

>>> from huggingface_hub import enable_webhook
>>> enabled_webhook = enable_webhook("654bbbc16f2ec14d77f109cc")
>>> enabled_webhook
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    domains=["repo", "discussion"],
    secret="my-secret",
    disabled=False,
)

fetch_job_logs

< >

( job_id: str namespace: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • job_id (str) — 任务的 ID。
  • namespace (str, 可选) — 任务运行的命名空间。默认为当前用户的命名空间。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌。如果未提供,将使用本地保存的令牌,这是推荐的身份验证方法。设置为 `False` 以禁用身份验证。请参阅:https://huggingface.co/docs/huggingface_hub/quick-start#authentication

从 Hugging Face 基础设施上的计算任务中获取所有日志。

示例

>>> from huggingface_hub import fetch_job_logs, run_job
>>> job = run_job("python:3.12", ["python", "-c" ,"print('Hello from HF compute!')"])
>>> for log in fetch_job_logs(job.job_id):
...     print(log)
Hello from HF compute!

file_exists

< >

( repo_id: str filename: str repo_type: Optional[str] = None revision: Optional[str] = None token: Union[str, bool, None] = None )

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个仓库名称,以 `/` 分隔。
  • filename (str) — 要检查的文件名,例如:`"config.json"`
  • repo_type (str, 可选) — 如果从数据集或空间获取仓库信息,则设置为 `"dataset"` 或 `"space"`;如果从模型获取仓库信息,则设置为 `None` 或 `"model"`。默认为 `None`。
  • revision (str, 可选) — 获取信息的仓库的版本。默认为 `"main"` 分支。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 `False`。

检查 Hugging Face Hub 上的仓库中是否存在某个文件。

示例

>>> from huggingface_hub import file_exists
>>> file_exists("bigcode/starcoder", "config.json")
True
>>> file_exists("bigcode/starcoder", "not-a-file")
False
>>> file_exists("bigcode/not-a-repo", "config.json")
False

get_collection

< >

( collection_slug: str token: Union[bool, str, None] = None )

参数

  • collection_slug (str) — Hub 上集合的 slug。例如:`"TheBloke/recent-models-64f9a55bb3115b4f513ec026"`。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 `False`。

获取 Hub 上集合的信息。

返回: Collection

示例

>>> from huggingface_hub import get_collection
>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")
>>> collection.title
'Recent models'
>>> len(collection.items)
37
>>> collection.items[0]
CollectionItem(
    item_object_id='651446103cd773a050bf64c2',
    item_id='TheBloke/U-Amethyst-20B-AWQ',
    item_type='model',
    position=88,
    note=None
)

get_dataset_tags

< >

( )

将所有有效的数据集标签列为一个嵌套的命名空间对象。

get_discussion_details

< >

( repo_id: str discussion_num: int repo_type: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个仓库名称,以 `/` 分隔。
  • discussion_num (int) — 讨论或拉取请求的编号。必须是严格的正整数。
  • repo_type (str, 可选) — 如果上传到数据集或空间,则设置为 `"dataset"` 或 `"space"`;如果上传到模型,则设置为 `None` 或 `"model"`。默认为 `None`。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 `False`。

从 Hub 获取讨论/拉取请求的详细信息。

返回:DiscussionWithDetails

引发以下错误

  • HTTPError 如果 HuggingFace API 返回错误
  • ValueError 如果某些参数值无效
  • RepositoryNotFoundError 如果找不到要下载的仓库。这可能是因为它不存在,或者是私有仓库而您没有访问权限。

get_full_repo_name

< >

( model_id: str organization: Optional[str] = None token: Union[bool, str, None] = None ) str

参数

  • model_id (str) — 模型的名称。
  • organization (str, 可选) — 如果传入此参数,仓库名称将在组织命名空间下,而不是用户命名空间下。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传入 False

返回

字符串

如果未传入组织,则仓库名称在用户命名空间下 ({username}/{model_id}),否则在组织命名空间下 ({organization}/{model_id})。

返回给定模型 ID 和可选组织的仓库名称。

get_hf_file_metadata

< >

( url: str token: Union[bool, str, None] = None proxies: Optional[Dict] = None timeout: Optional[float] = 10 )

参数

  • url (str) — 文件 URL,例如由 hf_hub_url() 返回。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传入 False
  • proxies (dict, 可选) — 协议到代理 URL 的字典映射,传递给 requests.request
  • timeout (float, 可选, 默认为 10) — 等待服务器发送元数据多少秒后放弃。

获取给定 URL 在 Hub 上版本化的文件的元数据。

get_inference_endpoint

< >

( name: str namespace: Optional[str] = None token: Union[bool, str, None] = None ) InferenceEndpoint

参数

  • name (str) — 要检索信息的推理端点的名称。
  • namespace (str, 可选) — 推理端点所在的命名空间。默认为当前用户。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传入 False

返回

InferenceEndpoint

有关请求的推理端点的信息。

获取有关推理端点的信息。

示例

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.get_inference_endpoint("my-text-to-image")
>>> endpoint
InferenceEndpoint(name='my-text-to-image', ...)

# Get status
>>> endpoint.status
'running'
>>> endpoint.url
'https://my-text-to-image.region.vendor.endpoints.huggingface.cloud'

# Run inference
>>> endpoint.client.text_to_image(...)

get_model_tags

< >

( )

以嵌套命名空间对象的形式列出所有有效的模型标签。

get_paths_info

< >

( repo_id: str paths: Union[List[str], str] expand: bool = False revision: Optional[str] = None repo_type: Optional[str] = None token: Union[str, bool, None] = None ) List[Union[RepoFile, RepoFolder]]

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个由 / 分隔的仓库名称。
  • paths (Union[List[str], str], 可选) — 要获取信息的路径。如果路径不存在,它将被忽略,而不会引发异常。
  • expand (bool, 可选, 默认为 False) — 是否获取有关路径的更多信息(例如,最后一次提交和文件的安全扫描结果)。此操作对服务器来说成本更高,因此每页只返回 50 个结果(而不是 1000 个)。由于分页是在 huggingface_hub 中实现的,除了获取结果所需的时间外,这对您是透明的。
  • revision (str, 可选) — 要获取信息的仓库版本。默认为 "main" 分支。
  • repo_type (str, 可选) — 要获取信息的仓库类型 ("model", "dataset""space")。默认为 "model"
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传入 False

返回

List[Union[RepoFile, RepoFolder]]

路径的信息,作为 RepoFileRepoFolder 对象的列表。

引发

RepositoryNotFoundErrorRevisionNotFoundError

  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type,私有仓库但未认证,或仓库不存在。
  • RevisionNotFoundError — 如果在仓库中找不到版本(错误 404)。

获取有关仓库路径的信息。

示例

>>> from huggingface_hub import get_paths_info
>>> paths_info = get_paths_info("allenai/c4", ["README.md", "en"], repo_type="dataset")
>>> paths_info
[
    RepoFile(path='README.md', size=2379, blob_id='f84cb4c97182890fc1dbdeaf1a6a468fd27b4fff', lfs=None, last_commit=None, security=None),
    RepoFolder(path='en', tree_id='dc943c4c40f53d02b31ced1defa7e5f438d5862e', last_commit=None)
]

get_repo_discussions

< >

( repo_id: str author: Optional[str] = None discussion_type: Optional[constants.DiscussionTypeFilter] = None discussion_status: Optional[constants.DiscussionStatusFilter] = None repo_type: Optional[str] = None token: Union[bool, str, None] = None ) Iterator[Discussion]

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个由 / 分隔的仓库名称。
  • author (str, 可选) — 传入一个值以按讨论作者进行筛选。None 表示不筛选。默认为 None
  • discussion_type (str, 可选) — 设置为 "pull_request" 以仅获取拉取请求,"discussion" 以仅获取讨论。设置为 "all"None 以获取两者。默认为 None
  • discussion_status (str, 可选) — 设置为 "open" (或 "closed") 以仅获取打开 (或关闭) 的讨论。设置为 "all"None 以获取两者。默认为 None
  • repo_type (str, 可选) — 如果从数据集或空间获取,则设置为 "dataset""space",如果从模型获取,则设置为 None"model"。默认为 None
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传入 False

返回

Iterator[Discussion]

Discussion 对象的迭代器。

获取给定仓库的讨论和拉取请求。

示例

将仓库的所有讨论收集到一个列表中

>>> from huggingface_hub import get_repo_discussions
>>> discussions_list = list(get_repo_discussions(repo_id="bert-base-uncased"))

迭代仓库的讨论

>>> from huggingface_hub import get_repo_discussions
>>> for discussion in get_repo_discussions(repo_id="bert-base-uncased"):
...     print(discussion.num, discussion.title)

get_safetensors_metadata

< >

( repo_id: str repo_type: Optional[str] = None revision: Optional[str] = None token: Union[bool, str, None] = None ) SafetensorsRepoMetadata

参数

  • repo_id (str) — 一个用户或组织名称和一个由 / 分隔的仓库名称。
  • repo_type (str, 可选) — 如果文件在数据集或空间中,则设置为 "dataset""space",如果在模型中,则设置为 None"model"。默认为 None
  • revision (str, 可选) — 获取文件的 git 版本。可以是一个分支名、一个标签或一个提交哈希。默认为 "main" 分支的头部。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传入 False

返回

SafetensorsRepoMetadata

与 safetensors 仓库相关的信息。

引发

NotASafetensorsRepoErrorSafetensorsParsingError

  • NotASafetensorsRepoError — 如果仓库不是 safetensors 仓库,即没有 model.safetensorsmodel.safetensors.index.json 文件。
  • SafetensorsParsingError — 如果 safetensors 文件头无法正确解析。

解析 Hub 上 safetensors 仓库的元数据。

我们首先检查仓库是单个 safetensors 文件还是分片的 safetensors 仓库。如果是单个 safetensors 文件,我们从该文件解析元数据。如果是分片的 safetensors 仓库,我们从索引文件解析元数据,然后从每个分片解析元数据。

要从单个 safetensors 文件解析元数据,请使用 parse_safetensors_file_metadata()

有关 safetensors 格式的更多详细信息,请查看 https://huggingface.co/docs/safetensors/index#format

示例

# Parse repo with single weights file
>>> metadata = get_safetensors_metadata("bigscience/bloomz-560m")
>>> metadata
SafetensorsRepoMetadata(
    metadata=None,
    sharded=False,
    weight_map={'h.0.input_layernorm.bias': 'model.safetensors', ...},
    files_metadata={'model.safetensors': SafetensorsFileMetadata(...)}
)
>>> metadata.files_metadata["model.safetensors"].metadata
{'format': 'pt'}

# Parse repo with sharded model
>>> metadata = get_safetensors_metadata("bigscience/bloom")
Parse safetensors files: 100%|██████████████████████████████████████████| 72/72 [00:12<00:00,  5.78it/s]
>>> metadata
SafetensorsRepoMetadata(metadata={'total_size': 352494542848}, sharded=True, weight_map={...}, files_metadata={...})
>>> len(metadata.files_metadata)
72  # All safetensors files have been fetched

# Parse repo with sharded model
>>> get_safetensors_metadata("runwayml/stable-diffusion-v1-5")
NotASafetensorsRepoError: 'runwayml/stable-diffusion-v1-5' is not a safetensors repo. Couldn't find 'model.safetensors.index.json' or 'model.safetensors' files.

get_space_runtime

< >

( repo_id: str token: Union[bool, str, None] = None ) SpaceRuntime

参数

  • repo_id (str) — 要更新的仓库 ID。例如:"bigcode/in-the-stack"
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传入 False

返回

SpaceRuntime

关于 Space 的运行时信息,包括 Space 的阶段和硬件。

获取有关 Space 的运行时信息。

get_space_variables

< >

( repo_id: str token: Union[bool, str, None] = None )

参数

  • repo_id (str) — 要查询的仓库 ID。例如:"bigcode/in-the-stack"
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传入 False

获取 Space 的所有变量。

变量允许您向 Space 设置环境变量,而无需对其进行硬编码。更多详情,请参阅 https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables

get_token_permission

< >

( token: Union[bool, str, None] = None ) Literal["read", "write", "fineGrained", None]

参数

返回

Literal["read", "write", "fineGrained", None]

令牌授予的权限(“read” 或 “write”)。如果未传入令牌、令牌无效或服务器未返回角色,则返回 None。这种情况通常发生在令牌是 OAuth 令牌时。

检查给定的 token 是否有效,并返回其权限。

此方法已弃用,并将在 1.0 版本中删除。权限比 get_token_permission 首次引入时更复杂。OAuth 和细粒度令牌允许更详细的权限。如果您需要了解与令牌关联的权限,请使用 whoami 并检查 'auth' 键。

有关令牌的更多详细信息,请参阅 https://huggingface.co/docs/hub/security-tokens#what-are-user-access-tokens

get_user_overview

< >

( username: str token: Union[bool, str, None] = None ) User

参数

返回

User

一个包含用户概览的 User 对象。

引发

HTTPError

  • HTTPError — 如果用户在 Hub 上不存在,则为 HTTP 404。

获取 Hub 上用户的概览。

get_webhook

< >

( webhook_id: str token: Union[bool, str, None] = None ) WebhookInfo

参数

  • webhook_id (str) — 要获取的 Webhook 的唯一标识符。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传入 False

返回

WebhookInfo

关于 Webhook 的信息。

通过其 ID 获取一个 Webhook。

示例

>>> from huggingface_hub import get_webhook
>>> webhook = get_webhook("654bbbc16f2ec14d77f109cc")
>>> print(webhook)
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    secret="my-secret",
    domains=["repo", "discussion"],
    disabled=False,
)

grant_access

< >

( repo_id: str user: str repo_type: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • repo_id (str) — 要授予访问权限的仓库 ID。
  • user (str) — 要授予访问权限的用户的用户名。
  • repo_type (str, optional) — 要授予访问权限的仓库类型。必须是 modeldatasetspace 之一。默认为 model
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

引发

HTTPError

  • HTTPError — 如果仓库未设门控,则返回 HTTP 400。
  • HTTPError — 如果用户已经有权访问该仓库,则返回 HTTP 400 错误。
  • HTTPError — 如果您对仓库只有只读权限,则返回 HTTP 403。如果您在仓库所属的组织中没有 writeadmin 角色,或者您传递了 read 令牌,则可能会发生这种情况。
  • HTTPError — 如果 Hub 上不存在该用户,则返回 HTTP 404。

为指定用户授予对给定受限仓库的访问权限。

授予访问权限不需要用户自己发送访问请求。用户会自动被添加到已接受列表中,这意味着他们可以下载文件。您可以在任何时候使用 cancel_access_request()reject_access_request() 撤销已授予的访问权限。

有关门控仓库的更多信息,请参阅 https://huggingface.co/docs/hub/models-gated

hf_hub_download

< >

( repo_id: str filename: str subfolder: Optional[str] = None repo_type: Optional[str] = None revision: Optional[str] = None cache_dir: Union[str, Path, None] = None local_dir: Union[str, Path, None] = None force_download: bool = False proxies: Optional[Dict] = None etag_timeout: float = 10 token: Union[bool, str, None] = None local_files_only: bool = False resume_download: Optional[bool] = None force_filename: Optional[str] = None local_dir_use_symlinks: Union[bool, Literal['auto']] = 'auto' ) str

参数

  • repo_id (str) — 用户或组织名称与仓库名称,由 / 分隔。
  • filename (str) — 仓库中的文件名。
  • subfolder (str, optional) — 一个可选值,对应仓库内的文件夹。
  • repo_type (str, optional) — 如果从数据集或空间下载,则设置为 "dataset""space";如果从模型下载,则为 None"model"。默认为 None
  • revision (str, optional) — 一个可选的 Git 修订 ID,可以是分支名、标签或提交哈希。
  • cache_dir (str, Path, optional) — 存储缓存文件的文件夹路径。
  • local_dir (str or Path, optional) — 如果提供,下载的文件将放置在该目录下。
  • force_download (bool, optional, defaults to False) — 文件是否应该被下载,即使它已经存在于本地缓存中。
  • proxies (dict, optional) — 协议到代理 URL 的映射字典,传递给 requests.request
  • etag_timeout (float, optional, defaults to 10) — 在获取 ETag 时,在放弃之前等待服务器发送数据的秒数,该参数传递给 requests.request
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • local_files_only (bool, optional, defaults to False) — 如果为 True,则避免下载文件,并在本地缓存文件存在时返回其路径。

返回

字符串

文件的本地路径,或者在网络关闭时,为磁盘上缓存的最新版本文件。

引发

RepositoryNotFoundError or RevisionNotFoundError or EntryNotFoundError or LocalEntryNotFoundError or EnvironmentError or OSError or ValueError

如果文件尚未存在于本地缓存中,则下载给定文件。

新的缓存文件布局如下

  • 缓存目录为每个 repo_id 包含一个子文件夹(按仓库类型命名空间)
  • 在每个仓库文件夹内
    • refs 是最新已知修订版本 => commit_hash 对的列表
    • blobs 包含实际的文件 blob(通过它们的 git-sha 或 sha256 标识,取决于它们是否是 LFS 文件)
    • snapshots 为每个提交包含一个子文件夹,每个“提交”包含在该特定提交时已解析的文件子集。每个文件名都是指向该特定提交时 blob 的符号链接。
[  96]  .
└── [ 160]  models--julien-c--EsperBERTo-small
    ├── [ 160]  blobs
    │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
    ├── [  96]  refs
    │   └── [  40]  main
    └── [ 128]  snapshots
        ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
        │   ├── [  52]  README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
        │   └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        └── [ 128]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48
            ├── [  52]  README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
            └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd

如果提供了 local_dir,仓库的文件结构将在此位置被复制。使用此选项时,不会使用 cache_dir,而是在 local_dir 的根目录下创建一个 .cache/huggingface/ 文件夹,以存储与下载文件相关的一些元数据。虽然此机制不如主缓存系统稳健,但它针对定期拉取仓库最新版本进行了优化。

hide_discussion_comment

< >

( repo_id: str discussion_num: int comment_id: str token: Union[bool, str, None] = None repo_type: Optional[str] = None ) DiscussionComment

参数

  • repo_id (str) — 一个命名空间(用户或组织)和仓库名称,由 / 分隔。
  • discussion_num (int) — 讨论或拉取请求的编号。必须是严格的正整数。
  • comment_id (str) — 要编辑的评论的 ID。
  • repo_type (str, optional) — 如果上传到数据集或空间,则设置为 "dataset""space";如果上传到模型,则为 None"model"。默认为 None
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

DiscussionComment

被隐藏的评论

隐藏讨论/拉取请求中的评论。

被隐藏的评论内容将无法再被检索。隐藏评论是不可逆的操作。

引发以下错误

  • HTTPError 如果 HuggingFace API 返回错误
  • ValueError 如果某些参数值无效
  • RepositoryNotFoundError 如果找不到要下载的仓库。这可能是因为它不存在,或者是私有仓库而您没有访问权限。

inspect_job

< >

( job_id: str namespace: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • job_id (str) — 作业的 ID。
  • namespace (str, optional) — 作业运行所在的命名空间。默认为当前用户的命名空间。
  • token (Union[bool, str, None], optional) — 一个有效的用户访问令牌。如果未提供,将使用本地保存的令牌,这是推荐的身份验证方法。设置为 False 以禁用身份验证。参考:https://huggingface.co/docs/huggingface_hub/quick-start#authentication

检查 Hugging Face 基础设施上的计算作业。

示例

>>> from huggingface_hub import inspect_job, run_job
>>> job = run_job("python:3.12", ["python", "-c" ,"print('Hello from HF compute!')"])
>>> inspect_job(job.job_id)
JobInfo(
    id='68780d00bbe36d38803f645f',
    created_at=datetime.datetime(2025, 7, 16, 20, 35, 12, 808000, tzinfo=datetime.timezone.utc),
    docker_image='python:3.12',
    space_id=None,
    command=['python', '-c', "print('Hello from HF compute!')"],
    arguments=[],
    environment={},
    secrets={},
    flavor='cpu-basic',
    status=JobStatus(stage='RUNNING', message=None)
)

list_accepted_access_requests

< >

( repo_id: str repo_type: Optional[str] = None token: Union[bool, str, None] = None ) List[AccessRequest]

参数

  • repo_id (str) — 获取访问请求的仓库 ID。
  • repo_type (str, optional) — 获取访问请求的仓库类型。必须是 modeldatasetspace 之一。默认为 model
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

List[AccessRequest]

AccessRequest 对象的列表。每个对象包含 usernameemailstatustimestamp 属性。如果受限仓库有自定义表单,fields 属性将填充用户的答案。

引发

HTTPError

  • HTTPError — 如果仓库未设门控,则返回 HTTP 400。
  • HTTPError — 如果您对仓库只有只读权限,则返回 HTTP 403。如果您在仓库所属的组织中没有 writeadmin 角色,或者您传递了 read 令牌,则可能会发生这种情况。

获取给定受限仓库的已接受访问请求。

已接受的请求意味着用户已请求访问仓库且请求已被接受。用户可以下载仓库的任何文件。如果批准模式是自动的,此列表默认应包含所有请求。已接受的请求可以随时使用 cancel_access_request()reject_access_request() 取消或拒绝。已取消的请求将返回到待处理列表,而已拒绝的请求将进入已拒绝列表。在这两种情况下,用户都将失去对仓库的访问权限。

有关门控仓库的更多信息,请参阅 https://huggingface.co/docs/hub/models-gated

示例

>>> from huggingface_hub import list_accepted_access_requests

>>> requests = list_accepted_access_requests("meta-llama/Llama-2-7b")
>>> len(requests)
411
>>> requests[0]
[
    AccessRequest(
        username='clem',
        fullname='Clem 🤗',
        email='***',
        timestamp=datetime.datetime(2023, 11, 23, 18, 4, 53, 828000, tzinfo=datetime.timezone.utc),
        status='accepted',
        fields=None,
    ),
    ...
]

list_collections

< >

( owner: Union[List[str], str, None] = None item: Union[List[str], str, None] = None sort: Optional[Literal['lastModified', 'trending', 'upvotes']] = None limit: Optional[int] = None token: Union[bool, str, None] = None ) Iterable[Collection]

参数

  • owner (List[str] or str, optional) — 按所有者用户名筛选。
  • item (List[str] or str, optional) — 筛选包含特定项目的收藏。例如:"models/teknium/OpenHermes-2.5-Mistral-7B""datasets/squad""papers/2311.12983"
  • sort (Literal["lastModified", "trending", "upvotes"], optional) — 按最后修改时间、热门趋势或点赞数对收藏进行排序。
  • limit (int, optional) — 要返回的收藏的最大数量。
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

Iterable[Collection]

一个可迭代的 Collection 对象。

根据给定的筛选条件,列出 Hugging Face Hub 上的收藏。

列出收藏时,每个收藏的项目列表最多被截断为 4 个项目。要检索收藏中的所有项目,必须使用 get_collection()

list_datasets

< >

( filter: Union[str, Iterable[str], None] = None author: Optional[str] = None benchmark: Optional[Union[str, List[str]]] = None dataset_name: Optional[str] = None gated: Optional[bool] = None language_creators: Optional[Union[str, List[str]]] = None language: Optional[Union[str, List[str]]] = None multilinguality: Optional[Union[str, List[str]]] = None size_categories: Optional[Union[str, List[str]]] = None tags: Optional[Union[str, List[str]]] = None task_categories: Optional[Union[str, List[str]]] = None task_ids: Optional[Union[str, List[str]]] = None search: Optional[str] = None sort: Optional[Union[Literal['last_modified'], str]] = None direction: Optional[Literal[-1]] = None limit: Optional[int] = None expand: Optional[List[ExpandDatasetProperty_T]] = None full: Optional[bool] = None token: Union[bool, str, None] = None ) Iterable[DatasetInfo]

参数

  • filter (str or Iterable[str], optional) — 用于筛选 Hub 上数据集的字符串或字符串列表。
  • author (str, optional) — 标识返回数据集作者的字符串。
  • benchmark (str or List, optional) — 一个字符串或字符串列表,可用于按其官方基准来识别 Hub 上的数据集。
  • dataset_name (str, optional) — 一个字符串或字符串列表,可用于按名称(如 SQACwikineural)识别 Hub 上的数据集。
  • gated (bool, optional) — 一个布尔值,用于筛选 Hub 上是否受限的数据集。默认情况下,返回所有数据集。如果传递 gated=True,则只返回受限数据集。如果传递 gated=False,则只返回非受限数据集。
  • language_creators (str or List, optional) — 一个字符串或字符串列表,可用于根据数据策划方式(如 crowdsourcedmachine_generated)识别 Hub 上的数据集。
  • language (str or List, optional) — 一个字符串或字符串列表,表示用于在 Hub 上筛选数据集的双字符语言。
  • multilinguality (str or List, optional) — 一个字符串或字符串列表,表示用于筛选包含多种语言的数据集的筛选器。
  • size_categories (str or List, optional) — 一个字符串或字符串列表,可用于按数据集大小(如 100K<n<1M1M<n<10M)识别 Hub 上的数据集。
  • tags (strList可选) — 用于在 Hub 上筛选数据集的字符串标签或标签列表。
  • task_categories (strList可选) — 可用于按设计任务(如 audio_classificationnamed_entity_recognition)在 Hub 上识别数据集的字符串或字符串列表。
  • task_ids (strList可选) — 可用于按特定任务(如 speech_emotion_recognitionparaphrase)在 Hub 上识别数据集的字符串或字符串列表。
  • search (str可选) — 返回的数据集中将包含的字符串。
  • sort (Literal["last_modified"]str可选) — 用于对结果模型进行排序的键。可能的值包括“last_modified”、“trending_score”、“created_at”、“downloads”和“likes”。
  • direction (Literal[-1]int可选) — 排序方向。值 -1 表示降序排序,而所有其他值表示升序排序。
  • limit (int可选) — 获取数据集数量的限制。将此选项保留为 None 将获取所有数据集。
  • expand (List[ExpandDatasetProperty_T]可选) — 在响应中返回的属性列表。使用时,只会返回列表中的属性。如果传递了 full,则无法使用此参数。可能的值包括 "author""cardData""citation""createdAt""disabled""description""downloads""downloadsAllTime""gated""lastModified""likes""paperswithcode_id""private""siblings""sha""tags""trendingScore""usedStorage""resourceGroup""xetEnabled"
  • full (bool可选) — 是否获取所有数据集数据,包括 last_modifiedcard_data 和文件。可以包含有用的信息,例如 PapersWithCode ID。
  • token (Union[bool, str, None],可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

Iterable[DatasetInfo]

huggingface_hub.hf_api.DatasetInfo 对象的可迭代对象。

根据给定的筛选条件,列出 Hugging Face Hub 上托管的数据集。

使用 filter 参数的示例

>>> from huggingface_hub import HfApi

>>> api = HfApi()

# List all datasets
>>> api.list_datasets()


# List only the text classification datasets
>>> api.list_datasets(filter="task_categories:text-classification")


# List only the datasets in russian for language modeling
>>> api.list_datasets(
...     filter=("language:ru", "task_ids:language-modeling")
... )

# List FiftyOne datasets (identified by the tag "fiftyone" in dataset card)
>>> api.list_datasets(tags="fiftyone")

使用 search 参数的示例

>>> from huggingface_hub import HfApi

>>> api = HfApi()

# List all datasets with "text" in their name
>>> api.list_datasets(search="text")

# List all datasets with "text" in their name made by google
>>> api.list_datasets(search="text", author="google")

list_inference_catalog

< >

( token: Union[bool, str, None] = None ) Liststr

参数

返回

Liststr

目录中可用模型 ID 的列表。

列出 Hugging Face 推理目录(Inference Catalog)中可用的模型。

推理目录的目标是提供一个经过筛选的模型列表,这些模型已针对推理进行了优化,并且其默认配置已经过测试。有关目录中可用模型的列表,请参见 https://endpoints.huggingface.co/catalog

使用 create_inference_endpoint_from_catalog() 从目录部署模型。

list_inference_catalog 是实验性的。其 API 未来可能会更改。如果您有任何建议或请求,请提供反馈。

list_inference_endpoints

< >

( namespace: Optional[str] = None token: Union[bool, str, None] = None ) ListInferenceEndpoint

参数

  • namespace (str可选) — 要列出端点的命名空间。默认为当前用户。设置为 "*" 以列出所有命名空间(即个人命名空间和用户所属的所有组织)中的所有端点。
  • token (Union[bool, str, None],可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

ListInferenceEndpoint

给定命名空间的所有推理端点的列表。

列出给定命名空间的所有推理端点。

示例

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.list_inference_endpoints()
[InferenceEndpoint(name='my-endpoint', ...), ...]

list_jobs

< >

( timeout: Optional[int] = None namespace: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • timeout (float可选) — 是否为向 Hub 的请求设置超时。
  • namespace (str可选) — 从中列出作业的命名空间。默认为当前用户的命名空间。
  • token (Union[bool, str, None]可选) — 一个有效的用户访问令牌。如果未提供,将使用本地保存的令牌,这是推荐的身份验证方法。设置为 False 以禁用身份验证。请参阅:https://huggingface.co/docs/huggingface_hub/quick-start#authentication

列出 Hugging Face 基础设施上的计算作业。

list_lfs_files

< >

( repo_id: str repo_type: Optional[str] = None token: Union[bool, str, None] = None ) Iterable[LFSFileInfo]

参数

  • repo_id (str) — 您正在列出 LFS 文件的仓库。
  • repo_type (str可选) — 仓库类型。如果从数据集或空间列出,则设置为 "dataset""space",如果从模型列出,则为 None"model"。默认为 None
  • token (Union[bool, str, None],可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

Iterable[LFSFileInfo]

LFSFileInfo 对象的迭代器。

列出 Hub 上仓库中的所有 LFS 文件。

这主要用于计算仓库使用了多少存储空间,并最终使用 permanently_delete_lfs_files() 清理大文件。请注意,这将是一个永久性操作,会影响所有引用此删除文件的提交,并且无法撤销。

示例

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> lfs_files = api.list_lfs_files("username/my-cool-repo")

# Filter files files to delete based on a combination of `filename`, `pushed_at`, `ref` or `size`.
# e.g. select only LFS files in the "checkpoints" folder
>>> lfs_files_to_delete = (lfs_file for lfs_file in lfs_files if lfs_file.filename.startswith("checkpoints/"))

# Permanently delete LFS files
>>> api.permanently_delete_lfs_files("username/my-cool-repo", lfs_files_to_delete)

list_liked_repos

< >

( user: Optional[str] = None token: Union[bool, str, None] = None ) UserLikes

参数

  • user (str可选) — 您想要获取其点赞的用户名。
  • token (Union[bool, str, None],可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

UserLikes

包含用户名和 3 个仓库 ID 列表的对象(1 个用于模型,1 个用于数据集,1 个用于空间)。

引发

ValueError

  • ValueError — 如果未传递 user 且未找到令牌(无论是从参数还是从机器)。

列出用户在 huggingface.co 上点赞的所有公共仓库。

此列表是公开的,因此令牌是可选的。如果未传递 user,则默认为已登录的用户。

另请参阅 unlike()

示例

>>> from huggingface_hub import list_liked_repos

>>> likes = list_liked_repos("julien-c")

>>> likes.user
"julien-c"

>>> likes.models
["osanseviero/streamlit_1.15", "Xhaheen/ChatGPT_HF", ...]

list_models

< >

( filter: Union[str, Iterable[str], None] = None author: Optional[str] = None gated: Optional[bool] = None inference: Optional[Literal['warm']] = None inference_provider: Optional[Union[Literal['all'], 'PROVIDER_T', List['PROVIDER_T']]] = None library: Optional[Union[str, List[str]]] = None language: Optional[Union[str, List[str]]] = None model_name: Optional[str] = None task: Optional[Union[str, List[str]]] = None trained_dataset: Optional[Union[str, List[str]]] = None tags: Optional[Union[str, List[str]]] = None search: Optional[str] = None pipeline_tag: Optional[str] = None emissions_thresholds: Optional[Tuple[float, float]] = None sort: Union[Literal['last_modified'], str, None] = None direction: Optional[Literal[-1]] = None limit: Optional[int] = None expand: Optional[List[ExpandModelProperty_T]] = None full: Optional[bool] = None cardData: bool = False fetch_config: bool = False token: Union[bool, str, None] = None ) Iterable[ModelInfo]

参数

  • filter (strIterable[str]可选) — 用于在 Hub 上筛选模型的字符串或字符串列表。
  • author (str可选) — 识别返回模型作者(用户或组织)的字符串。
  • gated (bool可选) — 一个布尔值,用于筛选 Hub 上是否受门控的模型。默认情况下,返回所有模型。如果传递 gated=True,则仅返回受门控的模型。如果传递 gated=False,则仅返回不受门控的模型。
  • inference (Literal["warm"]可选) — 如果为“warm”,则筛选 Hub 上当前至少由一个提供商服务的模型。
  • inference_provider (Literal["all"]str可选) — 用于筛选 Hub 上由特定提供商服务的模型的字符串。传递 "all" 以获取所有由至少一个提供商服务的模型。
  • library (strList可选) — 模型最初训练所使用的基础库的字符串或字符串列表,例如 pytorch、tensorflow 或 allennlp。
  • language (strList可选) — 语言的字符串或字符串列表,可以按名称和国家代码,例如“en”或“English”
  • model_name (str可选) — 包含 Hub 上模型完整或部分名称的字符串,例如“bert”或“bert-base-cased”
  • task (strList可选) — 模型设计任务的字符串或字符串列表,例如:“fill-mask”或“automatic-speech-recognition”
  • trained_dataset (strList可选) — Hub 上模型训练数据集的字符串标签或字符串标签列表。
  • tags (strList可选) — 用于按 Hub 上的标签筛选模型的字符串标签或标签列表,例如 text-generationspacy
  • search (str可选) — 将包含在返回的模型 ID 中的字符串。
  • pipeline_tag (str可选) — 用于按 Hub 上的 pipeline 标签筛选模型的字符串,例如 summarization
  • emissions_thresholds (Tuple可选) — 一个包含两个整数或浮点数的元组,表示筛选结果模型的最小和最大碳足迹(以克为单位)。
  • sort (Literal["last_modified"]str可选) — 用于对结果模型进行排序的键。可能的值包括“last_modified”、“trending_score”、“created_at”、“downloads”和“likes”。
  • direction (Literal[-1]int可选) — 排序方向。值 -1 表示降序排序,而所有其他值表示升序排序。
  • limit (int可选) — 获取模型数量的限制。将此选项保留为 None 将获取所有模型。
  • expand (List[ExpandModelProperty_T]可选) — 在响应中返回的属性列表。使用时,只会返回列表中的属性。如果传递了 fullcardDatafetch_config,则无法使用此参数。可能的值包括 "author""cardData""config""createdAt""disabled""downloads""downloadsAllTime""gated""gguf""inference""inferenceProviderMapping""lastModified""library_name""likes""mask_token""model-index""pipeline_tag""private""safetensors""sha""siblings""spaces""tags""transformersInfo""trendingScore""widgetData""resourceGroup""xetEnabled"
  • full (bool可选) — 是否获取所有模型数据,包括 last_modifiedsha、文件和 tags。使用筛选器时,此项默认设置为 True
  • cardData (bool可选) — 是否也获取模型的元数据。可以包含有用的信息,例如碳排放、指标和训练数据集。
  • fetch_config (bool可选) — 是否也获取模型配置。由于其大小,此项不包含在 full 中。
  • token (Union[bool, str, None],可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

Iterable[ModelInfo]

huggingface_hub.hf_api.ModelInfo 对象的可迭代对象。

根据给定的筛选条件,列出 Hugging Face Hub 上托管的模型。

示例

>>> from huggingface_hub import HfApi

>>> api = HfApi()

# List all models
>>> api.list_models()

# List text classification models
>>> api.list_models(filter="text-classification")

# List models from the KerasHub library
>>> api.list_models(filter="keras-hub")

# List models served by Cohere
>>> api.list_models(inference_provider="cohere")

# List models with "bert" in their name
>>> api.list_models(search="bert")

# List models with "bert" in their name and pushed by google
>>> api.list_models(search="bert", author="google")

list_organization_members

< >

( organization: str token: Union[bool, str, None] = None ) Iterable[User]

参数

  • organization (str) — 要获取其成员的组织名称。
  • token (Union[bool, str, None],可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

Iterable[User]

包含组织成员的 User 对象列表。

引发

HTTPError

  • HTTPError — HTTP 404 如果组织在 Hub 上不存在。

Hub 上组织的成员列表。

list_papers

< >

( query: Optional[str] = None token: Union[bool, str, None] = None ) Iterable[PaperInfo]

参数

  • query (str可选) — 用于查找论文的搜索查询字符串。如果提供,则返回与查询匹配的论文。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

Iterable[PaperInfo]

一个由 huggingface_hub.hf_api.PaperInfo 对象组成的可迭代对象。

根据给定的搜索查询,列出 Hugging Face Hub 上的每日论文。

示例

>>> from huggingface_hub import HfApi

>>> api = HfApi()

# List all papers with "attention" in their title
>>> api.list_papers(query="attention")

list_pending_access_requests

< >

( repo_id: str repo_type: Optional[str] = None token: Union[bool, str, None] = None ) List[AccessRequest]

参数

  • repo_id (str) — 要获取访问请求的仓库 ID。
  • repo_type (str, 可选) — 要获取访问请求的仓库类型。必须是 modeldatasetspace 之一。默认为 model
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

List[AccessRequest]

AccessRequest 对象的列表。每个对象包含 usernameemailstatustimestamp 属性。如果受限仓库有自定义表单,fields 属性将填充用户的答案。

引发

HTTPError

  • HTTPError — 如果仓库未设门控,则返回 HTTP 400。
  • HTTPError — 如果您对仓库只有只读权限,则返回 HTTP 403。如果您在仓库所属的组织中没有 writeadmin 角色,或者您传递了 read 令牌,则可能会发生这种情况。

获取给定封闭仓库的待处理访问请求。

待处理请求意味着用户已请求访问该仓库,但请求尚未被处理。如果审批模式是自动的,此列表应为空。待处理的请求可以使用 accept_access_request()reject_access_request() 来接受或拒绝。

有关门控仓库的更多信息,请参阅 https://huggingface.co/docs/hub/models-gated

示例

>>> from huggingface_hub import list_pending_access_requests, accept_access_request

# List pending requests
>>> requests = list_pending_access_requests("meta-llama/Llama-2-7b")
>>> len(requests)
411
>>> requests[0]
[
    AccessRequest(
        username='clem',
        fullname='Clem 🤗',
        email='***',
        timestamp=datetime.datetime(2023, 11, 23, 18, 4, 53, 828000, tzinfo=datetime.timezone.utc),
        status='pending',
        fields=None,
    ),
    ...
]

# Accept Clem's request
>>> accept_access_request("meta-llama/Llama-2-7b", "clem")

list_rejected_access_requests

< >

( repo_id: str repo_type: Optional[str] = None token: Union[bool, str, None] = None ) List[AccessRequest]

参数

  • repo_id (str) — 要获取访问请求的仓库 ID。
  • repo_type (str, 可选) — 要获取访问请求的仓库类型。必须是 modeldatasetspace 之一。默认为 model
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

List[AccessRequest]

AccessRequest 对象的列表。每个对象包含 usernameemailstatustimestamp 属性。如果受限仓库有自定义表单,fields 属性将填充用户的答案。

引发

HTTPError

  • HTTPError — 如果仓库未设门控,则返回 HTTP 400。
  • HTTPError — 如果您对仓库只有只读权限,则返回 HTTP 403。如果您在仓库所属的组织中没有 writeadmin 角色,或者您传递了 read 令牌,则可能会发生这种情况。

获取给定封闭仓库的已拒绝访问请求。

已拒绝的请求意味着用户已请求访问该仓库,并且该请求已被仓库所有者(您或您组织的其他用户)明确拒绝。该用户无法下载该仓库的任何文件。被拒绝的请求可以随时使用 accept_access_request()cancel_access_request() 来接受或取消。已取消的请求将返回到待处理列表,而已接受的请求将进入已接受列表。

有关门控仓库的更多信息,请参阅 https://huggingface.co/docs/hub/models-gated

示例

>>> from huggingface_hub import list_rejected_access_requests

>>> requests = list_rejected_access_requests("meta-llama/Llama-2-7b")
>>> len(requests)
411
>>> requests[0]
[
    AccessRequest(
        username='clem',
        fullname='Clem 🤗',
        email='***',
        timestamp=datetime.datetime(2023, 11, 23, 18, 4, 53, 828000, tzinfo=datetime.timezone.utc),
        status='rejected',
        fields=None,
    ),
    ...
]

list_repo_commits

< >

( repo_id: str repo_type: Optional[str] = None token: Union[bool, str, None] = None revision: Optional[str] = None formatted: bool = False ) List[GitCommitInfo]

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个由 / 分隔的仓库名称。
  • repo_type (str, 可选) — 如果列出数据集或 Space 的提交,则设置为 "dataset""space";如果列出模型的提交,则为 None"model"。默认为 None
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • revision (str, 可选) — 要从中获取提交的 git 修订版本。默认为 "main" 分支的 HEAD。
  • formatted (bool) — 是否返回 HTML 格式的提交标题和描述。默认为 False。

返回

List[GitCommitInfo]

Hub 上仓库提交信息的对象列表。

引发

RepositoryNotFoundErrorRevisionNotFoundError

  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type,私有仓库但未认证,或仓库不存在。
  • RevisionNotFoundError — 如果在仓库中找不到版本(错误 404)。

获取 Hub 上仓库给定修订版本的提交列表。

提交按日期排序(最近的提交在前)。

示例

>>> from huggingface_hub import HfApi
>>> api = HfApi()

# Commits are sorted by date (last commit first)
>>> initial_commit = api.list_repo_commits("gpt2")[-1]

# Initial commit is always a system commit containing the `.gitattributes` file.
>>> initial_commit
GitCommitInfo(
    commit_id='9b865efde13a30c13e0a33e536cf3e4a5a9d71d8',
    authors=['system'],
    created_at=datetime.datetime(2019, 2, 18, 10, 36, 15, tzinfo=datetime.timezone.utc),
    title='initial commit',
    message='',
    formatted_title=None,
    formatted_message=None
)

# Create an empty branch by deriving from initial commit
>>> api.create_branch("gpt2", "new_empty_branch", revision=initial_commit.commit_id)

list_repo_files

< >

( repo_id: str revision: Optional[str] = None repo_type: Optional[str] = None token: Union[str, bool, None] = None ) List[str]

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个由 / 分隔的仓库名称。
  • revision (str, 可选) — 要从中获取信息的仓库的修订版本。
  • repo_type (str, 可选) — 如果上传到数据集或 Space,则设置为 "dataset""space";如果上传到模型,则为 None"model"。默认为 None
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

List[str]

给定仓库中的文件列表。

获取给定仓库中的文件列表。

list_repo_likers

< >

( repo_id: str repo_type: Optional[str] = None token: Union[bool, str, None] = None ) Iterable[User]

参数

  • repo_id (str) — 要检索的仓库。例如:"user/my-cool-model"
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, 可选) — 如果上传到数据集或 Space,则设置为 "dataset""space";如果上传到模型,则为 None"model"。默认为 None

返回

Iterable[User]

一个由 huggingface_hub.hf_api.User 对象组成的可迭代对象。

列出所有在 Hugging Face Hub 上喜欢给定仓库的用户。

另请参阅 list_liked_repos()

list_repo_refs

< >

( repo_id: str repo_type: Optional[str] = None include_pull_requests: bool = False token: Union[str, bool, None] = None ) GitRefs

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个由 / 分隔的仓库名称。
  • repo_type (str, 可选) — 如果列出数据集或 Space 的引用,则设置为 "dataset""space";如果列出模型的引用,则为 None"model"。默认为 None
  • include_pull_requests (bool, 可选) — 是否在列表中包含拉取请求的引用。默认为 False
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

GitRefs

包含 Hub 上仓库所有分支和标签信息的对象。

获取给定仓库的引用列表(包括标签和分支)。

示例

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.list_repo_refs("gpt2")
GitRefs(branches=[GitRefInfo(name='main', ref='refs/heads/main', target_commit='e7da7f221d5bf496a48136c0cd264e630fe9fcc8')], converts=[], tags=[])

>>> 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')
    ]
)

list_repo_tree

< >

( repo_id: str path_in_repo: Optional[str] = None recursive: bool = False expand: bool = False revision: Optional[str] = None repo_type: Optional[str] = None token: Union[str, bool, None] = None ) Iterable[Union[RepoFile, RepoFolder]]

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个由 / 分隔的仓库名称。
  • path_in_repo (str, 可选) — 仓库中树(文件夹)的相对路径,例如:"checkpoints/1fec34a/results"。将默认为仓库的根树(文件夹)。
  • recursive (bool, 可选, 默认为 False) — 是否递归地列出树的文件和文件夹。
  • expand (bool, 可选, 默认为 False) — 是否获取有关树的文件和文件夹的更多信息(例如,最后一次提交和文件的安全扫描结果)。此操作对服务器来说开销更大,因此每页只返回 50 个结果(而不是 1000 个)。由于分页是在 huggingface_hub 中实现的,这对您来说是透明的,除了获取结果所需的时间。
  • revision (str, 可选) — 要从中获取树的仓库修订版本。默认为 "main" 分支。
  • repo_type (str, 可选) — 要从中获取树的仓库类型("model""dataset""space")。默认为 "model"
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

Iterable[Union[RepoFile, RepoFolder]]

有关树的文件和文件夹的信息,作为 RepoFileRepoFolder 对象的可迭代对象。文件和文件夹的顺序不保证。

引发

RepositoryNotFoundErrorRevisionNotFoundErrorEntryNotFoundError

  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type,私有仓库但未认证,或仓库不存在。
  • RevisionNotFoundError — 如果在仓库中找不到版本(错误 404)。
  • EntryNotFoundError — 如果树(文件夹)在仓库中不存在(错误 404)。

列出仓库树的文件和文件夹并获取它们的信息。

示例

获取有关仓库树的信息。

>>> from huggingface_hub import list_repo_tree
>>> repo_tree = list_repo_tree("lysandre/arxiv-nlp")
>>> repo_tree
<generator object HfApi.list_repo_tree at 0x7fa4088e1ac0>
>>> list(repo_tree)
[
    RepoFile(path='.gitattributes', size=391, blob_id='ae8c63daedbd4206d7d40126955d4e6ab1c80f8f', lfs=None, last_commit=None, security=None),
    RepoFile(path='README.md', size=391, blob_id='43bd404b159de6fba7c2f4d3264347668d43af25', lfs=None, last_commit=None, security=None),
    RepoFile(path='config.json', size=554, blob_id='2f9618c3a19b9a61add74f70bfb121335aeef666', lfs=None, last_commit=None, security=None),
    RepoFile(
        path='flax_model.msgpack', size=497764107, blob_id='8095a62ccb4d806da7666fcda07467e2d150218e',
        lfs={'size': 497764107, 'sha256': 'd88b0d6a6ff9c3f8151f9d3228f57092aaea997f09af009eefd7373a77b5abb9', 'pointer_size': 134}, last_commit=None, security=None
    ),
    RepoFile(path='merges.txt', size=456318, blob_id='226b0752cac7789c48f0cb3ec53eda48b7be36cc', lfs=None, last_commit=None, security=None),
    RepoFile(
        path='pytorch_model.bin', size=548123560, blob_id='64eaa9c526867e404b68f2c5d66fd78e27026523',
        lfs={'size': 548123560, 'sha256': '9be78edb5b928eba33aa88f431551348f7466ba9f5ef3daf1d552398722a5436', 'pointer_size': 134}, last_commit=None, security=None
    ),
    RepoFile(path='vocab.json', size=898669, blob_id='b00361fece0387ca34b4b8b8539ed830d644dbeb', lfs=None, last_commit=None, security=None)]
]

获取有关仓库树的更多信息(最后一次提交和文件的安全扫描结果)。

>>> from huggingface_hub import list_repo_tree
>>> repo_tree = list_repo_tree("prompthero/openjourney-v4", expand=True)
>>> list(repo_tree)
[
    RepoFolder(
        path='feature_extractor',
        tree_id='aa536c4ea18073388b5b0bc791057a7296a00398',
        last_commit={
            'oid': '47b62b20b20e06b9de610e840282b7e6c3d51190',
            'title': 'Upload diffusers weights (#48)',
            'date': datetime.datetime(2023, 3, 21, 9, 5, 27, tzinfo=datetime.timezone.utc)
        }
    ),
    RepoFolder(
        path='safety_checker',
        tree_id='65aef9d787e5557373fdf714d6c34d4fcdd70440',
        last_commit={
            'oid': '47b62b20b20e06b9de610e840282b7e6c3d51190',
            'title': 'Upload diffusers weights (#48)',
            'date': datetime.datetime(2023, 3, 21, 9, 5, 27, tzinfo=datetime.timezone.utc)
        }
    ),
    RepoFile(
        path='model_index.json',
        size=582,
        blob_id='d3d7c1e8c3e78eeb1640b8e2041ee256e24c9ee1',
        lfs=None,
        last_commit={
            'oid': 'b195ed2d503f3eb29637050a886d77bd81d35f0e',
            'title': 'Fix deprecation warning by changing `CLIPFeatureExtractor` to `CLIPImageProcessor`. (#54)',
            'date': datetime.datetime(2023, 5, 15, 21, 41, 59, tzinfo=datetime.timezone.utc)
        },
        security={
            'safe': True,
            'av_scan': {'virusFound': False, 'virusNames': None},
            'pickle_import_scan': None
        }
    )
    ...
]

list_spaces

< >

( filter: Union[str, Iterable[str], None] = None author: Optional[str] = None search: Optional[str] = None datasets: Union[str, Iterable[str], None] = None models: Union[str, Iterable[str], None] = None linked: bool = False sort: Union[Literal['last_modified'], str, None] = None direction: Optional[Literal[-1]] = None limit: Optional[int] = None expand: Optional[List[ExpandSpaceProperty_T]] = None full: Optional[bool] = None token: Union[bool, str, None] = None ) Iterable[SpaceInfo]

参数

  • filter (strIterable, 可选) — 一个字符串标签或标签列表,可用于在 Hub 上识别 Spaces。
  • author (str, 可选) — 一个标识返回 Spaces 作者的字符串。
  • search (str, 可选) — 将包含在返回的 Spaces 中的字符串。
  • datasets (strIterable, 可选) — 是否返回使用了数据集的 Spaces。可以传递特定数据集的名称作为字符串。
  • models (strIterable, 可选) — 是否返回使用了模型的 Spaces。可以传递特定模型的名称作为字符串。
  • linked (bool, 可选) — 是否返回使用了模型或数据集的 Spaces。
  • sort (Literal["last_modified"]str, 可选) — 用于对结果模型进行排序的键。可能的值为 “last_modified”、“trending_score”、“created_at” 和 “likes”。
  • direction (Literal[-1]int, 可选) — 排序方向。值 -1 按降序排序,而所有其他值按升序排序。
  • limit (int, 可选) — 获取的 Spaces 数量限制。将此选项留为 None 会获取所有 Spaces。
  • expand (List[ExpandSpaceProperty_T], 可选) — 响应中要返回的属性列表。使用时,只有列表中的属性会被返回。如果传递了 full,则不能使用此参数。可能的值为 "author""cardData""datasets""disabled""lastModified""createdAt""likes""models""private""runtime""sdk""siblings""sha""subdomain""tags""trendingScore""usedStorage""resourceGroup""xetEnabled"
  • full (bool, 可选) — 是否获取所有 Spaces 数据,包括 last_modifiedsiblingscard_data 字段。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

Iterable[SpaceInfo]

一个由 huggingface_hub.hf_api.SpaceInfo 对象组成的可迭代对象。

根据给定的筛选条件,列出托管在 Hugging Face Hub 上的 Spaces。

list_user_followers

< >

( username: str token: Union[bool, str, None] = None ) Iterable[User]

参数

  • username (str) — 要获取其关注者的用户的用户名。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

Iterable[User]

包含该用户关注者的 User 对象列表。

引发

HTTPError

  • HTTPError — 如果用户在 Hub 上不存在,则为 HTTP 404。

获取 Hub 上用户的关注者列表。

list_user_following

< >

( username: str token: Union[bool, str, None] = None ) Iterable[User]

参数

  • username (str) — 用户的用户名,用于获取该用户关注的用户列表。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

Iterable[User]

一个包含该用户所关注用户的 User 对象列表。

引发

HTTPError

  • HTTPError — 如果用户在 Hub 上不存在,则为 HTTP 404。

获取 Hub 上某个用户所关注的用户列表。

list_webhooks

< >

( token: Union[bool, str, None] = None ) List[WebhookInfo]

参数

返回

List[WebhookInfo]

Webhook 信息对象列表。

列出所有已配置的 webhook。

示例

>>> from huggingface_hub import list_webhooks
>>> webhooks = list_webhooks()
>>> len(webhooks)
2
>>> webhooks[0]
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    secret="my-secret",
    domains=["repo", "discussion"],
    disabled=False,
)

merge_pull_request

< >

( repo_id: str discussion_num: int token: Union[bool, str, None] = None comment: Optional[str] = None repo_type: Optional[str] = None ) DiscussionStatusChange

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个仓库名称,以 / 分隔。
  • discussion_num (int) — 讨论或拉取请求的编号。必须是严格的正整数。
  • comment (str, 可选) — 随状态变更一起发布的可选评论。
  • repo_type (str, 可选) — 如果上传到数据集或空间,则设置为 "dataset""space",如果上传到模型,则为 None"model"。默认为 None
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

DiscussionStatusChange

状态更改事件

合并一个拉取请求。

引发以下错误

  • HTTPError 如果 HuggingFace API 返回错误
  • ValueError 如果某些参数值无效
  • RepositoryNotFoundError 如果找不到要下载的仓库。这可能是因为它不存在,或者是私有仓库而您没有访问权限。

model_info

< >

( repo_id: str revision: Optional[str] = None timeout: Optional[float] = None securityStatus: Optional[bool] = None files_metadata: bool = False expand: Optional[List[ExpandModelProperty_T]] = None token: Union[bool, str, None] = None ) huggingface_hub.hf_api.ModelInfo

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个仓库名称,以 / 分隔。
  • revision (str, 可选) — 要获取信息的模型仓库的版本。
  • timeout (float, 可选) — 是否为向 Hub 的请求设置超时。
  • securityStatus (bool, 可选) — 是否也从模型仓库中检索安全状态。安全状态将在 security_repo_status 字段中返回。
  • files_metadata (bool, 可选) — 是否检索仓库中文件的元数据(大小、LFS元数据等)。默认为 False
  • expand (List[ExpandModelProperty_T], 可选) — 指定在响应中返回的属性列表。使用时,仅返回列表中的属性。如果传递了 `securityStatus` 或 `files_metadata`,则不能使用此参数。可能的值包括 ` "author" `、` "baseModels" `、` "cardData" `、` "childrenModelCount" `、` "config" `、` "createdAt" `、` "disabled" `、` "downloads" `、` "downloadsAllTime" `、` "gated" `、` "gguf" `、` "inference" `、` "inferenceProviderMapping" `、` "lastModified" `、` "library_name" `、` "likes" `、` "mask_token" `、` "model-index" `、` "pipeline_tag" `、` "private" `、` "safetensors" `、` "sha" `、` "siblings" `、` "spaces" `、` "tags" `、` "transformersInfo" `、` "trendingScore" `、` "widgetData" `、` "usedStorage" `、` "resourceGroup" ` 和 ` "xetEnabled" `。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

huggingface_hub.hf_api.ModelInfo

模型仓库信息。

获取 huggingface.co 上特定模型的信息

如果你传递了可接受的令牌或已登录,模型可以是私有的。

引发以下错误

move_repo

< >

( from_id: str to_id: str repo_type: Optional[str] = None token: Union[str, bool, None] = None )

参数

  • from_id (str) — 一个命名空间(用户或组织)和一个仓库名称,以 / 分隔。原始仓库标识符。
  • to_id (str) — 一个命名空间(用户或组织)和一个仓库名称,以 / 分隔。最终仓库标识符。
  • repo_type (str, 可选) — 如果上传到数据集或空间,则设置为 "dataset""space",如果上传到模型,则为 None"model"。默认为 None
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

将一个仓库从 namespace1/repo_name1 移动到 namespace2/repo_name2

请注意存在某些限制。有关移动仓库的更多信息,请参阅 https://huggingface.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo

引发以下错误

  • RepositoryNotFoundError 如果找不到要下载的仓库。这可能是因为它不存在,或者是私有仓库而您没有访问权限。

paper_info

< >

( id: str ) PaperInfo

参数

  • id (str, 可选) — 论文的 ArXiv ID。

返回

PaperInfo

一个 PaperInfo 对象。

引发

HTTPError

  • HTTPError — 如果论文在 Hub 上不存在,则返回 HTTP 404 错误。

获取 Hub 上一篇论文的信息。

parse_safetensors_file_metadata

< >

( repo_id: str filename: str repo_type: Optional[str] = None revision: Optional[str] = None token: Union[bool, str, None] = None ) SafetensorsFileMetadata

参数

  • repo_id (str) — 一个用户或组织名称与一个仓库名称,以 / 分隔。
  • filename (str) — 仓库中的文件名。
  • repo_type (str, 可选) — 如果文件在数据集或空间中,则设置为 "dataset""space";如果在模型中,则为 None"model"。默认为 None
  • revision (str, 可选) — 获取文件的 git 修订版本。可以是一个分支名、一个标签或一个提交哈希。默认为 "main" 分支的头部。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

SafetensorsFileMetadata

与 safetensors 文件相关的信息。

引发

NotASafetensorsRepoErrorSafetensorsParsingError

  • NotASafetensorsRepoError — 如果仓库不是 safetensors 仓库,即没有 model.safetensorsmodel.safetensors.index.json 文件。
  • SafetensorsParsingError — 如果 safetensors 文件头无法正确解析。

从 Hub 上的 safetensors 文件中解析元数据。

要一次性解析仓库中所有 safetensors 文件的元数据,请使用 get_safetensors_metadata()

有关 safetensors 格式的更多详细信息,请查看 https://huggingface.co/docs/safetensors/index#format

pause_inference_endpoint

< >

( name: str namespace: Optional[str] = None token: Union[bool, str, None] = None ) InferenceEndpoint

参数

  • name (str) — 要暂停的推理端点的名称。
  • namespace (str, 可选) — 推理端点所在的命名空间。默认为当前用户。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

InferenceEndpoint

关于已暂停的推理端点的信息。

暂停一个推理端点。

暂停的推理端点不会收费。可以使用 resume_inference_endpoint() 在任何时候恢复它。这与使用 scale_to_zero_inference_endpoint() 将推理端点缩减至零不同,后者在收到请求时会自动重启。

为方便起见,你也可以使用 pause_inference_endpoint() 暂停一个推理端点。

pause_space

< >

( repo_id: str token: Union[bool, str, None] = None ) SpaceRuntime

参数

  • repo_id (str) — 要暂停的空间的 ID。例如:"Salesforce/BLIP2"
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

SpaceRuntime

关于你的空间的运行时信息,包括 `stage=PAUSED` 和请求的硬件。

引发

RepositoryNotFoundErrorHfHubHTTPErrorBadRequestError

  • RepositoryNotFoundError — 如果你的空间未找到(错误 404)。很可能是 repo_id 错误,或者你的空间是私有的但你没有进行身份验证。
  • HfHubHTTPError — 403 Forbidden: 只有空间的所有者才能暂停它。如果你想管理一个不属于你的空间,可以发起一个讨论请求所有者,或者复制该空间。
  • BadRequestError — 如果你的空间是静态空间。静态空间始终运行且不收费。如果你想隐藏一个静态空间,可以将其设置为私有。

暂停你的空间。

暂停的空间会停止运行,直到其所有者手动重启。这与免费空间在 48 小时不活动后进入的休眠状态不同。暂停的时间不会计入你的账户账单,无论你选择了何种硬件。要重启你的空间,请使用 restart_space() 并访问你的空间设置页面。

更多详情,请访问文档

permanently_delete_lfs_files

< >

( repo_id: str lfs_files: Iterable[LFSFileInfo] rewrite_history: bool = True repo_type: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • repo_id (str) — 你要列出 LFS 文件的仓库。
  • lfs_files (Iterable[LFSFileInfo]) — 一个可迭代的 LFSFileInfo 项,用于从仓库中永久删除。使用 list_lfs_files() 列出仓库中的所有 LFS 文件。
  • rewrite_history (bool, 可选, 默认为 True) — 是否重写仓库历史记录以删除引用已删除 LFS 文件的文件指针(推荐)。
  • repo_type (str, 可选) — 仓库类型。如果要从数据集或空间列出,则设置为 "dataset""space";如果要从模型列出,则为 None"model"。默认为 None
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

从 Hub 上的仓库中永久删除 LFS 文件。

这是一个永久性操作,将影响所有引用已删除文件的提交,并可能损坏你的仓库。这是一个不可逆的操作。请仅在你清楚自己在做什么时使用它。

示例

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> lfs_files = api.list_lfs_files("username/my-cool-repo")

# Filter files files to delete based on a combination of `filename`, `pushed_at`, `ref` or `size`.
# e.g. select only LFS files in the "checkpoints" folder
>>> lfs_files_to_delete = (lfs_file for lfs_file in lfs_files if lfs_file.filename.startswith("checkpoints/"))

# Permanently delete LFS files
>>> api.permanently_delete_lfs_files("username/my-cool-repo", lfs_files_to_delete)

preupload_lfs_files

< >

( repo_id: str additions: Iterable[CommitOperationAdd] token: Union[str, bool, None] = None repo_type: Optional[str] = None revision: Optional[str] = None create_pr: Optional[bool] = None num_threads: int = 5 free_memory: bool = True gitignore_content: Optional[str] = None )

参数

  • repo_id (str) — 您将要提交文件的仓库,例如:"username/custom_transformers"
  • operations (Iterable of CommitOperationAdd) — 要上传的文件列表。警告:此列表中的对象将被修改以包含与上传相关的信息。请勿对多次提交重用相同的对象。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, 可选) — 要上传到的仓库类型(例如 "model" -默认-、"dataset""space")。
  • revision (str, 可选) — 提交的 git 修订版本。默认为 "main" 分支的头部。
  • create_pr (boolean, 可选) — 是否计划用该提交创建一个拉取请求。默认为 False
  • num_threads (int, optional) — 用于上传文件的并发线程数。默认为 5。将其设置为 2 意味着最多可以同时上传 2 个文件。
  • gitignore_content (str, optional) — .gitignore 文件的内容,用于了解哪些文件应被忽略。优先级顺序是:首先检查是否传入了 gitignore_content,然后检查 .gitignore 文件是否存在于要提交的文件列表中,最后默认使用 Hub 上已托管的 .gitignore 文件(如果有的话)。

将 LFS 文件预上传到 S3,为将来的提交做准备。

如果您是动态生成要上传的文件,并且不希望在一次性上传所有文件之前将它们存储在内存中,那么此方法非常有用。

这是一个高级用户方法。您不需要直接调用它来完成正常的提交。请直接使用 create_commit()

在此过程中,提交操作(Commit operations)将被修改。特别是,附加的 path_or_fileobj 将在上传后被移除以节省内存(并被一个空的 bytes 对象替换)。请不要重用相同的对象,除非是为了将它们传递给 create_commit()。如果您不想从提交操作对象中删除附加的内容,请传递 free_memory=False

示例

>>> from huggingface_hub import CommitOperationAdd, preupload_lfs_files, create_commit, create_repo

>>> repo_id = create_repo("test_preupload").repo_id

# Generate and preupload LFS files one by one
>>> operations = [] # List of all `CommitOperationAdd` objects that will be generated
>>> for i in range(5):
...     content = ... # generate binary content
...     addition = CommitOperationAdd(path_in_repo=f"shard_{i}_of_5.bin", path_or_fileobj=content)
...     preupload_lfs_files(repo_id, additions=[addition]) # upload + free memory
...     operations.append(addition)

# Create commit
>>> create_commit(repo_id, operations=operations, commit_message="Commit all shards")

reject_access_request

< >

( repo_id: str user: str repo_type: Optional[str] = None rejection_reason: Optional[str] token: Union[bool, str, None] = None )

参数

  • repo_id (str) — 要拒绝访问请求的仓库 ID。
  • user (str) — 应拒绝其访问请求的用户的用户名。
  • repo_type (str, optional) — 要拒绝访问请求的仓库类型。必须是 modeldatasetspace 之一。默认为 model
  • rejection_reason (str, optional) — 可选的拒绝原因,将对用户可见(最多 200 个字符)。
  • token (Union[bool, str, None], optional) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

引发

HTTPError

  • HTTPError — 如果仓库未设门控,则返回 HTTP 400。
  • HTTPError — 如果您对仓库只有只读权限,则返回 HTTP 403。如果您在仓库所属的组织中没有 writeadmin 角色,或者您传递了 read 令牌,则可能会发生这种情况。
  • HTTPError — 如果 Hub 上不存在该用户,则返回 HTTP 404。
  • HTTPError — 如果找不到该用户的访问请求,则返回 HTTP 404。
  • HTTPError — 如果用户访问请求已在被拒绝列表中,则会引发 HTTP 404 错误。

拒绝某个用户对指定受限仓库的访问请求。

被拒绝的请求将进入被拒绝列表。用户无法下载该仓库的任何文件。被拒绝的请求可以随时使用 accept_access_request()cancel_access_request() 来接受或取消。取消的请求将返回到待处理列表,而接受的请求将进入已接受列表。

有关门控仓库的更多信息,请参阅 https://huggingface.co/docs/hub/models-gated

rename_discussion

< >

( repo_id: str discussion_num: int new_title: str token: Union[bool, str, None] = None repo_type: Optional[str] = None ) DiscussionTitleChange

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个仓库名称,以 / 分隔。
  • discussion_num (int) — 讨论(Discussion)或拉取请求(Pull Request)的编号。必须是严格的正整数。
  • new_title (str) — 讨论的新标题。
  • repo_type (str, optional) — 如果上传到数据集或空间,则设置为 "dataset""space";如果上传到模型,则为 None"model"。默认为 None
  • token (Union[bool, str, None], optional) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

DiscussionTitleChange

标题更改事件

重命名一个讨论。

示例

>>> new_title = "New title, fixing a typo"
>>> HfApi().rename_discussion(
...     repo_id="username/repo_name",
...     discussion_num=34
...     new_title=new_title
... )
# DiscussionTitleChange(id='deadbeef0000000', type='title-change', ...)

引发以下错误

  • HTTPError 如果 HuggingFace API 返回错误
  • ValueError 如果某些参数值无效
  • RepositoryNotFoundError 如果找不到要下载的仓库。这可能是因为它不存在,或者是私有仓库而您没有访问权限。

repo_exists

< >

( repo_id: str repo_type: Optional[str] = None token: Union[str, bool, None] = None )

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个仓库名称,以 / 分隔。
  • repo_type (str, optional) — 如果从数据集或空间获取仓库信息,则设置为 "dataset""space";如果从模型获取仓库信息,则为 None"model"。默认为 None
  • token (Union[bool, str, None], optional) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

检查 Hugging Face Hub 上是否存在某个仓库。

示例

>>> from huggingface_hub import repo_exists
>>> repo_exists("google/gemma-7b")
True
>>> repo_exists("google/not-a-repo")
False

repo_info

< >

( repo_id: str revision: Optional[str] = None repo_type: Optional[str] = None timeout: Optional[float] = None files_metadata: bool = False expand: Optional[Union[ExpandModelProperty_T, ExpandDatasetProperty_T, ExpandSpaceProperty_T]] = None token: Union[bool, str, None] = None ) Union[SpaceInfo, DatasetInfo, ModelInfo]

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个仓库名称,以 / 分隔。
  • revision (str, optional) — 要获取信息的仓库版本。
  • repo_type (str, optional) — 如果从数据集或空间获取仓库信息,则设置为 "dataset""space";如果从模型获取仓库信息,则为 None"model"。默认为 None
  • timeout (float, optional) — 是否为向 Hub 发送的请求设置超时。
  • expand (ExpandModelProperty_T or ExpandDatasetProperty_T or ExpandSpaceProperty_T, optional) — 在响应中返回的属性列表。使用时,将只返回列表中的属性。如果传递了 files_metadata,则不能使用此参数。有关可用属性的详尽列表,请查看 model_info()dataset_info()space_info()
  • files_metadata (bool, optional) — 是否检索仓库中文件的元数据(大小、LFS 元数据等)。默认为 False
  • token (Union[bool, str, None], optional) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

Union[SpaceInfo, DatasetInfo, ModelInfo]

仓库信息,作为 huggingface_hub.hf_api.DatasetInfohuggingface_hub.hf_api.ModelInfohuggingface_hub.hf_api.SpaceInfo 对象。

获取给定类型的给定仓库的信息对象。

引发以下错误

request_space_hardware

< >

( repo_id: str hardware: SpaceHardware token: Union[bool, str, None] = None sleep_time: Optional[int] = None ) SpaceRuntime

参数

  • repo_id (str) — 要更新的仓库 ID。例如:"bigcode/in-the-stack"
  • hardware (str or SpaceHardware) — 运行空间所需的硬件。例如:"t4-medium"
  • token (Union[bool, str, None], optional) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • sleep_time (int, optional) — 在空间进入休眠状态之前等待的非活动秒数。如果您不希望空间休眠,请设置为 -1(升级硬件的默认行为)。对于免费硬件,您无法配置休眠时间(固定为 48 小时不活动)。更多详情请参见 https://huggingface.co/docs/hub/spaces-gpus#sleep-time

返回

SpaceRuntime

关于 Space 的运行时信息,包括 Space 的阶段和硬件。

为空间请求新硬件。

也可以在创建空间仓库时直接请求硬件!详情请参见 create_repo()

request_space_storage

< >

( repo_id: str storage: SpaceStorage token: Union[bool, str, None] = None ) SpaceRuntime

参数

  • repo_id (str) — 要更新的空间 ID。例如:"open-llm-leaderboard/open_llm_leaderboard"
  • storage (str or SpaceStorage) — 存储层级。可以是 ‘small’、‘medium’ 或 ‘large’。
  • token (Union[bool, str, None], optional) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

SpaceRuntime

关于 Space 的运行时信息,包括 Space 的阶段和硬件。

为空间请求持久存储。

持久存储一旦授予后,便无法减少。要减少存储,您必须通过 delete_space_storage() 将其删除。

restart_space

< >

( repo_id: str token: Union[bool, str, None] = None factory_reboot: bool = False ) SpaceRuntime

参数

  • repo_id (str) — 要重新启动的空间 ID。例如:"Salesforce/BLIP2"
  • token (Union[bool, str, None], optional) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • factory_reboot (bool, optional) — 如果为 True,空间将从头开始重建,不缓存任何依赖项。

返回

SpaceRuntime

关于您的空间的运行时信息。

引发

RepositoryNotFoundErrorHfHubHTTPErrorBadRequestError

  • RepositoryNotFoundError — 如果你的空间未找到(错误 404)。很可能是 repo_id 错误,或者你的空间是私有的但你没有进行身份验证。
  • HfHubHTTPError — 403 Forbidden: 只有空间的所有者才能重新启动它。如果您想重新启动一个不属于您的空间,可以通过发起讨论(Discussion)请求所有者,或者复制该空间。
  • BadRequestError — 如果你的空间是静态空间。静态空间始终运行且不收费。如果你想隐藏一个静态空间,可以将其设置为私有。

重新启动您的空间。

如果您已将空间暂停(参见 pause_space()),这是以编程方式重新启动空间的唯一方法。您必须是空间的所有者才能重新启动它。如果您使用的是升级硬件,您的账户将在空间重新启动后立即开始计费。无论空间当前处于何种状态,您都可以触发重新启动。

更多详情,请访问文档

resume_inference_endpoint

< >

( name: str namespace: Optional[str] = None running_ok: bool = True token: Union[bool, str, None] = None ) InferenceEndpoint

参数

  • name (str) — 要恢复的推理端点的名称。
  • namespace (str, optional) — 推理端点所在的命名空间。默认为当前用户。
  • running_ok (bool, optional) — 如果为 True,当推理端点已在运行时,该方法不会引发错误。默认为 True
  • token (Union[bool, str, None], optional) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

InferenceEndpoint

关于已恢复的推理端点的信息。

恢复一个推理端点。

为方便起见,您也可以使用 InferenceEndpoint.resume() 来恢复一个推理端点。

revision_exists

< >

( repo_id: str revision: str repo_type: Optional[str] = None token: Union[str, bool, None] = None )

参数

  • repo_id (str) — 一个命名空间(用户或组织)和一个仓库名称,以 / 分隔。
  • revision (str) — 要检查的仓库版本。
  • repo_type (str, optional) — 如果从数据集或空间获取仓库信息,则设置为 "dataset""space";如果从模型获取仓库信息,则为 None"model"。默认为 None
  • token (Union[bool, str, None], optional) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

检查 Hugging Face Hub 上的某个仓库是否存在特定的版本。

示例

>>> from huggingface_hub import revision_exists
>>> revision_exists("google/gemma-7b", "float16")
True
>>> revision_exists("google/gemma-7b", "not-a-revision")
False

run_as_future

< >

( fn: Callable[..., R] *args **kwargs ) Future

参数

  • fn (Callable) — 要在后台运行的方法。
  • *args, **kwargs — 调用该方法时使用的参数。

返回

Future

一个 Future 实例,用于获取任务的结果。

在后台运行一个方法并返回一个 Future 实例。

主要目标是在不阻塞主线程的情况下运行方法(例如,在训练期间推送数据)。后台作业会排队以保持顺序,但不会并行运行。如果您需要通过并行化大量 API 调用来加速脚本,则必须设置并使用您自己的 ThreadPoolExecutor

注意:像 upload_file()upload_folder()create_commit() 这样最常用的方法有一个 run_as_future: bool 参数,可以直接在后台调用它们。这等同于对它们调用 api.run_as_future(...),但更简洁。

示例

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> future = api.run_as_future(api.whoami) # instant
>>> future.done()
False
>>> future.result() # wait until complete and return result
(...)
>>> future.done()
True

run_job

< >

( image: str command: List[str] env: Optional[Dict[str, Any]] = None secrets: Optional[Dict[str, Any]] = None flavor: Optional[SpaceHardware] = None timeout: Optional[Union[int, float, str]] = None namespace: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • image (str) — 要使用的 Docker 镜像。例如:"ubuntu""python:3.12""pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel"。使用来自 Space 的镜像示例:"hf.co/spaces/lhoestq/duckdb"
  • command (List[str]) — 要运行的命令。例如:["echo", "hello"]
  • env (Dict[str, Any], 可选) — 为作业定义环境变量。
  • secrets (Dict[str, Any], 可选) — 为作业定义机密环境变量。
  • flavor (str, 可选) — 硬件的规格,与 Hugging Face Spaces 中的一样。有关可能的值,请参阅 SpaceHardware。默认为 "cpu-basic"
  • timeout (Union[int, float, str], 可选) — 作业的最大持续时间:int/float,单位为 s(秒,默认)、m(分钟)、h(小时)或 d(天)。例如:300"5m" 表示 5 分钟。
  • namespace (str, 可选) — 将在其中创建作业的命名空间。默认为当前用户的命名空间。
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌。如果未提供,将使用本地保存的令牌,这是推荐的身份验证方法。设置为 False 可禁用身份验证。请参考:https://huggingface.co/docs/huggingface_hub/quick-start#authentication

在 Hugging Face 基础设施上运行计算作业。

示例

运行您的第一个作业

>>> from huggingface_hub import run_job
>>> run_job("python:3.12", ["python", "-c" ,"print('Hello from HF compute!')"])

运行 GPU 作业

>>> from huggingface_hub import run_job
>>> image = "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel"
>>> command = ["python", "-c", "import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")"]
>>> run_job(image, command, flavor="a10g-small")

run_uv_job

< >

( script: str script_args: Optional[List[str]] = None dependencies: Optional[List[str]] = None python: Optional[str] = None image: Optional[str] = None env: Optional[Dict[str, Any]] = None secrets: Optional[Dict[str, Any]] = None flavor: Optional[SpaceHardware] = None timeout: Optional[Union[int, float, str]] = None namespace: Optional[str] = None token: Union[bool, str, None] = None _repo: Optional[str] = None )

参数

  • script (str) — UV 脚本的路径或 URL。
  • script_args (List[str], 可选) — 传递给脚本的参数。
  • dependencies (List[str], 可选) — 运行 UV 脚本所使用的依赖项。
  • python (str, 可选) — 使用特定的 Python 版本。默认为 3.12。
  • image (str, 可选,默认为 “ghcr.io/astral-sh/uv —python3.12-bookworm”): 使用一个已安装 uv 的自定义 Docker 镜像。
  • env (Dict[str, Any], 可选) — 为作业定义环境变量。
  • secrets (Dict[str, Any], 可选) — 为作业定义机密环境变量。
  • flavor (str, 可选) — 硬件的规格,与 Hugging Face Spaces 中的一样。有关可能的值,请参阅 SpaceHardware。默认为 "cpu-basic"
  • timeout (Union[int, float, str], 可选) — 作业的最大持续时间:int/float,单位为 s(秒,默认)、m(分钟)、h(小时)或 d(天)。例如:300"5m" 表示 5 分钟。
  • namespace (str, 可选) — 将在其中创建作业的命名空间。默认为当前用户的命名空间。
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌。如果未提供,将使用本地保存的令牌,这是推荐的身份验证方法。设置为 False 可禁用身份验证。请参考:https://huggingface.co/docs/huggingface_hub/quick-start#authentication

在 Hugging Face 基础设施上运行 UV 脚本作业。

示例

>>> from huggingface_hub import run_uv_job
>>> script = "https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py"
>>> run_uv_job(script, dependencies=["trl"], flavor="a10g-small")

scale_to_zero_inference_endpoint

< >

( name: str namespace: Optional[str] = None token: Union[bool, str, None] = None ) InferenceEndpoint

参数

  • name (str) — 要缩减至零的推理端点的名称。
  • namespace (str, 可选) — 推理端点所在的命名空间。默认为当前用户。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

InferenceEndpoint

关于缩减至零的推理端点的信息。

将推理端点缩减至零。

缩减至零的推理端点将不会被计费。它将在下一次请求时恢复,并有冷启动延迟。这与使用 pause_inference_endpoint() 暂停推理端点不同,后者需要使用 resume_inference_endpoint() 手动恢复。

为方便起见,您还可以使用 InferenceEndpoint.scale_to_zero() 将推理端点缩减至零。

set_space_sleep_time

< >

( repo_id: str sleep_time: int token: Union[bool, str, None] = None ) SpaceRuntime

参数

  • repo_id (str) — 要更新的仓库 ID。例如:"bigcode/in-the-stack"
  • sleep_time (int, 可选) — 在 Space 进入休眠状态前等待的非活动秒数。如果您不希望您的 Space 暂停,请设置为 -1(升级硬件的默认行为)。对于免费硬件,您无法配置休眠时间(该值固定为 48 小时不活动)。更多详情请参阅 https://huggingface.co/docs/hub/spaces-gpus#sleep-time
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

SpaceRuntime

关于 Space 的运行时信息,包括 Space 的阶段和硬件。

为在升级硬件上运行的 Space 设置自定义休眠时间。

您的 Space 将在 X 秒不活动后进入休眠状态。当您的 Space 处于“休眠”模式时,您不会被计费。如果有新访客访问您的 Space,它将会“唤醒”。只有升级的硬件才能配置休眠时间。要了解有关休眠阶段的更多信息,请参考 https://huggingface.co/docs/hub/spaces-gpus#sleep-time

在使用 request_space_hardware() 请求硬件时,也可以设置自定义休眠时间。

snapshot_download

< >

( repo_id: str repo_type: Optional[str] = None revision: Optional[str] = None cache_dir: Union[str, Path, None] = None local_dir: Union[str, Path, None] = None proxies: Optional[Dict] = None etag_timeout: float = 10 force_download: bool = False token: Union[bool, str, None] = None local_files_only: bool = False allow_patterns: Optional[Union[List[str], str]] = None ignore_patterns: Optional[Union[List[str], str]] = None max_workers: int = 8 tqdm_class: Optional[Type[base_tqdm]] = None local_dir_use_symlinks: Union[bool, Literal['auto']] = 'auto' resume_download: Optional[bool] = None ) str

参数

  • repo_id (str) — 用户或组织名称和仓库名称,用 / 分隔。
  • repo_type (str, 可选) — 如果从数据集或空间下载,则设置为 "dataset""space";如果从模型下载,则为 None"model"。默认为 None
  • revision (str, 可选) — 可选的 Git 修订版 ID,可以是一个分支名称、一个标签或一个提交哈希值。
  • cache_dir (str, Path, 可选) — 存储缓存文件的文件夹路径。
  • local_dir (strPath, 可选) — 如果提供,下载的文件将放置在此目录下。
  • proxies (dict, 可选) — 协议到代理 URL 的字典映射,传递给 requests.request
  • etag_timeout (float, 可选, 默认为 10) — 获取 ETag 时,在放弃之前等待服务器发送数据的秒数,传递给 requests.request
  • force_download (bool, 可选, 默认为 False) — 即使文件已存在于本地缓存中,是否也应下载。
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • local_files_only (bool, 可选, 默认为 False) — 如果为 True,则避免下载文件,如果本地缓存文件存在,则返回其路径。
  • allow_patterns (List[str]str, 可选) — 如果提供,则仅下载与至少一个模式匹配的文件。
  • ignore_patterns (List[str]str, 可选) — 如果提供,则不下载与任何模式匹配的文件。
  • max_workers (int, 可选) — 下载文件的并发线程数(1 个线程 = 1 个文件下载)。默认为 8。
  • tqdm_class (tqdm, 可选) — 如果提供,将覆盖进度条的默认行为。传递的参数必须继承自 tqdm.auto.tqdm 或至少模仿其行为。请注意,tqdm_class 不会传递给每个单独的下载。默认为自定义的 HF 进度条,可以通过设置 HF_HUB_DISABLE_PROGRESS_BARS 环境变量来禁用。

返回

字符串

仓库快照的文件夹路径。

引发

RepositoryNotFoundErrorRevisionNotFoundErrorEnvironmentErrorOSErrorValueError

下载仓库文件。

下载指定修订版中仓库文件的完整快照。当您需要仓库中的所有文件,但事先不知道具体需要哪些文件时,这非常有用。所有文件都嵌套在一个文件夹内,以保持它们相对于该文件夹的实际文件名。您还可以使用 allow_patternsignore_patterns 过滤要下载的文件。

如果提供了 local_dir,仓库的文件结构将在此位置被复制。使用此选项时,将不使用 cache_dir,并将在 local_dir 的根目录下创建一个 .cache/huggingface/ 文件夹,以存储与下载文件相关的一些元数据。虽然此机制不如主缓存系统稳健,但它为定期拉取仓库的最新版本进行了优化。

另一种方法是克隆仓库,但这需要安装并正确配置 git 和 git-lfs。使用 git 克隆仓库时,也无法过滤要下载的文件。

space_info

< >

( repo_id: str revision: Optional[str] = None timeout: Optional[float] = None files_metadata: bool = False expand: Optional[List[ExpandSpaceProperty_T]] = None token: Union[bool, str, None] = None ) SpaceInfo

参数

  • repo_id (str) — 一个命名空间(用户或组织)和仓库名称,用 / 分隔。
  • revision (str, 可选) — 要获取信息的空间仓库的修订版。
  • timeout (float, 可选) — 是否为向 Hub 的请求设置超时。
  • files_metadata (bool, 可选) — 是否检索仓库中文件的元数据(大小、LFS 元数据等)。默认为 False
  • expand (List[ExpandSpaceProperty_T], 可选) — 在响应中返回的属性列表。使用时,只有列表中的属性会被返回。如果传递了 full,则不能使用此参数。可能的值为 "author""cardData""createdAt""datasets""disabled""lastModified""likes""models""private""runtime""sdk""siblings""sha""subdomain""tags""trendingScore""usedStorage""resourceGroup""xetEnabled"
  • token (Union[bool, str, None], 可选) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

SpaceInfo

空间仓库信息。

获取 huggingface.co 上某个特定 Space 的信息。

如果传递了可接受的令牌,Space 可以是私有的。

引发以下错误

super_squash_history

< >

( repo_id: str branch: Optional[str] = None commit_message: Optional[str] = None repo_type: Optional[str] = None token: Union[str, bool, None] = None )

参数

  • repo_id (str) — 命名空间(用户或组织)和仓库名称,以 / 分隔。
  • branch (str, optional) — 要压缩历史的分支。默认为 "main" 分支的头部。
  • commit_message (str, optional) — 用于压缩提交的提交信息。
  • repo_type (str, optional) — 如果是列出数据集或 Space 的提交,则设置为 "dataset""space";如果是列出模型的提交,则为 None"model"。默认为 None
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

引发

RepositoryNotFoundErrorRevisionNotFoundErrorBadRequestError

  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type,私有仓库但未认证,或仓库不存在。
  • RevisionNotFoundError — 如果找不到要压缩的分支。
  • BadRequestError — 如果分支的引用无效。您不能在标签上压缩历史记录。

在 Hub 上的仓库的某个分支上压缩提交历史。

当您知道将进行数百次提交并且不想让历史变得混乱时,压缩仓库历史非常有用。压缩提交只能在分支的头部执行。

一旦压缩,提交历史将无法恢复。这是一个不可逆的操作。

一旦某个分支的历史被压缩,就无法将其合并回另一个分支,因为它们的历史已经分叉。

示例

>>> from huggingface_hub import HfApi
>>> api = HfApi()

# Create repo
>>> repo_id = api.create_repo("test-squash").repo_id

# Make a lot of commits.
>>> api.upload_file(repo_id=repo_id, path_in_repo="file.txt", path_or_fileobj=b"content")
>>> api.upload_file(repo_id=repo_id, path_in_repo="lfs.bin", path_or_fileobj=b"content")
>>> api.upload_file(repo_id=repo_id, path_in_repo="file.txt", path_or_fileobj=b"another_content")

# Squash history
>>> api.super_squash_history(repo_id=repo_id)

unlike

< >

( repo_id: str token: Union[bool, str, None] = None repo_type: Optional[str] = None )

参数

  • repo_id (str) — 要取消点赞的仓库。示例:"user/my-cool-model"
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, optional) — 如果要取消点赞的是数据集或 Space,则设置为 "dataset""space";如果要取消点赞的是模型,则为 None"model"。默认为 None

引发

RepositoryNotFoundError

  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type,私有仓库但未认证,或仓库不存在。

取消对 Hub 上指定仓库的点赞(例如,从收藏列表中移除)。

为防止垃圾邮件行为,无法通过脚本 点赞 仓库。

另请参阅 list_liked_repos()

示例

>>> from huggingface_hub import list_liked_repos, unlike
>>> "gpt2" in list_liked_repos().models # we assume you have already liked gpt2
True
>>> unlike("gpt2")
>>> "gpt2" in list_liked_repos().models
False

update_collection_item

< >

( collection_slug: str item_object_id: str note: Optional[str] = None position: Optional[int] = None token: Union[bool, str, None] = None )

参数

  • collection_slug (str) — 要更新的合集的 slug。示例:"TheBloke/recent-models-64f9a55bb3115b4f513ec026"
  • item_object_id (str) — 合集中项目的 ID。这不是 Hub 上项目(repo_id 或 paper id)的 ID。它必须从 CollectionItem 对象中检索。示例:collection.items[0].item_object_id
  • note (str, optional) — 附加到合集中项目的备注。备注的最大长度为 500 个字符。
  • position (int, optional) — 项目在合集中的新位置。
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

更新合集中的一个项目。

示例

>>> from huggingface_hub import get_collection, update_collection_item

# Get collection first
>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")

# Update item based on its ID (add note + update position)
>>> update_collection_item(
...     collection_slug="TheBloke/recent-models-64f9a55bb3115b4f513ec026",
...     item_object_id=collection.items[-1].item_object_id,
...     note="Newly updated model!"
...     position=0,
... )

update_collection_metadata

< >

( collection_slug: str title: Optional[str] = None description: Optional[str] = None position: Optional[int] = None private: Optional[bool] = None theme: Optional[str] = None token: Union[bool, str, None] = None )

参数

  • collection_slug (str) — 要更新的合集的 slug。示例:"TheBloke/recent-models-64f9a55bb3115b4f513ec026"
  • title (str) — 要更新的合集的标题。
  • description (str, optional) — 要更新的合集的描述。
  • position (int, optional) — 合集在用户合集列表中的新位置。
  • private (bool, optional) — 合集是否应为私有。
  • theme (str, optional) — Hub 上合集的主题。
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

更新 Hub 上合集的元数据。

所有参数都是可选的。只有提供的元数据才会被更新。

返回: Collection

示例

>>> from huggingface_hub import update_collection_metadata
>>> collection = update_collection_metadata(
...     collection_slug="username/iccv-2023-64f9a55bb3115b4f513ec026",
...     title="ICCV Oct. 2023"
...     description="Portfolio of models, datasets, papers and demos I presented at ICCV Oct. 2023",
...     private=False,
...     theme="pink",
... )
>>> collection.slug
"username/iccv-oct-2023-64f9a55bb3115b4f513ec026"
# ^collection slug got updated but not the trailing ID

update_inference_endpoint

< >

( name: str accelerator: Optional[str] = None instance_size: Optional[str] = None instance_type: Optional[str] = None min_replica: Optional[int] = None max_replica: Optional[int] = None scale_to_zero_timeout: Optional[int] = None repository: Optional[str] = None framework: Optional[str] = None revision: Optional[str] = None task: Optional[str] = None custom_image: Optional[Dict] = None env: Optional[Dict[str, str]] = None secrets: Optional[Dict[str, str]] = None domain: Optional[str] = None path: Optional[str] = None cache_http_responses: Optional[bool] = None tags: Optional[List[str]] = None namespace: Optional[str] = None token: Union[bool, str, None] = None ) InferenceEndpoint

参数

  • name (str) — 要更新的推理端点的名称。
  • accelerator (str, optional) — 用于推理的硬件加速器(例如 "cpu")。
  • instance_size (str, optional) — 用于托管模型的实例的大小或类型(例如 "x4")。
  • instance_type (str, optional) — 推理端点将部署的云实例类型(例如 "intel-icl")。
  • min_replica (int, optional) — 推理端点保持运行的最小副本(实例)数量。
  • max_replica (int, optional) — 推理端点可以扩展到的最大副本(实例)数量。
  • scale_to_zero_timeout (int, optional) — 非活动端点缩减至零之前的持续时间(分钟)。
  • repository (str, optional) — 与推理端点关联的模型仓库的名称(例如 "gpt2")。
  • framework (str, optional) — 用于模型的机器学习框架(例如 "custom")。
  • revision (str, optional) — 在推理端点上部署的特定模型修订版(例如 "6c0e6080953db56375760c0471a8c5f2929baf11")。
  • task (str, optional) — 部署模型的任务(例如 "text-classification")。
  • custom_image (Dict, optional) — 用于推理端点的自定义 Docker 镜像。如果您想部署一个运行在 text-generation-inference (TGI) 框架上的推理端点,这将非常有用(请参阅示例)。
  • env (Dict[str, str], optional) — 注入到容器环境中的非机密环境变量
  • secrets (Dict[str, str], optional) — 注入到容器环境中的机密值。
  • domain (str, optional) — 推理端点部署的自定义域名,如果设置,推理端点将在此域名下可用(例如 "my-new-domain.cool-website.woof")。
  • path (str, optional) — 已部署模型的自定义路径,应以 / 开头(例如 "/models/google-bert/bert-base-uncased")。
  • cache_http_responses (bool, optional) — 是否缓存来自推理端点的 HTTP 响应。
  • tags (List[str], optional) — 与推理端点关联的标签列表。
  • namespace (str, optional) — 将要更新推理端点的命名空间。默认为当前用户的命名空间。
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

InferenceEndpoint

有关更新后的推理端点的信息。

更新一个推理端点。

此方法允许更新计算配置、部署的模型、路由或它们的任意组合。所有参数都是可选的,但至少必须提供一个。

为了方便起见,您也可以使用 InferenceEndpoint.update() 来更新推理端点。

update_repo_settings

< >

( repo_id: str gated: Optional[Literal['auto', 'manual', False]] = None private: Optional[bool] = None token: Union[str, bool, None] = None repo_type: Optional[str] = None xet_enabled: Optional[bool] = None )

参数

  • repo_id (str) — 命名空间(用户或组织)和仓库名称,以 / 分隔。
  • gated (Literal["auto", "manual", False], optional) — 存储库的访问控制状态。如果设置为 None (默认值),则不会更新存储库的 gated 设置。
    • “auto”:存储库受访问控制,访问请求会根据预定义标准自动批准或拒绝。
    • “manual”:存储库受访问控制,访问请求需要手动批准。
    • False:存储库不受访问控制,任何人都可以访问。
  • private (bool, optional) — 存储库是否应为私有。
  • token (Union[str, bool, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False。
  • repo_type (str, optional) — 要更新设置的存储库类型("model""dataset""space")。默认为 "model"
  • xet_enabled (bool, optional) — 是否为存储库启用 Xet 存储。

引发

ValueErrorHfHubHTTPErrorRepositoryNotFoundError

  • ValueError — 如果 gated 不是“auto”、“manual”或 False 之一。
  • ValueError — 如果 repo_type 不是 constants.REPO_TYPES 中的值之一。
  • HfHubHTTPError — 如果向 Hugging Face Hub API 的请求失败。
  • RepositoryNotFoundError — 如果要下载的仓库找不到。这可能是因为它不存在,或者它被设置为 private 而您没有访问权限。

更新存储库的设置,包括访问控制和可见性。

为了更好地控制存储库的使用方式,Hub 允许存储库作者为其存储库启用访问请求,并将存储库的可见性设置为私有。

update_repo_visibility

< >

( repo_id: str private: bool = False token: Union[str, bool, None] = None repo_type: Optional[str] = None )

参数

  • repo_id (str, optional) — 一个命名空间(用户或组织)和一个存储库名称,由 / 分隔。
  • private (bool, optional, defaults to False) — 存储库是否应为私有。
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, optional) — 如果上传到数据集或空间,则设置为 "dataset""space";如果上传到模型,则为 None"model"。默认为 None

更新存储库的可见性设置。

已弃用。请改用 update_repo_settings

引发以下错误

  • RepositoryNotFoundError 如果找不到要下载的仓库。这可能是因为它不存在,或者是私有仓库而您没有访问权限。

update_webhook

< >

( webhook_id: str url: Optional[str] = None watched: Optional[List[Union[Dict, WebhookWatchedItem]]] = None domains: Optional[List[constants.WEBHOOK_DOMAIN_T]] = None secret: Optional[str] = None token: Union[bool, str, None] = None ) WebhookInfo

参数

  • webhook_id (str) — 要更新的 webhook 的唯一标识符。
  • url (str, optional) — 将发送有效负载的 URL。
  • watched (List[WebhookWatchedItem], optional) — 要监视的项目列表。可以是用户、组织、模型、数据集或空间。更多详情请参阅 WebhookWatchedItem。监视的项目也可以作为普通字典提供。
  • domains (List[Literal["repo", "discussion"]], optional) — 要监视的域。可以包括“repo”、“discussion”或两者。
  • secret (str, optional) — 用于签署有效负载的密钥,提供额外的安全层。
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

WebhookInfo

关于已更新的 webhook 的信息。

更新现有的 webhook。

示例

>>> from huggingface_hub import update_webhook
>>> updated_payload = update_webhook(
...     webhook_id="654bbbc16f2ec14d77f109cc",
...     url="https://new.webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
...     watched=[{"type": "user", "name": "julien-c"}, {"type": "org", "name": "HuggingFaceH4"}],
...     domains=["repo"],
...     secret="my-secret",
... )
>>> print(updated_payload)
WebhookInfo(
    id="654bbbc16f2ec14d77f109cc",
    url="https://new.webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
    watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
    domains=["repo"],
    secret="my-secret",
    disabled=False,

upload_file

< >

( path_or_fileobj: Union[str, Path, bytes, BinaryIO] path_in_repo: str repo_id: str token: Union[str, bool, None] = None repo_type: Optional[str] = None revision: Optional[str] = None commit_message: Optional[str] = None commit_description: Optional[str] = None create_pr: Optional[bool] = None parent_commit: Optional[str] = None run_as_future: bool = False ) CommitInfo or Future

参数

  • path_or_fileobj (str, Path, bytes, or IO) — 本地机器上的文件路径或二进制数据流/文件对象/缓冲区。
  • path_in_repo (str) — 存储库中的相对文件路径,例如:"checkpoints/1fec34a/weights.bin"
  • repo_id (str) — 文件将上传到的存储库,例如:"username/custom_transformers"
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, optional) — 如果上传到数据集或空间,则设置为 "dataset""space";如果上传到模型,则为 None"model"。默认为 None
  • revision (str, optional) — 要提交的 git 修订版本。默认为 "main" 分支的头部。
  • commit_message (str, optional) — 生成的提交的摘要/标题/第一行
  • commit_description (str optional) — 生成的提交的描述
  • create_pr (boolean, optional) — 是否为此提交创建一个拉取请求。默认为 False。如果未设置 revision,则针对 "main" 分支打开拉取请求。如果设置了 revision 并且它是一个分支,则针对此分支打开拉取请求。如果设置了 revision 但不是分支名称(例如:提交的 oid),服务器将返回 RevisionNotFoundError
  • parent_commit (str, optional) — 父提交的 OID / SHA,以十六进制字符串表示。也支持简写(前 7 个字符)。如果指定且 create_prFalse,则当 revision 未指向 parent_commit 时,提交将失败。如果指定且 create_prTrue,则拉取请求将从 parent_commit 创建。指定 parent_commit 可确保在提交更改之前存储库未发生变化,这在存储库被并发更新/提交时尤其有用。
  • run_as_future (bool, optional) — 是否在后台运行此方法。后台作业按顺序运行,不阻塞主线程。传递 run_as_future=True 将返回一个 Future 对象。默认为 False

返回

CommitInfo or Future

CommitInfo 的实例,包含有关新创建的提交的信息(提交哈希、提交 URL、PR URL、提交消息……)。如果传递了 run_as_future=True,则返回一个 Future 对象,执行后将包含结果。

将本地文件(最大 50 GB)上传到给定的存储库。上传通过 HTTP post 请求完成,不需要安装 git 或 git-lfs。

引发以下错误

upload_file 假定存储库已存在于 Hub 上。如果您收到客户端错误 404,请确保您已通过身份验证,并且 repo_idrepo_type 设置正确。如果存储库不存在,请先使用 create_repo() 创建它。

示例

>>> from huggingface_hub import upload_file

>>> with open("./local/filepath", "rb") as fobj:
...     upload_file(
...         path_or_fileobj=fileobj,
...         path_in_repo="remote/file/path.h5",
...         repo_id="username/my-dataset",
...         repo_type="dataset",
...         token="my_token",
...     )
"https://huggingface.co/datasets/username/my-dataset/blob/main/remote/file/path.h5"

>>> upload_file(
...     path_or_fileobj=".\\local\\file\\path",
...     path_in_repo="remote/file/path.h5",
...     repo_id="username/my-model",
...     token="my_token",
... )
"https://huggingface.co/username/my-model/blob/main/remote/file/path.h5"

>>> upload_file(
...     path_or_fileobj=".\\local\\file\\path",
...     path_in_repo="remote/file/path.h5",
...     repo_id="username/my-model",
...     token="my_token",
...     create_pr=True,
... )
"https://huggingface.co/username/my-model/blob/refs%2Fpr%2F1/remote/file/path.h5"

upload_folder

< >

( repo_id: str folder_path: Union[str, Path] path_in_repo: Optional[str] = None commit_message: Optional[str] = None commit_description: Optional[str] = None token: Union[str, bool, None] = None repo_type: Optional[str] = None revision: Optional[str] = None create_pr: Optional[bool] = None parent_commit: Optional[str] = None allow_patterns: Optional[Union[List[str], str]] = None ignore_patterns: Optional[Union[List[str], str]] = None delete_patterns: Optional[Union[List[str], str]] = None run_as_future: bool = False ) CommitInfo or Future

参数

  • repo_id (str) — 文件将上传到的存储库,例如:"username/custom_transformers"
  • folder_path (str or Path) — 本地文件系统上要上传的文件夹的路径
  • path_in_repo (str, optional) — 存储库中目录的相对路径,例如:"checkpoints/1fec34a/results"。将默认为存储库的根文件夹。
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, optional) — 如果上传到数据集或空间,则设置为 "dataset""space";如果上传到模型,则为 None"model"。默认为 None
  • revision (str, optional) — 要提交的 git 修订版本。默认为 "main" 分支的头部。
  • commit_message (str, optional) — 生成的提交的摘要/标题/第一行。默认为:f"Upload {path_in_repo} with huggingface_hub"
  • commit_description (str optional) — 生成的提交的描述
  • create_pr (boolean, optional) — 是否为此提交创建一个拉取请求。默认为 False。如果未设置 revision,则针对 "main" 分支打开拉取请求。如果设置了 revision 并且它是一个分支,则针对此分支打开拉取请求。如果设置了 revision 但不是分支名称(例如:提交的 oid),服务器将返回 RevisionNotFoundError
  • parent_commit (str, optional) — 父提交的 OID / SHA,以十六进制字符串表示。也支持简写(前 7 个字符)。如果指定且 create_prFalse,则当 revision 未指向 parent_commit 时,提交将失败。如果指定且 create_prTrue,则拉取请求将从 parent_commit 创建。指定 parent_commit 可确保在提交更改之前存储库未发生变化,这在存储库被并发更新/提交时尤其有用。
  • allow_patterns (List[str] or str, optional) — 如果提供,则仅上传至少匹配一个模式的文件。
  • ignore_patterns (List[str] or str, optional) — 如果提供,则不上传匹配任何模式的文件。
  • delete_patterns (List[str] or str, optional) — 如果提供,则在提交新文件时,匹配任何模式的远程文件将从存储库中删除。如果您不知道哪些文件已经上传,这会很有用。注意:为避免不一致,即使 .gitattributes 文件匹配模式,也不会被删除。
  • run_as_future (bool, optional) — 是否在后台运行此方法。后台作业按顺序运行,不阻塞主线程。传递 run_as_future=True 将返回一个 Future 对象。默认为 False

返回

CommitInfo or Future

CommitInfo 的实例,包含有关新创建的提交的信息(提交哈希、提交 URL、PR URL、提交消息……)。如果传递了 run_as_future=True,则返回一个 Future 对象,执行后将包含结果。

将本地文件夹上传到给定的存储库。上传通过 HTTP 请求完成,不需要安装 git 或 git-lfs。

文件夹的结构将被保留。存储库中已存在的同名文件将被覆盖。其他文件将保持不变。

使用 allow_patternsignore_patterns 参数指定要上传的文件。这些参数接受单个模式或模式列表。模式是标准通配符(globbing 模式),如此处所述。如果同时提供了 allow_patternsignore_patterns,则两个约束都将适用。默认情况下,将上传文件夹中的所有文件。

使用 delete_patterns 参数指定要删除的远程文件。输入类型与 allow_patterns 相同(见上文)。如果还提供了 path_in_repo,则模式将与相对于此文件夹的路径匹配。例如,upload_folder(..., path_in_repo="experiment", delete_patterns="logs/*") 将删除 ./experiment/logs/ 下的任何远程文件。请注意,即使 .gitattributes 文件匹配模式,也不会被删除。

任何子目录中存在的 .git/ 文件夹都将被忽略。但是,请注意,.gitignore 文件不会被考虑。

内部使用 HfApi.create_commit

引发以下错误

upload_folder 假定存储库已存在于 Hub 上。如果您收到客户端错误 404,请确保您已通过身份验证,并且 repo_idrepo_type 设置正确。如果存储库不存在,请先使用 create_repo() 创建它。

在处理大型文件夹(数千个文件或数百GB)时,我们建议改用 upload_large_folder()

示例

# Upload checkpoints folder except the log files
>>> upload_folder(
...     folder_path="local/checkpoints",
...     path_in_repo="remote/experiment/checkpoints",
...     repo_id="username/my-dataset",
...     repo_type="datasets",
...     token="my_token",
...     ignore_patterns="**/logs/*.txt",
... )
# "https://huggingface.co/datasets/username/my-dataset/tree/main/remote/experiment/checkpoints"

# Upload checkpoints folder including logs while deleting existing logs from the repo
# Useful if you don't know exactly which log files have already being pushed
>>> upload_folder(
...     folder_path="local/checkpoints",
...     path_in_repo="remote/experiment/checkpoints",
...     repo_id="username/my-dataset",
...     repo_type="datasets",
...     token="my_token",
...     delete_patterns="**/logs/*.txt",
... )
"https://huggingface.co/datasets/username/my-dataset/tree/main/remote/experiment/checkpoints"

# Upload checkpoints folder while creating a PR
>>> upload_folder(
...     folder_path="local/checkpoints",
...     path_in_repo="remote/experiment/checkpoints",
...     repo_id="username/my-dataset",
...     repo_type="datasets",
...     token="my_token",
...     create_pr=True,
... )
"https://huggingface.co/datasets/username/my-dataset/tree/refs%2Fpr%2F1/remote/experiment/checkpoints"

upload_large_folder

< >

( repo_id: str folder_path: Union[str, Path] repo_type: str revision: Optional[str] = None private: Optional[bool] = None allow_patterns: Optional[Union[List[str], str]] = None ignore_patterns: Optional[Union[List[str], str]] = None num_workers: Optional[int] = None print_report: bool = True print_report_every: int = 60 )

参数

  • repo_id (str) — 文件将上传到的仓库。例如 "HuggingFaceTB/smollm-corpus"
  • folder_path (strPath) — 本地文件系统上要上传的文件夹路径。
  • repo_type (str) — 仓库的类型。必须是 "model""dataset""space" 之一。与所有其他 HfApi 方法不同,此处明确要求 repo_type。这是为了避免在向 Hub 上传大型文件夹时出现任何错误,从而防止需要重新上传所有内容。
  • revision (str, 可选) — 要提交到的分支。如果未提供,将使用 main 分支。
  • private (bool, 可选) — 仓库是否应为私有。如果为 None(默认值),仓库将是公开的,除非组织的默认设置为私有。
  • allow_patterns (List[str]str, 可选) — 如果提供,则只上传匹配至少一个模式的文件。
  • ignore_patterns (List[str]str, 可选) — 如果提供,匹配任何模式的文件都不会被上传。
  • num_workers (int, 可选) — 启动的工作进程数。默认为 os.cpu_count() - 2(最少为 2)。如果你的机器允许,更多的工作进程可能会加快处理速度。然而,在网络连接较慢的机器上,建议保持较低的工作进程数以确保更好的续传能力。因为如果进程中断,部分上传的文件将不得不完全重新上传。
  • print_report (bool, 可选) — 是否打印上传进度的报告。默认为 True。报告每 X 秒(默认为 60 秒)打印到 sys.stdout,并覆盖之前的报告。
  • print_report_every (int, 可选) — 打印报告的频率。默认为 60 秒。

以最稳健的方式将大型文件夹上传到 Hub。

启动多个工作进程以优化方式上传文件。在提交到仓库之前,文件必须被哈希,并且如果是 LFS 文件,则必须预上传。工作进程将为文件夹中的每个文件执行这些任务。在每一步中,有关上传过程的一些元数据信息会保存在文件夹下的 .cache/.huggingface/ 中,以便在进程中断时能够恢复。整个过程可能会产生多次提交。

需要注意的几点

尽管 upload_large_folder 在上传大型文件夹方面更为稳健,但在功能上比 upload_folder() 更受限。具体来说:

  • 你不能设置自定义的 path_in_repo。如果想上传到子文件夹,你需要在本地设置好相应的结构。
  • 你不能设置自定义的 commit_messagecommit_description,因为会创建多次提交。
  • 上传时不能从仓库中删除文件。请先单独进行一次提交来删除文件。
  • 你不能直接创建 PR。请先创建 PR(通过 UI 或使用 create_pull_request()),然后通过传递 revision 参数来向其提交。

技术细节

upload_large_folder 过程如下:

  1. (检查参数并设置。)
  2. 如果仓库不存在,则创建仓库。
  3. 列出本地待上传的文件。
  4. 运行验证检查,如果可能超出仓库限制,则显示警告。
    • 如果文件总数超过 10 万个(推荐限制),则发出警告。
    • 如果任何文件夹包含超过 1 万个文件(推荐限制),则发出警告。
    • 对大于 20GB(推荐)或 50GB(硬限制)的文件发出警告。
  5. 启动工作进程。工作进程可以执行以下任务:
    • 哈希一个文件。
    • 获取文件列表的上传模式(常规或 LFS)。
    • 预上传一个 LFS 文件。
    • 提交一批文件。一旦一个工作进程完成一项任务,它将根据优先级列表(见下文)移至下一个任务,直到所有文件都已上传并提交。
  6. 工作进程运行时,定期向 sys.stdout 打印报告。

优先级顺序

  1. 如果距离上次提交尝试已超过 5 分钟(且至少有 1 个文件),则提交。
  2. 如果至少有 150 个文件准备好提交,则提交。
  3. 如果至少有 10 个文件已被哈希,则获取上传模式。
  4. 如果至少有 1 个文件且没有工作进程在预上传,则预上传 LFS 文件。
  5. 如果至少有 1 个文件且没有工作进程在哈希,则哈希文件。
  6. 如果至少有 1 个文件且没有工作进程在获取上传模式,则获取上传模式。
  7. 如果至少有 1 个文件,则预上传 LFS 文件(例外:如果启用了 hf_transfer,一次只能有 1 个工作进程预上传 LFS)。
  8. 如果至少有 1 个文件要哈希,则哈希文件。
  9. 如果至少有 1 个文件要获取上传模式,则获取上传模式。
  10. 如果至少有 1 个文件要提交,并且距离上次提交尝试至少 1 分钟,则提交。
  11. 如果至少有 1 个文件要提交,并且所有其他队列都为空,则提交。

特殊规则

  • 如果启用了 hf_transfer,一次只能有 1 个 LFS 上传器。否则 CPU 会被 hf_transfer 占用过多。
  • 一次只能有一个工作进程进行提交。
  • 如果没有可用任务,工作进程会等待 10 秒后再次检查。

whoami

< >

( token: Union[bool, str, None] = None )

参数

调用 HF API 以了解“whoami”。

API 数据类

AccessRequest

class huggingface_hub.hf_api.AccessRequest

< >

( username: str fullname: str email: Optional[str] timestamp: datetime status: Literal['pending', 'accepted', 'rejected'] fields: Optional[Dict[str, Any]] = None )

参数

  • username (str) — 请求访问的用户的用户名。
  • fullname (str) — 请求访问的用户的全名。
  • email (Optional[str]) — 请求访问的用户的电子邮件。只有在用户被手动授予访问权限的情况下,在 /accepted 列表中该值才可能为 `None`。
  • timestamp (datetime) — 请求的时间戳。
  • status (Literal["pending", "accepted", "rejected"]) — 请求的状态。可以是 ["pending", "accepted", "rejected"] 之一。
  • fields (Dict[str, Any], 可选) — 用户在准入表单中填写的附加字段。

包含用户访问请求信息的数据结构。

CommitInfo

class huggingface_hub.CommitInfo

< >

( *args commit_url: str _url: Optional[str] = None **kwargs )

参数

  • commit_url (str) — 提交所在的 URL。
  • commit_message (str) — 已创建提交的摘要(第一行)。
  • commit_description (str) — 已创建提交的描述。可以为空。
  • oid (str) — 提交的哈希 ID。例如:"91c54ad1727ee830252e457677f467be0bfd8a57"
  • pr_url (str, 可选) — 已创建的 PR 的 URL(如果有的话)。当传递 `create_pr=True` 时会填充此字段。
  • pr_revision (str, 可选) — 已创建的 PR 的修订版本(如果有的话)。当传递 `create_pr=True` 时会填充此字段。例如:`"refs/pr/1"`。
  • pr_num (int, 可选) — 已创建的 PR 讨论的编号(如果有的话)。当传递 `create_pr=True` 时会填充此字段。可以作为 `discussion_num` 传递给 get_discussion_details()。例如:`1`。
  • repo_url (RepoUrl) — 提交的仓库 URL,包含 repo_id、repo_type 等信息。
  • _url (str, 可选) — 用于 str 兼容性的旧版 URL。可以是指向 Hub 上已上传文件的 URL(如果由 upload_file() 返回)、指向 Hub 上已上传文件夹的 URL(如果由 upload_folder() 返回)或指向 Hub 上提交的 URL(如果由 create_commit() 返回)。默认为 `commit_url`。使用此属性已被弃用。请改用 `commit_url`。

包含有关新创建的提交信息的数据结构。

由任何在 Hub 上创建提交的方法返回:create_commit()upload_file()upload_folder()delete_file()delete_folder()。为了向后兼容,它继承自 str,但使用特定于 str 的方法已被弃用。

DatasetInfo

class huggingface_hub.DatasetInfo

< >

( **kwargs )

参数

  • id (str) — 数据集的 ID。
  • author (str) — 数据集的作者。
  • sha (str) — 此特定修订版本的仓库 SHA。
  • created_at (datetime, 可选) — 仓库在 Hub 上的创建日期。请注意,最低值为 `2022-03-02T23:29:04.000Z`,对应于我们开始存储创建日期的日期。
  • last_modified (datetime, 可选) — 仓库的最后一次提交日期。
  • private (bool) — 仓库是否为私有。
  • disabled (bool, 可选) — 仓库是否被禁用。
  • gated (Literal["auto", "manual", False], 可选) — 仓库是否有准入限制。如果是,是手动批准还是自动批准。
  • downloads (int) — 数据集在过去 30 天内的下载次数。
  • downloads_all_time (int) — 模型自创建以来的累计下载次数。
  • likes (int) — 数据集的点赞数。
  • tags (List[str]) — 数据集的标签列表。
  • card_data (DatasetCardData, 可选) — 作为 huggingface_hub.repocard_data.DatasetCardData 对象的模型卡元数据。
  • siblings (List[RepoSibling]) — 构成数据集的 huggingface_hub.hf_api.RepoSibling 对象列表。
  • paperswithcode_id (str, 可选) — 数据集的 Papers with code ID。
  • trending_score (int, optional) — 数据集的热度得分。

包含 Hub 上数据集的信息。此对象由 dataset_info()list_datasets() 返回。

此类别的大多数属性都是可选的。这是因为 Hub 返回的数据取决于所做的查询。通常,查询越具体,返回的信息就越多。相反,当使用 list_datasets() 列出数据集时,只返回属性的一个子集。

GitRefInfo

class huggingface_hub.GitRefInfo

< >

( name: str ref: str target_commit: str )

参数

  • name (str) — 引用的名称(例如标签名或分支名)。
  • ref (str) — Hub 上的完整 git 引用(例如 "refs/heads/main""refs/tags/v1.0")。
  • target_commit (str) — 引用的目标提交的 OID(例如 "e7da7f221d5bf496a48136c0cd264e630fe9fcc8")。

包含 Hub 上仓库的 git 引用信息。

GitCommitInfo

class huggingface_hub.GitCommitInfo

< >

( commit_id: str authors: List[str] created_at: datetime title: str message: str formatted_title: Optional[str] formatted_message: Optional[str] )

参数

  • commit_id (str) — 提交的 OID(例如 "e7da7f221d5bf496a48136c0cd264e630fe9fcc8")。
  • authors (List[str]) — 提交的作者列表。
  • created_at (datetime) — 提交的创建日期和时间。
  • title (str) — 提交的标题。这是一个由作者输入的自由文本值。
  • message (str) — 提交的描述。这是一个由作者输入的自由文本值。
  • formatted_title (str) — 格式化为 HTML 的提交标题。仅在设置 formatted=True 时返回。
  • formatted_message (str) — 格式化为 HTML 的提交描述。仅在设置 formatted=True 时返回。

包含 Hub 上仓库的 git 提交信息。更多详情请查看 list_repo_commits()

GitRefs

class huggingface_hub.GitRefs

< >

( branches: List[GitRefInfo] converts: List[GitRefInfo] tags: List[GitRefInfo] pull_requests: Optional[List[GitRefInfo]] = None )

参数

  • branches (List[GitRefInfo]) — 一个包含仓库分支信息的 GitRefInfo 列表。
  • converts (List[GitRefInfo]) — 一个包含仓库“convert”引用信息的 GitRefInfo 列表。Converts 是用于在数据集仓库中推送预处理数据的引用(内部使用)。
  • tags (List[GitRefInfo]) — 一个包含仓库标签信息的 GitRefInfo 列表。
  • pull_requests (List[GitRefInfo], optional) — 一个包含仓库拉取请求信息的 GitRefInfo 列表。仅在设置 include_prs=True 时返回。

包含 Hub 上仓库的所有 git 引用信息。

此对象由 list_repo_refs() 返回。

InferenceProviderMapping

class huggingface_hub.hf_api.InferenceProviderMapping

< >

( **kwargs )

LFSFileInfo

class huggingface_hub.hf_api.LFSFileInfo

< >

( **kwargs )

参数

  • file_oid (str) — 文件的 SHA-256 对象 ID。这是永久删除文件时需要传递的标识符。
  • filename (str) — LFS 对象的可能文件名。更多信息请参见上面的注释。
  • oid (str) — LFS 对象的 OID。
  • pushed_at (datetime) — LFS 对象推送到仓库的日期。
  • ref (str, optional) — LFS 对象推送到的引用(如果有的话)。
  • size (int) — LFS 对象的大小。

包含有关 Hub 上仓库中存储为 LFS 的文件的信息。

用于列出和永久删除仓库中的 LFS 文件以释放空间。更多详情请查看 list_lfs_files()permanently_delete_lfs_files()

Git LFS 文件使用 SHA-256 对象 ID 而非文件路径进行跟踪,以优化性能。这种方法是必要的,因为单个对象可以被不同提交中的多个路径引用,这使得搜索和解析这些连接变得不切实际。请查看我们的文档,了解如何知道每个 SHA 关联的文件名。

示例

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> lfs_files = api.list_lfs_files("username/my-cool-repo")

# Filter files files to delete based on a combination of `filename`, `pushed_at`, `ref` or `size`.
# e.g. select only LFS files in the "checkpoints" folder
>>> lfs_files_to_delete = (lfs_file for lfs_file in lfs_files if lfs_file.filename.startswith("checkpoints/"))

# Permanently delete LFS files
>>> api.permanently_delete_lfs_files("username/my-cool-repo", lfs_files_to_delete)

ModelInfo

class huggingface_hub.ModelInfo

< >

( **kwargs )

参数

  • id (str) — 模型 ID。
  • author (str, optional) — 模型的作者。
  • sha (str, optional) — 在特定修订版本下的仓库 SHA。
  • created_at (datetime, optional) — 在 Hub 上创建仓库的日期。请注意,最小值是 2022-03-02T23:29:04.000Z,对应于我们开始存储创建日期的日期。
  • last_modified (datetime, optional) — 最后一次提交到仓库的日期。
  • private (bool) — 仓库是否为私有。
  • disabled (bool, optional) — 仓库是否被禁用。
  • downloads (int) — 过去 30 天内模型的下载次数。
  • downloads_all_time (int) — 模型自创建以来的累计下载次数。
  • gated (Literal["auto", "manual", False], optional) — 仓库是否有访问限制。如果是,是手动批准还是自动批准。
  • gguf (Dict, optional) — 模型的 GGUF 信息。
  • inference (Literal["warm"], optional) — 模型在推理提供商上的状态。如果模型由至少一个提供商提供服务,则为 Warm。
  • inference_provider_mapping (List[InferenceProviderMapping], optional) — 一个按用户提供商顺序排列的 InferenceProviderMapping 列表。
  • likes (int) — 模型的点赞数。
  • library_name (str, optional) — 与模型关联的库。
  • tags (List[str]) — 模型的标签列表。与 card_data.tags 相比,包含由 Hub 计算的额外标签(例如支持的库、模型的 arXiv)。
  • pipeline_tag (str, optional) — 与模型关联的流水线标签。
  • mask_token (str, optional) — 模型使用的掩码标记。
  • widget_data (Any, optional) — 与模型关联的小组件数据。
  • model_index (Dict, optional) — 用于评估的模型索引。
  • config (Dict, optional) — 模型配置。
  • transformers_info (TransformersInfo, optional) — 与模型关联的 Transformers 特定信息(自动类、处理器等)。
  • trending_score (int, optional) — 模型的热度得分。
  • card_data (ModelCardData, optional) — 模型卡元数据,作为 huggingface_hub.repocard_data.ModelCardData 对象。
  • siblings (List[RepoSibling]) — 构成模型的 huggingface_hub.hf_api.RepoSibling 对象列表。
  • spaces (List[str], 可选) — 使用该模型的 Space 列表。
  • safetensors (SafeTensorsInfo, 可选) — 模型的 safetensors 信息。
  • security_repo_status (Dict, 可选) — 模型的安全扫描状态。

包含有关 Hub 上模型的信息。此对象由 model_info()list_models() 返回。

此类别的大多数属性都是可选的。这是因为 Hub 返回的数据取决于所做的查询。通常,查询越具体,返回的信息就越多。相反,当使用 list_models() 列出模型时,仅返回属性的子集。

RepoSibling

class huggingface_hub.hf_api.RepoSibling

< >

( rfilename: str size: Optional[int] = None blob_id: Optional[str] = None lfs: Optional[BlobLfsInfo] = None )

参数

  • rfilename (str) — 文件名,相对于仓库根目录。
  • size (int, 可选) — 文件大小,以字节为单位。当 repo_info() 的 `files_metadata` 参数设置为 `True` 时,此属性被定义。否则为 `None`。
  • blob_id (str, 可选) — 文件的 git OID。当 repo_info() 的 `files_metadata` 参数设置为 `True` 时,此属性被定义。否则为 `None`。
  • lfs (BlobLfsInfo, 可选) — 文件的 LFS 元数据。当 repo_info() 的 `files_metadata` 参数设置为 `True` 且文件使用 Git LFS 存储时,此属性被定义。否则为 `None`。

包含有关 Hub 上仓库中文件的基本信息。

除了 `rfilename` 外,此类的所有属性都是可选的。这是因为在 Hub 上列出仓库时(使用 list_models()list_datasets()list_spaces()),只返回文件名。如果您需要更多信息,如文件大小、blob id 或 lfs 详细信息,您必须一次从一个仓库中专门请求它们(使用 model_info()dataset_info()space_info()),因为这会给后端服务器检索这些信息带来更多约束。

RepoFile

class huggingface_hub.hf_api.RepoFile

< >

( **kwargs )

参数

  • path (str) — 相对于仓库根目录的文件路径。
  • size (int) — 文件大小,以字节为单位。
  • blob_id (str) — 文件的 git OID。
  • lfs (BlobLfsInfo) — 文件的 LFS 元数据。
  • last_commit (LastCommitInfo, 可选) — 文件的最后一次提交元数据。仅当使用 `expand=True` 调用 list_repo_tree()get_paths_info() 时定义。
  • security (BlobSecurityInfo, 可选) — 文件的安全扫描元数据。仅当使用 `expand=True` 调用 list_repo_tree()get_paths_info() 时定义。

包含有关 Hub 上文件的信息。

RepoUrl

class huggingface_hub.RepoUrl

< >

( url: Any endpoint: Optional[str] = None )

参数

  • url (Any) — 仓库 URL 的字符串值。
  • endpoint (str, 可选) — Hub 的端点。默认为 https://huggingface.co

引发

ValueError

str 的子类,描述 Hub 上的仓库 URL。

`RepoUrl` 由 `HfApi.create_repo` 返回。为了向后兼容,它继承自 `str`。在初始化时,会解析 URL 以填充属性

  • endpoint (`str`)
  • namespace (`Optional[str]`)
  • repo_name (`str`)
  • repo_id (`str`)
  • repo_type (`Literal["model", "dataset", "space"]`)
  • url (`str`)

示例

>>> RepoUrl('https://huggingface.co/gpt2')
RepoUrl('https://huggingface.co/gpt2', endpoint='https://huggingface.co', repo_type='model', repo_id='gpt2')

>>> RepoUrl('https://hub-ci.huggingface.co/datasets/dummy_user/dummy_dataset', endpoint='https://hub-ci.huggingface.co')
RepoUrl('https://hub-ci.huggingface.co/datasets/dummy_user/dummy_dataset', endpoint='https://hub-ci.huggingface.co', repo_type='dataset', repo_id='dummy_user/dummy_dataset')

>>> RepoUrl('hf://datasets/my-user/my-dataset')
RepoUrl('hf://datasets/my-user/my-dataset', endpoint='https://huggingface.co', repo_type='dataset', repo_id='user/dataset')

>>> HfApi.create_repo("dummy_model")
RepoUrl('https://huggingface.co/Wauplin/dummy_model', endpoint='https://huggingface.co', repo_type='model', repo_id='Wauplin/dummy_model')

SafetensorsRepoMetadata

class huggingface_hub.utils.SafetensorsRepoMetadata

< >

( metadata: typing.Optional[typing.Dict] sharded: bool weight_map: typing.Dict[str, str] files_metadata: typing.Dict[str, huggingface_hub.utils._safetensors.SafetensorsFileMetadata] )

参数

  • metadata (Dict, 可选) — 包含在 ‘model.safetensors.index.json’ 文件中的元数据,如果该文件存在。仅对分片模型填充。
  • sharded (bool) — 仓库是否包含分片模型。
  • weight_map (Dict[str, str]) — 所有权重的映射。键是张量名称,值是包含这些张量的文件的文件名。
  • files_metadata (Dict[str, SafetensorsFileMetadata]) — 所有文件元数据的映射。键是文件名,值是相应文件的元数据,作为 `SafetensorsFileMetadata` 对象。
  • parameter_count (Dict[str, int]) — 每种数据类型的参数数量映射。键是数据类型,值是该数据类型的参数数量。

Safetensors 仓库的元数据。

如果一个仓库的根目录下包含 ‘model.safetensors’ 权重文件(非共享模型)或 ‘model.safetensors.index.json’ 索引文件(分片模型),则该仓库被视为 Safetensors 仓库。

此类由 get_safetensors_metadata() 返回。

有关 safetensors 格式的更多详细信息,请查看 https://huggingface.co/docs/safetensors/index#format

SafetensorsFileMetadata

class huggingface_hub.utils.SafetensorsFileMetadata

< >

( metadata: typing.Dict[str, str] tensors: typing.Dict[str, huggingface_hub.utils._safetensors.TensorInfo] )

参数

  • metadata (Dict) — 文件中包含的元数据。
  • tensors (Dict[str, TensorInfo]) — 所有张量的映射。键是张量名称,值是相应张量的信息,作为 `TensorInfo` 对象。
  • parameter_count (Dict[str, int]) — 每种数据类型的参数数量映射。键是数据类型,值是该数据类型的参数数量。

托管在 Hub 上的 Safetensors 文件的元数据。

此类由 parse_safetensors_file_metadata() 返回。

有关 safetensors 格式的更多详细信息,请查看 https://huggingface.co/docs/safetensors/index#format

SpaceInfo

class huggingface_hub.SpaceInfo

< >

( **kwargs )

参数

  • id (str) — Space 的 ID。
  • author (str, 可选) — Space 的作者。
  • sha (str, 可选) — 仓库在此特定修订版的 SHA。
  • created_at (datetime, 可选) — 仓库在 Hub 上创建的日期。请注意,最低值为 `2022-03-02T23:29:04.000Z`,对应于我们开始存储创建日期的日期。
  • last_modified (datetime, 可选) — 对仓库的最后一次提交日期。
  • private (bool) — 仓库是否为私有。
  • gated (Literal["auto", "manual", False], 可选) — 仓库是否受限。如果是,是手动批准还是自动批准。
  • disabled (bool, 可选) — Space 是否被禁用。
  • host (str, 可选) — Space 的主机 URL。
  • subdomain (str, 可选) — Space 的子域。
  • likes (int) — Space 的点赞数。
  • tags (List[str]) — Space 的标签列表。
  • siblings (List[RepoSibling]) — 构成 Space 的 huggingface_hub.hf_api.RepoSibling 对象列表。
  • card_data (SpaceCardData, 可选) — Space 卡片元数据,作为 huggingface_hub.repocard_data.SpaceCardData 对象。
  • runtime (SpaceRuntime, 可选) — Space 运行时信息,作为 huggingface_hub.hf_api.SpaceRuntime 对象。
  • sdk (str, 可选) — Space 使用的 SDK。
  • models (List[str], 可选) — Space 使用的模型列表。
  • datasets (List[str], 可选) — Space 使用的数据集列表。
  • trending_score (int, 可选) — Space 的热门分数。

包含有关 Hub 上 Space 的信息。此对象由 space_info()list_spaces() 返回。

此类别的大多数属性都是可选的。这是因为 Hub 返回的数据取决于所做的查询。通常,查询越具体,返回的信息就越多。相反,当使用 list_spaces() 列出 Space 时,仅返回属性的子集。

TensorInfo

class huggingface_hub.utils.TensorInfo

< >

( dtype: typing.Literal['F64', 'F32', 'F16', 'BF16', 'I64', 'I32', 'I16', 'I8', 'U8', 'BOOL'] shape: typing.List[int] data_offsets: typing.Tuple[int, int] )

参数

  • dtype (str) — 张量的数据类型(“F64”、“F32”、“F16”、“BF16”、“I64”、“I32”、“I16”、“I8”、“U8”、“BOOL”)。
  • shape (List[int]) — 张量的形状。
  • data_offsets (Tuple[int, int]) — 文件中数据的偏移量,格式为元组 [BEGIN, END]
  • parameter_count (int) — 张量中的参数数量。

关于张量的信息。

有关 safetensors 格式的更多详细信息,请查看 https://huggingface.co/docs/safetensors/index#format

User

class huggingface_hub.User

< >

( **kwargs )

参数

  • username (str) — 用户在 Hub 上的名称(唯一)。
  • fullname (str) — 用户的全名。
  • avatar_url (str) — 用户头像的 URL。
  • details (str, optional) — 用户的详细信息。
  • is_following (bool, optional) — 认证用户是否正在关注此用户。
  • is_pro (bool, optional) — 用户是否是专业版用户。
  • num_models (int, optional) — 用户创建的模型数量。
  • num_datasets (int, optional) — 用户创建的数据集数量。
  • num_spaces (int, optional) — 用户创建的 Spaces 数量。
  • num_discussions (int, optional) — 用户发起的讨论数量。
  • num_papers (int, optional) — 用户撰写的论文数量。
  • num_upvotes (int, optional) — 用户收到的点赞数。
  • num_likes (int, optional) — 用户给出的点赞数量。
  • num_following (int, optional) — 该用户正在关注的用户数量。
  • num_followers (int, optional) — 关注该用户的用户数量。
  • orgs (Organization 的列表) — 用户所属组织的列表。

包含有关 Hub 上用户的信息。

UserLikes

class huggingface_hub.UserLikes

< >

( user: str total: int datasets: List[str] models: List[str] spaces: List[str] )

参数

  • user (str) — 我们为其获取点赞的用户的名称。
  • total (int) — 点赞总数。
  • datasets (List[str]) — 用户点赞的数据集列表(以 repo_ids 形式)。
  • models (List[str]) — 用户点赞的模型列表(以 repo_ids 形式)。
  • spaces (List[str]) — 用户点赞的 Spaces 列表(以 repo_ids 形式)。

包含有关用户在 Hub 上点赞的信息。

WebhookInfo

class huggingface_hub.WebhookInfo

< >

( id: str url: str watched: List[WebhookWatchedItem] domains: List[constants.WEBHOOK_DOMAIN_T] secret: Optional[str] disabled: bool )

参数

  • id (str) — Webhook 的 ID。
  • url (str) — Webhook 的 URL。
  • watched (List[WebhookWatchedItem]) — Webhook 监视的项目列表,请参阅 WebhookWatchedItem
  • domains (List[WEBHOOK_DOMAIN_T]) — Webhook 正在监视的域列表。可以是 ["repo", "discussions"] 中的一个。
  • secret (str, optional) — Webhook 的密钥。
  • disabled (bool) — Webhook 是否被禁用。

包含有关 Webhook 信息的数据结构。

WebhookWatchedItem

class huggingface_hub.WebhookWatchedItem

< >

( type: Literal['dataset', 'model', 'org', 'space', 'user'] name: str )

参数

  • type (Literal["dataset", "model", "org", "space", "user"]) — 要监视的项目的类型。可以是 ["dataset", "model", "org", "space", "user"] 中的一个。
  • name (str) — 要监视的项目的名称。可以是用户名、组织名、模型名、数据集名或 Space 名。

包含有关 Webhook 监视的项目信息的数据结构。

CommitOperation

以下是 `CommitOperation()` 支持的值

class huggingface_hub.CommitOperationAdd

< >

( path_in_repo: str path_or_fileobj: typing.Union[str, pathlib.Path, bytes, typing.BinaryIO] )

参数

  • path_in_repo (str) — 仓库中的相对文件路径,例如:"checkpoints/1fec34a/weights.bin"
  • path_or_fileobj (str, Path, bytes, or BinaryIO) — 以下任一:
    • 要上传的本地文件的路径(作为 `str` 或 `pathlib.Path`)
    • 保存要上传文件内容的字节缓冲区(`bytes`)
    • 一个“文件对象”(`io.BufferedIOBase` 的子类),通常通过 `open(path, "rb")` 获取。它必须支持 `seek()` 和 `tell()` 方法。

引发

ValueError

  • ValueError — 如果 `path_or_fileobj` 不是 `str`、`Path`、`bytes` 或 `io.BufferedIOBase` 中的一种。
  • ValueError — 如果 `path_or_fileobj` 是一个 `str` 或 `Path` 但不是一个已存在文件的路径。
  • ValueError — 如果 `path_or_fileobj` 是一个 `io.BufferedIOBase` 但它不同时支持 `seek()` 和 `tell()`。

包含将文件上传到 Hub 仓库所需信息的数据结构。

as_file

< >

( with_tqdm: bool = False )

参数

  • with_tqdm (bool, optional, 默认为 False) — 如果为 True,迭代文件对象时将显示进度条。仅当类文件对象是文件路径时才有效。纯字节和缓冲区不支持。

一个上下文管理器,它产生一个类文件对象,允许读取 `path_or_fileobj` 后面的底层数据。

示例

>>> operation = CommitOperationAdd(
...        path_in_repo="remote/dir/weights.h5",
...        path_or_fileobj="./local/weights.h5",
... )
CommitOperationAdd(path_in_repo='remote/dir/weights.h5', path_or_fileobj='./local/weights.h5')

>>> with operation.as_file() as file:
...     content = file.read()

>>> with operation.as_file(with_tqdm=True) as file:
...     while True:
...         data = file.read(1024)
...         if not data:
...              break
config.json: 100%|█████████████████████████| 8.19k/8.19k [00:02<00:00, 3.72kB/s]

>>> with operation.as_file(with_tqdm=True) as file:
...     requests.put(..., data=file)
config.json: 100%|█████████████████████████| 8.19k/8.19k [00:02<00:00, 3.72kB/s]

b64content

< >

( )

`path_or_fileobj` 经过 base64 编码的内容

返回: bytes

class huggingface_hub.CommitOperationDelete

< >

( path_in_repo: str is_folder: typing.Union[bool, typing.Literal['auto']] = 'auto' )

参数

  • path_in_repo (str) — 仓库中的相对文件路径,例如:文件的路径为 `"checkpoints/1fec34a/weights.bin"` 或文件夹的路径为 `"checkpoints/1fec34a/"`。
  • is_folder (bool or Literal["auto"], optional) — 删除操作是否应用于文件夹。如果为“auto”,则通过检查路径是否以“/”(文件夹)结尾来自动猜测路径类型。要明确设置路径类型,可以设置 `is_folder=True` 或 `is_folder=False`。

包含从 Hub 仓库中删除文件或文件夹所需信息的数据结构。

class huggingface_hub.CommitOperationCopy

< >

( src_path_in_repo: str path_in_repo: str src_revision: typing.Optional[str] = None _src_oid: typing.Optional[str] = None _dest_oid: typing.Optional[str] = None )

参数

  • src_path_in_repo (str) — 待复制文件在仓库中的相对路径,例如 `"checkpoints/1fec34a/weights.bin"`。
  • path_in_repo (str) — 文件要复制到的仓库中的相对路径,例如 `"checkpoints/1fec34a/weights_copy.bin"`。
  • src_revision (str, optional) — 待复制文件的 git 修订版本。可以是任何有效的 git 修订版本。默认为目标提交的修订版本。

包含在 Hub 仓库中复制文件所需信息的数据结构。

局限性

  • 只有 LFS 文件可以被复制。要复制常规文件,您需要先将其下载到本地再重新上传。
  • 不支持跨仓库复制。

注意:您可以组合使用 CommitOperationCopyCommitOperationDelete 在 Hub 上重命名 LFS 文件。

CommitScheduler

class huggingface_hub.CommitScheduler

< >

( repo_id: str folder_path: typing.Union[str, pathlib.Path] every: typing.Union[int, float] = 5 path_in_repo: typing.Optional[str] = None repo_type: typing.Optional[str] = None revision: typing.Optional[str] = None private: typing.Optional[bool] = None token: typing.Optional[str] = None allow_patterns: typing.Union[typing.List[str], str, NoneType] = None ignore_patterns: typing.Union[typing.List[str], str, NoneType] = None squash_history: bool = False hf_api: typing.Optional[ForwardRef('HfApi')] = None )

参数

  • repo_id (str) — 要提交到的仓库的 ID。
  • folder_path (strPath) — 需要定期上传的本地文件夹路径。
  • every (intfloat, 可选) — 每次提交之间间隔的分钟数。默认为 5 分钟。
  • path_in_repo (str, 可选) — 仓库中目录的相对路径,例如:"checkpoints/"。默认为仓库的根文件夹。
  • repo_type (str, 可选) — 要提交到的仓库类型。默认为 model
  • revision (str, 可选) — 要提交到的仓库的版本。默认为 main
  • private (bool, 可选) — 是否将仓库设为私有。如果为 None(默认值),仓库将是公开的,除非组织的默认设置是私有。如果仓库已存在,此值将被忽略。
  • token (str, 可选) — 用于提交到仓库的令牌。默认为保存在本地计算机上的令牌。
  • allow_patterns (List[str]str, 可选) — 如果提供,则只上传至少匹配一个模式的文件。
  • ignore_patterns (List[str]str, 可选) — 如果提供,则不上传任何匹配模式的文件。
  • squash_history (bool, 可选) — 是否在每次提交后压缩仓库的历史记录。默认为 False。当仓库变得过大时,压缩提交历史有助于避免性能下降。
  • hf_api (HfApi, 可选) — 用于向 Hub 提交的 HfApi 客户端。可以设置自定义配置(用户代理、令牌等)。

用于定期将本地文件夹上传到 Hub 的调度器(例如,每 5 分钟推送到 Hub)。

推荐使用调度器作为上下文管理器。这可以确保调度器在脚本结束时被正确停止并触发最后一次提交。调度器也可以使用 stop 方法手动停止。请查看上传指南以了解更多关于如何使用它的信息。

示例

>>> from pathlib import Path
>>> from huggingface_hub import CommitScheduler

# Scheduler uploads every 10 minutes
>>> csv_path = Path("watched_folder/data.csv")
>>> CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path=csv_path.parent, every=10)

>>> with csv_path.open("a") as f:
...     f.write("first line")

# Some time later (...)
>>> with csv_path.open("a") as f:
...     f.write("second line")

使用上下文管理器的示例

>>> from pathlib import Path
>>> from huggingface_hub import CommitScheduler

>>> with CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path="watched_folder", every=10) as scheduler:
...     csv_path = Path("watched_folder/data.csv")
...     with csv_path.open("a") as f:
...         f.write("first line")
...     (...)
...     with csv_path.open("a") as f:
...         f.write("second line")

# Scheduler is now stopped and last commit have been triggered

push_to_hub

< >

( )

将文件夹推送到 Hub 并返回提交信息。

此方法不应直接调用。它由调度器在后台运行,并遵循队列机制以避免并发提交。直接调用此方法可能导致并发问题。

push_to_hub 的默认行为是假设文件夹为只追加模式。它会列出文件夹中的所有文件,并只上传已更改的文件。如果未发现更改,该方法将返回而不进行任何提交。如果你想改变这种行为,可以继承 CommitScheduler 并重写此方法。例如,这在提交前将数据压缩到单个文件中会很有用。更多细节和示例,请查看我们的集成指南

stop

< >

( )

停止调度器。

已停止的调度器无法重新启动。主要用于测试目的。

trigger

< >

( )

触发一个 push_to_hub 并返回一个 future 对象。

此方法每隔 every 分钟自动调用一次。你也可以手动调用它来立即触发一次提交,而无需等待下一次计划的提交。

< > 在 GitHub 上更新