HfApi 客户端
以下是 HfApi
类的文档,它充当 Hugging Face Hub API 的 Python 封装器。
所有来自 HfApi
的方法也可以直接从包的根目录访问。下面详细介绍了这两种方法。
使用根方法更直接,但 HfApi 类为您提供更大的灵活性。 特别是,您可以传递一个令牌,该令牌将在所有 HTTP 调用中重复使用。 这与 huggingface-cli login
或 login() 不同,因为令牌不会持久保存在机器上。 也可以提供不同的端点或配置自定义用户代理。
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`, *可选*) — 要接受访问请求的仓库类型。 必须是
model
、dataset
或space
之一。 默认为model
。 - token (`Union[bool, str, None]`, *可选*) — 有效的用户访问令牌(字符串)。 默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。 要禁用身份验证,请传递 `False`。
引发
HTTPError
接受来自用户对给定受限仓库的访问请求。
一旦请求被接受,用户将能够下载仓库的任何文件并访问社区选项卡。 如果审批模式是自动的,您不必手动接受请求。 已接受的请求可以随时使用 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
向 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
< source >( 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
< source >( 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
< source >( 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。
-
RepositoryNotFoundError — 如果仓库不存在、是私有的或用户无权访问,则引发此错误。 如果
repo_id
或repo_type
不正确,或者仓库是私有的但用户未通过身份验证,则可能发生这种情况。 -
GatedRepoError — 如果仓库存在但已受限,且用户未被授权访问,则引发此错误。
检查提供的用户令牌是否有权访问 Hugging Face Hub 上的特定仓库。
此方法验证通过提供的令牌进行身份验证的用户是否有权访问指定的仓库。 如果未找到仓库,或者用户缺乏访问所需的权限,则该方法会引发相应的异常。
示例
检查用户是否有权访问仓库
>>> from huggingface_hub import auth_check
>>> from huggingface_hub.utils import GatedRepoError, RepositoryNotFoundError
try:
auth_check("user/my-cool-model")
except GatedRepoError:
# Handle gated repository error
print("You do not have permission to access this gated repository.")
except RepositoryNotFoundError:
# Handle repository not found error
print("The repository was not found or you do not have access.")
在此示例中
- 如果用户有权访问,该方法将成功完成。
- 如果仓库是受限的或不存在,将引发相应的异常,允许用户进行相应处理。
cancel_access_request
< source >( repo_id: str user: str repo_type: Optional[str] = None token: Union[bool, str, None] = None )
参数
- repo_id (
str
) — 要取消访问请求的仓库 ID。 - user (
str
) — 应该取消访问请求的用户的用户名。 - repo_type (
str
, 可选) — 要取消访问请求的仓库类型。必须是model
、dataset
或space
之一。默认为model
。 - token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
引发
HTTPError
取消用户对给定受限仓库的访问请求。
取消的请求将返回到待处理列表,并且用户将失去对仓库的访问权限。
有关受限仓库的更多信息,请参阅 https://huggingface.co/docs/hub/models-gated。
change_discussion_status
< source >( 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
。
状态更改事件
关闭或重新打开讨论或拉取请求。
示例
>>> 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
< source >( 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
。
新创建的评论
在给定的讨论中创建新评论。
示例
>>> 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
< source >( repo_id: str branch: str revision: Optional[str] = None token: Union[bool, str, None] = None repo_type: Optional[str] = None exist_ok: bool = False )
参数
- repo_id (
str
) — 将在其中创建分支的仓库。示例:"user/my-cool-model"
。 - branch (
str
) — 要创建的分支的名称。 - revision (
str
, 可选) — 从哪个 Git 版本创建分支。它可以是分支名称或提交的 OID/SHA,以十六进制字符串表示。默认为"main"
分支的头部。 - token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。 - repo_type (
str
, 可选) — 如果在数据集或 Space 上创建分支,则设置为"dataset"
或"space"
;如果标记模型,则设置为None
或"model"
。默认为None
。 - exist_ok (
bool
, 可选, 默认为False
) — 如果为True
,则在分支已存在时不要引发错误。
- RepositoryNotFoundError — 如果未找到仓库(错误 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
< source >( 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
create_commit
< source >( 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
ofCommitOperation()
) — 要包含在提交中的操作的可迭代对象,可以是以下之一:- CommitOperationAdd 以上传文件
- CommitOperationDelete 以删除文件
- CommitOperationCopy 以复制文件
操作对象将被修改以包含与上传相关的信息。请勿为多个提交重用相同的对象。
- commit_message (
str
) — 将要创建的提交的摘要(第一行)。 - commit_description (
str
, optional) — 将要创建的提交的描述 - token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。 - repo_type (
str
, optional) — 如果上传到数据集或 Space,则设置为"dataset"
或"space"
;如果上传到模型,则设置为None
或"model"
。默认为None
。 - revision (
str
, optional) — 从哪个 git 修订版本提交。默认为"main"
分支的头部。 - create_pr (
boolean
, optional) — 是否使用该提交创建拉取请求。默认为False
。如果未设置revision
,则针对"main"
分支打开 PR。如果设置了revision
并且是一个分支,则针对此分支打开 PR。如果设置了revision
并且不是分支名称(例如:提交 oid),则服务器返回RevisionNotFoundError
。 - num_threads (
int
, optional) — 用于上传文件的并发线程数。默认为 5。设置为 2 表示最多 2 个文件将并发上传。 - parent_commit (
str
, optional) — 父提交的 OID / SHA,作为十六进制字符串。也支持简写形式(前 7 个字符)。如果指定且create_pr
为False
,则当revision
未指向parent_commit
时,提交将失败。如果指定且create_pr
为True
,则将从parent_commit
创建拉取请求。指定parent_commit
可确保在提交更改之前仓库未发生更改,并且在仓库同时更新/提交时尤其有用。 - run_as_future (
bool
, optional) — 是否在后台运行此方法。后台作业按顺序运行,不会阻塞主线程。传递run_as_future=True
将返回一个 Future 对象。默认为False
。
返回
CommitInfo 或 Future
包含有关新创建的提交信息的 CommitInfo 实例(提交哈希值、提交 URL、PR URL、提交消息等)。如果传递了 run_as_future=True
,则返回一个 Future 对象,该对象将在执行时包含结果。
引发
ValueError
或 RepositoryNotFoundError
ValueError
— 如果提交消息为空。ValueError
— 如果父提交不是有效的提交 OID。ValueError
— 如果提交了带有无效元数据部分的 README.md 文件。在这种情况下,提交将提前失败,在尝试上传任何文件之前。ValueError
— 如果create_pr
为True
且 revision 既不是None
也不是"main"
。- RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type、私有但未通过身份验证或仓库不存在。
在给定的仓库中创建一个提交,根据需要删除和上传文件。
CommitOperation
的输入列表将在提交过程中被修改。请勿为多个提交重用相同的对象。
create_commit
假设仓库已存在于 Hub 上。如果您收到客户端错误 404,请确保您已通过身份验证,并且 repo_id
和 repo_type
设置正确。如果仓库不存在,请先使用 create_repo() 创建它。
create_commit
限制为 25k 个 LFS 文件和 1GB 的常规文件负载。
create_commits_on_pr
< source >( 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
ofList
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_id
和 repo_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
< source >( 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。
引发以下错误
HTTPError
如果 HuggingFace API 返回错误ValueError
如果某些参数值无效- RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在,或者因为它设置为
private
并且您无权访问。
create_inference_endpoint
< source >( 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
。
关于更新后的 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
< source >( 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() 的包装器。
引发以下错误
HTTPError
如果 HuggingFace API 返回错误ValueError
如果某些参数值无效- RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在,或者因为它设置为
private
并且您无权访问。
create_repo
< source >( 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 toFalse
) — 模型仓库是否应为私有。 - repo_type (
str
, optional) — 如果上传到数据集或 Space,则设置为"dataset"
或"space"
,如果上传到模型,则设置为None
或"model"
。 默认为None
。 - exist_ok (
bool
, optional, defaults toFalse
) — 如果为True
,则仓库已存在时不会引发错误。 - resource_group_id (
str
, optional) — 在其中创建仓库的资源组。 资源组仅适用于组织,并允许定义组织的哪些成员可以访问该资源。 资源组的 ID 可以在 Hub 上资源页面的 URL 中找到(例如,"66670e5163145ca562cb1988"
)。 要了解有关资源组的更多信息,请参阅 https://huggingface.co/docs/hub/en/security-resource-groups。 - space_sdk (
str
, optional) — 如果 repo_type 为 “space”,则选择要使用的 SDK。 可以是 “streamlit”、“gradio”、“docker” 或 “static”。 - space_hardware (
SpaceHardware
或str
, optional) — 如果 repo_type 为 “space”,则选择硬件。 有关完整列表,请参阅 SpaceHardware。 - space_storage (
SpaceStorage
或str
, optional) — 持久存储层选择。 示例:"small"
。 有关完整列表,请参阅 SpaceStorage。 - space_sleep_time (
int
, optional) — Space 进入休眠状态前等待的非活动秒数。 如果您不希望 Space 休眠,则设置为-1
(升级硬件的默认行为)。 对于免费硬件,您无法配置休眠时间(值固定为 48 小时非活动时间)。 有关更多详细信息,请参阅 https://huggingface.co/docs/hub/spaces-gpus#sleep-time。 - space_secrets (
List[Dict[str, str]]
, optional) — 要在您的 Space 中设置的密钥列表。 每个项目的格式为{"key": ..., "value": ..., "description": ...}
,其中 description 是可选的。 有关更多详细信息,请参阅 https://huggingface.co/docs/hub/spaces-overview#managing-secrets。 - space_variables (
List[Dict[str, str]]
, optional) — 要在您的 Space 中设置的公共环境变量列表。 每个项目采用{"key": ..., "value": ..., "description": ...}
的形式,其中 description 是可选的。 有关更多详细信息,请参阅 https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables。
返回
新创建的仓库的 URL。 值是 str
的子类,包含诸如 endpoint
、repo_type
和 repo_id
之类的属性。
在 HuggingFace Hub 上创建一个空仓库。
create_tag
< source >( 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
,则在标签已存在时不会引发错误。
- 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
。
返回
有关新创建的 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
。
数据集仓库信息。
获取 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
。
- 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
< source >( path_in_repo: str repo_id: str token: Union[str, bool, None] = None repo_type: Optional[str] = None revision: Optional[str] = None commit_message: Optional[str] = None commit_description: Optional[str] = None create_pr: Optional[bool] = None parent_commit: Optional[str] = None )
参数
- path_in_repo (
str
) — 仓库中的相对文件路径,例如:"checkpoints/1fec34a/weights.bin"
- repo_id (
str
) — 将从中删除文件的仓库,例如:"username/custom_transformers"
- token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。 默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。 要禁用身份验证,请传递
False
。 - repo_type (
str
, 可选) — 如果文件在数据集或 Space 中,则设置为"dataset"
或"space"
,如果文件在模型中,则设置为None
或"model"
。 默认为None
。 - revision (
str
, 可选) — 要从中提交的 git 修订版本。 默认为"main"
分支的头部。 - commit_message (
str
, 可选) — 生成的提交的摘要/标题/第一行。 默认为f"使用 huggingface_hub 删除 {path_in_repo}"
。 - commit_description (
str
可选) — 生成的提交的描述 - create_pr (
boolean
, 可选) — 是否使用该提交创建拉取请求。 默认为False
。 如果未设置revision
,则针对"main"
分支打开 PR。 如果设置了revision
并且是分支,则针对此分支打开 PR。 如果设置了revision
且不是分支名称(示例:提交 oid),则服务器将返回RevisionNotFoundError
。 - parent_commit (
str
, 可选) — 父提交的 OID / SHA,作为十六进制字符串。 也支持简写形式(前 7 个字符)。 如果指定且create_pr
为False
,则当revision
未指向parent_commit
时,提交将失败。 如果指定且create_pr
为True
,则将从parent_commit
创建拉取请求。 指定parent_commit
可确保在提交更改之前仓库未更改,并且在并发更新/提交仓库时尤其有用。
删除给定仓库中的文件。
引发以下错误
HTTPError
如果 HuggingFace API 返回错误ValueError
如果某些参数值无效- RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在,或者因为它设置为
private
并且您无权访问。 - RevisionNotFoundError 如果找不到要从中下载的修订版本。
- EntryNotFoundError 如果找不到要下载的文件。
delete_files
< source >( repo_id: str delete_patterns: List[str] token: Union[bool, str, None] = None repo_type: Optional[str] = None revision: Optional[str] = None commit_message: Optional[str] = None commit_description: Optional[str] = None create_pr: Optional[bool] = None parent_commit: Optional[str] = None )
参数
- repo_id (
str
) — 将从中删除文件夹的仓库,例如:"username/custom_transformers"
- delete_patterns (
List[str]
) — 要删除的文件或文件夹列表。 每个字符串可以是文件路径、文件夹路径或 Unix shell 风格的通配符。 例如:["file.txt", "folder/", "data/*.parquet"]
- token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。 默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。 要禁用身份验证,请传递
False
。 到存储的令牌。 - repo_type (
str
, 可选) — 要从中删除文件的仓库类型。 可以是"model"
、"dataset"
或"space"
。 默认为"model"
。 - revision (
str
, 可选) — 要从中提交的 git 修订版本。 默认为"main"
分支的头部。 - commit_message (
str
, 可选) — 生成的提交的摘要(第一行)。 默认为f"使用 huggingface_hub 删除文件"
。 - commit_description (
str
可选) — 生成的提交的描述。 - create_pr (
boolean
, 可选) — 是否使用该提交创建拉取请求。 默认为False
。 如果未设置revision
,则针对"main"
分支打开 PR。 如果设置了revision
并且是分支,则针对此分支打开 PR。 如果设置了revision
且不是分支名称(示例:提交 oid),则服务器将返回RevisionNotFoundError
。 - parent_commit (
str
, 可选) — 父提交的 OID / SHA,作为十六进制字符串。 也支持简写形式(前 7 个字符)。 如果指定且create_pr
为False
,则当revision
未指向parent_commit
时,提交将失败。 如果指定且create_pr
为True
,则将从parent_commit
创建拉取请求。 指定parent_commit
可确保在提交更改之前仓库未更改,并且在并发更新/提交仓库时尤其有用。
从 Hub 上的仓库中删除文件。
如果提供了文件夹路径,则整个文件夹及其包含的所有文件都将被删除。
delete_folder
< source >( 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_pr
为False
,则当revision
未指向parent_commit
时,提交将失败。如果指定且create_pr
为True
,则将从parent_commit
创建拉取请求。指定parent_commit
可确保在提交更改之前仓库未发生更改,并且在仓库并发更新/提交时尤其有用。
删除给定仓库中的文件夹。
围绕 create_commit() 方法的简单包装器。
delete_inference_endpoint
< source >( 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
< source >( 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 — 如果找不到要从中删除的仓库,并且
missing_ok
设置为 False(默认值)。
从 HuggingFace Hub 删除仓库。警告:此操作不可逆。
delete_space_secret
< source >( 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
< source >( 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
。
返回
关于 Space 的运行时信息,包括 Space 阶段和硬件。
引发
BadRequestError
BadRequestError
— 如果 Space 没有持久化存储。
删除 Space 的持久化存储。
delete_space_variable
< source >( 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
< source >( 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
。
- RepositoryNotFoundError — 如果未找到仓库(错误 404):错误的 repo_id/repo_type、私有但未通过身份验证或仓库不存在。
- RevisionNotFoundError — 如果未找到标签。
从 Hub 上的仓库中删除一个标签。
delete_webhook
< source >( 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。
disable_webhook
< source >( webhook_id: str token: Union[bool, str, None] = None ) → WebhookInfo
参数
- webhook_id (
str
) — 要禁用的 webhook 的唯一标识符。 - token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。 默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。 要禁用身份验证,请传递
False
。
返回
关于已禁用 webhook 的信息。
禁用一个 webhook(使其变为“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
< source >( 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 (
SpaceHardware
或str
, 可选) — 硬件选择。 示例:"t4-medium"
。 有关完整列表,请参阅 SpaceHardware。 - storage (
SpaceStorage
或str
, 可选) — 持久存储层级的选择。 示例:"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。
返回
新创建的仓库的 URL。 值是 str
的子类,包含诸如 endpoint
、repo_type
和 repo_id
之类的属性。
引发
RepositoryNotFoundError 或 HTTPError
- RepositoryNotFoundError — 如果找不到
from_id
或to_id
中的一个。 这可能是因为它不存在,或者因为它设置为private
并且您没有访问权限。 HTTPError
— 如果 HuggingFace API 返回错误
复制一个 Space。
以编程方式复制一个 Space。 新 Space 将在您的帐户中创建,并且状态将与原始 Space 相同(运行中或已暂停)。 无论 Space 的当前状态如何,您都可以复制 Space。
示例
>>> from huggingface_hub import duplicate_space
# Duplicate a Space to your account
>>> duplicate_space("multimodalart/dreambooth-training")
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)
# Can set custom destination id and visibility flag.
>>> duplicate_space("multimodalart/dreambooth-training", to_id="my-dreambooth", private=True)
RepoUrl('https://huggingface.co/spaces/nateraw/my-dreambooth',...)
edit_discussion_comment
< source >( 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
。
已编辑的评论
编辑 Discussion / Pull Request 上的评论。
引发以下错误
HTTPError
如果 HuggingFace API 返回错误ValueError
如果某些参数值无效- RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在,或者因为它设置为
private
并且您无权访问。
enable_webhook
< source >( webhook_id: str token: Union[bool, str, None] = None ) → WebhookInfo
参数
- webhook_id (
str
) — 要启用的 webhook 的唯一标识符。 - token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
关于已启用的 webhook 的信息。
启用 webhook(使其“激活”)。
示例
>>> from huggingface_hub import 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
< source >( 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 上的仓库中是否存在文件。
get_collection
< source >( 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_discussion_details
< source >( 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 的详细信息。
引发以下错误
HTTPError
如果 HuggingFace API 返回错误ValueError
如果某些参数值无效- RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在,或者因为它设置为
private
并且您无权访问。
get_full_repo_name
< source >( 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
< source >( 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
< source >( 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
。
关于请求的推理端点的信息。
获取有关推理端点的信息。
示例
>>> 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_paths_info
< source >( 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 toFalse
) — 是否获取有关路径的更多信息(例如,上次提交和文件的安全扫描结果)。此操作对服务器来说开销更大,因此每页仅返回 50 个结果(而不是 1000 个)。由于分页已在huggingface_hub
中实现,因此这对您来说是透明的,除了获取结果所需的时间。 - revision (
str
, optional) — 从中获取信息的仓库修订版本。默认为"main"
分支。 - repo_type (
str
, optional) — 从中获取信息的仓库类型 ("model"
,"dataset"
或"space"
)。默认为"model"
。 - token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
List[Union[RepoFile, RepoFolder]]
关于路径的信息,以 RepoFile
和 RepoFolder
对象的列表形式返回。
- RepositoryNotFoundError — 如果未找到仓库(错误 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
< source >( 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。
示例
get_safetensors_metadata
< source >( 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 仓库相关的信息。
引发
NotASafetensorsRepoError
或 SafetensorsParsingError
NotASafetensorsRepoError
— 如果仓库不是 safetensors 仓库,即没有model.safetensors
或model.safetensors.index.json
文件。SafetensorsParsingError
— 如果 safetensors 文件头无法正确解析。
解析 Hub 上 safetensors 仓库的元数据。
我们首先检查仓库是具有单个 safetensors 文件还是分片 safetensors 仓库。如果是单个 safetensors 文件,我们从此文件解析元数据。如果是分片 safetensors 仓库,我们从索引文件解析元数据,然后从每个分片解析元数据。
要从单个 safetensors 文件解析元数据,请使用 parse_safetensors_file_metadata()。
有关 safetensors 格式的更多详细信息,请查看 https://huggingface.co/docs/safetensors/index#format。
示例
# Parse repo with single weights file
>>> metadata = get_safetensors_metadata("bigscience/bloomz-560m")
>>> metadata
SafetensorsRepoMetadata(
metadata=None,
sharded=False,
weight_map={'h.0.input_layernorm.bias': 'model.safetensors', ...},
files_metadata={'model.safetensors': SafetensorsFileMetadata(...)}
)
>>> metadata.files_metadata["model.safetensors"].metadata
{'format': 'pt'}
# Parse repo with sharded model
>>> metadata = get_safetensors_metadata("bigscience/bloom")
Parse safetensors files: 100%|██████████████████████████████████████████| 72/72 [00:12<00:00, 5.78it/s]
>>> metadata
SafetensorsRepoMetadata(metadata={'total_size': 352494542848}, sharded=True, weight_map={...}, files_metadata={...})
>>> len(metadata.files_metadata)
72 # All safetensors files have been fetched
# Parse repo with sharded model
>>> get_safetensors_metadata("runwayml/stable-diffusion-v1-5")
NotASafetensorsRepoError: 'runwayml/stable-diffusion-v1-5' is not a safetensors repo. Couldn't find 'model.safetensors.index.json' or 'model.safetensors' files.
get_space_runtime
< source >( 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
。
返回
关于 Space 的运行时信息,包括 Space 阶段和硬件。
获取有关 Space 的运行时信息。
get_space_variables
< source >( 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
< source >( token: Union[bool, str, None] = None ) → Literal["read", "write", None]
参数
- token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
Literal["read", "write", None]
令牌授予的权限(“read”或“write”)。 如果未传递令牌或令牌无效,则返回 None
。
检查给定的 token
是否有效,并返回其权限。
有关令牌的更多详细信息,请参阅 https://huggingface.co/docs/hub/security-tokens#what-are-user-access-tokens。
get_user_overview
< source >( username: str token: Union[bool, str, None] = None ) → User
参数
- username (
str
) — 要获取概览的用户的用户名。 - token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
User
带有用户概览的 User 对象。
引发
HTTPError
HTTPError
— HTTP 404 如果 Hub 上不存在该用户。
获取 Hub 上用户的概览。
get_webhook
< source >( webhook_id: str token: Union[bool, str, None] = None ) → WebhookInfo
参数
- webhook_id (
str
) — 要获取的 webhook 的唯一标识符。 - token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
关于 webhook 的信息。
通过 ID 获取 webhook。
示例
>>> from huggingface_hub import get_webhook
>>> webhook = get_webhook("654bbbc16f2ec14d77f109cc")
>>> print(webhook)
WebhookInfo(
id="654bbbc16f2ec14d77f109cc",
watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
secret="my-secret",
domains=["repo", "discussion"],
disabled=False,
)
grant_access
< source >( repo_id: str user: str repo_type: Optional[str] = None token: Union[bool, str, None] = None )
参数
- repo_id (
str
) — 要授予访问权限的仓库 ID。 - user (
str
) — 要授予访问权限的用户的用户名。 - repo_type (
str
, 可选) — 要授予访问权限的仓库类型。必须是model
、dataset
或space
之一。默认为model
。 - token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
引发
HTTPError
授予用户对给定受限仓库的访问权限。
授予访问权限不需要用户自行发送访问请求。用户将自动添加到接受列表中,这意味着他们可以下载文件。您可以随时使用 cancel_access_request() 或 reject_access_request() 撤销已授予的访问权限。
有关受限仓库的更多信息,请参阅 https://huggingface.co/docs/hub/models-gated。
hf_hub_download
< source >( 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 (
str
或Path
, 可选) — 如果提供,下载的文件将放置在此目录下。 - 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
文件的本地路径;如果网络已关闭,则返回磁盘上缓存的文件的最新版本。
引发
RepositoryNotFoundError 或 RevisionNotFoundError 或 EntryNotFoundError 或 LocalEntryNotFoundError 或 EnvironmentError
或 OSError
或 ValueError
- RepositoryNotFoundError — 如果找不到要从中下载的仓库。这可能是因为它不存在,或者因为它设置为
private
且您没有访问权限。 - RevisionNotFoundError — 如果找不到要从中下载的修订版本。
- EntryNotFoundError — 如果找不到要下载的文件。
- LocalEntryNotFoundError — 如果网络已禁用或不可用,并且在缓存中找不到文件。
EnvironmentError
— 如果token=True
但找不到令牌。OSError
— 如果无法确定 ETag。ValueError
— 如果某些参数值无效。
如果本地缓存中尚不存在给定文件,则下载该文件。
新的缓存文件布局如下所示
- 缓存目录包含每个 repo_id 的一个子文件夹(按仓库类型命名空间)
- 在每个仓库文件夹内
- refs 是最新已知修订版本 => commit_hash 对的列表
- blobs 包含实际的文件 blobs(由其 git-sha 或 sha256 标识,具体取决于它们是否为 LFS 文件)
- snapshots 包含每个提交的子文件夹,每个“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
< source >( 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
。
隐藏的评论
隐藏讨论/拉取请求上的评论。
引发以下错误
HTTPError
如果 HuggingFace API 返回错误ValueError
如果某些参数值无效- RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在,或者因为它设置为
private
并且您无权访问。
like
< source >( 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 — 如果未找到仓库(错误 404):错误的 repo_id/repo_type、私有但未通过身份验证或仓库不存在。
点赞 Hub 上的给定仓库(例如,设置为收藏夹)。
另请参阅 unlike() 和 list_liked_repos()。
list_accepted_access_requests
< source >( repo_id: str repo_type: Optional[str] = None token: Union[bool, str, None] = None ) → List[AccessRequest]
参数
- repo_id (
str
) — 要获取访问请求的仓库 ID。 - 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[AccessRequest]
AccessRequest
对象的列表。 每次都包含 username
、email
、status
和 timestamp
属性。 如果受控仓库具有自定义表单,则 fields
属性将填充用户的答案。
引发
HTTPError
获取给定受控仓库的已接受访问请求。
“已接受请求”表示用户已请求访问该仓库,并且该请求已被接受。 用户可以下载仓库的任何文件。 如果审批模式为自动,则此列表默认应包含所有请求。 可以随时使用 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
< source >( 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]
orstr
, optional) — 按所有者的用户名筛选。 - item (
List[str]
orstr
, 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
< source >( 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
orIterable[str]
, optional) — 用于在 Hub 上筛选数据集的字符串或字符串列表。 - author (
str
, optional) — 用于标识返回数据集的作者的字符串。 - benchmark (
str
orList
, optional) — 可用于通过其官方基准测试在 Hub 上识别数据集的字符串或字符串列表。 - dataset_name (
str
, optional) — 可用于通过其名称(例如SQAC
或wikineural
)在 Hub 上识别数据集的字符串或字符串列表。 - gated (
bool
, optional) — 用于在 Hub 上筛选受控数据集或非受控数据集的布尔值。 默认情况下,返回所有数据集。 如果传递gated=True
,则仅返回受控数据集。 如果传递gated=False
,则仅返回非受控数据集。 - language_creators (
str
orList
, optional) — 可用于通过数据是如何策划的(例如crowdsourced
或machine_generated
)来识别 Hub 上数据集的字符串或字符串列表。 - language (
str
orList
, optional) — 表示双字符语言的字符串或字符串列表,用于在 Hub 上按语言筛选数据集。 - multilinguality (
str
orList
, optional) — 表示包含多种语言的数据集的筛选器的字符串或字符串列表。 - size_categories (
str
orList
, optional) — 可用于通过数据集大小(例如100K<n<1M
或1M<n<10M
)在 Hub 上识别数据集的字符串或字符串列表。 - tags (
str
orList
, optional) — 用于在 Hub 上筛选数据集的字符串标签或标签列表。 - task_categories (
str
orList
, optional) — 可用于通过设计的任务(例如audio_classification
或named_entity_recognition
)在 Hub 上识别数据集的字符串或字符串列表。 - task_ids (
str
或List
, 可选) — 一个字符串或字符串列表,可用于通过特定任务(例如speech_emotion_recognition
或paraphrase
)在 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_modified
、card_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")
list_inference_endpoints
< source >( 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
。
返回
给定命名空间的所有推理端点的列表。
列出给定命名空间的所有推理端点。
list_liked_repos
< source >( user: Optional[str] = None token: Union[bool, str, None] = None ) → UserLikes
参数
- user (
str
, 可选) — 您要获取点赞的用户的名称。 - token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
包含用户名和 3 个仓库 ID 列表(1 个用于模型,1 个用于数据集,1 个用于 Spaces)的对象。
引发
ValueError
ValueError
— 如果未传递user
且未找到令牌(来自参数或机器)。
列出 huggingface.co 上用户点赞的所有公共仓库。
此列表是公开的,因此令牌是可选的。如果未传递 user
,则默认为登录用户。
获取 huggingface.co 上所有指标的公共列表
list_models
< source >( filter: Union[str, Iterable[str], None] = None author: Optional[str] = None gated: Optional[bool] = None inference: Optional[Literal['cold', 'frozen', 'warm']] = None library: Optional[Union[str, List[str]]] = None language: Optional[Union[str, List[str]]] = None model_name: Optional[str] = None task: Optional[Union[str, List[str]]] = None trained_dataset: Optional[Union[str, List[str]]] = None tags: Optional[Union[str, List[str]]] = None search: Optional[str] = None pipeline_tag: Optional[str] = None emissions_thresholds: Optional[Tuple[float, float]] = None sort: Union[Literal['last_modified'], str, None] = None direction: Optional[Literal[-1]] = None limit: Optional[int] = None expand: Optional[List[ExpandModelProperty_T]] = None full: Optional[bool] = None cardData: bool = False fetch_config: bool = False token: Union[bool, str, None] = None ) → Iterable[ModelInfo]
参数
- filter (
str
或Iterable[str]
, 可选) — 用于在 Hub 上过滤模型的字符串或字符串列表。 - author (
str
, 可选) — 标识返回模型的作者(用户或组织)的字符串。 - gated (
bool
, 可选) — 用于在 Hub 上过滤门控模型或非门控模型的布尔值。默认情况下,返回所有模型。如果传递gated=True
,则仅返回门控模型。如果传递gated=False
,则仅返回非门控模型。 - inference (
Literal["cold", "frozen", "warm"]
, 可选) — 用于按模型在 Inference API 上的状态在 Hub 上过滤模型的字符串。Warm 模型可立即使用。Cold 模型将在首次推理调用时加载。Frozen 模型在 Inference API 中不可用。 - library (
str
或List
, 可选) — 模型最初训练的基础库的字符串或字符串列表,例如 pytorch、tensorflow 或 allennlp。 - language (
str
或List
, 可选) — 语言的字符串或字符串列表,包括名称和国家/地区代码,例如 “en” 或 “English” - model_name (
str
, 可选) — 包含 Hub 上模型的完整或部分名称的字符串,例如 “bert” 或 “bert-base-cased” - task (
str
或List
, 可选) — 模型设计的任务的字符串或字符串列表,例如:“fill-mask” 或 “automatic-speech-recognition” - trained_dataset (
str
或List
, 可选) — Hub 上模型的训练数据集的字符串标签或字符串标签列表。 - tags (
str
或List
, 可选) — 用于在 Hub 上按标签过滤模型的字符串标签或标签列表,例如text-generation
或spacy
。 - search (
str
, 可选) — 将包含在返回的模型 ID 中的字符串。 - pipeline_tag (
str
, 可选) — 用于在 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]
, 可选) — 要在响应中返回的属性列表。使用时,将仅返回列表中的属性。如果传递了full
、cardData
或fetch_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_modified
、sha
、文件和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 上托管的模型,可以根据一些过滤器进行过滤。
list_organization_members
< source >( organization: str token: Union[bool, str, None] = None ) → Iterable[User]
参数
- organization (
str
) — 要获取其成员的组织的名称。 - token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
Iterable[User]
包含组织成员的 User 对象列表。
引发
HTTPError
HTTPError
— HTTP 404 如果 Hub 上不存在该组织。
列出 Hub 上组织的成员。
list_papers
< source >( 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 上的每日论文。
list_pending_access_requests
< source >( repo_id: str repo_type: Optional[str] = None token: Union[bool, str, None] = None ) → List[AccessRequest]
参数
- repo_id (
str
) — 要获取访问请求的仓库 ID。 - repo_type (
str
, 可选) — 要获取访问请求的仓库类型。必须是model
、dataset
或space
之一。默认为model
。 - token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
List[AccessRequest]
AccessRequest
对象的列表。 每次都包含 username
、email
、status
和 timestamp
属性。 如果受控仓库具有自定义表单,则 fields
属性将填充用户的答案。
引发
HTTPError
获取给定 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
< source >( repo_id: str repo_type: Optional[str] = None token: Union[bool, str, None] = None ) → List[AccessRequest]
参数
- repo_id (
str
) — 要获取访问请求的仓库 ID。 - repo_type (
str
, 可选) — 要获取访问请求的仓库类型。必须是model
、dataset
或space
之一。默认为model
。 - token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
List[AccessRequest]
AccessRequest
对象的列表。 每次都包含 username
、email
、status
和 timestamp
属性。 如果受控仓库具有自定义表单,则 fields
属性将填充用户的答案。
引发
HTTPError
获取给定 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 上仓库提交信息的对象列表。
- 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
。
返回
包含有关 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 toFalse
) — 是否递归地列出树的文件和文件夹。 - expand (
bool
, optional, defaults toFalse
) — 是否获取关于树的文件和文件夹的更多信息(例如,上次提交和文件的安全扫描结果)。此操作对于服务器来说开销更大,因此每页仅返回 50 个结果(而不是 1000 个)。由于分页已在huggingface_hub
中实现,因此这对您是透明的,除了获取结果所需的时间。 - revision (
str
, optional) — 要从中获取树的仓库版本。默认为"main"
分支。 - repo_type (
str
, optional) — 要从中获取树的仓库类型 ("model"
,"dataset"
或"space"
)。默认为"model"
。 - token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
Iterable[Union[RepoFile, RepoFolder]]
关于树的文件和文件夹的信息,作为 RepoFile
和 RepoFolder
对象的可迭代对象。不保证文件和文件夹的顺序。
- RepositoryNotFoundError — 如果未找到仓库(错误 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
< source >( 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
orIterable
, optional) — 可用于在 Hub 上识别 Spaces 的字符串标签或标签列表。 - author (
str
, optional) — 用于标识返回的 Spaces 的作者的字符串。 - search (
str
, optional) — 将包含在返回的 Spaces 中的字符串。 - datasets (
str
orIterable
, optional) — 是否返回使用数据集的 Spaces。特定的数据集名称可以作为字符串传递。 - models (
str
orIterable
, optional) — 是否返回使用模型的 Spaces。特定的模型名称可以作为字符串传递。 - linked (
bool
, optional) — 是否返回使用模型或数据集的 Spaces。 - sort (
Literal["last_modified"]
orstr
, optional) — 用于对结果 Spaces 进行排序的键。可能的值是 huggingface_hub.hf_api.SpaceInfo` 类的属性。 - direction (
Literal[-1]
orint
, 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_modified
、siblings
和card_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
< source >( 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
< source >( 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
< source >( token: Union[bool, str, None] = None ) → List[WebhookInfo]
参数
- token (Union[bool, str, None], optional) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
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
< source >( 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
。
状态更改事件
合并拉取请求。
引发以下错误
HTTPError
如果 HuggingFace API 返回错误ValueError
如果某些参数值无效- RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在,或者因为它设置为
private
并且您无权访问。
model_info
< source >( 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) — 要在响应中返回的属性列表。使用后,将仅返回列表中的属性。如果传递了securityStatus
或files_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.co 上一个特定模型的信息
如果您传递可接受的令牌或已登录,模型可以是私有的。
引发以下错误
- RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在,或者因为它设置为
private
并且您无权访问。 - RevisionNotFoundError 如果找不到要从中下载的修订版本。
move_repo
< source >( 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
< source >( id: str ) → PaperInfo
获取 Hub 上论文的信息。
parse_safetensors_file_metadata
< source >( repo_id: str filename: str repo_type: Optional[str] = None revision: Optional[str] = None token: Union[bool, str, None] = None ) → SafetensorsFileMetadata
参数
- repo_id (
str
) — 用户或组织名称以及仓库名称,用/
分隔。 - filename (
str
) — 仓库中文件的名称。 - repo_type (
str
, 可选) — 如果文件位于数据集或 Space 中,则设置为"dataset"
或"space"
,如果位于模型中,则设置为None
或"model"
。默认为None
。 - revision (
str
, 可选) — 从中获取文件的 git 修订版本。可以是分支名称、标签或提交哈希值。默认为"main"
分支的头部。 - token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
SafetensorsFileMetadata
与 safetensors 文件相关的信息。
引发
NotASafetensorsRepoError
或 SafetensorsParsingError
NotASafetensorsRepoError
— 如果仓库不是 safetensors 仓库,即没有model.safetensors
或model.safetensors.index.json
文件。SafetensorsParsingError
— 如果 safetensors 文件头无法正确解析。
从 Hub 上的 safetensors 文件解析元数据。
要一次性解析仓库中所有 safetensors 文件的元数据,请使用 get_safetensors_metadata()。
有关 safetensors 格式的更多详细信息,请查看 https://huggingface.co/docs/safetensors/index#format。
pause_inference_endpoint
< source >( 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
。
关于已暂停的推理端点的信息。
暂停推理端点。
已暂停的推理端点将不会收费。可以使用 resume_inference_endpoint() 随时恢复。这与使用 scale_to_zero_inference_endpoint() 将推理端点缩放到零不同,后者会在收到请求时自动重启。
为方便起见,您还可以使用 pause_inference_endpoint() 暂停推理端点。
pause_space
< source >( repo_id: str token: Union[bool, str, None] = None ) → SpaceRuntime
参数
- repo_id (
str
) — 要暂停的 Space 的 ID。示例:"Salesforce/BLIP2"
。 - token (Union[bool, str, None], 可选) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
关于您的 Space 的运行时信息,包括 stage=PAUSED
和请求的硬件。
- RepositoryNotFoundError — 如果未找到您的 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
< source >( 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
< source >( repo_id: str user: str repo_type: Optional[str] = None token: Union[bool, str, None] = None )
参数
- repo_id (
str
) — 要拒绝访问请求的仓库 ID。 - user (
str
) — 应该拒绝访问请求的用户的用户名。 - repo_type (
str
, 可选) — 要拒绝访问请求的仓库类型。必须是model
、dataset
或space
之一。默认为model
。 - token (Union[bool, str, None], optional) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
引发
HTTPError
拒绝来自用户对给定门控仓库的访问请求。
被拒绝的请求将进入拒绝列表。用户无法下载仓库的任何文件。可以使用 accept_access_request() 和 cancel_access_request() 随时接受或取消被拒绝的请求。取消的请求将返回待处理列表,而接受的请求将进入接受列表。
有关受限仓库的更多信息,请参阅 https://huggingface.co/docs/hub/models-gated。
rename_discussion
< source >( 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
。
标题更改事件
重命名讨论。
示例
>>> 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
< source >( 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 上。
repo_info
< source >( 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_T
或ExpandDatasetProperty_T
或ExpandSpaceProperty_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.DatasetInfo、huggingface_hub.hf_api.ModelInfo 或 huggingface_hub.hf_api.SpaceInfo 对象。
获取给定类型的给定仓库的信息对象。
引发以下错误
- RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在,或者因为它设置为
private
并且您无权访问。 - RevisionNotFoundError 如果找不到要从中下载的修订版本。
request_space_hardware
< source >( repo_id: str hardware: SpaceHardware token: Union[bool, str, None] = None sleep_time: Optional[int] = None ) → SpaceRuntime
参数
- repo_id (
str
) — 要更新的仓库 ID。示例:"bigcode/in-the-stack"
。 - hardware (
str
或 SpaceHardware) — 运行 Space 的硬件。示例:"t4-medium"
。 - token (Union[bool, str, None], optional) — 一个有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。 - sleep_time (
int
, 可选) — 在 Space 进入休眠状态之前等待的不活动秒数。如果您不希望您的 Space 休眠,请设置为-1
(升级硬件的默认行为)。对于免费硬件,您无法配置休眠时间(该值固定为 48 小时不活动)。有关更多详细信息,请参阅 https://huggingface.co/docs/hub/spaces-gpus#sleep-time。
返回
关于 Space 的运行时信息,包括 Space 阶段和硬件。
为 Space 请求新硬件。
在创建 Space 仓库时也可以直接请求硬件!有关详细信息,请参阅 create_repo()。
request_space_storage
< source >( repo_id: str storage: SpaceStorage token: Union[bool, str, None] = None ) → SpaceRuntime
参数
- repo_id (
str
) — 要更新的 Space 的 ID。示例:"open-llm-leaderboard/open_llm_leaderboard"
。 - storage (
str
或 SpaceStorage) — 存储层级。可以是 ‘small’、‘medium’ 或 ‘large’。 - token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
关于 Space 的运行时信息,包括 Space 阶段和硬件。
为 Space 请求持久存储。
持久存储一旦被授予,就无法减少。要减少持久存储,您必须通过 delete_space_storage() 删除它。
restart_space
< source >( 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。
返回
关于您的 Space 的运行时信息。
- 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
< source >( 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
。
关于恢复的 Inference Endpoint 的信息。
恢复 Inference Endpoint。
为了方便起见,您还可以使用 InferenceEndpoint.resume() 恢复 Inference Endpoint。
revision_exists
< source >( 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 上仓库的特定修订版本是否存在。
run_as_future
< source >( fn: Callable[..., R] *args **kwargs ) → Future
在后台运行方法并返回 Future 实例。
主要目标是在不阻塞主线程的情况下运行方法(例如,在训练期间推送数据)。后台作业被排队以保持顺序,但不会并行运行。如果您需要通过并行化大量 API 调用来加速脚本,则必须设置和使用您自己的 ThreadPoolExecutor。
注意:最常用的方法,如 upload_file()、upload_folder() 和 create_commit(),都有一个 run_as_future: bool
参数,可以直接在后台调用它们。这等效于对它们调用 api.run_as_future(...)
,但更简洁。
scale_to_zero_inference_endpoint
< source >( 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
。
关于缩放至零的推理端点的信息。
将推理端点缩放至零。
缩放至零的推理端点将不会被收费。它将在下次请求时恢复,并带有冷启动延迟。这与使用 pause_inference_endpoint() 暂停推理端点不同,后者需要使用 resume_inference_endpoint() 手动恢复。
为了方便起见,您还可以使用 InferenceEndpoint.scale_to_zero() 将推理端点缩放至零。
set_space_sleep_time
< source >( repo_id: str sleep_time: int token: Union[bool, str, None] = None ) → SpaceRuntime
参数
- repo_id (
str
) — 要更新的仓库的 ID。 示例:"bigcode/in-the-stack"
。 - sleep_time (
int
, optional) — 在 Space 进入休眠状态之前等待的非活动秒数。如果您不希望您的 Space 暂停(升级硬件的默认行为),请设置为-1
。 对于免费硬件,您无法配置休眠时间(值固定为 48 小时的非活动时间)。 有关更多详细信息,请参阅 https://huggingface.co/docs/hub/spaces-gpus#sleep-time。 - token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。
返回
关于 Space 的运行时信息,包括 Space 阶段和硬件。
为在升级硬件上运行的 Space 设置自定义休眠时间。
您的 Space 将在 X 秒不活动后进入休眠状态。当您的 Space 处于“休眠”模式时,您不会被收费。如果新的访问者访问您的 Space,它将“唤醒”它。 只有升级的硬件才能配置休眠时间。要了解有关休眠阶段的更多信息,请参阅 https://huggingface.co/docs/hub/spaces-gpus#sleep-time。
在请求硬件时,也可以使用 request_space_hardware() 设置自定义休眠时间。
snapshot_download
< source >( repo_id: str repo_type: Optional[str] = None revision: Optional[str] = None cache_dir: Union[str, Path, None] = None local_dir: Union[str, Path, None] = None proxies: Optional[Dict] = None etag_timeout: float = 10 force_download: bool = False token: Union[bool, str, None] = None local_files_only: bool = False allow_patterns: Optional[Union[List[str], str]] = None ignore_patterns: Optional[Union[List[str], str]] = None max_workers: int = 8 tqdm_class: Optional[base_tqdm] = None local_dir_use_symlinks: Union[bool, Literal['auto']] = 'auto' resume_download: Optional[bool] = None ) → str
参数
- repo_id (
str
) — 用户或组织名称以及仓库名称,以/
分隔。 - repo_type (
str
, optional) — 如果从数据集或 Space 下载,则设置为"dataset"
或"space"
;如果从模型下载,则设置为None
或"model"
。 默认为None
。 - revision (
str
, optional) — 可选的 Git 修订版本 ID,可以是分支名称、标签或提交哈希值。 - cache_dir (
str
,Path
, optional) — 存储缓存文件的文件夹的路径。 - local_dir (
str
或Path
, optional) — 如果提供,下载的文件将放置在此目录下。 - proxies (
dict
, optional) — 字典,将协议映射到传递给requests.request
的代理 URL。 - etag_timeout (
float
, optional, defaults to10
) — 获取 ETag 时,在放弃之前等待服务器发送数据多少秒,该值将传递给requests.request
。 - force_download (
bool
, optional, defaults toFalse
) — 即使本地缓存中已存在该文件,是否应下载该文件。 - token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。默认为本地保存的令牌,这是推荐的身份验证方法(参见 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。要禁用身份验证,请传递
False
。 - local_files_only (
bool
, optional, defaults toFalse
) — 如果为True
,则避免下载文件,如果本地缓存文件中存在该文件,则返回该文件的路径。 - allow_patterns (
List[str]
或str
, optional) — 如果提供,则仅下载与至少一个模式匹配的文件。 - ignore_patterns (
List[str]
或str
, optional) — 如果提供,则不下载与任何模式匹配的文件。 - max_workers (
int
, optional) — 用于下载文件的并发线程数(1 个线程 = 1 个文件下载)。 默认为 8。 - tqdm_class (
tqdm
, optional) — 如果提供,则覆盖进度条的默认行为。传递的参数必须继承自tqdm.auto.tqdm
或至少模仿其行为。 请注意,tqdm_class
不会传递给每个单独的下载。默认为自定义 HF 进度条,可以通过设置HF_HUB_DISABLE_PROGRESS_BARS
环境变量来禁用。
返回
str
仓库快照的文件夹路径。
引发
RepositoryNotFoundError 或 RevisionNotFoundError 或 EnvironmentError
或 OSError
或 ValueError
- RepositoryNotFoundError — 如果找不到要从中下载的仓库。这可能是因为它不存在,或者因为它设置为
private
且您没有访问权限。 - RevisionNotFoundError — 如果找不到要从中下载的修订版本。
EnvironmentError
— 如果token=True
且找不到令牌。OSError
— 如果无法确定 ETag。ValueError
— 如果某些参数值无效。
下载仓库文件。
下载指定修订版本的仓库文件的完整快照。当您想要仓库中的所有文件时,这非常有用,因为您事先不知道您将需要哪些文件。所有文件都嵌套在一个文件夹中,以便保持其相对于该文件夹的实际文件名。您还可以使用 allow_patterns
和 ignore_patterns
过滤要下载的文件。
如果提供了 local_dir
,则仓库的文件结构将在此位置复制。使用此选项时,将不会使用 cache_dir
,并且将在 local_dir
的根目录中创建一个 .cache/huggingface/
文件夹,以存储一些与下载文件相关的元数据。虽然此机制不如主缓存系统那样强大,但它针对定期拉取仓库的最新版本进行了优化。
另一种方法是克隆仓库,但这需要安装并正确配置 git 和 git-lfs。使用 git 克隆仓库时,也无法过滤要下载的文件。
space_info
< source >( 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
。
返回
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 — 如果未找到仓库(错误 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 — 如果未找到仓库(错误 404):错误的 repo_id/repo_type、私有但未通过身份验证或仓库不存在。
取消喜欢 Hub 上的给定仓库(例如,从收藏列表中删除)。
另请参阅 like() 和 list_liked_repos()。
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
。
关于更新后的 Inference Endpoint 的信息。
更新推理端点。
此方法允许更新计算配置、部署的模型或两者兼而有之。 所有参数都是可选的,但必须至少提供一个。
为方便起见,您还可以使用 InferenceEndpoint.update() 更新推理端点。
update_repo_settings
< source >( 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"
。
引发
ValueError
或 HfHubHTTPError 或 RepositoryNotFoundError
ValueError
— 如果 gated 不是 “auto”、“manual” 或 False 之一。ValueError
— 如果 repo_type 不是 constants.REPO_TYPES 中的值之一。- HfHubHTTPError — 如果对 Hugging Face Hub API 的请求失败。
- RepositoryNotFoundError — 如果找不到要从中下载的仓库。这可能是因为它不存在,或者因为它设置为
private
且您没有访问权限。
更新仓库的设置,包括门控访问和可见性。
为了更好地控制仓库的使用方式,Hub 允许仓库作者为其仓库启用访问请求,并将仓库的可见性设置为私有。
update_repo_visibility
< source >( 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
< source >( 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
。
返回
关于更新后的 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
< source >( 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
, orIO
) — 本地计算机上的文件路径或二进制数据流/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_pr
为False
,则当revision
未指向parent_commit
时,提交将失败。如果指定且create_pr
为True
,则将从parent_commit
创建拉取请求。指定parent_commit
可确保在提交更改之前仓库未更改,并且在并发更新/提交仓库时特别有用。 - run_as_future (
bool
, optional) — 是否在后台运行此方法。后台作业按顺序运行,而不会阻塞主线程。传递run_as_future=True
将返回一个 Future 对象。默认为False
。
返回
CommitInfo 或 Future
包含有关新创建的提交信息的 CommitInfo 实例(提交哈希值、提交 URL、PR URL、提交消息等)。如果传递了 run_as_future=True
,则返回一个 Future 对象,该对象将在执行时包含结果。
将本地文件(最大 50 GB)上传到给定的仓库。上传通过 HTTP post 请求完成,不需要安装 git 或 git-lfs。
引发以下错误
HTTPError
如果 HuggingFace API 返回错误ValueError
如果某些参数值无效- RepositoryNotFoundError 如果找不到要从中下载的仓库。这可能是因为它不存在,或者因为它设置为
private
并且您无权访问。 - RevisionNotFoundError 如果找不到要从中下载的修订版本。
upload_file
假设仓库已存在于 Hub 上。如果您收到客户端错误 404,请确保您已通过身份验证,并且 repo_id
和 repo_type
设置正确。如果仓库不存在,请先使用 create_repo() 创建它。
示例
>>> from huggingface_hub import upload_file
>>> with open("./local/filepath", "rb") as fobj:
... upload_file(
... path_or_fileobj=fileobj,
... path_in_repo="remote/file/path.h5",
... repo_id="username/my-dataset",
... repo_type="dataset",
... token="my_token",
... )
"https://huggingface.co/datasets/username/my-dataset/blob/main/remote/file/path.h5"
>>> upload_file(
... path_or_fileobj=".\\local\\file\\path",
... path_in_repo="remote/file/path.h5",
... repo_id="username/my-model",
... token="my_token",
... )
"https://huggingface.co/username/my-model/blob/main/remote/file/path.h5"
>>> upload_file(
... path_or_fileobj=".\\local\\file\\path",
... path_in_repo="remote/file/path.h5",
... repo_id="username/my-model",
... token="my_token",
... create_pr=True,
... )
"https://huggingface.co/username/my-model/blob/refs%2Fpr%2F1/remote/file/path.h5"
upload_folder
< source >( 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
orPath
) — 要上传的本地文件系统上的文件夹路径 - 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_commits
和create_pr
都为 True,则在多提交过程中创建的 PR 将保持打开状态。 - parent_commit (
str
, 可选) — 父提交的 OID / SHA,作为十六进制字符串。 也支持简写形式(前 7 个字符)。 如果指定且create_pr
为False
,则当revision
未指向parent_commit
时,提交将失败。 如果指定且create_pr
为True
,则将从parent_commit
创建拉取请求。 指定parent_commit
可确保在提交更改之前仓库未发生更改,并且在仓库同时更新/提交时特别有用。 - allow_patterns (
List[str]
或str
, 可选) — 如果提供,则仅上传与至少一个模式匹配的文件。 - ignore_patterns (
List[str]
或str
, 可选) — 如果提供,则不上传与任何模式匹配的文件。 - delete_patterns (
List[str]
或str
, 可选) — 如果提供,则在提交新文件时,将从仓库中删除与任何模式匹配的远程文件。 如果您不知道哪些文件已被上传,这将非常有用。 注意:为避免差异,即使.gitattributes
文件与模式匹配也不会被删除。 - 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
。
返回
CommitInfo 或 Future
CommitInfo 的实例,其中包含有关新创建的提交的信息(提交哈希值、提交 URL、PR URL、提交消息等)。 如果传递了 run_as_future=True
,则返回一个 Future 对象,其中将包含执行时的结果。 str
或 Future
:如果 multi_commits=True
,则返回为推送更改而创建的 PR 的 URL。 如果传递了 run_as_future=True
,则返回一个 Future 对象,其中将包含执行时的结果。
将本地文件夹上传到给定的仓库。 上传通过 HTTP 请求完成,不需要安装 git 或 git-lfs。
文件夹的结构将被保留。 仓库中已存在的同名文件将被覆盖。 其他文件将保持不变。
使用 allow_patterns
和 ignore_patterns
参数来指定要上传的文件。 这些参数接受单个模式或模式列表。 模式是标准通配符(globbing 模式),如 此处 所述。 如果同时提供了 allow_patterns
和 ignore_patterns
,则两个约束都适用。 默认情况下,将上传文件夹中的所有文件。
使用 delete_patterns
参数来指定要删除的远程文件。 输入类型与 allow_patterns
相同(见上文)。 如果还提供了 path_in_repo
,则模式将与相对于此文件夹的路径进行匹配。 例如,upload_folder(..., path_in_repo="experiment", delete_patterns="logs/*")
将删除 ./experiment/logs/
下的任何远程文件。 请注意,即使 .gitattributes
文件与模式匹配也不会被删除。
任何子目录中存在的任何 .git/
文件夹都将被忽略。 但是,请注意,.gitignore
文件不考虑在内。
在底层使用 HfApi.create_commit
。
引发以下错误
HTTPError
如果 HuggingFace API 返回错误ValueError
如果某些参数值无效
upload_folder
假定仓库已在 Hub 上存在。 如果您收到客户端错误 404,请确保您已通过身份验证,并且 repo_id
和 repo_type
设置正确。 如果仓库不存在,请先使用 create_repo() 创建它。
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
< source >( 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 (
str
或Path
) — 要上传的本地文件系统上的文件夹路径。 - 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/
下的文件夹中,以便在中断后能够恢复该过程。整个过程可能会产生多次提交。
需要记住的几件事
- 仓库限制仍然适用:https://huggingface.co/docs/hub/repositories-recommendations
- 不要并行启动多个进程。
- 您可以随时中断和恢复该过程。
- 不要将同一个文件夹上传到多个仓库。如果需要这样做,必须先删除本地
.cache/.huggingface/
文件夹。
虽然 upload_large_folder
在上传大型文件夹时更加稳健,但在功能方面,它比 upload_folder() 更受限制。 实际上:
- 您无法设置自定义的
path_in_repo
。 如果要上传到子文件夹,则需要在本地设置正确的结构。 - 您无法设置自定义的
commit_message
和commit_description
,因为会创建多次提交。 - 上传时无法从仓库中删除内容。请先进行单独的提交。
- 您无法直接创建 PR。 请先创建 PR(从 UI 或使用 create_pull_request()),然后通过传递
revision
来提交到 PR。
技术细节
upload_large_folder
进程如下:
- (检查参数和设置。)
- 如果仓库不存在,则创建仓库。
- 列出要上传的本地文件。
- 启动 worker。Worker 可以执行以下任务:
- 哈希文件。
- 获取文件列表的上传模式(常规或 LFS)。
- 预上传 LFS 文件。
- 提交一批文件。一旦 worker 完成一项任务,它将根据优先级列表(见下文)移动到下一个任务,直到所有文件都已上传和提交。
- 在 worker 运行时,定期向 sys.stdout 打印报告。
优先级顺序
- 如果距离上次提交尝试超过 5 分钟(且至少有 1 个文件),则提交。
- 如果至少有 150 个文件准备好提交,则提交。
- 如果至少有 10 个文件已哈希,则获取上传模式。
- 如果至少有 1 个文件且没有 worker 正在预上传,则预上传 LFS 文件。
- 如果至少有 1 个文件且没有 worker 正在哈希,则哈希文件。
- 如果至少有 1 个文件且没有 worker 正在获取上传模式,则获取上传模式。
- 如果至少有 1 个文件,则预上传 LFS 文件(例外:如果启用了 hf_transfer,则一次只能有 1 个 worker 预上传 LFS)。
- 如果至少有 1 个文件要哈希,则哈希文件。
- 如果至少有 1 个文件要获取上传模式,则获取上传模式。
- 如果至少有 1 个文件要提交且距离上次提交尝试至少 1 分钟,则提交。
- 如果至少有 1 个文件要提交且所有其他队列都为空,则提交。
特殊规则
- 如果启用了
hf_transfer
,则一次只能有 1 个 LFS 上传器。 否则,CPU 将被hf_transfer
占用过多。 - 一次只能有一个 worker 可以提交。
- 如果没有可用任务,worker 将等待 10 秒钟,然后再重新检查。
whoami
< source >( token: Union[bool, str, None] = None )
参数
- token (Union[bool, str, None], optional) — 有效的用户访问令牌(字符串)。 默认为本地保存的令牌,这是推荐的身份验证方法(请参阅 https://huggingface.co/docs/huggingface_hub/quick-start#authentication)。 要禁用身份验证,请传递
False
。
调用 HF API 以了解“我是谁”。
huggingface_hub.plan_multi_commits
< source >( 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
列表的列表,表示删除提交。
将操作列表拆分为要执行的提交列表。
实现遵循次优(但简单)的算法
- 删除操作按提交分组在一起,每个提交最多包含
max_operations_per_commits
个操作。 - 所有超过
max_upload_size_per_commit
的添加操作都将逐个提交。 - 所有剩余的添加操作都将分组在一起,并在每次达到
max_operations_per_commit
或max_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
< source >( 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
< source >( *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
< source >( **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
< source >( name: str ref: str target_commit: str )
包含关于 Hub 上仓库的 git 引用的信息。
GitCommitInfo
class huggingface_hub.GitCommitInfo
< source >( 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
< source >( 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
< source >( **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
ValueError
— 如果 URL 无法解析。ValueError
— 如果repo_type
未知。
str
的子类,描述 Hub 上的仓库 URL。
RepoUrl
由 HfApi.create_repo
返回。它继承自 str
以实现向后兼容性。在初始化时,URL 被解析以填充属性
- endpoint (
str
) - namespace (
Optional[str]
) - repo_name (
str
) - repo_id (
str
) - repo_type (
Literal["model", "dataset", "space"]
) - url (
str
)
示例
>>> RepoUrl('https://huggingface.co/gpt2')
RepoUrl('https://huggingface.co/gpt2', endpoint='https://huggingface.co', repo_type='model', repo_id='gpt2')
>>> RepoUrl('https://hub-ci.huggingface.co/datasets/dummy_user/dummy_dataset', endpoint='https://hub-ci.huggingface.co')
RepoUrl('https://hub-ci.huggingface.co/datasets/dummy_user/dummy_dataset', endpoint='https://hub-ci.huggingface.co', repo_type='dataset', repo_id='dummy_user/dummy_dataset')
>>> RepoUrl('hf://datasets/my-user/my-dataset')
RepoUrl('hf://datasets/my-user/my-dataset', endpoint='https://huggingface.co', repo_type='dataset', repo_id='user/dataset')
>>> HfApi.create_repo("dummy_model")
RepoUrl('https://huggingface.co/Wauplin/dummy_model', endpoint='https://huggingface.co', repo_type='model', repo_id='Wauplin/dummy_model')
SafetensorsRepoMetadata
class huggingface_hub.utils.SafetensorsRepoMetadata
< 源代码 >( metadata: 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
< source >( metadata: Dict tensors: Dict )
Hub 上托管的 Safetensors 文件的元数据。
此类由 parse_safetensors_file_metadata() 返回。
有关 safetensors 格式的更多详细信息,请查看 https://huggingface.co/docs/safetensors/index#format。
SpaceInfo
class huggingface_hub.SpaceInfo
< source >( **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
< source >( dtype: Literal shape: List data_offsets: Tuple )
关于张量的信息。
有关 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] )
包含关于 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
< source >( type: Literal['dataset', 'model', 'org', 'space', 'user'] name: str )
包含有关 webhook 监视的条目的信息的数据结构。
CommitOperation
以下是 CommitOperation()
支持的值
class huggingface_hub.CommitOperationAdd
< source >( path_in_repo: str path_or_fileobj: Union )
参数
- path_in_repo (
str
) — 仓库中的相对文件路径,例如:"checkpoints/1fec34a/weights.bin"
- path_or_fileobj (
str
,Path
,bytes
, 或BinaryIO
) — 可以是:- 本地文件的路径 (
str
或pathlib.Path
格式) 用于上传 - 字节缓冲区 (
bytes
),包含要上传的文件内容 - “文件对象” (
io.BufferedIOBase
的子类),通常通过open(path, "rb")
获得。它必须支持seek()
和tell()
方法。
- 本地文件的路径 (
引发
ValueError
ValueError
— 如果path_or_fileobj
不是str
,Path
,bytes
或io.BufferedIOBase
类型之一。ValueError
— 如果path_or_fileobj
是str
或Path
类型,但不是现有文件的路径。ValueError
— 如果path_or_fileobj
是io.BufferedIOBase
类型,但它不支持seek()
和tell()
方法。
数据结构,用于保存将文件上传到 Hub 仓库的必要信息。
as_file
< source >( with_tqdm: bool = False )
一个上下文管理器,它产生一个类文件对象,允许读取 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]
class huggingface_hub.CommitOperationDelete
< source >( path_in_repo: str is_folder: Union = 'auto' )
数据结构,用于保存从 Hub 仓库中删除文件或文件夹的必要信息。
class huggingface_hub.CommitOperationCopy
< source >( src_path_in_repo: str path_in_repo: str src_revision: Optional = None )
数据结构,用于保存将文件复制到 Hub 仓库的必要信息。
局限性
- 只能复制 LFS 文件。要复制常规文件,您需要先在本地下载,然后再重新上传。
- 不支持跨仓库复制。
注意:您可以组合使用 CommitOperationCopy 和 CommitOperationDelete 来重命名 Hub 上的 LFS 文件。
CommitScheduler
class huggingface_hub.CommitScheduler
< source >( 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 (
str
或Path
) — 要定期上传的本地文件夹的路径。 - every (
int
或float
, 可选) — 每次提交之间间隔的分钟数。默认为 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")
将文件夹推送到 Hub 并返回提交信息。
此方法不应直接调用。它由调度器在后台运行,并遵循队列机制以避免并发提交。直接调用此方法可能会导致并发问题。
push_to_hub
的默认行为是假定为仅追加文件夹。它列出文件夹中的所有文件,并仅上传更改的文件。如果未找到更改,则该方法返回,不提交任何内容。如果您想更改此行为,可以从 CommitScheduler 继承并重写此方法。例如,这对于在提交之前将数据压缩到一个文件中可能很有用。有关更多详细信息和示例,请查看我们的集成指南。
触发 push_to_hub
并返回 future。
此方法每 every
分钟自动调用一次。您也可以手动调用它以立即触发提交,而无需等待下一次计划的提交。