Hugging Face 的徽标

数据集查看器文档

快速入门

Hugging Face's logo
加入 Hugging Face 社区

并获得增强型文档体验

开始

快速入门

在本快速入门中，您将学习如何使用数据集查看器的 REST API 来

  • 检查中心上的数据集是否正常工作。
  • 返回数据集的子集和拆分。
  • 预览数据集的前 100 行。
  • 下载数据集的行切片。
  • 在数据集中搜索一个词。
  • 根据查询字符串过滤行。
  • 将数据集作为 parquet 文件访问。
  • 获取数据集大小（以行数或字节数表示）。
  • 获取有关数据集的统计信息。

API 端点

每个功能都通过一个端点提供服务，这些端点在下面的表格中进行了总结

端点 方法 描述 查询参数
/is-valid GET 检查特定数据集是否有效。 dataset: 数据集的名称
/splits GET 获取数据集的子集和拆分列表。 dataset: 数据集的名称
/first-rows GET 获取数据集拆分的第一行。 - dataset: 数据集的名称
- config: 配置的名称
- split: 拆分的名称
/rows GET 获取数据集拆分的行切片。 - dataset: 数据集的名称
- config: 配置的名称
- split: 拆分的名称
- offset: 切片的偏移量
- length: 切片的长度（最大 100）
/search GET 在数据集拆分中搜索文本。 - dataset: 数据集的名称
- config: 配置的名称
- split: 拆分的名称
- query: 要搜索的文本
/filter GET 过滤数据集拆分中的行。 - dataset: 数据集的名称
- config: 配置的名称
- split: 拆分的名称
- where: 过滤查询
- orderby: 排序子句
- offset: 切片的偏移量
- length: 切片的长度（最大 100）
/parquet GET 获取数据集的 parquet 文件列表。 dataset: 数据集的名称
/size GET 获取数据集的大小。 dataset: 数据集的名称
/statistics GET 获取有关数据集拆分的统计信息。 - dataset: 数据集的名称
- config: 配置的名称
- split: 拆分的名称
/croissant GET 获取有关数据集的 Croissant 元数据。 - dataset: 数据集的名称

使用数据集查看器 API 不需要安装或设置。

如果您还没有，请注册一个 Hugging Face 帐户！虽然您可以在没有 Hugging Face 帐户的情况下使用数据集查看器 API，但您将无法访问 受限数据集，例如 CommonVoice 和 ImageNet，除非您提供 用户令牌，您可以在用户设置中找到该令牌。

请随时在 Postman、ReDoc 或 RapidAPI 中试用 API。本快速入门将向您展示如何以编程方式查询端点。

REST API 的基本 URL 为

https://datasets-server.huggingface.co

私有和受限数据集

对于 私有 和 受限 数据集，您需要在查询的 headers 中提供您的用户令牌。否则，您将收到一条错误消息，要求您重新进行身份验证。

数据集查看器支持由 PRO 用户 或 企业中心组织 拥有的私有数据集。

Python
JavaScript
cURL
import requests
headers = {"Authorization": f"Bearer {API_TOKEN}"}
API_URL = "https://datasets-server.huggingface.co/is-valid?dataset=allenai/WildChat-nontoxic"
def query():
    response = requests.get(API_URL, headers=headers)
    return response.json()
data = query()

如果您尝试访问受限数据集而不提供您的用户令牌，您将看到以下错误

print(data)
{'error': 'The dataset does not exist, or is not accessible without authentication (private or gated). Please check the spelling of the dataset name or retry with authentication.'}

检查数据集有效性

要检查特定数据集是否有效，例如，烂番茄，请使用 /is-valid 端点

Python
JavaScript
cURL
import requests
API_URL = "https://datasets-server.huggingface.co/is-valid?dataset=cornell-movie-review-data/rotten_tomatoes"
def query():
    response = requests.get(API_URL)
    return response.json()
data = query()

此方法返回数据集是否提供预览（参见 /first-rows）、查看器（参见 /rows）、搜索（参见 /search）、过滤器（参见 /filter）和统计信息（参见 /statistics）。

{ "preview": true, "viewer": true, "search": true, "filter": true, "statistics": true }

列出配置和拆分

/splits 端点返回数据集中的拆分 JSON 列表。

Python
JavaScript
cURL
import requests
API_URL = "https://datasets-server.huggingface.co/splits?dataset=cornell-movie-review-data/rotten_tomatoes"
def query():
    response = requests.get(API_URL)
    return response.json()
data = query()

此方法返回数据集中的可用子集和拆分。

{
  "splits": [
    { "dataset": "cornell-movie-review-data/rotten_tomatoes", "config": "default", "split": "train" },
    {
      "dataset": "cornell-movie-review-data/rotten_tomatoes",
      "config": "default",
      "split": "validation"
    },
    { "dataset": "cornell-movie-review-data/rotten_tomatoes", "config": "default", "split": "test" }
  ],
  "pending": [],
  "failed": []
}

预览数据集

/first-rows 端点返回数据集前 100 行的 JSON 列表。它还返回数据特征（“列”数据类型）的类型。您应该指定要预览的数据集名称、子集名称（您可以在 /splits 端点找到子集名称）和拆分名称。

Python
JavaScript
cURL
import requests
API_URL = "https://datasets-server.huggingface.co/first-rows?dataset=cornell-movie-review-data/rotten_tomatoes&config=default&split=train"
def query():
    response = requests.get(API_URL)
    return response.json()
data = query()

此方法返回数据集的前 100 行。

{
  "dataset": "cornell-movie-review-data/rotten_tomatoes",
  "config": "default",
  "split": "train",
  "features": [
    {
      "feature_idx": 0,
      "name": "text",
      "type": { "dtype": "string", "_type": "Value" }
    },
    {
      "feature_idx": 1,
      "name": "label",
      "type": { "names": ["neg", "pos"], "_type": "ClassLabel" }
    }
  ],
  "rows": [
    {
      "row_idx": 0,
      "row": {
        "text": "the rock is destined to be the 21st century's new \" conan \" and that he's going to make a splash even greater than arnold schwarzenegger , jean-claud van damme or steven segal .",
        "label": 1
      },
      "truncated_cells": []
    },
    {
      "row_idx": 1,
      "row": {
        "text": "the gorgeously elaborate continuation of \" the lord of the rings \" trilogy is so huge that a column of words cannot adequately describe co-writer/director peter jackson's expanded vision of j . r . r . tolkien's middle-earth .",
        "label": 1
      },
      "truncated_cells": []
    },
    ...,
    ...
  ]
}

下载数据集片段

/rows 端点返回数据集在任何给定位置（偏移量）的片段行 JSON 列表。它还返回数据特征（“列”数据类型）的类型。您应该指定数据集名称、子集名称（您可以在 /splits 端点找到子集名称）、拆分名称以及要下载的片段的偏移量和长度。

Python
JavaScript
cURL
import requests
API_URL = "https://datasets-server.huggingface.co/rows?dataset=cornell-movie-review-data/rotten_tomatoes&config=default&split=train&offset=150&length=10"
def query():
    response = requests.get(API_URL)
    return response.json()
data = query()

您每次最多可以下载 100 行片段。

响应如下所示

{
  "features": [
    {
      "feature_idx": 0,
      "name": "text",
      "type": { "dtype": "string", "_type": "Value" }
    },
    {
      "feature_idx": 1,
      "name": "label",
      "type": { "names": ["neg", "pos"], "_type": "ClassLabel" }
    }
  ],
  "rows": [
    {
      "row_idx": 150,
      "row": {
        "text": "enormously likable , partly because it is aware of its own grasp of the absurd .",
        "label": 1
      },
      "truncated_cells": []
    },
    {
      "row_idx": 151,
      "row": {
        "text": "here's a british flick gleefully unconcerned with plausibility , yet just as determined to entertain you .",
        "label": 1
      },
      "truncated_cells": []
    },
    ...,
    ...
  ],
  "num_rows_total": 8530,
  "num_rows_per_page": 100,
  "partial": false
}

在数据集中搜索文本

/search 端点返回与文本查询匹配的数据集片段行 JSON 列表。即使值嵌套在字典中，文本也会在 string 类型的列中搜索。它还返回数据特征（“列”数据类型）的类型。响应格式与 /rows 端点相同。您应该指定数据集名称、子集名称（您可以在 /splits 端点找到子集名称）、拆分名称以及要在文本列中查找的搜索查询。

Python
JavaScript
cURL
import requests
API_URL = "https://datasets-server.huggingface.co/search?dataset=cornell-movie-review-data/rotten_tomatoes&config=default&split=train&query=cat"
def query():
    response = requests.get(API_URL)
    return response.json()
data = query()

您每次最多可以获取 100 行片段，您也可以使用 offset 和 length 参数（如 /rows 端点）请求其他片段。

响应如下所示

{
  "features": [
    {
      "feature_idx": 0,
      "name": "text",
      "type": { "dtype": "string", "_type": "Value" }
    },
    {
      "feature_idx": 1,
      "name": "label",
      "type": { "dtype": "int64", "_type": "Value" }
    }
  ],
  "rows": [
    {
      "row_idx": 9,
      "row": {
        "text": "take care of my cat offers a refreshingly different slice of asian cinema .",
        "label": 1
      },
      "truncated_cells": []
    },
    {
      "row_idx": 472,
      "row": {
        "text": "[ \" take care of my cat \" ] is an honestly nice little film that takes us on an examination of young adult life in urban south korea through the hearts and minds of the five principals .",
        "label": 1
      },
      "truncated_cells": []
    },
    ...,
    ...
  ],
  "num_rows_total": 12,
  "num_rows_per_page": 100,
  "partial": false
}

访问 Parquet 文件

数据集查看器将 Hub 上的每个数据集转换为 Parquet 格式。/parquet 端点返回数据集的 Parquet URL 的 JSON 列表。

Python
JavaScript
cURL
import requests
API_URL = "https://datasets-server.huggingface.co/parquet?dataset=cornell-movie-review-data/rotten_tomatoes"
def query():
    response = requests.get(API_URL)
    return response.json()
data = query()

此方法返回每个拆分的 Parquet 文件的 URL。

{
  "parquet_files": [
    {
      "dataset": "cornell-movie-review-data/rotten_tomatoes",
      "config": "default",
      "split": "test",
      "url": "https://huggingface.co/datasets/cornell-movie-review-data/rotten_tomatoes/resolve/refs%2Fconvert%2Fparquet/default/test/0000.parquet",
      "filename": "0000.parquet",
      "size": 92206
    },
    {
      "dataset": "cornell-movie-review-data/rotten_tomatoes",
      "config": "default",
      "split": "train",
      "url": "https://huggingface.co/datasets/cornell-movie-review-data/rotten_tomatoes/resolve/refs%2Fconvert%2Fparquet/default/train/0000.parquet",
      "filename": "0000.parquet",
      "size": 698845
    },
    {
      "dataset": "cornell-movie-review-data/rotten_tomatoes",
      "config": "default",
      "split": "validation",
      "url": "https://huggingface.co/datasets/cornell-movie-review-data/rotten_tomatoes/resolve/refs%2Fconvert%2Fparquet/default/validation/0000.parquet",
      "filename": "0000.parquet",
      "size": 90001
    }
  ],
  "pending": [],
  "failed": [],
  "partial": false
}

获取数据集的大小

/size 端点返回一个 JSON，其中包含数据集的大小（行数和字节大小），以及每个子集和拆分的大小。

Python
JavaScript
cURL
import requests
API_URL = "https://datasets-server.huggingface.co/size?dataset=cornell-movie-review-data/rotten_tomatoes"
def query():
    response = requests.get(API_URL)
    return response.json()
data = query()

此方法返回数据集的大小，以及每个子集和拆分的大小。

{
  "size": {
    "dataset": {
      "dataset": "cornell-movie-review-data/rotten_tomatoes",
      "num_bytes_original_files": 487770,
      "num_bytes_parquet_files": 881052,
      "num_bytes_memory": 1345449,
      "num_rows": 10662
    },
    "configs": [
      {
        "dataset": "cornell-movie-review-data/rotten_tomatoes",
        "config": "default",
        "num_bytes_original_files": 487770,
        "num_bytes_parquet_files": 881052,
        "num_bytes_memory": 1345449,
        "num_rows": 10662,
        "num_columns": 2
      }
    ],
    "splits": [
      {
        "dataset": "cornell-movie-review-data/rotten_tomatoes",
        "config": "default",
        "split": "train",
        "num_bytes_parquet_files": 698845,
        "num_bytes_memory": 1074806,
        "num_rows": 8530,
        "num_columns": 2
      },
      {
        "dataset": "cornell-movie-review-data/rotten_tomatoes",
        "config": "default",
        "split": "validation",
        "num_bytes_parquet_files": 90001,
        "num_bytes_memory": 134675,
        "num_rows": 1066,
        "num_columns": 2
      },
      {
        "dataset": "cornell-movie-review-data/rotten_tomatoes",
        "config": "default",
        "split": "test",
        "num_bytes_parquet_files": 92206,
        "num_bytes_memory": 135968,
        "num_rows": 1066,
        "num_columns": 2
      }
    ]
  },
  "pending": [],
  "failed": [],
  "partial": false
}
< > 在 GitHub 上更新

←🤗 数据集查看器 在 Hub 上分析数据集→