Hub Python 库

( 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 请求的库的名称。将添加到 user-agent 标头中。示例："transformers"。
library_version (str, 可选) — 发出 HTTP 请求的库的版本。将添加到 user-agent 标头中。示例："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, 可选) — 要接受访问请求的仓库类型。必须是 model、dataset 或 space 之一。默认为 model。
token (Union[bool, str, None], 可选) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

引发

HTTPError

HTTPError — 如果仓库未门控，则返回 HTTP 400。
HTTPError — 如果您只有对仓库的只读访问权限，则返回 HTTP 403。如果您在仓库所属的组织中没有 write 或 admin 角色，或者您传递了 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, optional) — 附加到集合中项目的注释。注释的最大大小为 500 个字符。
exists_ok (bool, optional) — 如果为 True，则在项目已存在时不要引发错误。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

引发

HTTPError

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

将项目添加到 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, optional) — 密钥描述。示例："Github API key to access the Github API"。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 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) — 变量的描述。示例："Model Repo ID of the implemented model"。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 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, optional) — 仓库的类型。应为 "model"、"dataset" 或 "space" 之一。如果未指定，则默认为 "model"。
token (Union[bool, str, None], optional) — 有效的用户访问令牌。如果未提供，将使用本地保存的令牌，这是推荐的身份验证方法。设置为 False 以禁用身份验证。请参阅：https://huggingface.co/docs/huggingface_hub/quick-start#authentication。

引发

RepositoryNotFoundError 或 GatedRepoError

RepositoryNotFoundError — 如果仓库不存在、是私有的或用户无权访问，则引发。如果 repo_id 或 repo_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, optional) — 要取消访问请求的仓库的类型。必须是 model、dataset 或 space 之一。默认为 model。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

引发

HTTPError

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

取消给定门控仓库的用户访问请求。

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

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

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, 可选) — 如果上传到数据集或 Space，则设置为 "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 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。

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, 可选) — 如果上传到数据集或 Space，则设置为 "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 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。

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, 可选) — 如果在数据集或 Space 上创建分支，则设置为 "dataset" 或 "space"，如果在模型上标记，则设置为 None 或 "model"。默认为 None。
exist_ok (bool, 可选，默认为 False) — 如果为 True，则在分支已存在时不要引发错误。

引发

RepositoryNotFoundError 或 BadRequestError 或 HfHubHTTPError

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()) — 要包含在提交中的操作的可迭代对象，可以是以下之一：
- CommitOperationAdd 用于上传文件
- CommitOperationDelete 用于删除文件
- CommitOperationCopy 用于复制文件
操作对象将被修改以包含与上传相关的信息。不要为多个提交重用相同的对象。
commit_message (str) — 将要创建的提交的摘要（第一行）。
commit_description (str, optional) — 将要创建的提交的描述。
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。
revision (str, optional) — 要从中提交的 git 版本。默认为 "main" 分支的头部。
create_pr (boolean, optional) — 是否使用该提交创建拉取请求。默认为 False。如果未设置 revision，则针对 "main" 分支打开 PR。如果设置了 revision 并且是分支，则针对该分支打开 PR。如果设置了 revision 并且不是分支名称（例如：提交 oid），则服务器会返回 RevisionNotFoundError。
num_threads (int, optional) — 用于上传文件的并发线程数。默认为 5。设置为 2 意味着最多将并发上传 2 个文件。
parent_commit (str, optional) — 父提交的 OID / SHA，作为十六进制字符串。也支持简写形式（前 7 个字符）。如果指定了此项且 create_pr 为 False，则当 revision 未指向 parent_commit 时，提交将失败。如果指定了此项且 create_pr 为 True，则将从 parent_commit 创建拉取请求。指定 parent_commit 可确保在提交更改之前仓库未发生更改，并且在仓库同时更新/提交时尤其有用。
run_as_future (bool, optional) — 是否在后台运行此方法。后台作业按顺序运行，不会阻塞主线程。传递 run_as_future=True 将返回一个 Future 对象。默认为 False。

返回值

CommitInfo 或 Future

CommitInfo 的实例，包含有关新创建的提交的信息（提交哈希、提交 URL、PR URL、提交消息等）。如果传递了 run_as_future=True，则返回一个 Future 对象，该对象将在执行时包含结果。

引发

ValueError 或 RepositoryNotFoundError

ValueError — 如果提交消息为空。
ValueError — 如果父提交不是有效的提交 OID。
ValueError — 如果提交了具有无效元数据部分的 README.md 文件。在这种情况下，提交将提前失败，在尝试上传任何文件之前。
ValueError — 如果 create_pr 为 True 且 revision 既不是 None 也不是 "main"。
RepositoryNotFoundError — 如果找不到仓库（错误 404）：错误的 repo_id/repo_type、私有但未经验证或仓库不存在。

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

在提交过程中，输入的 CommitOperation 列表将被修改。不要为多个提交重用相同的对象。

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

create_commit 限制为 25k 个 LFS 文件和 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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。
description (str, optional) — 拉取请求的可选描述。默认为 "Discussion opened with the huggingface_hub Python library"
pull_request (bool, optional) — 是创建拉取请求还是讨论。如果为 True，则创建拉取请求。如果为 False，则创建讨论。默认为 False。
repo_type (str, optional) — 如果上传到数据集或 Space，则设置为 "dataset" 或 "space"；如果上传到模型，则设置为 None 或 "model"。默认为 None。

创建讨论或拉取请求。

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

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

返回： DiscussionWithDetails

引发以下错误

HTTPError 如果 HuggingFace API 返回错误
ValueError 如果某些参数值无效
RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。

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 = 0 max_replica: int = 1 scale_to_zero_timeout: int = 15 revision: Optional[str] = None task: Optional[str] = None custom_image: Optional[Dict] = None secrets: Optional[Dict[str, str]] = None type: InferenceEndpointType = <InferenceEndpointType.PROTECTED: 'protected'> 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。
max_replica (int, 可选) — 推理端点要扩展到的最大副本（实例）数。默认为 1。
scale_to_zero_timeout (int, 可选) — 不活动端点扩展到零之前的持续时间（分钟）。默认为 15。
revision (str, 可选) — 要部署在推理端点上的特定模型修订版本 (例如，"6c0e6080953db56375760c0471a8c5f2929baf11")。
task (str, 可选) — 在其上部署模型的任务 (例如，"text-classification")。
custom_image (Dict, 可选) — 用于推理端点的自定义 Docker 镜像。如果您想部署在 text-generation-inference (TGI) 框架上运行的推理端点，这将非常有用（请参阅示例）。
secrets (Dict[str, str], 可选) — 要注入到容器环境中的密钥值。
type ([`InferenceEndpointType], *可选*) -- 推理端点的类型，可以是 “protected”(默认),“public”或“private”。
namespace (str, 可选) — 将在其中创建推理端点的命名空间。默认为当前用户的命名空间。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

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

创建一个新的推理端点。

示例

>>> 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",
...     custom_image={
...         "health_route": "/health",
...         "env": {
...             "MAX_BATCH_PREFILL_TOKENS": "2048",
...             "MAX_INPUT_LENGTH": "1024",
...             "MAX_TOTAL_TOKENS": "1512",
...             "MODEL_ID": "/repository"
...         },
...         "url": "ghcr.io/huggingface/text-generation-inference:1.1.0",
...     },
...    secrets={"MY_SECRET_KEY": "secret_value"},
... )

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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。
namespace (str, 可选) — 将在其中创建推理端点的命名空间。默认为当前用户的命名空间。

返回值

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

从 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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。
description (str, 可选) — 拉取请求的可选描述。默认为 "Discussion opened with the huggingface_hub Python library"
repo_type (str, 可选) — 如果上传到数据集或 Space，则设置为 "dataset" 或 "space"；如果上传到模型，则设置为 None 或 "model"。默认为 None。

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

使用更改创建拉取请求也可以通过 HfApi.create_commit() 一次完成；

这是 HfApi.create_discussion() 的包装器。

返回： DiscussionWithDetails

引发以下错误

HTTPError 如果 HuggingFace API 返回错误
ValueError 如果某些参数值无效
RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。

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

返回值

RepoUrl

新创建仓库的 URL。值是 str 的子类，包含诸如 endpoint、repo_type 和 repo_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, optional) — 要创建的标签的描述。
revision (str, optional) — 要标记的 git 修订版本。它可以是分支名称或提交的 OID/SHA，以十六进制字符串表示。也支持简写（前 7 个字符）。默认为 "main" 分支的头部。
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。
exist_ok (bool, optional, defaults to False) — 如果为 True，则在标签已存在时不要引发错误。

引发

RepositoryNotFoundError 或 RevisionNotFoundError 或 HfHubHTTPError

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) — 要将 payload 发送到的 URL。
watched (List[WebhookWatchedItem]) — 要由 webhook 监视的 WebhookWatchedItem 列表。它可以是用户、组织、模型、数据集或 Spaces。被监视的项目也可以作为纯字典提供。
domains (List[Literal["repo", "discussion"]], optional) — 要监视的域列表。可以是 “repo”、“discussion” 或两者都有。
secret (str, optional) — 用于对 payload 进行签名的密钥。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

关于新创建的 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, optional) — 从中获取数据集仓库信息的修订版本。
timeout (float, optional) — 是否为 Hub 的请求设置超时。
files_metadata (bool, optional) — 是否检索仓库中文件的元数据（大小、LFS 元数据等）。默认为 False。
expand (List[ExpandDatasetProperty_T], optional) — 要在响应中返回的属性列表。使用时，只会返回列表中的属性。如果传递了 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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

hf_api.DatasetInfo

数据集仓库信息。

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

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

引发以下错误

RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。
RevisionNotFoundError 如果找不到要下载的修订版本。

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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。
repo_type (str, optional) — 如果在数据集或 Space 上创建分支，则设置为 "dataset" 或 "space"，如果标记模型，则设置为 None 或 "model"。默认为 None。

引发

RepositoryNotFoundError 或 HfHubHTTPError

RepositoryNotFoundError — 如果找不到仓库（错误 404）：错误的 repo_id/repo_type、私有但未经验证或仓库不存在。
HfHubHTTPError — 如果尝试删除受保护的分支。例如：无法删除 main。
HfHubHTTPError — 如果尝试删除不存在的分支。

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

delete_collection

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

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

参数

collection_slug (str) — 要删除的合集的 Slug。示例："TheBloke/recent-models-64f9a55bb3115b4f513ec026"。
missing_ok (bool, optional) — 如果为 True，则在合集不存在时，不引发错误。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（参见 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) — Slug of the collection to update. Example: "TheBloke/recent-models-64f9a55bb3115b4f513ec026".
item_object_id (str) — 集合中项目的 ID。这不是 Hub 上项目的 ID（repo_id 或 paper 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"使用 huggingface_hub 删除 {path_in_repo}"。
commit_description (str 可选) — 生成的提交的描述
create_pr (boolean, 可选) — 是否使用该提交创建拉取请求。默认为 False。如果未设置 revision，则针对 "main" 分支打开 PR。如果设置了 revision 并且是分支，则针对此分支打开 PR。如果设置了 revision 且不是分支名称（例如：提交 oid），则服务器会返回 RevisionNotFoundError。
parent_commit (str, 可选) — 父提交的 OID / SHA，为十六进制字符串。也支持简写形式（前 7 个字符）。如果指定且 create_pr 为 False，则当 revision 未指向 parent_commit 时，提交将失败。如果指定且 create_pr 为 True，则将从 parent_commit 创建拉取请求。指定 parent_commit 可确保在提交更改之前仓库未发生更改，并且在仓库同时更新/提交时特别有用。

删除给定仓库中的文件。

引发以下错误

HTTPError 如果 HuggingFace API 返回错误
ValueError 如果某些参数值无效
RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。
RevisionNotFoundError 如果找不到要下载的修订版本。
EntryNotFoundError 如果找不到要下载的文件。

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"使用 huggingface_hub 删除文件"。
commit_description (str 可选) — 生成的提交的描述。
create_pr (boolean, 可选) — 是否使用该提交创建拉取请求。默认为 False。如果未设置 revision，则针对 "main" 分支打开 PR。如果设置了 revision 并且是分支，则针对此分支打开 PR。如果设置了 revision 且不是分支名称（例如：提交 oid），则服务器会返回 RevisionNotFoundError。
parent_commit (str, 可选) — 父提交的 OID / SHA，为十六进制字符串。也支持简写形式（前 7 个字符）。如果指定且 create_pr 为 False，则当 revision 未指向 parent_commit 时，提交将失败。如果指定且 create_pr 为 True，则将从 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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。传递 None 以使用存储的令牌。
repo_type (str, optional) — 如果文件夹位于数据集或 Space 中，则设置为 "dataset" 或 "space"，如果位于模型中，则设置为 None 或 "model"。默认为 None。
revision (str, optional) — 要从中提交的 git 修订版本。默认为 "main" 分支的头部。
commit_message (str, optional) — 生成的提交的摘要/标题/第一行。默认为 f"Delete folder {path_in_repo} with huggingface_hub"。
commit_description (str optional) — 生成的提交的描述。
create_pr (boolean, optional) — 是否使用该提交创建拉取请求。默认为 False。如果未设置 revision，则针对 "main" 分支打开 PR。如果设置了 revision 并且是分支，则针对此分支打开 PR。如果设置了 revision 且不是分支名称（例如：提交 oid），服务器将返回 RevisionNotFoundError。
parent_commit (str, optional) — 父提交的 OID / SHA，以十六进制字符串表示。也支持简写形式（前 7 个字符）。如果指定且 create_pr 为 False，则当 revision 未指向 parent_commit 时，提交将失败。如果指定且 create_pr 为 True，则将从 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, optional) — 推理端点所在的命名空间。默认为当前用户。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。
repo_type (str, optional) — 如果上传到数据集或 Space，则设置为 "dataset" 或 "space"，如果上传到模型，则设置为 None 或 "model"。
missing_ok (bool, optional, defaults to False) — 如果为 True，则在仓库不存在时不要引发错误。

引发

RepositoryNotFoundError

RepositoryNotFoundError — 如果找不到要从中删除的仓库，并且 missing_ok 设置为 False（默认）。

从 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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

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

引发

BadRequestError

BadRequestError — 如果 Space 没有持久存储。

删除 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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

从 Space 中删除一个变量。

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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。
repo_type (str, optional) — 如果标记数据集或 Space，则设置为 "dataset" 或 "space" ；如果标记模型，则设置为 None 或 "model" 。默认为 None。

引发

RepositoryNotFoundError 或 RevisionNotFoundError

RepositoryNotFoundError — 如果找不到仓库（错误 404）：错误的 repo_id/repo_type、私有但未经验证或仓库不存在。
RevisionNotFoundError — 如果未找到标签。

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

delete_webhook

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

参数

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

返回值

None

删除一个 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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

关于已禁用 webhook 的信息。

禁用一个 webhook（使其变为“禁用”状态）。

示例

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

返回值

RepoUrl

新创建仓库的 URL。值是 str 的子类，包含诸如 endpoint、repo_type 和 repo_id 等属性。

引发

RepositoryNotFoundError 或 HTTPError

RepositoryNotFoundError — 如果 from_id 或 to_id 之一找不到。这可能是因为它不存在，或者因为它被设置为 private 并且您没有访问权限。
HTTPError — 如果 HuggingFace API 返回错误

复制 Space。

以编程方式复制 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) — Discussion 或 Pull Request 的编号。必须是严格的正整数。
comment_id (str) — 要编辑的评论的 ID。
new_content (str) — 评论的新内容。评论支持 markdown 格式。
repo_type (str, optional) — 如果上传到数据集或 Space，则设置为 "dataset" 或 "space"；如果上传到模型，则设置为 None 或 "model"。默认为 None。
token (Union[bool, str, None], 可选) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

DiscussionComment

已编辑的评论

编辑 Discussion / Pull Request 上的评论。

引发以下错误

HTTPError 如果 HuggingFace API 返回错误
ValueError 如果某些参数值无效
RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。

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。

返回值

关于已启用 webhook 的信息。

启用 webhook (使其“激活”)。

示例

>>> 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,
)

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, optional) — 如果从数据集或 Space 获取仓库信息，则设置为 "dataset" 或 "space"；如果从模型获取仓库信息，则设置为 None 或 "model"。默认为 None。
revision (str, optional) — 要从中获取信息的仓库修订版本。默认为 "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 的信息。

返回值：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) — Discussion 或 Pull Request 的编号。必须是严格的正整数。
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。

从 Hub 获取 Discussion 或 Pull Request 的详细信息。

返回： DiscussionWithDetails

引发以下错误

HTTPError 如果 HuggingFace API 返回错误
ValueError 如果某些参数值无效
RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。

get_full_repo_name

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

参数

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

返回值

str

如果在没有传递 organization 的情况下，仓库名称位于用户的命名空间中 ({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() 返回的 url。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。
proxies (dict, optional) — 字典，将协议映射到传递给 requests.request 的代理 URL。
timeout (float, optional, defaults to 10) — 服务器在放弃之前等待发送元数据多少秒，默认为 10 秒。

获取给定 url 的 Hub 上版本控制的文件的元数据。

get_inference_endpoint

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

参数

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

返回值

有关请求的 Inference Endpoint 的信息。

获取有关 Inference Endpoint 的信息。

示例

>>> 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], optional) — 要获取信息的路径。如果路径不存在，则会忽略它，而不会引发异常。
expand (bool, optional, defaults to False) — 是否获取有关路径的更多信息（例如，上次提交和文件的安全扫描结果）。此操作对服务器来说成本更高，因此每页仅返回 50 个结果（而不是 1000 个）。由于 huggingface_hub 中实现了分页，因此这对您来说是透明的，除了获取结果所需的时间。
revision (str, optional) — 从中获取信息的仓库的版本。默认为 "main" 分支。
repo_type (str, optional) — 从中获取信息的仓库的类型（"model"、"dataset" 或 "space"）。默认为 "model"。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

List[Union[RepoFile, RepoFolder]]

有关路径的信息，作为 RepoFile 和 RepoFolder 对象的列表。

引发

RepositoryNotFoundError 或 RevisionNotFoundError

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, 可选) — 如果从数据集或 Space 获取，则设置为 "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, 可选) — 如果文件在数据集或 Space 中，则设置为 "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 仓库相关的信息。

引发

NotASafetensorsRepoError 或 SafetensorsParsingError

NotASafetensorsRepoError — 如果仓库不是 safetensors 仓库，即没有 model.safetensors 或 model.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。

返回值

关于 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 中的所有变量。

get_token_permission

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

参数

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

返回值

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

参数

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

返回值

User

一个带有用户概览的 User 对象。

引发

HTTPError

HTTPError — HTTP 404 如果 Hub 上不存在该用户。

获取 Hub 上用户的概览。

get_webhook

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

参数

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

返回值

关于 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) — 要授予访问权限的仓库的类型。必须是 model、dataset 或 space 之一。默认为 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。如果您在仓库所属的组织中没有 write 或 admin 角色，或者您传递了 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) — 如果从数据集或 Space 下载，则设置为 "dataset" 或 "space"；如果从模型下载，则设置为 None 或 "model"。默认为 None。
revision (str, optional) — 可选的 Git 修订 ID，可以是分支名称、标签或提交哈希。
cache_dir (str, Path, optional) — 存储缓存文件的文件夹路径。
local_dir (str 或 Path, optional) — 如果提供，则下载的文件将放置在此目录下。
force_download (bool, optional, defaults to False) — 即使本地缓存中已存在该文件，是否仍应下载该文件。默认为 False。
proxies (dict, optional) — 将协议映射到传递给 requests.request 的代理 URL 的字典。
etag_timeout (float, optional, defaults to 10) — 获取 ETag 时，等待服务器发送数据多少秒后放弃，该值会传递给 requests.request。默认为 10。
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，则避免下载文件，如果本地缓存文件中存在该文件，则返回该文件的路径。默认为 False。

返回值

str

文件的本地路径；如果网络已关闭，则返回磁盘上缓存的文件的最新版本。

引发

RepositoryNotFoundError 或 RevisionNotFoundError 或 EntryNotFoundError 或 LocalEntryNotFoundError 或 EnvironmentError 或 OSError 或 ValueError

RepositoryNotFoundError — 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 且您没有访问权限。
RevisionNotFoundError — 如果找不到要从中下载的修订版本。
EntryNotFoundError — 如果找不到要下载的文件。
LocalEntryNotFoundError — 如果网络已禁用或不可用，并且在缓存中找不到文件。
EnvironmentError — 如果 token=True 但找不到令牌。
OSError — 如果无法确定 ETag。
ValueError — 如果某些参数值无效。

如果本地缓存中尚不存在给定文件，则下载该文件。

新的缓存文件布局如下所示

缓存目录包含每个 repo_id 的一个子文件夹（按仓库类型命名空间）
在每个仓库文件夹内
- refs 是最新已知修订版本 => commit_hash 对的列表
- blobs 包含实际的文件 blobs（由其 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, 可选) — 如果上传到数据集或 Space，则设置为 "dataset" 或 "space"；如果上传到模型，则设置为 None 或 "model"。默认为 None。
token (Union[bool, str, None], 可选) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

DiscussionComment

隐藏的评论

隐藏 Discussion / Pull Request 上的评论。

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

引发以下错误

HTTPError 如果 HuggingFace API 返回错误
ValueError 如果某些参数值无效
RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。

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, 可选) — 要获取访问请求的仓库的类型。必须是 model、dataset 或 space 之一。默认为 model。
token (Union[bool, str, None], 可选) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

List[AccessRequest]

AccessRequest 对象的列表。每次都包含 username、email、status 和 timestamp 属性。如果门控仓库有自定义表单，则 fields 属性将填充用户的答案。

引发

HTTPError

HTTPError — 如果仓库未门控，则返回 HTTP 400。
HTTPError — 如果您只有对仓库的只读访问权限，则返回 HTTP 403。如果您在仓库所属的组织中没有 write 或 admin 角色，或者您传递了 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, 可选) — 按所有者的用户名筛选。
item (List[str] or str, 可选) — 筛选包含特定项目的集合。示例："models/teknium/OpenHermes-2.5-Mistral-7B"、"datasets/squad" 或 "papers/2311.12983"。
sort (Literal["lastModified", "trending", "upvotes"], 可选) — 按上次修改时间、流行度或赞数对集合进行排序。
limit (int, 可选) — 要返回的最大集合数。
token (Union[bool, str, None], 可选) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

Iterable[Collection]

Collection 对象的迭代器。

列出 Huggingface 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 或 Iterable[str], 可选) — 用于在 Hub 上过滤数据集的字符串或字符串列表。
author (str, 可选) — 标识返回数据集的作者的字符串。
benchmark (str 或 List, 可选) — 可用于通过其官方基准来识别 Hub 上的数据集的字符串或字符串列表。
dataset_name (str, 可选) — 可用于通过其名称（例如 SQAC 或 wikineural ）识别 Hub 上的数据集的字符串或字符串列表。
gated (bool, 可选) — 用于在 Hub 上过滤门控或非门控数据集的布尔值。默认情况下，返回所有数据集。如果传递 gated=True，则仅返回门控数据集。如果传递 gated=False，则仅返回非门控数据集。
language_creators (str 或 List, 可选) — 可用于通过数据是如何策划的（例如 crowdsourced 或 machine_generated ）来识别 Hub 上的数据集的字符串或字符串列表。
language (str 或 List, 可选) — 表示双字符语言的字符串或字符串列表，用于在 Hub 上按语言筛选数据集。
multilinguality (str 或 List, 可选) — 表示包含多种语言的数据集的过滤器的字符串或字符串列表。
size_categories (str 或 List, 可选) — 可用于通过数据集大小（例如 100K<n<1M 或 1M<n<10M ）来识别 Hub 上的数据集的字符串或字符串列表。
tags (str 或 List, 可选) — 用于在 Hub 上过滤数据集的字符串标签或标签列表。
task_categories (str 或 List, 可选) — 一个字符串或字符串列表，可用于通过设计的任务在 Hub 上识别数据集，例如 audio_classification 或 named_entity_recognition。
task_ids (str 或 List, 可选) — 一个字符串或字符串列表，可用于通过特定任务在 Hub 上识别数据集，例如 speech_emotion_recognition 或 paraphrase。
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_modified、card_data 和文件。可以包含有用的信息，例如 PapersWithCode ID。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 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

参数

token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。

返回值

Liststr

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

列出 Hugging Face Inference 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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 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_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, 可选) — 仓库类型。如果要从数据集或 Space 中列出，请设置为 "dataset" 或 "space"；如果要从模型中列出，请设置为 None 或 "model"。默认为 None。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

UserLikes

包含用户名和 3 个仓库 ID 列表（模型、数据集和 Spaces 各一个）的对象。

引发

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['cold', 'frozen', 'warm']] = 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 (str 或 Iterable[str], 可选) — 用于在 Hub 上过滤模型的字符串或字符串列表。
author (str, 可选) — 用于标识返回模型的作者（用户或组织）的字符串。
gated (bool, 可选) — 一个布尔值，用于过滤 Hub 上是否为门控模型。默认情况下，返回所有模型。如果传递 gated=True，则仅返回门控模型。如果传递 gated=False，则仅返回非门控模型。
inference (Literal["cold", "frozen", "warm"], 可选) — 用于按模型在 Inference API 上的状态过滤 Hub 上的模型的字符串。Warm 模型可立即使用。Cold 模型将在首次推理调用时加载。Frozen 模型在 Inference API 中不可用。
library (str 或 List, 可选) — 模型最初训练所用的基础库的字符串或字符串列表，例如 pytorch、tensorflow 或 allennlp。
language (str 或 List, 可选) — 语言的字符串或字符串列表，包括名称和国家代码，例如 “en” 或 “English”。
model_name (str, 可选) — 包含 Hub 上模型完整或部分名称的字符串，例如 “bert” 或 “bert-base-cased”。
task (str 或 List, 可选) — 模型设计的任务的字符串或字符串列表，例如：“fill-mask” 或 “automatic-speech-recognition”。
trained_dataset (str 或 List, 可选) — Hub 上模型训练数据集的字符串标签或字符串标签列表。
tags (str 或 List, 可选) — 用于按标签过滤 Hub 上的模型的字符串标签或标签列表，例如 text-generation 或 spacy。
search (str, 可选) — 将包含在返回模型 ID 中的字符串。
pipeline_tag (str, 可选) — 用于按 pipeline 标签过滤 Hub 上的模型的字符串，例如 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], 可选) — 要在响应中返回的属性列表。使用时，仅返回列表中的属性。如果传递了 full、cardData 或 fetch_config，则不能使用此参数。可能的值为 "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"。
full (bool, 可选) — 是否获取所有模型数据，包括 last_modified、sha、文件和 tags。当使用过滤器时，默认设置为 True。
cardData (bool, 可选) — 是否也获取模型的元数据。可以包含有用的信息，例如碳排放、指标和训练数据集。
fetch_config (bool, 可选) — 是否也获取模型配置。由于其大小，未包含在 full 中。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

Iterable[ModelInfo]

一个 huggingface_hub.hf_api.ModelInfo 对象的迭代器。

列出 Huggingface Hub 上托管的模型，并给定一些过滤器。

使用 filter 参数的示例用法

>>> from huggingface_hub import HfApi

>>> api = HfApi()

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

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

# List only models from the AllenNLP library
>>> api.list_models(filter="allennlp")

使用 search 参数的示例用法

>>> from huggingface_hub import HfApi

>>> api = HfApi()

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

# List all models with "bert" in their name made 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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

Iterable[User]

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

引发

HTTPError

HTTPError — 如果 Hub 上不存在该组织，则返回 HTTP 404 错误。

列出 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, 可选) — 获取访问请求的仓库类型。必须是 model，dataset 或 space 之一。默认为 model。
token (Union[bool, str, None], 可选) — 有效的用户访问令牌 (字符串)。默认为本地保存的令牌，这是推荐的身份验证方法（参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

List[AccessRequest]

AccessRequest 对象的列表。每次都包含 username、email、status 和 timestamp 属性。如果门控仓库有自定义表单，则 fields 属性将填充用户的答案。

引发

HTTPError

HTTPError — 如果仓库未门控，则返回 HTTP 400。
HTTPError — 如果您只有对仓库的只读访问权限，则返回 HTTP 403。如果您在仓库所属的组织中没有 write 或 admin 角色，或者您传递了 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, 可选) — 获取访问请求的仓库类型。必须是 model，dataset 或 space 之一。默认为 model。
token (Union[bool, str, None], 可选) — 有效的用户访问令牌 (字符串)。默认为本地保存的令牌，这是推荐的身份验证方法（参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

List[AccessRequest]

AccessRequest 对象的列表。每次都包含 username、email、status 和 timestamp 属性。如果门控仓库有自定义表单，则 fields 属性将填充用户的答案。

引发

HTTPError

HTTPError — 如果仓库未门控，则返回 HTTP 400。
HTTPError — 如果您只有对仓库的只读访问权限，则返回 HTTP 403。如果您在仓库所属的组织中没有 write 或 admin 角色，或者您传递了 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" 分支的头部。
formatted (bool) — 是否返回提交的 HTML 格式的标题和描述。默认为 False。

返回值

List[GitCommitInfo]

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

引发

RepositoryNotFoundError 或 RevisionNotFoundError

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, optional) — 如果上传到数据集或 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, optional) — 如果要列出数据集或 Space 的 refs，则设置为 "dataset" 或 "space"；如果要列出模型的 refs，则设置为 None 或 "model"。默认为 None。
include_pull_requests (bool, optional) — 是否在列表中包含来自拉取请求的 refs。默认为 False。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

GitRefs

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

获取给定仓库的 refs 列表（包括标签和分支）。

示例

>>> 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, optional) — 仓库中树（文件夹）的相对路径，例如："checkpoints/1fec34a/results"。默认为仓库的根树（文件夹）。
recursive (bool, optional, defaults to False) — 是否递归地列出树的文件和文件夹。
expand (bool, optional, defaults to False) — 是否获取有关树的文件和文件夹的更多信息（例如，上次提交和文件的安全扫描结果）。此操作对服务器来说成本更高，因此每页仅返回 50 个结果（而不是 1000 个）。由于 huggingface_hub 中实现了分页，因此这对您来说是透明的，除了获取结果所需的时间。
revision (str, optional) — 从中获取树的仓库修订版本。默认为 "main" 分支。
repo_type (str, optional) — 从中获取树的仓库类型（"model"、"dataset" 或 "space"）。默认为 "model"。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

Iterable[Union[RepoFile, RepoFolder]]

关于树的文件和文件夹的信息，作为 RepoFile 和 RepoFolder 对象的迭代器。不保证文件和文件夹的顺序。

引发

RepositoryNotFoundError 或 RevisionNotFoundError 或 EntryNotFoundError

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 (str or Iterable, optional) — 可用于识别 Hub 上的 Spaces 的字符串标签或标签列表。
author (str, optional) — 用于标识返回的 Spaces 的作者的字符串。
search (str, optional) — 将包含在返回的 Spaces 中的字符串。
datasets (str or Iterable, optional) — 是否返回使用数据集的 Spaces。可以将特定数据集的名称作为字符串传递。
models (str or Iterable, optional) — 是否返回使用模型的 Spaces。可以将特定模型的名称作为字符串传递。
linked (bool, optional) — 是否返回使用模型或数据集的 Spaces。
sort (Literal["last_modified"] or str, optional) — 用于对结果模型进行排序的键。可能的值为“last_modified”、“trending_score”、“created_at”和“likes”。
direction (Literal[-1] or int, optional) — 排序方向。值 -1 按降序排序，而所有其他值按升序排序。
limit (int, 可选) — 获取的 Space 应用数量上限。如果将此选项设置为 None，则会获取所有 Space 应用。
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, 可选) — 是否获取所有 Space 应用数据，包括 last_modified、siblings 和 card_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 上托管的 space 应用，可根据某些过滤器进行筛选。

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 — HTTP 404 如果 Hub 上不存在该用户。

获取 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 — HTTP 404 如果 Hub 上不存在该用户。

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

list_webhooks

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

参数

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

返回值

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) — 讨论或 Pull Request 的编号。必须是严格正整数。
comment (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。

返回值

DiscussionStatusChange

状态更改事件

合并 Pull Request。

引发以下错误

HTTPError 如果 HuggingFace API 返回错误
ValueError 如果某些参数值无效
RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。

model_info

huggingface_hub.hf_api.ModelInfo

( 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.co 上一个特定模型的信息

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

引发以下错误

RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。
RevisionNotFoundError 如果找不到要下载的修订版本。

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, 可选) — 如果上传到数据集或 Space，则设置为 "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 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。

paper_info

( id: str ) → PaperInfo

参数

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

返回值

PaperInfo

一个 PaperInfo 对象。

引发

HTTPError

HTTPError — HTTP 404 如果 Hub 上不存在该论文。

获取 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, 可选) — 如果文件在数据集或 Space 中，则设置为 "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 文件相关的信息。

引发

NotASafetensorsRepoError 或 SafetensorsParsingError

NotASafetensorsRepoError — 如果仓库不是 safetensors 仓库，即没有 model.safetensors 或 model.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) — 要暂停的 Inference Endpoint 的名称。
namespace (str, 可选) — Inference Endpoint 所在的命名空间。默认为当前用户。
token (Union[bool, str, None], 可选) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

有关已暂停的 Inference Endpoint 的信息。

暂停 Inference Endpoint。

暂停的 Inference Endpoint 将不会收费。可以使用 resume_inference_endpoint() 随时恢复它。这与使用 scale_to_zero_inference_endpoint() 将 Inference Endpoint 缩放到零不同，后者会在收到请求时自动重启。

为了方便起见，您还可以使用 pause_inference_endpoint() 暂停 Inference Endpoint。

pause_space

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

参数

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

返回值

关于您的 Space 的运行时信息，包括 stage=PAUSED 和请求的硬件。

引发

RepositoryNotFoundError 或 HfHubHTTPError 或 BadRequestError

RepositoryNotFoundError — 如果找不到您的 Space（错误 404）。很可能是错误的 repo_id 或您的 Space 是私有的，但您未通过身份验证。
HfHubHTTPError — 403 禁止：只有 Space 的所有者才能暂停它。如果您想管理一个您不拥有的 Space，可以打开讨论向所有者询问，或复制该 Space。
BadRequestError — 如果您的 Space 是静态 Space。静态 Space 始终运行且永不计费。如果您想隐藏静态 Space，可以将其设置为私有。

暂停您的 Space。

暂停的 Space 将停止执行，直到其所有者手动重启。这与免费 Space 在 48 小时不活动后进入的休眠状态不同。暂停时间不计入您的帐户，无论您选择了什么硬件。要重启您的 Space，请使用 restart_space() 并转到您的 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, optional, default to True) — 是否重写仓库历史以删除引用已删除 LFS 文件的文件指针（推荐）。
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。

永久删除 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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。
repo_type (str, optional) — 要上传到的仓库类型（例如，"model" - 默认值 -，"dataset" 或 "space"）。
revision (str, optional) — 要从中提交的 git 修订版本。默认为 "main" 分支的头部。
create_pr (boolean, optional) — 是否计划使用该提交创建拉取请求。默认为 False。
num_threads (int, optional) — 用于上传文件的并发线程数。默认为 5。设置为 2 表示最多将并发上传 2 个文件。
gitignore_content (str, optional) — .gitignore 文件的内容，用于了解应忽略哪些文件。优先级顺序为：首先检查是否传递了 gitignore_content，然后检查 .gitignore 文件是否在要提交的文件列表中，最后默认为 Hub 上已托管的 .gitignore 文件（如果有）。

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

如果您要动态生成要上传的文件，并且不想在一次性全部上传之前将它们存储在内存中，则此方法很有用。

这是一种高级用户方法。您无需直接调用它即可进行正常提交。请直接使用 create_commit()。

提交操作将在过程中被修改。特别是，在上传后，将删除附加的 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) — 要拒绝访问请求的仓库类型。必须是 model、dataset 或 space 之一。默认为 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。如果您在仓库所属的组织中没有 write 或 admin 角色，或者您传递了 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) — 讨论或拉取请求的编号。必须是严格的正整数。
new_title (str) — 讨论的新标题
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。

返回值

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 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。

repo_exists

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

参数

repo_id (str) — 命名空间（用户或组织）和仓库名称，用 / 分隔。
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。

检查 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) — 如果从数据集或 Space 获取仓库信息，请设置为 "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.DatasetInfo, huggingface_hub.hf_api.ModelInfo 或 huggingface_hub.hf_api.SpaceInfo 对象。

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

引发以下错误

RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。
RevisionNotFoundError 如果找不到要下载的修订版本。

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 或 SpaceHardware) — 运行 Space 的硬件。示例： "t4-medium"。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。
sleep_time (int, optional) — 在 Space 进入休眠状态之前等待的不活动秒数。如果您不希望您的 Space 休眠（升级硬件的默认行为），请设置为 -1。对于免费硬件，您无法配置休眠时间（值固定为 48 小时不活动）。有关更多详细信息，请参阅 https://huggingface.co/docs/hub/spaces-gpus#sleep-time。

返回值

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

为 Space 请求新硬件。

在创建 Space 仓库时也可以直接请求硬件！有关详细信息，请参阅 create_repo()。

request_space_storage

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

参数

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

返回值

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

为 Space 请求持久存储。

持久存储一旦授予就无法减少。要减少，您必须通过 delete_space_storage() 删除它。

restart_space

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

参数

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

返回值

关于您的 Space 的运行时信息。

引发

RepositoryNotFoundError 或 HfHubHTTPError 或 BadRequestError

RepositoryNotFoundError — 如果找不到您的 Space（错误 404）。很可能是错误的 repo_id 或您的 Space 是私有的，但您未通过身份验证。
HfHubHTTPError — 403 Forbidden: 只有 Space 的所有者才能重启它。如果您想重启一个您不拥有的 Space，可以联系所有者发起讨论或复制该 Space。
BadRequestError — 如果您的 Space 是静态 Space。静态 Space 始终运行且永不计费。如果您想隐藏静态 Space，可以将其设置为私有。

重启您的 Space。

这是以编程方式重启 Space 的唯一方法，如果您已将其设置为暂停状态（参见 pause_space()）。您必须是 Space 的所有者才能重启它。如果您使用的是升级后的硬件，您的帐户将在 Space 重启后立即开始计费。无论 Space 的当前状态如何，您都可以触发重启。

更多详情，请访问文档。

resume_inference_endpoint

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

参数

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

返回值

关于已恢复的 Inference Endpoint 的信息。

恢复 Inference Endpoint。

为方便起见，您还可以使用 InferenceEndpoint.resume() 来恢复 Inference Endpoint。

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, 可选) — 如果要从数据集或 Space 获取仓库信息，请设置为 "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

scale_to_zero_inference_endpoint

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

参数

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

返回值

关于缩放至零的 Inference Endpoint 的信息。

将 Inference Endpoint 缩放至零。

缩放至零的 Inference Endpoint 将不会被收费。它将在下次请求时恢复，但会有冷启动延迟。这与使用 pause_inference_endpoint() 暂停 Inference Endpoint 不同，后者需要使用 resume_inference_endpoint() 手动恢复。

为方便起见，您还可以使用 InferenceEndpoint.scale_to_zero() 将 Inference Endpoint 缩放至零。

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, optional) — Space 进入休眠状态前等待的非活动秒数。如果您不希望您的 Space 暂停（升级硬件的默认行为），请设置为 -1。对于免费硬件，您无法配置休眠时间（该值固定为 48 小时的非活动时间）。有关更多详细信息，请参阅 https://huggingface.co/docs/hub/spaces-gpus#sleep-time。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

关于 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[base_tqdm] = None local_dir_use_symlinks: Union[bool, Literal['auto']] = 'auto' resume_download: Optional[bool] = None ) → str

参数

repo_id (str) — 用户名或组织名称，以及仓库名称，以 / 分隔。
repo_type (str, optional) — 如果从数据集或 Space 下载，则设置为 "dataset" 或 "space"，如果从模型下载，则设置为 None 或 "model"。默认为 None。
revision (str, optional) — 可选的 Git 修订 ID，可以是分支名称、标签或提交哈希值。
cache_dir (str, Path, optional) — 缓存文件存储路径的文件夹。
local_dir (str 或 Path, optional) — 如果提供，下载的文件将放置在此目录下。
proxies (dict, optional) — 字典，将协议映射到传递给 requests.request 的代理 URL。
etag_timeout (float, optional, defaults to 10) — 获取 ETag 时，等待服务器发送数据多少秒后放弃，该参数会传递给 requests.request。
force_download (bool, optional, defaults to False) — 是否强制下载文件，即使本地缓存中已存在该文件。
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，则避免下载文件，并且如果本地缓存文件中存在该文件，则返回其路径。
allow_patterns (List[str] 或 str, optional) — 如果提供，则仅下载与至少一个模式匹配的文件。
ignore_patterns (List[str] 或 str, optional) — 如果提供，则不下载与任何模式匹配的文件。
max_workers (int, optional) — 用于下载文件的并发线程数（1 个线程 = 1 个文件下载）。默认为 8。
tqdm_class (tqdm, optional) — 如果提供，则覆盖进度条的默认行为。传递的参数必须继承自 tqdm.auto.tqdm 或至少模仿其行为。请注意，tqdm_class 不会传递给每个单独的下载。默认为自定义 HF 进度条，可以通过设置 HF_HUB_DISABLE_PROGRESS_BARS 环境变量来禁用。

返回值

str

仓库快照的文件夹路径。

引发

RepositoryNotFoundError 或 RevisionNotFoundError 或 EnvironmentError 或 OSError 或 ValueError

RepositoryNotFoundError — 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 且您没有访问权限。
RevisionNotFoundError — 如果找不到要从中下载的修订版本。
EnvironmentError — 如果 token=True 且找不到令牌。
OSError — 如果无法确定 ETag。
ValueError — 如果某些参数值无效。

下载仓库文件。

下载指定修订版本的仓库文件的完整快照。当您需要仓库中的所有文件时，这非常有用，因为您事先不知道您需要哪些文件。所有文件都嵌套在一个文件夹中，以保持其相对于该文件夹的实际文件名。您还可以使用 allow_patterns 和 ignore_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, optional) — 要从中获取信息的 space 仓库的修订版本。
timeout (float, optional) — 是否为 Hub 的请求设置超时。
files_metadata (bool, optional) — 是否检索仓库中文件的元数据（大小、LFS 元数据等）。默认为 False。
expand (List[ExpandSpaceProperty_T], optional) — 要在响应中返回的属性列表。使用后，将仅返回列表中的属性。如果传递了 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], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

SpaceInfo

space 仓库信息。

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

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

引发以下错误

RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。
RevisionNotFoundError 如果找不到要下载的修订版本。

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, 可选) — 要压缩的分支。默认为 "main" 分支的头部。
commit_message (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。

引发

RepositoryNotFoundError or RevisionNotFoundError or BadRequestError

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], 可选) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。
repo_type (str, 可选) — 如果要取消喜欢数据集或 space，请设置为 "dataset" 或 "space"；如果要取消喜欢模型，则设置为 None 或 "model"。默认为 None。

引发

RepositoryNotFoundError

RepositoryNotFoundError — 如果找不到仓库（错误 404）：错误的 repo_id/repo_type、私有但未经验证或仓库不存在。

取消喜欢 Hub 上的给定仓库（例如，从收藏列表中删除）。

为了防止垃圾邮件使用，无法从脚本中 like 仓库。

另请参阅 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 上项目的 ID（repo_id 或论文 id）。它必须从 CollectionItem 对象中检索。例如：collection.items[0].item_object_id。
note (str, 可选) — 要附加到集合中项目的注释。注释的最大长度为 500 个字符。
position (int, 可选) — 项目在集合中的新位置。
token (Union[bool, str, None], 可选) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 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, 可选) — 要更新的集合的描述。
position (int, 可选) — 集合在用户集合列表中的新位置。
private (bool, 可选) — 集合是否应为私有。
theme (str, 可选) — Hub 上集合的主题。
token (Union[bool, str, None], 可选) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 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 secrets: Optional[Dict[str, str]] = None namespace: Optional[str] = None token: Union[bool, str, None] = None ) → InferenceEndpoint

参数

name (str) — 要更新的 Inference Endpoint 的名称。
accelerator (str, optional) — 用于推理的硬件加速器 (例如 "cpu")。
instance_size (str, optional) — 用于托管模型的实例大小或类型 (例如 "x4")。
instance_type (str, optional) — Inference Endpoint 将部署到的云实例类型 (例如 "intel-icl")。
min_replica (int, optional) — 为 Inference Endpoint 保持运行的最小副本（实例）数量。
max_replica (int, optional) — Inference Endpoint 要扩展到的最大副本（实例）数量。
scale_to_zero_timeout (int, optional) — 不活动的端点缩减为零之前的持续时间（分钟）。
repository (str, optional) — 与 Inference Endpoint 关联的模型仓库的名称 (例如 "gpt2")。
framework (str, optional) — 用于模型的机器学习框架 (例如 "custom")。
revision (str, optional) — 要部署在 Inference Endpoint 上的特定模型修订版本 (例如 "6c0e6080953db56375760c0471a8c5f2929baf11")。
task (str, optional) — 在其上部署模型的任务 (例如 "text-classification")。
custom_image (Dict, optional) — 用于 Inference Endpoint 的自定义 Docker 镜像。如果您想部署在 text-generation-inference (TGI) 框架上运行的 Inference Endpoint，这将非常有用（请参阅示例）。
secrets (Dict[str, str], optional) — 要注入到容器环境中的密钥值。
namespace (str, optional) — Inference Endpoint 将更新到的命名空间。默认为当前用户的命名空间。
token (Union[bool, str, None], optional) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

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

更新 Inference Endpoint。

此方法允许更新计算配置、已部署的模型或两者都更新。所有参数都是可选的，但必须至少提供一个参数。

为了方便起见，您还可以使用 InferenceEndpoint.update() 更新 Inference Endpoint。

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 Storage。

引发

ValueError 或 HfHubHTTPError 或 RepositoryNotFoundError

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, 可选) — 命名空间（用户或组织）和仓库名称，用 / 分隔。
private (bool, 可选, 默认为 False) — 仓库是否应为私有。
token (Union[bool, str, None], 可选) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。
repo_type (str, 可选) — 如果上传到数据集或 Space，则设置为 "dataset" 或 "space"；如果上传到模型，则设置为 None 或 "model"。默认为 None。

更新仓库的可见性设置。

已弃用。请改用 update_repo_settings。

引发以下错误

RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。

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, 可选) — 将有效负载发送到的 URL。
watched (List[WebhookWatchedItem], 可选) — 要监视的项目列表。可以是用户、组织、模型、数据集或 Spaces。有关更多详细信息，请参阅 WebhookWatchedItem。监视的项目也可以以纯字典形式提供。
domains (List[Literal["repo", "discussion"]], 可选) — 要监视的域。可以包括 “repo”、“discussion” 或两者都包括。
secret (str, 可选) — 用于对有效负载进行签名的密钥，提供额外的安全层。
token (Union[bool, str, None], 可选) — 有效的用户访问令牌（字符串）。默认为本地保存的令牌，这是推荐的身份验证方法（参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication）。要禁用身份验证，请传递 False。

返回值

有关更新后的 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, 或 IO) — 本地计算机上文件的路径或二进制数据流/fileobj/缓冲区。
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, 可选) — 生成的提交的摘要/标题/第一行
commit_description (str 可选) — 生成的提交的描述
create_pr (boolean, 可选) — 是否使用该提交创建拉取请求 (Pull Request)。默认为 False。如果未设置 revision，则 PR 将针对 "main" 分支打开。如果设置了 revision 且为一个分支，则 PR 将针对该分支打开。如果设置了 revision 且不是分支名称（例如：提交 oid），服务器将返回 RevisionNotFoundError 错误。
parent_commit (str, 可选) — 父提交的 OID/SHA，以十六进制字符串表示。也支持简写形式（前 7 个字符）。如果指定了此参数且 create_pr 为 False，则当 revision 未指向 parent_commit 时，提交将失败。如果指定了此参数且 create_pr 为 True，则将从 parent_commit 创建拉取请求。指定 parent_commit 可确保在提交更改之前仓库未发生更改，并且在仓库同时更新/提交时特别有用。
run_as_future (bool, 可选) — 是否在后台运行此方法。后台作业按顺序运行，而不会阻塞主线程。传递 run_as_future=True 将返回一个 Future 对象。默认为 False。

返回值

CommitInfo 或 Future

将本地文件（最大 50 GB）上传到给定的仓库。上传通过 HTTP POST 请求完成，不需要安装 git 或 git-lfs。

引发以下错误

HTTPError 如果 HuggingFace API 返回错误
ValueError 如果某些参数值无效
RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在，或者因为它设置为 private 并且您没有访问权限。
RevisionNotFoundError 如果找不到要下载的修订版本。

upload_file 假设仓库已存在于 Hub 上。如果收到 Client error 404 错误，请确保您已通过身份验证，并且 repo_id 和 repo_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 或 Future

参数

repo_id (str) — 文件将被上传到的仓库，例如： "username/custom_transformers"
folder_path (str 或 Path) — 本地文件系统中要上传的文件夹路径
path_in_repo (str, 可选) — 仓库中目录的相对路径，例如： "checkpoints/1fec34a/results"。默认为仓库的根文件夹。
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 revision。默认为 "main" 分支的头部。
commit_message (str, 可选) — 生成的提交的摘要/标题/第一行。默认为： f"Upload {path_in_repo} with huggingface_hub"
commit_description (str 可选) — 生成的提交的描述
create_pr (boolean, 可选) — 是否使用该提交创建拉取请求（Pull Request）。默认为 False。如果未设置 revision，则针对 "main" 分支打开 PR。如果设置了 revision 并且是分支，则针对此分支打开 PR。如果设置了 revision 且不是分支名称（例如：提交 oid），则服务器会返回 RevisionNotFoundError。
parent_commit (str, 可选) — 父提交的 OID / SHA，作为十六进制字符串。也支持简写形式（前 7 个字符）。如果指定且 create_pr 为 False，则当 revision 未指向 parent_commit 时，提交将失败。如果指定且 create_pr 为 True，则将从 parent_commit 创建拉取请求。指定 parent_commit 可确保在提交更改之前仓库未更改，并且在仓库并发更新/提交时特别有用。
allow_patterns (List[str] 或 str, 可选) — 如果提供，则仅上传与至少一个模式匹配的文件。
ignore_patterns (List[str] 或 str, 可选) — 如果提供，则不上传与任何模式匹配的文件。
delete_patterns (List[str] 或 str, 可选) — 如果提供，则在提交新文件时，将从仓库中删除与任何模式匹配的远程文件。如果您不知道哪些文件已被上传，这将非常有用。注意：为避免差异，即使 .gitattributes 文件与模式匹配也不会被删除。
run_as_future (bool, 可选) — 是否在后台运行此方法。后台作业按顺序运行，不会阻塞主线程。传递 run_as_future=True 将返回一个 Future 对象。默认为 False。

返回值

CommitInfo 或 Future

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

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

使用 allow_patterns 和 ignore_patterns 参数来指定要上传的文件。这些参数接受单个模式或模式列表。模式是标准通配符（globbing patterns），如此处所述。如果同时提供了 allow_patterns 和 ignore_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。

引发以下错误

HTTPError 如果 HuggingFace API 返回错误
ValueError 如果某些参数值无效

upload_folder 假设仓库已存在于 Hub 上。如果您收到客户端错误 404，请确保您已通过身份验证，并且 repo_id 和 repo_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 (str 或 Path) — 本地文件系统中要上传的文件夹路径。
repo_type (str) — 仓库类型。必须是 "model"、"dataset" 或 "space" 之一。与所有其他 HfApi 方法不同，此处显式要求 repo_type。这是为了避免在将大型文件夹上传到 Hub 时出现任何错误，从而防止必须重新上传所有内容。
revision (str, optional) — 要提交到的分支。如果未提供，将使用 main 分支。
private (bool, optional) — 仓库是否应为私有。如果为 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/ 下的文件夹中，以便在中断时能够恢复该过程。整个过程可能会产生多次提交。

需要记住的一些事项

仓库限制仍然适用：https://huggingface.co/docs/hub/repositories-recommendations
不要并行启动多个进程。
您可以随时中断和恢复该过程。
不要将同一个文件夹上传到多个仓库。如果需要这样做，您必须先删除本地 .cache/.huggingface/ 文件夹。

虽然 upload_large_folder 在上传大型文件夹方面更加强大，但与 upload_folder() 相比，功能上有所限制。实际上：

您无法设置自定义的 path_in_repo。如果您想上传到子文件夹，您需要在本地设置正确的结构。
您无法设置自定义的 commit_message 和 commit_description，因为会创建多个提交。
上传时您无法从仓库中删除内容。请先进行单独的提交。
您无法直接创建 PR。请先创建 PR（从 UI 或使用 create_pull_request()），然后通过传递 revision 提交到该 PR。

技术细节

upload_large_folder 进程如下：

（检查参数并进行设置。）
如果仓库不存在，则创建仓库。
列出要上传的本地文件。
启动工作进程。工作进程可以执行以下任务：
- 哈希文件。
- 获取文件列表的上传模式（常规或 LFS）。
- 预上传 LFS 文件。
- 提交一批文件。一旦工作进程完成一个任务，它将根据优先级列表（见下文）移动到下一个任务，直到所有文件都上传并提交。
在工作进程运行时，定期向 sys.stdout 打印报告。

优先级顺序

如果距离上次提交尝试已超过 5 分钟（且至少有 1 个文件），则提交。
如果至少有 150 个文件准备好提交，则提交。
如果至少有 10 个文件已被哈希，则获取上传模式。
如果至少有 1 个 LFS 文件且没有工作进程正在预上传，则预上传 LFS 文件。
如果至少有 1 个文件且没有工作进程正在哈希，则哈希文件。
如果至少有 1 个文件且没有工作进程正在获取上传模式，则获取上传模式。
如果至少有 1 个 LFS 文件，则预上传 LFS 文件（例外：如果启用了 hf_transfer，则一次只能有 1 个工作进程预上传 LFS）。
如果至少有 1 个文件要哈希，则哈希文件。
如果至少有 1 个文件要获取上传模式，则获取上传模式。
如果至少有 1 个文件要提交且距离上次提交尝试至少 1 分钟，则提交。
如果至少有 1 个文件要提交且所有其他队列都为空，则提交。

特殊规则

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

whoami

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

参数

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

调用 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 时填充。可以在 get_discussion_details() 中作为 discussion_num 传递。示例： 1。
repo_url (RepoUrl) — 包含仓库ID、仓库类型等信息的提交的仓库 URL。
_url (str, optional) — 为了与 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, optional) — 仓库在 Hub 上创建的日期。请注意，最低值为 2022-03-02T23:29:04.000Z，对应于我们开始存储创建日期的日期。
last_modified (datetime, optional) — 上次提交到仓库的日期。
private (bool) — 仓库是否为私有。
disabled (bool, optional) — 仓库是否被禁用。
gated (Literal["auto", "manual", False], optional) — 仓库是否为受限访问。如果是，则表示是手动批准还是自动批准。
downloads (int) — 数据集在过去 30 天内的下载次数。
downloads_all_time (int) — 模型自创建以来的累积下载次数。
likes (int) — 数据集的点赞数。
tags (List[str]) — 数据集的标签列表。
card_data (DatasetCardData, optional) — 作为 huggingface_hub.repocard_data.DatasetCardData 对象的模型卡元数据。
siblings (List[RepoSibling]) — 构成数据集的 huggingface_hub.hf_api.RepoSibling 对象列表。
paperswithcode_id (str, optional) — 数据集的 Papers With Code ID。
trending_score (int, optional) — 数据集的趋势评分。

包含有关 Hub 上数据集的信息。

此类的大多数属性是可选的。这是因为 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]) — GitRefInfo 列表，包含仓库中 “convert” 引用的信息。“Converts” 是指（内部）用于在数据集仓库中推送预处理数据的引用。
tags (List[GitRefInfo]) — GitRefInfo 列表，包含仓库中标签的信息。
pull_requests (List[GitRefInfo], 可选) — GitRefInfo 列表，包含仓库中拉取请求的信息。仅当设置了 include_prs=True 时返回。

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

对象由 list_repo_refs() 返回。

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, 可选) — 推送 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, 可选) — 模型的作者。
sha (str, 可选) — 此特定修订版本的仓库 SHA。
created_at (datetime, 可选) — 仓库在 Hub 上的创建日期。请注意，最低值是 2022-03-02T23:29:04.000Z，对应于我们开始存储创建日期的日期。
last_modified (datetime, 可选) — 仓库上次提交的日期。
private (bool) — 仓库是否为私有。
disabled (bool, 可选) — 仓库是否被禁用。
downloads (int) — 模型在过去 30 天内的下载次数。
downloads_all_time (int) — 模型自创建以来的累计下载次数。
gated (Literal["auto", "manual", False], optional) — 仓库是否为受限访问。如果是，则说明是手动批准还是自动批准。
gguf (Dict, optional) — 模型的 GGUF 信息。
inference (Literal["cold", "frozen", "warm"], optional) — 模型在推理 API 上的状态。Warm 模型可立即使用。Cold 模型将在首次推理调用时加载。Frozen 模型在推理 API 中不可用。
inference_provider_mapping (Dict, optional) — 模型的推理提供商映射。
likes (int) — 模型的点赞数。
library_name (str, optional) — 与模型关联的库名称。
tags (List[str]) — 模型的标签列表。与 card_data.tags 相比，包含 Hub 计算的额外标签（例如，支持的库、模型的 arXiv）。
pipeline_tag (str, optional) — 与模型关联的 Pipeline 标签。
mask_token (str, optional) — 模型使用的 Mask token。
widget_data (Any, optional) — 与模型关联的 Widget 数据。
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], optional) — 使用该模型的 Spaces 列表。
safetensors (SafeTensorsInfo, optional) — 模型的 safetensors 信息。
security_repo_status (Dict, optional) — 模型的安全扫描状态。

包含有关 Hub 上模型的信息。

此类的多数属性是可选的。这是因为 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, optional) — 文件的大小，以字节为单位。当 repo_info() 的 files_metadata 参数设置为 True 时，定义此属性。否则为 None。
blob_id (str, optional) — 文件的 git OID。当 repo_info() 的 files_metadata 参数设置为 True 时，定义此属性。否则为 None。
lfs (BlobLfsInfo, optional) — 文件的 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

ValueError — 如果 URL 无法解析。
ValueError — 如果 repo_type 未知。

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, optional) — Space 的主机 URL。
subdomain (str, optional) — Space 的子域名。
likes (int) — Space 的点赞数。
tags (List[str]) — Space 的标签列表。
siblings (List[RepoSibling]) — 构成 Space 的 huggingface_hub.hf_api.RepoSibling 对象列表。
card_data (SpaceCardData, optional) — Space Card 元数据，作为 huggingface_hub.repocard_data.SpaceCardData 对象。
runtime (SpaceRuntime, optional) — Space 运行时信息，作为 huggingface_hub.hf_api.SpaceRuntime 对象。
sdk (str, optional) — Space 使用的 SDK。
models (List[str], optional) — Space 使用的模型列表。
datasets (List[str], optional) — Space 使用的数据集列表。
trending_score (int, optional) — Space 的热度评分。

包含关于 Hub 上 Space 的信息。

这个类的大多数属性是可选的。这是因为 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) — tensor 的数据类型 (“F64”, “F32”, “F16”, “BF16”, “I64”, “I32”, “I16”, “I8”, “U8”, “BOOL”)。
shape (List[int]) — tensor 的形状。
data_offsets (Tuple[int, int]) — 文件中数据的偏移量，以元组 [BEGIN, END] 形式表示。
parameter_count (int) — tensor 中的参数数量。

关于 tensor 的信息。

有关 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) — 用户创建的 Space 数量。
num_discussions (int, optional) — 用户发起的讨论数量。
num_papers (int, optional) — 用户撰写的论文数量。
num_upvotes (int, optional) — 用户收到的赞同票数。
num_likes (int, optional) — 用户给出的点赞数。
num_following (int, optional) — 此用户正在关注的用户数量。
num_followers (int, 可选) — 关注此用户的用户数。
orgs (Organization 的列表 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, 可选) — 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, 或 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, 可选, 默认为 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 文件。要复制常规文件，您需要将其下载到本地并重新上传。
不支持跨仓库复制。

注意：您可以结合 CommitOperationCopy 和 CommitOperationDelete 来重命名 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 (str or Path) — 要定期上传的本地文件夹的路径。
every (int or float, optional) — 每次提交之间间隔的分钟数。默认为 5 分钟。
path_in_repo (str, optional) — 仓库中目录的相对路径，例如： "checkpoints/"。默认为仓库的根文件夹。
repo_type (str, optional) — 要提交到的仓库的类型。默认为 model。
revision (str, optional) — 要提交到的仓库的版本。默认为 main。
private (bool, optional) — 是否将仓库设为私有。如果为 `None`（默认），则仓库将是公开的，除非组织的默认设置为私有。如果仓库已存在，则此值将被忽略。
token (str, optional) — 用于提交到仓库的令牌。默认为保存在机器上的令牌。
allow_patterns (List[str] or str, optional) — 如果提供，则仅上传与至少一个模式匹配的文件。
ignore_patterns (List[str] or str, optional) — 如果提供，则不上传与任何模式匹配的文件。
squash_history (bool, optional) — 是否在每次提交后压缩仓库的历史记录。默认为 `False`。当仓库变得太大时，压缩提交有助于避免仓库性能下降。
hf_api (HfApi, optional) — 用于提交到 Hub 的 HfApi 客户端。可以使用自定义设置（用户代理、令牌等）进行设置。

调度器，用于定期将本地文件夹上传到 Hub（例如，每 5 分钟推送到 hub）。

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

示例

>>> 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 继承并覆盖此方法。例如，这对于在提交之前将数据压缩到单个文件中可能很有用。有关更多详细信息和示例，请查看我们的 integration guide 。

stop

( )

停止调度器。

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

trigger