Hub 文档
Hub API 接口
并获得增强的文档体验
开始使用
Hub API 接口
我们有开放的接口,您可以使用它们从 Hub 中检索信息,以及执行某些操作,例如创建模型、数据集或 Space 仓库。我们提供了一个包装器 Python 库 huggingface_hub
,可以轻松访问这些接口。我们还提供了 webhooks 来接收关于仓库的实时增量信息。祝您使用愉快!
以下接口的基本 URL 是 https://huggingface.co
。例如,要构建下面的 `/api/models` 调用,可以调用 URL https://huggingface.co/api/models
Hub API Playground
想要尝试我们的 API 吗?现在就在我们的 Playground 上试用吧!
仓库列表 API
以下接口帮助获取存储在 Hub 上的模型、数据集和 Spaces 的信息。
createdAt
属性指示了相应仓库创建的时间。需要注意的是,对于在我们开始存储创建日期之前创建的所有仓库,都分配了一个唯一值 2022-03-02T23:29:04.000Z
。GET /api/models
获取 Hub 中所有模型的信息。响应是分页的,使用 Link
header 来获取下一页。您可以指定额外的参数以获得更具体的结果。
search
: 基于仓库及其用户名中的子字符串进行过滤,例如resnet
或microsoft
author
: 按作者或组织过滤模型,例如huggingface
或microsoft
filter
: 基于标签进行过滤,例如text-classification
或spacy
。sort
: 排序时使用的属性,例如downloads
或author
。direction
: 排序方向,例如-1
表示降序,任何其他值表示升序。limit
: 限制获取的模型数量。full
: 是否获取大多数模型数据,例如所有标签、文件等。config
: 是否也获取仓库配置。
负载
params = {
"search":"search",
"author":"author",
"filter":"filter",
"sort":"sort",
"direction":"direction",
"limit":"limit",
"full":"full",
"config":"config"
}
这等同于 huggingface_hub.list_models()
。
GET /api/models/{repo_id} 或 /api/models/{repo_id}/revision/{revision}
获取特定模型的所有信息。
这等同于 huggingface_hub.model_info(repo_id, revision)
。
GET /api/models-tags-by-type
获取 Hub 中托管的所有可用模型标签。
这等同于 huggingface_hub.get_model_tags()
。
GET /api/datasets
获取 Hub 中所有数据集的信息。响应是分页的,使用 Link
header 来获取下一页。您可以指定额外的参数以获得更具体的结果。
search
: 基于仓库及其用户名中的子字符串进行过滤,例如pets
或microsoft
author
: 按作者或组织过滤数据集,例如huggingface
或microsoft
filter
: 基于标签进行过滤,例如task_categories:text-classification
或languages:en
。sort
: 排序时使用的属性,例如downloads
或author
。direction
: 排序方向,例如-1
表示降序,任何其他值表示升序。limit
: 限制获取的数据集数量。full
: 是否获取大多数数据集数据,例如所有标签、文件等。
负载
params = {
"search":"search",
"author":"author",
"filter":"filter",
"sort":"sort",
"direction":"direction",
"limit":"limit",
"full":"full",
"config":"config"
}
这等同于 huggingface_hub.list_datasets()
。
GET /api/datasets/{repo_id} 或 /api/datasets/{repo_id}/revision/{revision}
获取特定数据集的所有信息。
full
: 是否获取大多数数据集数据,例如所有标签、文件等。
负载
params = {"full": "full"}
这等同于 huggingface_hub.dataset_info(repo_id, revision)
。
GET /api/datasets/{repo_id}/parquet
获取自动转换的 parquet 文件列表。
将 subset 和 split 追加到 URL 以获取特定 subset 和 split 的文件列表
GET /api/datasets/{repo_id}/parquet/{subset}
GET /api/datasets/{repo_id}/parquet/{subset}/{split}
GET /api/datasets/{repo_id}/parquet/{subset}/{split}/{n}.parquet
获取自动转换的 parquet 文件的第 n 个分片,针对特定的 subset(也称为 “config”)和 split。
GET /api/datasets/{repo_id}/croissant
获取 Croissant 元数据。更多详情请访问 https://huggingface.co/docs/datasets-server/croissant。
GET /api/datasets-tags-by-type
获取 Hub 中托管的所有可用数据集标签。
这等同于 huggingface_hub.get_dataset_tags()
。
GET /api/spaces
获取 Hub 中所有 Spaces 的信息。响应是分页的,使用 Link
header 获取下一页。您可以指定其他参数以获得更具体的结果。
search
: 基于仓库及其用户名中的子字符串进行过滤,例如resnet
或microsoft
author
: 按作者或组织过滤模型,例如huggingface
或microsoft
filter
: 基于标签进行过滤,例如text-classification
或spacy
。sort
: 排序时使用的属性,例如downloads
或author
。direction
: 排序方向,例如-1
表示降序,任何其他值表示升序。limit
: 限制获取的模型数量。full
: 是否获取大多数模型数据,例如所有标签、文件等。
负载
params = {
"search":"search",
"author":"author",
"filter":"filter",
"sort":"sort",
"direction":"direction",
"limit":"limit",
"full":"full",
"config":"config"
}
这等同于 huggingface_hub.list_spaces()
。
GET /api/spaces/{repo_id} 或 /api/spaces/{repo_id}/revision/{revision}
获取特定模型的所有信息。
这等同于 huggingface_hub.space_info(repo_id, revision)
。
Repo API
以下端点管理仓库设置,例如创建和删除仓库。
POST /api/repos/create
创建一个仓库。默认情况下是模型仓库。
参数
type
: 仓库类型(数据集或 Space;默认为模型)。name
: 仓库名称。organization
: 组织名称(可选)。private
: 仓库是否为私有。sdk
: 当类型为space
时 (streamlit, gradio, docker 或 static)
负载
payload = {
"type":"model",
"name":"name",
"organization": "organization",
"private":"private",
"sdk": "sdk"
}
这等同于 huggingface_hub.create_repo()
。
DELETE /api/repos/delete
删除一个仓库。默认情况下是模型仓库。
参数
type
: 仓库类型(数据集或 Space;默认为模型)。name
: 仓库名称。organization
: 组织名称(可选)。
负载
payload = {
"type": "model",
"name": "name",
"organization": "organization",
}
这等同于 huggingface_hub.delete_repo()
。
PUT /api/repos/{repo_type}/{repo_id}/settings
更新仓库可见性。
负载
payload = {
"private": "private",
}
这等同于 huggingface_hub.update_repo_settings()
。
POST /api/repos/move
移动仓库(在同一命名空间内重命名或从用户转移到组织)。
参数
fromRepo
: 要重命名的仓库。toRepo
: 仓库的新名称。type
: 仓库类型(数据集或 Space;默认为模型)。
负载
payload = {
"fromRepo" : "namespace/repo_name",
"toRepo" : "namespace2/repo_name2",
"type": "model",
}
这等同于 huggingface_hub.move_repo()
。
User API
以下端点获取有关用户的信息。
GET /api/whoami-v2
获取用户名和用户所属的组织。
负载
headers = { "authorization" : "Bearer $token" }
这等同于 huggingface_hub.whoami()
。
Organization API
以下端点获取组织成员列表。
GET /api/organizations/{organization_name}/members
获取组织成员。
负载
headers = { "authorization" : "Bearer $token" }
这等同于 huggingface_hub.list_organization_members()
。
Resource Groups API
以下端点管理资源组。资源组是一项企业功能。
GET /api/organizations/{name}/resource-groups
获取经过身份验证的用户有权查看的组织中的所有资源组。
GET /api/organizations/{name}/resource-groups/{resourceGroupId}
获取有关特定资源组的详细信息。
POST /api/organizations/{name}/resource-groups
在组织中创建一个新的资源组。
参数
name
: 资源组的名称(必填)description
: 资源组的描述(可选)users
: 资源组中的用户及其角色列表(可选)repos
: 仓库列表(可选)autoJoin
: 自动用户加入的设置(可选)
负载
payload = {
"name": "name",
"description": "description",
"users": [
{
"user": "username",
"role": "admin" // or "write" or "read"
}
],
"repos": [
{
"type": "dataset",
"name": "huggingface/repo"
}
]
}
PATCH /api/organizations/{name}/resource-groups/{resourceGroupId}
更新资源组的元数据。
参数
name
: 资源组的新名称(可选)description
: 资源组的新描述(可选)
负载
payload = {
"name": "name",
"description": "description"
}
POST /api/organizations/{name}/resource-groups/{resourceGroupId}/settings
更新资源组的设置。
负载
payload = {
"autoJoin": {
"enabled": true,
"role": "read" // or "write" or "admin"
}
}
DELETE /api/organizations/{name}/resource-groups/{resourceGroupId}
删除资源组。
POST /api/organizations/{name}/resource-groups/{resourceGroupId}/users
向资源组添加用户。
负载
payload = {
"users": [
{
"user": "username",
"role": "admin" // or "write" or "read"
}
]
}
DELETE /api/organizations/{name}/resource-groups/{resourceGroupId}/users/{username}
从资源组中移除用户。
PATCH /api/organizations/{name}/resource-groups/{resourceGroupId}/users/{username}
更新用户在资源组中的角色。
负载
payload = {
"role": "admin" // or "write" or "read"
}
POST /api/(models|spaces|datasets)/{namespace}/{repo}/resource-group
更新资源组的仓库。
负载
payload = {
"resourceGroupId": "6771d4700000000000000000" // (allow `null` for removing the repo's resource group)
}
GET /api/(models|spaces|datasets)/{namespace}/{repo}/resource-group
获取仓库的详细资源组信息
Paper Pages API
以下端点获取有关论文的信息。
GET /api/papers/{arxiv_id}
获取 Paper 页面的 API 等效项,即作者、摘要和讨论评论等元数据。
GET /api/arxiv/{arxiv_id}/repos
获取所有引用论文的模型、数据集和 Spaces。
GET /api/daily_papers
获取 AK 和社区策划的每日论文。它等同于 https://huggingface.co/papers。
Collections API
使用 Collections 在专用页面上对 Hub 中的仓库(模型、数据集、Spaces 和论文)进行分组。
您可以在 Collections 指南中了解更多信息。Collections 也可以使用 Python 客户端进行管理(请参阅 指南)。
POST /api/collections
在 Hub 上创建一个新的 collection,包含标题、描述(可选)和第一个项目(可选)。项目由类型(model
、dataset
、space
或 paper
)和 ID(Hub 上的 repo_id 或 paper_id)定义。
负载
payload = {
"title": "My cool models",
"namespace": "username_or_org",
"description": "Here is a shortlist of models I've trained.",
"item" : {
"type": "model",
"id": "username/cool-model",
}
"private": false,
}
这等同于 huggingface_hub.create_collection()
。
GET /api/collections/{namespace}/{slug}-{id}
返回有关 collection 的信息。
这等同于 huggingface_hub.get_collection()
。
GET /api/collections
根据某些条件列出 Hub 中的 collections。支持的参数是
owner
(string): 筛选由特定用户或组织创建的 collections。item
(string): 筛选包含特定项目的 collections。值必须是 item_type 和 item_id 的串联。示例:"models/teknium/OpenHermes-2.5-Mistral-7B"
、"datasets/rajpurkar/squad"
或"papers/2311.12983"
。sort
(string): 对返回的 collections 进行排序。支持的值为"lastModified"
、"trending"
(默认)和"upvotes"
。limit
(int): 每页的最大 collections 数量 (100)。q
(string): 基于标题和描述的子字符串进行筛选。
如果未设置任何参数,则返回所有 collections。
响应是分页的。要获取所有 collections,您必须遵循 Link
header。
列出 collections 时,每个 collection 的项目列表最多截断为 4 个项目。要检索 collection 中的所有项目,您需要使用其 collection slug 进行额外调用。
负载
params = {
"owner": "TheBloke",
"item": "models/teknium/OpenHermes-2.5-Mistral-7B",
"sort": "lastModified",
"limit" : 1,
}
这等同于 huggingface_hub.list_collections()
。
PATCH /api/collections/{namespace}/{slug}-{id}
更新 Hub 上 collection 的元数据。您不能使用此方法添加或修改 collection 的项目。有效负载的所有字段都是可选的。
负载
payload = {
"title": "My cool models",
"description": "Here is a shortlist of models I've trained.",
"private": false,
"position": 0, // position of the collection on your profile
"theme": "green",
}
这等同于 huggingface_hub.update_collection_metadata()
。
DELETE /api/collections/{namespace}/{slug}-{id}
返回一个集合。这是一个不可逆的操作。已删除的集合无法恢复。
这等同于 huggingface_hub.delete_collection()
。
POST /api/collections/{namespace}/{slug}-{id}/item
向集合添加一个条目。一个条目由类型(model
、dataset
、space
或 paper
)和 ID(Hub 上的 repo_id 或 paper_id)定义。也可以为条目附加注释(可选)。
负载
payload = {
"item" : {
"type": "model",
"id": "username/cool-model",
}
"note": "Here is the model I trained on ...",
}
这等同于 huggingface_hub.add_collection_item()
。
PATCH /api/collections/{namespace}/{slug}-{id}/items/{item_id}
更新集合中的一个条目。您必须知道条目的对象 ID,该 ID 与向集合添加条目时提供的 repo_id/paper_id 不同。item_id
可以通过获取集合来检索。
您可以更新附加到条目的注释或条目在集合中的位置。这两个字段都是可选的。
payload = {
"position": 0,
"note": "Here is the model I trained on ...",
}
这等同于 huggingface_hub.update_collection_item()
。
DELETE /api/collections/{namespace}/{slug}-{id}/items/{item_id}
从集合中移除一个条目。您必须知道条目的对象 ID,该 ID 与向集合添加条目时提供的 repo_id/paper_id 不同。item_id
可以通过获取集合来检索。
这等同于 huggingface_hub.delete_collection_item()
。