HuggingFace Datasets Server 快速入门指南

HuggingFace Datasets Server 快速入门指南

notebooks Notebooks using the Hugging Face libraries 🤗 项目地址: https://gitcode.com/gh_mirrors/note/notebooks

概述

HuggingFace Datasets Server 提供了一套完整的 REST API，让开发者能够便捷地访问和处理托管在平台上的数据集。本指南将详细介绍如何通过这些 API 进行数据集操作，包括数据预览、切片下载、搜索过滤等核心功能。

API 基础

端点概览

Datasets Server 提供了多个功能端点，每个端点对应不同的数据集操作：

| 端点功能 | HTTP方法 | 描述 | 关键参数 | |---------|---------|------|---------| | 数据集有效性检查 | GET | 验证数据集是否可用 | dataset | | 获取配置和分割 | GET | 列出数据集配置和分割 | dataset | | 预览前100行 | GET | 获取数据集前100行样本 | dataset, config, split | | 获取数据切片 | GET | 下载指定位置的数据切片 | dataset, config, split, offset, length | | 文本搜索 | GET | 在数据集中搜索文本 | dataset, config, split, query | | 数据过滤 | GET | 根据条件过滤数据行 | dataset, config, split, where | | 获取Parquet文件 | GET | 获取数据集的Parquet文件列表 | dataset | | 获取数据集大小 | GET | 获取数据集行数或字节大小 | dataset | | 获取统计信息 | GET | 获取数据集统计信息 | dataset, config, split |

基础URL

所有API请求都基于以下URL：

https://datasets-server.huggingface.co

核心功能详解

1. 数据集验证

在开始使用数据集前，建议先验证其有效性：

import requests

def check_dataset_validity(dataset_name):
    url = f"https://datasets-server.huggingface.co/is-valid?dataset={dataset_name}"
    response = requests.get(url)
    return response.json()

# 示例：验证Rotten Tomatoes数据集
validity = check_dataset_validity("rotten_tomatoes")
print(validity)

响应示例：

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

2. 获取数据集结构

了解数据集的分割(如train/test/validation)非常重要：

def get_dataset_splits(dataset_name):
    url = f"https://datasets-server.huggingface.co/splits?dataset={dataset_name}"
    response = requests.get(url)
    return response.json()

splits = get_dataset_splits("rotten_tomatoes")

响应示例：

{
  "splits": [
    {"dataset": "rotten_tomatoes", "config": "default", "split": "train"},
    {"dataset": "rotten_tomatoes", "config": "default", "split": "validation"},
    {"dataset": "rotten_tomatoes", "config": "default", "split": "test"}
  ]
}

3. 数据预览

快速查看数据集前100行样本：

def preview_dataset(dataset_name, config, split):
    url = f"https://datasets-server.huggingface.co/first-rows?dataset={dataset_name}&config={config}&split={split}"
    response = requests.get(url)
    return response.json()

preview = preview_dataset("rotten_tomatoes", "default", "train")

响应包含特征类型和样本数据：

{
  "features": [
    {
      "name": "text",
      "type": {"dtype": "string"}
    },
    {
      "name": "label",
      "type": {"names": ["neg", "pos"]}
    }
  ],
  "rows": [
    {
      "row": {
        "text": "the rock is destined to be...",
        "label": 1
      }
    }
  ]
}

4. 数据切片下载

获取数据集的特定部分：

def get_data_slice(dataset_name, config, split, offset=0, length=10):
    url = f"https://datasets-server.huggingface.co/rows?dataset={dataset_name}&config={config}&split={split}&offset={offset}&length={length}"
    response = requests.get(url)
    return response.json()

slice_data = get_data_slice("rotten_tomatoes", "default", "train", 150, 10)

5. 高级功能

文本搜索

def search_in_dataset(dataset_name, config, split, query):
    url = f"https://datasets-server.huggingface.co/search?dataset={dataset_name}&config={config}&split={split}&query={query}"
    response = requests.get(url)
    return response.json()

数据过滤

def filter_dataset(dataset_name, config, split, condition):
    url = f"https://datasets-server.huggingface.co/filter?dataset={dataset_name}&config={config}&split={split}&where={condition}"
    response = requests.get(url)
    return response.json()

访问受限数据集

对于受限访问数据集，需要在请求头中添加认证令牌：

headers = {"Authorization": f"Bearer {API_TOKEN}"}
response = requests.get(API_URL, headers=headers)

最佳实践

1. 分页处理：对于大型数据集，使用offset和length参数实现分页加载
2. 错误处理：检查API响应中的错误信息
3. 缓存机制：对频繁访问的数据考虑本地缓存
4. 类型转换：根据返回的特征类型信息正确处理数据

总结

HuggingFace Datasets Server API 提供了强大而灵活的方式来访问和处理数据集。通过本指南介绍的各种端点，开发者可以轻松实现从简单预览到复杂查询的各种数据操作需求。建议从简单的数据集验证和预览开始，逐步尝试更高级的搜索和过滤功能。

notebooks Notebooks using the Hugging Face libraries 🤗 项目地址: https://gitcode.com/gh_mirrors/note/notebooks