Hub Python 库文档

HfApi 客户端

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

HfApi 客户端

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

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

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

from huggingface_hub import HfApi, list_models

# Use root method
models = list_models()

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

HfApi

class huggingface_hub.HfApi

< >

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

accept_access_request

< >

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

参数

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

引发

HTTPError

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

接受来自用户对给定受限仓库的访问请求。

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

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

add_collection_item

< >

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

参数

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

引发

HTTPError

  • HTTPError — HTTP 403,如果您只有对仓库的只读访问权限。 如果您在仓库所属的组织中没有 `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, 可选) — 密钥描述。示例:"Github API key to access the Github API"
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

在 Space 中添加或更新密钥。

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

add_space_variable

< >

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

参数

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

在 Space 中添加或更新变量。

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

auth_check

< >

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

参数

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

引发

RepositoryNotFoundErrorGatedRepoError

  • RepositoryNotFoundError — 如果仓库不存在、是私有的或用户无权访问,则引发此错误。 如果 repo_idrepo_type 不正确,或者仓库是私有的但用户未通过身份验证,则可能发生这种情况。

  • GatedRepoError — 如果仓库存在但已受限,且用户未被授权访问,则引发此错误。

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

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

示例

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

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

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

在此示例中

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

cancel_access_request

< >

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

参数

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

引发

HTTPError

  • HTTPError — HTTP 400,如果仓库未被限制访问。
  • HTTPError — HTTP 403,如果您只有对仓库的只读访问权限。 如果您在仓库所属的组织中没有 `write` 或 `admin` 角色,或者您传递了 `read` 令牌,则可能会发生这种情况。
  • HTTPError — HTTP 404,如果 Hub 上不存在该用户。
  • 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,则在分支已存在时不要引发错误。

引发

RepositoryNotFoundErrorBadRequestErrorHfHubHTTPError

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

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

create_collection

< >

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

参数

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

在 Hub 上创建新的 Collection。

返回值: Collection

示例

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

create_commit

< >

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

参数

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

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

  • commit_message (str) — 将要创建的提交的摘要(第一行)。
  • commit_description (str, 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_prFalse,则当 revision 未指向 parent_commit 时,提交将失败。如果指定且 create_prTrue,则将从 parent_commit 创建拉取请求。指定 parent_commit 可确保在提交更改之前仓库未发生更改,并且在仓库同时更新/提交时尤其有用。
  • run_as_future (bool, optional) — 是否在后台运行此方法。后台作业按顺序运行,不会阻塞主线程。传递 run_as_future=True 将返回一个 Future 对象。默认为 False

返回

CommitInfoFuture

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

引发

ValueErrorRepositoryNotFoundError

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

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

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

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

create_commit 限制为 25k 个 LFS 文件和 1GB 的常规文件负载。

create_commits_on_pr

< >

( repo_id: str addition_commits: List[List[CommitOperationAdd]] deletion_commits: List[List[CommitOperationDelete]] commit_message: str commit_description: Optional[str] = None token: Union[str, bool, None] = None repo_type: Optional[str] = None merge_pr: bool = True num_threads: int = 5 verbose: bool = False ) str

参数

  • repo_id (str) — 将在其中推送提交的仓库。示例: "username/my-cool-model"
  • addition_commits (List of List of CommitOperationAdd) — 包含 CommitOperationAdd 列表的列表。每个子列表将在 PR 上生成一个提交。

    deletion_commits — 包含 CommitOperationDelete 列表的列表。每个子列表将在 PR 上生成一个提交。删除提交在添加提交之前推送。

  • commit_message (str) — 将要创建的提交的摘要(第一行)。也将是 PR 的标题。
  • commit_description (str, optional) — 将要创建的提交的描述。描述将添加到 PR 中。
  • 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
  • merge_pr (bool) — 如果设置为 True,则在此过程结束时合并拉取请求。默认为 True
  • num_threads (int, optional) — 用于上传文件的并发线程数。默认为 5。
  • verbose (bool) — 如果设置为 True,则进程将在详细模式下运行,即打印有关正在进行的任务的信息。默认为 False

返回

str

指向已创建 PR 的 URL。

引发

MultiCommitException

  • MultiCommitException — 如果在此过程中发生意外问题:空提交、PR 中意外的提交、意外的 PR 描述等。

以多个提交的形式将更改推送到 Hub。

提交被推送到草稿 PR 分支。如果上传失败或中断,可以恢复。进度在 PR 描述中跟踪。在此过程结束时,PR 设置为打开状态,并且标题更新为与初始提交消息匹配。如果传递了 merge_pr=True,则 PR 将自动合并。

所有删除提交首先推送,然后是添加提交。提交的顺序不能保证,因为我们将来可能会实现并行提交。请确保您没有多次更新同一文件。

create_commits_on_pr 是实验性的。其 API 和行为可能会在未来更改,恕不另行通知。

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

示例

>>> from huggingface_hub import HfApi, plan_multi_commits
>>> addition_commits, deletion_commits = plan_multi_commits(
...     operations=[
...          CommitOperationAdd(...),
...          CommitOperationAdd(...),
...          CommitOperationDelete(...),
...          CommitOperationDelete(...),
...          CommitOperationAdd(...),
...     ],
... )
>>> HfApi().create_commits_on_pr(
...     repo_id="my-cool-model",
...     addition_commits=addition_commits,
...     deletion_commits=deletion_commits,
...     (...)
...     verbose=True,
... )

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) — Pull Request 的可选描述。默认为 "Discussion opened with the huggingface_hub Python library"
  • pull_request (bool, optional) — 是否创建 Pull Request 或讨论。如果为 True,则创建 Pull Request。如果为 False,则创建讨论。默认为 False
  • repo_type (str, optional) — 如果上传到数据集或 Space,请设置为 "dataset""space";如果上传到模型,则设置为 None"model"。默认为 None

创建讨论或 Pull Request。

通过编程方式创建的 Pull Request 将处于 "draft" 状态。

使用 HfApi.create_commit() 也可以一次性完成创建包含更改的 Pull Request。

返回值: 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) — 新 Inference Endpoint 的唯一名称。
  • repository (str) — 与 Inference Endpoint 关联的模型仓库的名称 (例如 "gpt2")。
  • framework (str) — 模型使用的机器学习框架 (例如 "custom")。
  • accelerator (str) — 用于推理的硬件加速器 (例如 "cpu")。
  • instance_size (str) — 用于托管模型的实例的大小或类型 (例如 "x4")。
  • instance_type (str) — Inference Endpoint 将部署到的云实例类型 (例如 "intel-icl")。
  • region (str) — 将在其中创建 Inference Endpoint 的云区域 (例如 "us-east-1")。
  • vendor (str) — 将托管 Inference Endpoint 的云提供商或供应商 (例如 "aws")。
  • account_id (str, optional) — 用于将 VPC 链接到私有 Inference Endpoint 的帐户 ID (如果适用)。
  • min_replica (int, optional) — 为 Inference Endpoint 保持运行的最小副本 (实例) 数。默认为 0。
  • max_replica (int, optional) — Inference Endpoint 要扩展到的最大副本 (实例) 数。默认为 1。
  • scale_to_zero_timeout (int, optional) — 不活动端点缩减为零之前的持续时间,以分钟为单位。默认为 15。
  • 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) — 要注入到容器环境中的密钥值。
  • type ([`InferenceEndpointType], *optional*) -- Inference Endpoint 的类型,可以是 “protected”(默认),“public”“private”`。
  • namespace (str, optional) — 将在其中创建 Inference Endpoint 的命名空间。默认为当前用户的命名空间。
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌 (字符串)。默认为本地保存的令牌,这是推荐的身份验证方法 (请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

InferenceEndpoint

关于更新后的 Inference Endpoint 的信息。

创建一个新的 Inference Endpoint。

示例

>>> 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_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, optional) — 拉取请求的可选描述。 默认为 "Discussion opened with the huggingface_hub Python library"
  • repo_type (str, optional) — 如果上传到数据集或 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: bool = False 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, defaults to False) — 模型仓库是否应为私有。
  • 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 (SpaceHardwarestr, optional) — 如果 repo_type 为 “space”,则选择硬件。 有关完整列表,请参阅 SpaceHardware
  • space_storage (SpaceStoragestr, 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 的子类,包含诸如 endpointrepo_typerepo_id 之类的属性。

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

create_tag

< >

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

参数

  • repo_id (str) — 将在其中标记提交的仓库。 示例: "user/my-cool-model"
  • tag (str) — 要创建的标签的名称。
  • tag_message (str, 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, 可选, 默认为 False) — 如果为 True,则在标签已存在时不会引发错误。

引发

RepositoryNotFoundErrorRevisionNotFoundErrorHfHubHTTPError

  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type、私有但未通过身份验证或仓库不存在。
  • RevisionNotFoundError — 如果在仓库中找不到修订版本(错误 404)。
  • HfHubHTTPError — 如果仓库上已存在该分支(错误 409)且 exist_ok 设置为 False

在 Hub 上为仓库的给定提交打标签。

create_webhook

< >

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

参数

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

返回

WebhookInfo

有关新创建的 webhook 的信息。

创建一个新的 webhook。

示例

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

dataset_info

< >

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

参数

  • repo_id (str) — 命名空间(用户或组织)和仓库名称,用 / 分隔。
  • revision (str, 可选) — 从中获取数据集仓库信息的修订版本。
  • timeout (float, 可选) — 是否为 Hub 的请求设置超时。
  • files_metadata (bool, 可选) — 是否检索仓库中文件的元数据(大小、LFS 元数据等)。默认为 False
  • expand (List[ExpandDatasetProperty_T], 可选) — 要在响应中返回的属性列表。使用后,将仅返回列表中的属性。如果传递了 files_metadata,则不能使用此参数。可能的值为 "author""cardData""citation""createdAt""disabled""description""downloads""downloadsAllTime""gated""lastModified""likes""paperswithcode_id""private""siblings""sha""tags""trendingScore"
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 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], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, 可选) — 如果在数据集或 Space 上创建分支,则设置为 "dataset""space";如果标记模型,则设置为 None"model"。默认为 None

引发

RepositoryNotFoundErrorHfHubHTTPError

  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type、私有但未通过身份验证或仓库不存在。
  • HfHubHTTPError — 如果尝试删除受保护的分支。 例如:无法删除 main
  • HfHubHTTPError — 如果尝试删除不存在的分支。

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

delete_collection

< >

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

参数

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

删除 Hub 上的集合。

示例

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

这是一个不可逆的操作。删除的集合无法恢复。

delete_collection_item

< >

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

参数

  • collection_slug (str) — 要更新的集合的 Slug。 示例:"TheBloke/recent-models-64f9a55bb3115b4f513ec026"
  • item_object_id (str) — 集合中项目的 ID。 这不是 Hub 上的项目 ID(repo_id 或 paper id)。 它必须从 CollectionItem 对象中检索。 示例:collection.items[0]._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_prFalse,则当 revision 未指向 parent_commit 时,提交将失败。 如果指定且 create_prTrue,则将从 parent_commit 创建拉取请求。 指定 parent_commit 可确保在提交更改之前仓库未更改,并且在并发更新/提交仓库时尤其有用。

删除给定仓库中的文件。

引发以下错误

delete_files

< >

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

参数

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

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

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

delete_folder

< >

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

参数

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

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

围绕 create_commit() 方法的简单包装器。

delete_inference_endpoint

< >

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

参数

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

删除推理端点。

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

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

delete_repo

< >

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

参数

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

从 Space 中删除密钥。

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

delete_space_storage

< >

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

参数

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

返回

SpaceRuntime

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

引发

BadRequestError

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

删除 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 中删除一个变量。

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

delete_tag

< >

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

参数

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

引发

RepositoryNotFoundErrorRevisionNotFoundError

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

delete_webhook

< >

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

参数

  • webhook_id (str) — 要删除的 webhook 的唯一标识符。
  • token (Union[bool, str, None], 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

返回

WebhookInfo

关于已禁用 webhook 的信息。

禁用一个 webhook(使其变为“disabled”状态)。

示例

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

duplicate_space

< >

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

参数

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

返回

RepoUrl

新创建的仓库的 URL。 值是 str 的子类,包含诸如 endpointrepo_typerepo_id 之类的属性。

引发

RepositoryNotFoundErrorHTTPError

  • RepositoryNotFoundError — 如果找不到 from_idto_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) — 讨论或 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], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 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

参数

返回

WebhookInfo

关于已启用的 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], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 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 上的 Collection 的 Slug。示例:"TheBloke/recent-models-64f9a55bb3115b4f513ec026"
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 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 的命名空间 ({organization}/{model_id}) 下。

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

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

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

get_inference_endpoint

< >

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

参数

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

返回

InferenceEndpoint

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

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

示例

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

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

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

get_model_tags

< >

( )

将所有有效的模型标签列为嵌套的命名空间对象

get_paths_info

< >

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

参数

  • repo_id (str) — 命名空间(用户或组织)和仓库名称,用 / 分隔。
  • paths (Union[List[str], str], 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]]

关于路径的信息,以 RepoFileRepoFolder 对象的列表形式返回。

引发

RepositoryNotFoundErrorRevisionNotFoundError

  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type、私有但未通过身份验证或仓库不存在。
  • RevisionNotFoundError — 如果在仓库中找不到修订版本(错误 404)。

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

示例

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

get_repo_discussions

< >

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

参数

  • repo_id (str) — 命名空间(用户或组织)和仓库名称,用 / 分隔。
  • author (str, optional) — 传递一个值以按讨论作者进行筛选。 None 表示不筛选。默认为 None
  • discussion_type (str, optional) — 设置为 "pull_request" 以仅获取拉取请求,设置为 "discussion" 以仅获取讨论。设置为 "all"None 以同时获取两者。默认为 None
  • discussion_status (str, optional) — 设置为 "open" (或 "closed")以仅获取打开的(或关闭的)讨论。设置为 "all"None 以同时获取两者。默认为 None
  • 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

返回

Iterator[Discussion]

Discussion 对象的迭代器。

获取给定仓库的 Discussion 和 Pull Request。

示例

在一个列表中收集仓库的所有 discussion

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

迭代仓库的 discussion

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

返回

SafetensorsRepoMetadata

与 safetensors 仓库相关的信息。

引发

NotASafetensorsRepoErrorSafetensorsParsingError

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

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

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

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

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

示例

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

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

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

get_space_runtime

< >

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

参数

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

返回

SpaceRuntime

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

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

get_space_variables

< >

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

参数

  • repo_id (str) — 要查询的仓库 ID。 示例:"bigcode/in-the-stack"
  • token (Union[bool, str, None], 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

get_token_permission

< >

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

参数

返回

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

令牌授予的权限(“read”或“write”)。 如果未传递令牌或令牌无效,则返回 None

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

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

get_user_overview

< >

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

参数

返回

User

带有用户概览的 User 对象。

引发

HTTPError

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

获取 Hub 上用户的概览。

get_webhook

< >

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

参数

返回

WebhookInfo

关于 webhook 的信息。

通过 ID 获取 webhook。

示例

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

grant_access

< >

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

参数

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

引发

HTTPError

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

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

授予访问权限不需要用户自行发送访问请求。用户将自动添加到接受列表中,这意味着他们可以下载文件。您可以随时使用 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, 可选) — 与模型仓库内文件夹对应的可选值。
  • repo_type (str, 可选) — 如果从数据集或 Space 下载,则设置为 "dataset""space";如果从模型下载,则设置为 None"model"。默认为 None
  • revision (str, 可选) — 可选的 Git 修订 ID,可以是分支名称、标签或提交哈希值。
  • cache_dir (str, Path, 可选) — 存储缓存文件的文件夹路径。
  • local_dir (strPath, 可选) — 如果提供,下载的文件将放置在此目录下。
  • force_download (bool, 可选, 默认为 False) — 即使本地缓存中已存在该文件,是否仍应下载该文件。
  • proxies (dict, 可选) — 将协议映射到传递给 requests.request 的代理 URL 的字典。
  • etag_timeout (float, 可选, 默认为 10) — 获取 ETag 时,在放弃之前等待服务器发送数据多少秒,该值将传递给 requests.request
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • local_files_only (bool, 可选, 默认为 False) — 如果为 True,则避免下载文件,并在本地缓存文件中存在该文件时返回其路径。

返回

str

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

引发

RepositoryNotFoundErrorRevisionNotFoundErrorEntryNotFoundErrorLocalEntryNotFoundErrorEnvironmentErrorOSErrorValueError

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

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

  • 缓存目录包含每个 repo_id 的一个子文件夹(按仓库类型命名空间)
  • 在每个仓库文件夹内
    • refs 是最新已知修订版本 => commit_hash 对的列表
    • blobs 包含实际的文件 blobs(由其 git-sha 或 sha256 标识,具体取决于它们是否为 LFS 文件)
    • snapshots 包含每个提交的子文件夹,每个“commit”包含在该特定提交时已解析的文件子集。每个文件名都是指向该特定提交处的 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

隐藏的评论

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

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

引发以下错误

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

like

< >

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

参数

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

引发

RepositoryNotFoundError

  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type、私有但未通过身份验证或仓库不存在。

点赞 Hub 上的给定仓库(例如,设置为收藏夹)。

另请参阅 unlike()list_liked_repos()

示例

>>> from huggingface_hub import like, list_liked_repos, unlike
>>> like("gpt2")
>>> "gpt2" in list_liked_repos().models
True
>>> unlike("gpt2")
>>> "gpt2" in list_liked_repos().models
False

list_accepted_access_requests

< >

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

参数

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

返回

List[AccessRequest]

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

引发

HTTPError

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

返回

Iterable[Collection]

Collection 对象的迭代器。

列出 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 or Iterable[str], optional) — 用于在 Hub 上筛选数据集的字符串或字符串列表。
  • author (str, optional) — 用于标识返回数据集的作者的字符串。
  • benchmark (str or List, optional) — 可用于通过其官方基准测试在 Hub 上识别数据集的字符串或字符串列表。
  • dataset_name (str, optional) — 可用于通过其名称(例如 SQACwikineural)在 Hub 上识别数据集的字符串或字符串列表。
  • gated (bool, optional) — 用于在 Hub 上筛选受控数据集或非受控数据集的布尔值。 默认情况下,返回所有数据集。 如果传递 gated=True,则仅返回受控数据集。 如果传递 gated=False,则仅返回非受控数据集。
  • language_creators (str or List, optional) — 可用于通过数据是如何策划的(例如 crowdsourcedmachine_generated)来识别 Hub 上数据集的字符串或字符串列表。
  • language (str or List, optional) — 表示双字符语言的字符串或字符串列表,用于在 Hub 上按语言筛选数据集。
  • multilinguality (str or List, optional) — 表示包含多种语言的数据集的筛选器的字符串或字符串列表。
  • size_categories (str or List, optional) — 可用于通过数据集大小(例如 100K<n<1M1M<n<10M)在 Hub 上识别数据集的字符串或字符串列表。
  • tags (str or List, optional) — 用于在 Hub 上筛选数据集的字符串标签或标签列表。
  • task_categories (str or List, optional) — 可用于通过设计的任务(例如 audio_classificationnamed_entity_recognition)在 Hub 上识别数据集的字符串或字符串列表。
  • task_ids (strList, 可选) — 一个字符串或字符串列表,可用于通过特定任务(例如 speech_emotion_recognitionparaphrase)在 Hub 上识别数据集。
  • search (str, 可选) — 一个字符串,将包含在返回的数据集中。
  • sort (Literal["last_modified"]str, 可选) — 用于对结果数据集进行排序的键。可能的值是 huggingface_hub.hf_api.DatasetInfo 类的属性。
  • 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"
  • full (bool, 可选) — 是否获取所有数据集数据,包括 last_modifiedcard_data 和文件。可以包含有用的信息,例如 PapersWithCode ID。
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

Iterable[DatasetInfo]

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

列出 Huggingface 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_endpoints

< >

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

参数

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

返回

ListInferenceEndpoint

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

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

示例

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

list_liked_repos

< >

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

参数

返回

UserLikes

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

引发

ValueError

  • ValueError — 如果未传递 user 且未找到令牌(来自参数或机器)。

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

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

另请参阅 like()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_metrics

< >

( ) List[MetricInfo]

返回

List[MetricInfo]

MetricInfo 对象列表。

获取 huggingface.co 上所有指标的公共列表

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

返回

Iterable[ModelInfo]

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

列出 Hugging Face Hub 上托管的模型,可以根据一些过滤器进行过滤。

使用 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]

参数

返回

Iterable[User]

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

引发

HTTPError

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

列出 Hub 上组织的成员。

list_papers

< >

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

参数

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

返回

Iterable[PaperInfo]

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

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

示例

>>> from huggingface_hub import HfApi

>>> api = HfApi()

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

list_pending_access_requests

< >

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

参数

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

返回

List[AccessRequest]

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

引发

HTTPError

  • HTTPError — HTTP 400,如果仓库未被限制访问。
  • HTTPError — HTTP 403,如果您只有对仓库的只读访问权限。 如果您在仓库所属的组织中没有 `write` 或 `admin` 角色,或者您传递了 `read` 令牌,则可能会发生这种情况。

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

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

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

示例

>>> from huggingface_hub import list_pending_access_requests, accept_access_request

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

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

list_rejected_access_requests

< >

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

参数

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

返回

List[AccessRequest]

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

引发

HTTPError

  • HTTPError — HTTP 400,如果仓库未被限制访问。
  • HTTPError — HTTP 403,如果您只有对仓库的只读访问权限。 如果您在仓库所属的组织中没有 `write` 或 `admin` 角色,或者您传递了 `read` 令牌,则可能会发生这种情况。

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

已拒绝的请求表示用户已请求访问仓库,但该请求已被仓库所有者(您或您组织中的其他用户)明确拒绝。用户无法下载仓库的任何文件。可以使用 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 上仓库提交信息的对象列表。

引发

RepositoryNotFoundErrorRevisionNotFoundError

  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type、私有但未通过身份验证或仓库不存在。
  • RevisionNotFoundError — 如果在仓库中找不到修订版本(错误 404)。

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

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

示例

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

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

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

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

list_repo_files

< >

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

参数

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

返回

List[str]

给定仓库中的文件列表。

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

list_repo_likers

< >

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

参数

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

返回

Iterable[User]

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

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

另请参阅 like()list_liked_repos()

list_repo_refs

< >

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

参数

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

返回

GitRefs

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

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

示例

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

>>> api.list_repo_refs("bigcode/the-stack", repo_type='dataset')
GitRefs(
    branches=[
        GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
        GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
    ],
    converts=[],
    tags=[
        GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
    ]
)

list_repo_tree

< >

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

参数

  • repo_id (str) — 命名空间(用户或组织)和仓库名称,用 / 分隔。
  • path_in_repo (str, 可选) — 仓库中树(文件夹)的相对路径,例如:"checkpoints/1fec34a/results"。将默认为仓库的根树(文件夹)。
  • recursive (bool, 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]]

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

引发

RepositoryNotFoundErrorRevisionNotFoundErrorEntryNotFoundError

  • RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type、私有但未通过身份验证或仓库不存在。
  • RevisionNotFoundError — 如果在仓库中找不到修订版本(错误 404)。
  • EntryNotFoundError — 如果仓库中不存在树(文件夹)(错误 404)。

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

示例

获取关于仓库树的信息。

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

获取关于仓库树的更多信息(上次提交和文件的安全扫描结果)

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

list_spaces

< >

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

参数

  • filter (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) — 用于对结果 Spaces 进行排序的键。可能的值是 huggingface_hub.hf_api.SpaceInfo` 类的属性。
  • direction (Literal[-1] or int, optional) — 排序方向。值 -1 按降序排序,而所有其他值按升序排序。
  • limit (int, optional) — 获取的 Spaces 数量的限制。将此选项保留为 None 将获取所有 Spaces。
  • expand (List[ExpandSpaceProperty_T], optional) — 要在响应中返回的属性列表。使用时,仅返回列表中的属性。如果传递了 full,则不能使用此参数。可能的值为 "author""cardData""datasets""disabled""lastModified""createdAt""likes""models""private""runtime""sdk""siblings""sha""subdomain""tags""trendingScore"
  • full (bool, optional) — 是否获取所有 Spaces 数据,包括 last_modifiedsiblingscard_data 字段。
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

Iterable[SpaceInfo]

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

列出 Huggingface Hub 上托管的 spaces,并根据一些过滤器进行筛选。

list_user_followers

< >

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

参数

  • username (str) — 要获取其关注者的用户的用户名。
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 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], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 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]

参数

返回

WebhookInfo 列表

webhook 信息对象列表。

列出所有已配置的 webhook。

示例

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

merge_pull_request

< >

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

参数

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

返回

DiscussionStatusChange

状态更改事件

合并拉取请求。

引发以下错误

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

model_info

< >

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

参数

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

返回

huggingface_hub.hf_api.ModelInfo

模型仓库信息。

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

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

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

引发以下错误

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

paper_info

< >

( id: str ) PaperInfo

参数

  • id (str, optional) — 论文的 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 文件相关的信息。

引发

NotASafetensorsRepoErrorSafetensorsParsingError

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

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

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

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

pause_inference_endpoint

< >

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

参数

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

返回

InferenceEndpoint

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

暂停推理端点。

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

为方便起见,您还可以使用 pause_inference_endpoint() 暂停推理端点。

pause_space

< >

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

参数

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

返回

SpaceRuntime

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

引发

RepositoryNotFoundErrorHfHubHTTPErrorBadRequestError

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

暂停您的 Space。

暂停的 Space 将停止执行,直到其所有者手动重启。这与空闲 Space 在 48 小时不活动后进入休眠状态不同。暂停时间不会计入您的帐户,无论您选择了什么硬件。要重启您的 Space,请使用 restart_space() 并转到您的 Space 设置页面。

有关更多详细信息,请访问 文档

preupload_lfs_files

< >

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

参数

  • repo_id (str) — 您将在其中提交文件的仓库,例如:"username/custom_transformers"
  • operations (Iterable of CommitOperationAdd) — 要上传的文件列表。警告:此列表中的对象将被修改,以包含与上传相关的信息。请勿为多个提交重复使用相同的对象。
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False
  • repo_type (str, 可选) — 要上传到的仓库类型(例如,"model" - 默认值 -,"dataset""space")。
  • revision (str, 可选) — 从中提交的 git 修订版本。默认为 "main" 分支的头部。
  • create_pr (boolean, 可选) — 是否计划为此提交创建拉取请求。默认为 False
  • num_threads (int, 可选) — 用于上传文件的并发线程数。默认为 5。设置为 2 表示最多并发上传 2 个文件。
  • gitignore_content (str, 可选) — .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 token: Union[bool, str, None] = None )

参数

  • repo_id (str) — 要拒绝访问请求的仓库 ID。
  • user (str) — 应该拒绝访问请求的用户的用户名。
  • repo_type (str, 可选) — 要拒绝访问请求的仓库类型。必须是 modeldatasetspace 之一。默认为 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 — HTTP 404,如果 Hub 上不存在该用户。
  • 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, 可选) — 如果上传到数据集或 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, 可选) — 如果从数据集或 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, 可选) — 获取信息的仓库版本。
  • repo_type (str, 可选) — 如果从数据集或 Space 获取仓库信息,则设置为 "dataset""space";如果从模型获取仓库信息,则设置为 None"model"。默认为 None
  • timeout (float, 可选) — 是否为 Hub 的请求设置超时。
  • expand (ExpandModelProperty_TExpandDatasetProperty_TExpandSpaceProperty_T, 可选) — 在响应中返回的属性列表。使用时,仅返回列表中的属性。如果传递了 files_metadata,则不能使用此参数。有关可用属性的完整列表,请查看 model_info()dataset_info()space_info()
  • files_metadata (bool, 可选) — 是否检索仓库中文件的元数据(大小、LFS 元数据等)。默认为 False
  • token (Union[bool, str, None], optional) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

Union[SpaceInfo, DatasetInfo, ModelInfo]

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

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

引发以下错误

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

返回

SpaceRuntime

关于 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 (strSpaceStorage) — 存储层级。可以是 ‘small’、‘medium’ 或 ‘large’。
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

SpaceRuntime

关于 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, optional) — 如果为 True,Space 将从头开始重建,而不缓存任何 requirements。

返回

SpaceRuntime

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

引发

RepositoryNotFoundErrorHfHubHTTPErrorBadRequestError

  • RepositoryNotFoundError — 如果未找到您的 Space(错误 404)。很可能是错误的 repo_id 或您的 Space 是私有的,但您未通过身份验证。
  • HfHubHTTPError — 403 Forbidden:只有 Space 的所有者才能重启它。如果您想重启您不拥有的 Space,请通过开启 Discussion 询问所有者或复制 Space。
  • BadRequestError — 如果您的 Space 是静态 Space。静态 Space 始终运行且永不计费。如果您想隐藏静态 Space,可以将其设置为私有。

重启您的 Space。

如果您已将 Space 设置为暂停状态(请参阅 pause_space()),这是以编程方式重启 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, optional) — Inference Endpoint 所在的命名空间。默认为当前用户。
  • running_ok (bool, optional) — 如果为 True,则当 Inference Endpoint 已经在运行时,该方法不会引发错误。默认为 True
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

InferenceEndpoint

关于恢复的 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, 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 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, optional) — Inference Endpoint 所在的命名空间。默认为当前用户。
  • token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递 False

返回

InferenceEndpoint

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

将推理端点缩放至零。

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

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

set_space_sleep_time

< >

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

参数

  • repo_id (str) — 要更新的仓库的 ID。 示例:"bigcode/in-the-stack"
  • sleep_time (int, 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

返回

SpaceRuntime

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

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

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

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

snapshot_download

< >

( repo_id: str repo_type: Optional[str] = None revision: Optional[str] = None cache_dir: Union[str, Path, None] = None local_dir: Union[str, Path, None] = None proxies: Optional[Dict] = None etag_timeout: float = 10 force_download: bool = False token: Union[bool, str, None] = None local_files_only: bool = False allow_patterns: Optional[Union[List[str], str]] = None ignore_patterns: Optional[Union[List[str], str]] = None max_workers: int = 8 tqdm_class: Optional[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 (strPath, 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

仓库快照的文件夹路径。

引发

RepositoryNotFoundErrorRevisionNotFoundErrorEnvironmentErrorOSErrorValueError

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

下载仓库文件。

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

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

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

space_info

< >

( repo_id: str revision: Optional[str] = None timeout: Optional[float] = None files_metadata: bool = False expand: Optional[List[ExpandModelProperty_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], 可选) — 要在响应中返回的属性列表。使用时,仅返回列表中的属性。如果传递了 full 参数,则不能使用此参数。可能的值为 "author", "cardData", "createdAt", "datasets", "disabled", "lastModified", "likes", "models", "private", "runtime", "sdk", "siblings", "sha", "subdomain", "tags""trendingScore"
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 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 like, list_liked_repos, unlike
>>> like("gpt2")
>>> "gpt2" in list_liked_repos().models
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 或 paper 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) — 要更新的推理端点的名称。
  • accelerator (str, 可选) — 用于推理的硬件加速器(例如,"cpu")。
  • instance_size (str, 可选) — 用于托管模型实例的大小或类型(例如,"x4")。
  • instance_type (str, 可选) — 推理端点将部署到的云实例类型(例如,"intel-icl")。
  • min_replica (int, 可选) — 为推理端点保持运行的最小副本(实例)数。
  • max_replica (int, 可选) — 推理端点要扩展到的最大副本(实例)数。
  • scale_to_zero_timeout (int, 可选) — 不活动端点扩展到零之前的持续时间(分钟)。
  • repository (str, 可选) — 与推理端点关联的模型仓库的名称(例如,"gpt2")。
  • framework (str, 可选) — 用于模型的机器学习框架(例如,"custom")。
  • revision (str, 可选) — 要在推理端点上部署的特定模型修订版本(例如,"6c0e6080953db56375760c0471a8c5f2929baf11")。
  • task (str, 可选) — 要在其上部署模型的任务(例如,"text-classification")。
  • custom_image (Dict, 可选) — 用于推理端点的自定义 Docker 镜像。 如果您想部署在 text-generation-inference (TGI) 框架上运行的推理端点,这将非常有用(请参阅示例)。
  • secrets (Dict[str, str], 可选) — 要注入到容器环境中的密钥值。
  • namespace (str, 可选) — 将在其中更新推理端点的命名空间。 默认为当前用户的命名空间。
  • token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。 默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。 要禁用身份验证,请传递 False

返回

InferenceEndpoint

关于更新后的 Inference Endpoint 的信息。

更新推理端点。

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

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

update_repo_settings

< >

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

参数

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

引发

ValueErrorHfHubHTTPErrorRepositoryNotFoundError

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

更新仓库的设置,包括门控访问和可见性。

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

update_repo_visibility

< >

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

参数

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

返回

WebhookInfo

关于更新后的 webhook 的信息。

更新现有的 webhook。

示例

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

upload_file

< >

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

参数

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

返回

CommitInfoFuture

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

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

引发以下错误

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

示例

>>> from huggingface_hub import upload_file

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

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

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

upload_folder

< >

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

参数

  • repo_id (str) — 文件将上传到的仓库,例如:"username/custom_transformers"
  • folder_path (str or 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 修订版本。 默认为 "main" 分支的头部。
  • commit_message (str, 可选) — 生成的提交的摘要/标题/第一行。 默认为:f"使用 huggingface_hub 上传 {path_in_repo}"
  • commit_description (str 可选) — 生成的提交的描述
  • create_pr (boolean, 可选) — 是否使用该提交创建拉取请求 (Pull Request)。 默认为 False。 如果未设置 revision,则针对 "main" 分支打开 PR。 如果设置了 revision 并且是一个分支,则针对此分支打开 PR。 如果设置了 revision 且不是分支名称(例如:提交 oid),则服务器返回 RevisionNotFoundError。 如果 multi_commitscreate_pr 都为 True,则在多提交过程中创建的 PR 将保持打开状态。
  • parent_commit (str, 可选) — 父提交的 OID / SHA,作为十六进制字符串。 也支持简写形式(前 7 个字符)。 如果指定且 create_prFalse,则当 revision 未指向 parent_commit 时,提交将失败。 如果指定且 create_prTrue,则将从 parent_commit 创建拉取请求。 指定 parent_commit 可确保在提交更改之前仓库未发生更改,并且在仓库同时更新/提交时特别有用。
  • allow_patterns (List[str]str, 可选) — 如果提供,则仅上传与至少一个模式匹配的文件。
  • ignore_patterns (List[str]str, 可选) — 如果提供,则不上传与任何模式匹配的文件。
  • delete_patterns (List[str]str, 可选) — 如果提供,则在提交新文件时,将从仓库中删除与任何模式匹配的远程文件。 如果您不知道哪些文件已被上传,这将非常有用。 注意:为避免差异,即使 .gitattributes 文件与模式匹配也不会被删除。
  • multi_commits (bool) — 已弃用。 对于大型上传,请改用 upload_large_folder。 如果为 True,则使用多提交过程将更改推送到 PR。 默认为 False
  • multi_commits_verbose (bool) — 已弃用。 对于大型上传,请改用 upload_large_folder。 如果为 True 且使用了 multi_commits,则会向用户显示更多信息。
  • run_as_future (bool, 可选) — 是否在后台运行此方法。 后台作业按顺序运行,不会阻塞主线程。 传递 run_as_future=True 将返回一个 Future 对象。 默认为 False

返回

CommitInfoFuture

CommitInfo 的实例,其中包含有关新创建的提交的信息(提交哈希值、提交 URL、PR URL、提交消息等)。 如果传递了 run_as_future=True,则返回一个 Future 对象,其中将包含执行时的结果。 strFuture:如果 multi_commits=True,则返回为推送更改而创建的 PR 的 URL。 如果传递了 run_as_future=True,则返回一个 Future 对象,其中将包含执行时的结果。

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

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

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

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

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

在底层使用 HfApi.create_commit

引发以下错误

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

multi_commits 是实验性的。 它的 API 和行为可能会在未来更改,恕不另行通知。

示例

# 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: bool = False allow_patterns: Optional[Union[List[str], str]] = None ignore_patterns: Optional[Union[List[str], str]] = None num_workers: Optional[int] = None print_report: bool = True print_report_every: int = 60 )

参数

  • repo_id (str) — 要将文件上传到的仓库。 例如:"HuggingFaceTB/smollm-corpus"
  • folder_path (strPath) — 要上传的本地文件系统上的文件夹路径。
  • repo_type (str) — 仓库的类型。 必须是 "model""dataset""space" 之一。 与所有其他 HfApi 方法不同,此处显式要求 repo_type。 这是为了避免在将大型文件夹上传到 Hub 时出现任何错误,从而防止不得不重新上传所有内容。
  • revision (str, optional) — 要提交到的分支。 如果未提供,将使用 main 分支。
  • private (bool, optional) — 仓库是否应为私有。 默认为 False。
  • 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。

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

需要记住的几件事

虽然 upload_large_folder 在上传大型文件夹时更加稳健,但在功能方面,它比 upload_folder() 更受限制。 实际上:

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

技术细节

upload_large_folder 进程如下:

  1. (检查参数和设置。)
  2. 如果仓库不存在,则创建仓库。
  3. 列出要上传的本地文件。
  4. 启动 worker。Worker 可以执行以下任务:
    • 哈希文件。
    • 获取文件列表的上传模式(常规或 LFS)。
    • 预上传 LFS 文件。
    • 提交一批文件。一旦 worker 完成一项任务,它将根据优先级列表(见下文)移动到下一个任务,直到所有文件都已上传和提交。
  5. 在 worker 运行时,定期向 sys.stdout 打印报告。

优先级顺序

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

特殊规则

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

whoami

< >

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

参数

调用 HF API 以了解“我是谁”。

huggingface_hub.plan_multi_commits

< >

( operations: Iterable max_operations_per_commit: int = 50 max_upload_size_per_commit: int = 2147483648 ) Tuple[List[List[CommitOperationAdd]], List[List[CommitOperationDelete]]]

参数

  • operations (CommitOperation()List) — 要拆分为提交的操作列表。
  • max_operations_per_commit (int) — 单个提交中操作的最大数量。 默认为 50。
  • max_upload_size_per_commit (int) — 单个提交中要上传的最大大小(以字节为单位)。 默认为 2GB。 大于此限制的文件将上传,每次提交 1 个文件。

返回

Tuple[List[List[CommitOperationAdd]], List[List[CommitOperationDelete]]]

一个元组。 第一个项目是 CommitOperationAdd 列表的列表,表示要推送的添加提交。 第二个项目是 CommitOperationDelete 列表的列表,表示删除提交。

将操作列表拆分为要执行的提交列表。

实现遵循次优(但简单)的算法

  1. 删除操作按提交分组在一起,每个提交最多包含 max_operations_per_commits 个操作。
  2. 所有超过 max_upload_size_per_commit 的添加操作都将逐个提交。
  3. 所有剩余的添加操作都将分组在一起,并在每次达到 max_operations_per_commitmax_upload_size_per_commit 限制时进行拆分。

我们不尝试优化拆分以获得最少的提交次数,因为这是一个 NP 难问题(请参阅 装箱问题)。 对于我们的用例,使用次优解决方案没有问题,因此我们倾向于易于解释的实现。

plan_multi_commits 处于实验阶段。 其 API 和行为可能会在未来更改,恕不另行通知。

示例

>>> from huggingface_hub import HfApi, plan_multi_commits
>>> addition_commits, deletion_commits = plan_multi_commits(
...     operations=[
...          CommitOperationAdd(...),
...          CommitOperationAdd(...),
...          CommitOperationDelete(...),
...          CommitOperationDelete(...),
...          CommitOperationAdd(...),
...     ],
... )
>>> HfApi().create_commits_on_pr(
...     repo_id="my-cool-model",
...     addition_commits=addition_commits,
...     deletion_commits=deletion_commits,
...     (...)
...     verbose=True,
... )

不保证操作的初始顺序! 所有删除操作将在添加操作之前执行。 如果您没有多次更新同一个文件,那就没问题。

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], optional) — 用户在门控表单中填写的其他字段。

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

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) — Commit 哈希 ID。 示例:"91c54ad1727ee830252e457677f467be0bfd8a57"
  • pr_url (str, optional) — 已创建的 PR 的 URL(如果有)。 当传递 create_pr=True 时填充。
  • pr_revision (str, optional) — 已创建的 PR 的修订版本(如果有)。 当传递 create_pr=True 时填充。 示例:"refs/pr/1"
  • pr_num (int, optional) — 已创建的 PR 讨论的编号(如果有)。 当传递 create_pr=True 时填充。 可以在 get_discussion_details() 中作为 discussion_num 传递。 示例:1
  • repo_url (RepoUrl) — 提交的仓库 URL,包含 repo_id、repo_type 等信息。
  • _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) — 此特定修订版本的 Repo 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) — commit 的描述。这是一个由作者输入的自由文本值。
  • formatted_title (str) — commit 的标题,格式为 HTML。仅当设置了 formatted=True 时返回。
  • formatted_message (str) — commit 的描述,格式为 HTML。仅当设置了 formatted=True 时返回。

包含关于 Hub 上仓库的 git commit 的信息。请查看 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” refs 的信息。“Converts” 是(内部)用于在 Dataset 仓库中推送预处理数据的 refs。
  • tags (List[GitRefInfo]) — GitRefInfo 的列表,包含关于仓库标签的信息。
  • pull_requests (List[GitRefInfo], optional) — GitRefInfo 的列表,包含关于仓库拉取请求的信息。仅当设置了 include_prs=True 时返回。

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

对象由 list_repo_refs() 返回。

ModelInfo

class huggingface_hub.ModelInfo

< >

( **kwargs )

参数

  • id (str) — 模型的 ID。
  • author (str, optional) — 模型的作者(可选)。
  • sha (str, optional) — 此特定修订版本的仓库 SHA(可选)。
  • created_at (datetime, optional) — 仓库在 Hub 上创建的日期(可选)。请注意,最低值是 2022-03-02T23:29:04.000Z,对应于我们开始存储创建日期的日期。
  • last_modified (datetime, optional) — 仓库上次 commit 的日期(可选)。
  • private (bool) — 仓库是否为私有。
  • disabled (bool, optional) — 仓库是否被禁用(可选)。
  • downloads (int) — 该模型在过去 30 天内的下载次数。
  • downloads_all_time (int) — 该模型自创建以来的累计下载次数。
  • gated (Literal["auto", "manual", False], optional) — 仓库是否已设门控(gated)(可选)。如果是,则表示是手动批准还是自动批准。
  • gguf (Dict, optional) — 模型的 GGUF 信息(可选)。
  • inference (Literal["cold", "frozen", "warm"], optional) — 模型在 Inference API 上的状态(可选)。 Warm 模型可立即使用。Cold 模型将在首次推理调用时加载。Frozen 模型在 Inference API 中不可用。
  • 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 特定信息(auto class、processor 等)(可选)。
  • trending_score (int, 可选) — 模型的趋势分数。
  • card_data (ModelCardData, 可选) — 模型卡元数据,作为 huggingface_hub.repocard_data.ModelCardData 对象。
  • siblings (List[RepoSibling]) — 构成模型的 huggingface_hub.hf_api.RepoSibling 对象列表。
  • spaces (List[str], 可选) — 使用该模型的 Spaces 列表。
  • safetensors (SafeTensorsInfo, 可选) — 模型的 safetensors 信息。

包含关于 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, 可选) — 文件大小,以字节为单位。当 repo_info()files_metadata 参数设置为 True 时,此属性被定义。否则为 None
  • blob_id (str, 可选) — 文件的 git OID。当 repo_info()files_metadata 参数设置为 True 时,此属性被定义。否则为 None
  • lfs (BlobLfsInfo, 可选) — 文件的 LFS 元数据。当 repo_info()files_metadata 参数设置为 True 且文件使用 Git LFS 存储时,此属性被定义。否则为 None

包含关于 Hub 仓库内仓库文件的基本信息。

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

RepoFile

class huggingface_hub.hf_api.RepoFile

< >

( **kwargs )

参数

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

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

RepoUrl

class huggingface_hub.RepoUrl

< >

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

参数

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

引发

ValueError

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

RepoUrlHfApi.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: Optional sharded: bool weight_map: Dict files_metadata: Dict )

参数

  • 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: Dict tensors: Dict )

参数

  • 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, 可选) — 此特定修订版本的 Repo SHA。
  • created_at (datetime, 可选) — Repo 在 Hub 上创建的日期。请注意,最低值是 2022-03-02T23:29:04.000Z,对应于我们开始存储创建日期的日期。
  • last_modified (datetime, 可选) — Repo 上次提交的日期。
  • private (bool) — Repo 是否为私有。
  • gated (Literal["auto", "manual", False], 可选) — Repo 是否已门控。如果是,则表示是手动批准还是自动批准。
  • disabled (bool, 可选) — Space 是否被禁用。
  • host (str, 可选) — Space 的 Host URL。
  • subdomain (str, 可选) — Space 的子域名。
  • likes (int) — Space 的点赞数。
  • tags (List[str]) — Space 的标签列表。
  • siblings (List[RepoSibling]) — 构成 Space 的 huggingface_hub.hf_api.RepoSibling 对象列表。
  • card_data (SpaceCardData, 可选) — Space Card 元数据,作为 huggingface_hub.repocard_data.SpaceCardData 对象。
  • runtime (SpaceRuntime, 可选) — Space 运行时信息,作为 huggingface_hub.hf_api.SpaceRuntime 对象。
  • sdk (str, 可选) — Space 使用的 SDK。
  • models (List[str], 可选) — Space 使用的模型列表。
  • datasets (List[str], 可选) — Space 使用的数据集列表。
  • trending_score (int, 可选) — Space 的热度评分。

包含有关 Hub 上的 Space 的信息。

此类的多数属性是可选的。这是因为 Hub 返回的数据取决于发出的查询。一般来说,查询越具体,返回的信息就越多。相反,当使用 list_spaces() 列出 space 时,仅返回属性的子集。

TensorInfo

class huggingface_hub.utils.TensorInfo

< >

( dtype: Literal shape: List data_offsets: Tuple )

参数

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

关于张量的信息。

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

用户

class huggingface_hub.User

< >

( **kwargs )

参数

  • username (str) — Hub 上的用户名(唯一)。
  • fullname (str) — 用户的全名。
  • avatar_url (str) — 用户头像的 URL。
  • details (str, optional) — 用户的详细信息。
  • is_following (bool, optional) — 经过身份验证的用户是否正在关注此用户。
  • is_pro (bool, optional) — 用户是否为专业用户。
  • num_models (int, optional) — 用户创建的模型数量。
  • num_datasets (int, optional) — 用户创建的数据集数量。
  • num_spaces (int, optional) — 用户创建的 Spaces 数量。
  • num_discussions (int, optional) — 用户发起的讨论数量。
  • num_papers (int, optional) — 用户撰写的论文数量。
  • num_upvotes (int, optional) — 用户收到的赞同票数。
  • num_likes (int, optional) — 用户给出的点赞数。
  • num_following (int, optional) — 此用户正在关注的用户数量。
  • num_followers (int, optional) — 关注此用户的用户数量。
  • orgs (list of 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 上用户点赞的信息。

Webhook信息

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: Union )

参数

  • path_in_repo (str) — 仓库中的相对文件路径,例如: "checkpoints/1fec34a/weights.bin"
  • path_or_fileobj (str, Path, bytes, 或 BinaryIO) — 可以是:
    • 本地文件的路径 (strpathlib.Path 格式) 用于上传
    • 字节缓冲区 (bytes),包含要上传的文件内容
    • “文件对象” (io.BufferedIOBase 的子类),通常通过 open(path, "rb") 获得。它必须支持 seek()tell() 方法。

引发

ValueError

  • ValueError — 如果 path_or_fileobj 不是 str, Path, bytesio.BufferedIOBase 类型之一。
  • ValueError — 如果 path_or_fileobjstrPath 类型,但不是现有文件的路径。
  • ValueError — 如果 path_or_fileobjio.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: Union = 'auto' )

参数

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

数据结构,用于保存从 Hub 仓库中删除文件或文件夹的必要信息。

class huggingface_hub.CommitOperationCopy

< >

( src_path_in_repo: str path_in_repo: str src_revision: Optional = None )

参数

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

数据结构,用于保存将文件复制到 Hub 仓库的必要信息。

局限性

  • 只能复制 LFS 文件。要复制常规文件,您需要先在本地下载,然后再重新上传。
  • 不支持跨仓库复制。

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

CommitScheduler

class huggingface_hub.CommitScheduler

< >

( repo_id: str folder_path: Union every: Union = 5 path_in_repo: Optional = None repo_type: Optional = None revision: Optional = None private: bool = False token: Optional = None allow_patterns: Union = None ignore_patterns: Union = None squash_history: bool = False hf_api: Optional = None )

参数

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

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

调度器在实例化时启动并无限期运行。在脚本结束时,将触发最后一次提交。查看上传指南以了解有关如何使用它的更多信息。

示例

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

push_to_hub

< >

( )

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

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

push_to_hub 的默认行为是假定为仅追加文件夹。它列出文件夹中的所有文件,并仅上传更改的文件。如果未找到更改,则该方法返回,不提交任何内容。如果您想更改此行为,可以从 CommitScheduler 继承并重写此方法。例如,这对于在提交之前将数据压缩到一个文件中可能很有用。有关更多详细信息和示例,请查看我们的集成指南

stop

< >

( )

停止调度器。

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

trigger

< >

( )

触发 push_to_hub 并返回 future。

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

< > 在 GitHub 上更新