Hub documentation

Hugging Face 数据集上传决策指南

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Hugging Face 数据集上传决策指南

本指南主要面向大语言模型（LLM），旨在帮助用户以最兼容的格式将数据集上传至 Hugging Face Hub。用户也可以参考本指南来了解上传流程及最佳实践。

将数据集上传至 Hugging Face Hub 的决策指南。针对 Dataset Viewer 的兼容性以及与 Hugging Face 生态系统的集成进行了优化。

如果你是按照本指南操作的 LLM 或 agent，请在运行上传命令前，通过 hf --help 和 hf <command> --help（例如 hf upload --help、hf auth --help）查看确切的标志。CLI 与已安装的 huggingface_hub 版本相匹配，因此请优先参考其输出，而不是凭记忆回忆的标志。

概述

您的目标是帮助用户将数据集上传到 Hugging Face Hub。理想情况下，该数据集应与 Dataset Viewer（因此也与 load_dataset 函数）兼容，以确保轻松访问和使用。您应努力满足以下标准：

标准	描述	优先级
遵守仓库限制	确保数据集符合 Hugging Face 对文件大小、仓库大小和文件数量的存储限制。有关具体限制，请参阅下方的 Critical Constraints 部分。	必需
使用与 Hub 兼容的格式	尽可能使用 Parquet 格式（压缩率最佳、类型信息丰富、支持大型数据集）。对于较小的数据集（<数 GB），JSON/JSONL 或 CSV 也是可以接受的。对于较小的数据集，原始文件非常适合存储图像/音频，同时需遵守仓库限制。对于大型媒体集合，请使用 WebDataset（.tar）。当转换不切实际时，可以使用特定领域的格式。	期望
Dataset Viewer 兼容性	组织数据以配合自动数据集查看器使用，从而实现预览和便捷的探索。这通常意味着使用受支持的格式并采用合理的文件组织方式。本指南稍后部分将提供验证步骤。	期望
合理组织数据	使用符合 Hub 惯例的逻辑文件夹结构（例如 train/test 划分）。可以使用 Configs 来定义数据集的不同配置。这既便于人类理解，也便于自动加载数据。	期望
使用合适的 Features	在使用 datasets 库时，请指定正确的特征类型（例如 Image()、Audio()、ClassLabel()），以确保正确的数据处理和查看器功能。这将启用针对特定类型的优化和预览。	使用 datasets 库时必填
记录非标准数据集	如果无法转换为兼容 Hub 的格式，必须使用自定义格式，请确保严格遵守仓库限制，并提供清晰的文档说明如何下载和加载数据集。包含使用示例以及任何特殊要求。	必需（当 datasets 库不兼容时）

无文件访问权限的工作方式

当您无法直接访问用户的文件（例如，通过 Web 界面）时，请让用户运行这些命令以了解其数据集：

数据集结构：

# Show directory tree (install with: pip install tree or brew install tree)
tree -L 3 --filelimit 20

# Alternative without tree:
find . -type f -name "*.csv" -o -name "*.json" -o -name "*.parquet" | head -20

检查文件大小：

# Total dataset size
du -sh .

# Individual file sizes
ls -lh data/

查看数据格式：

# First few lines of CSV/JSON
head -n 5 data/train.csv

# Check image folder structure
ls -la images/ | head -10

快速文件计数：

# Count files by type
find . -name "*.jpg" | wc -l

关键约束

存储限制：

如果这些值与 storage-limits 不同，则以 storage-limits 为准。

# Machine-readable Hub limits
hub_limits:
  max_file_size_gb: 500 # absolute hard stop per file
  recommended_file_size_gb: 200 # split larger files into chunks below this
  max_files_per_folder: 10000 # Git performance threshold
  max_files_per_repo: 100000 # recommended maximum; keep well below
  viewer_row_size_mb: 2 # approximate per-row viewer limit
  # No per-repo size limit: repo size counts against the account's storage quota

人类可读的摘要：

每个文件：最大 500GB，建议小于 200GB
每个文件夹:<10k 个文件
每个仓库：建议少于 10 万个文件
账户存储（公共和私有）取决于套餐：请参阅存储套餐

请参阅 https://huggingface.co/docs/hub/storage-limits 了解当前的存储计划和仓库建议。

按数据类型快速参考

您的数据	推荐方法	快速命令
CSV/JSON 文件	使用内置加载器（通过内存映射处理任意大小）	`load_dataset("csv", data_files="data.csv").push_to_hub("username/dataset")`
文件夹中的图像	使用 imagefolder 进行自动类别检测	`load_dataset("imagefolder", data_dir="./images").push_to_hub("username/dataset")`
音频文件	使用 audiofolder 进行自动组织	`load_dataset("audiofolder", data_dir="./audio").push_to_hub("username/dataset")`
视频文件	使用 videofolder 进行自动组织	`load_dataset("videofolder", data_dir="./videos").push_to_hub("username/dataset")`
PDF 文档	使用 pdffolder 进行文本提取	`load_dataset("pdffolder", data_dir="./pdfs").push_to_hub("username/dataset")`
非常大的数据集（100GB 以上）	使用 `max_shard_size` 来控制内存使用	`dataset.push_to_hub("username/dataset", max_shard_size="5GB")`
大量文件/目录（>10k）	使用 `upload_folder`/`hf upload`（可处理大文件或大量文件的上传）	`hf upload username/dataset ./data --repo-type=dataset`
流式传输大型媒体	用于高效流式处理的 WebDataset 格式	创建 .tar 分片，然后运行 `hf upload`
科学数据（HDF5、NetCDF）	使用 Array 特征转换为 Parquet	参见 Scientific Data 部分
自定义/专有格式	如果无法转换，请详细记录	带有完整 README 的 `hf upload`

上传工作流

✓ 收集数据集信息（如有需要）：
- 数据类型是什么？（图像、文本、音频、CSV 等）
- 它是如何组织的？（文件夹结构、单个文件、多个文件）
- 大约多大？
- 这些文件是什么格式？
- 有什么特殊要求吗？（例如，流式传输、私有访问）
- 检查是否存在描述该数据集的现有 README 或文档文件
✓ 身份验证：
- CLI: hf auth login
- 或使用令牌：HfApi(token="hf_...") 或设置 HF_TOKEN 环境变量
✓ 识别您的数据类型：查看上方的快速参考表
✓ 选择上传方式：
- 小型文件（<1GB）且为 Hub 兼容格式：可使用 Hub UI 进行快速上传
- 内置加载器可用：使用加载器 + push_to_hub()（参见快速参考表）
- 大型数据集或大量文件：使用 upload_folder / hf upload，它们可处理大型上传（自动多提交、可恢复）。
- 自定义格式：如果可能，转换为与 Hub 兼容的格式；否则，请详细记录

✓ 在本地测试（如果使用内置加载器）：

# Validate your dataset loads correctly before uploading
dataset = load_dataset("loader_name", data_dir="./your_data")
print(dataset)

✓ 上传到 Hub：

# Basic upload
dataset.push_to_hub("username/dataset-name")

# With options for large datasets
dataset.push_to_hub(
    "username/dataset-name",
    max_shard_size="5GB",  # Control memory usage
    private=True  # For private datasets
)

✓ 验证您的上传：
- 查看数据集查看器：https://huggingface.co/datasets/username/dataset-name
- 测试加载：load_dataset("username/dataset-name")
- 如果查看器显示错误，请检查故障排除部分

常见的转换模式

当内置加载器与您的数据结构不匹配时，请将 datasets 库用作兼容层。将您的数据转换为 Dataset 对象，然后使用 push_to_hub() 以获得最大的灵活性并兼容 Dataset Viewer。

从 DataFrame

如果您已经在 pandas、polars 或其他 dataframe 库中处理数据，可以直接进行转换：

# From pandas DataFrame
import pandas as pd
from datasets import Dataset

df = pd.read_csv("your_data.csv")
dataset = Dataset.from_pandas(df)
dataset.push_to_hub("username/dataset-name")

# From polars DataFrame (direct method)
import polars as pl
from datasets import Dataset

df = pl.read_csv("your_data.csv")
dataset = Dataset.from_polars(df)  # Direct conversion
dataset.push_to_hub("username/dataset-name")

# From PyArrow Table (useful for scientific data)
import pyarrow as pa
from datasets import Dataset

# If you have a PyArrow table
table = pa.table({'data': [1, 2, 3], 'labels': ['a', 'b', 'c']})
dataset = Dataset(table)
dataset.push_to_hub("username/dataset-name")

# For Spark/Dask dataframes, see https://huggingface.co/docs/hub/datasets-libraries

自定义格式转换

当内置加载器与您的数据格式不匹配时，请遵循以下原则将其转换为 Dataset 对象：

设计原则

1. 优先使用宽表/扁平结构而非连接

将关系型数据反规范化为单行，以提升易用性
在每个示例中包含所有相关信息
倾向于使用更大但更易用的数据 - Hugging Face 的基础设施使用先进的去重（XetHub）和 Parquet 优化来高效处理冗余

2. 使用配置来管理逻辑数据集变体

除了训练/测试/验证集划分之外，还可以使用配置来定义数据的不同子集或视图
每个配置可以具有不同的功能或数据组织方式
示例：特定于语言的配置、特定于任务的视图或数据模态

转换方法

小型数据集（可放入内存）- 使用 Dataset.from_dict()：

# Parse your custom format into a dictionary
data_dict = {
    "text": ["example1", "example2"],
    "label": ["positive", "negative"],
    "score": [0.9, 0.2]
}

# Create dataset with appropriate features
from datasets import Dataset, Features, Value, ClassLabel
features = Features({
    'text': Value('string'),
    'label': ClassLabel(names=['negative', 'positive']),
    'score': Value('float32')
})

dataset = Dataset.from_dict(data_dict, features=features)
dataset.push_to_hub("username/dataset")

大型数据集（内存高效）- 使用 Dataset.from_generator()：

def data_generator():
    # Parse your custom format progressively
    for item in parse_large_file("data.custom"):
        yield {
            "text": item["content"],
            "label": item["category"],
            "embedding": item["vector"]
        }

# Specify features for Dataset Viewer compatibility
from datasets import Features, Value, ClassLabel, List
features = Features({
    'text': Value('string'),
    'label': ClassLabel(names=['cat1', 'cat2', 'cat3']),
    'embedding': List(feature=Value('float32'), length=768)
})

dataset = Dataset.from_generator(data_generator, features=features)
dataset.push_to_hub("username/dataset", max_shard_size="1GB")

提示：对于大型数据集，建议先使用子集进行测试，方法是在生成器中添加限制，或在创建后使用 .select(range(100))。

使用配置实现数据集变体

# Push different configurations of your dataset
dataset_en = Dataset.from_dict(english_data, features=features)
dataset_en.push_to_hub("username/multilingual-dataset", config_name="english")

dataset_fr = Dataset.from_dict(french_data, features=features)
dataset_fr.push_to_hub("username/multilingual-dataset", config_name="french")

# Users can then load specific configs
dataset = load_dataset("username/multilingual-dataset", "english")

多模态示例

文本 + 音频（语音识别）：

def speech_generator():
    for audio_file in Path("audio/").glob("*.wav"):
        transcript_file = audio_file.with_suffix(".txt")
        yield {
            "audio": str(audio_file),
            "text": transcript_file.read_text().strip(),
            "speaker_id": audio_file.stem.split("_")[0]
        }

features = Features({
    'audio': Audio(sampling_rate=16000),
    'text': Value('string'),
    'speaker_id': Value('string')
})

dataset = Dataset.from_generator(speech_generator, features=features)
dataset.push_to_hub("username/speech-dataset")

每个示例包含多张图片：

# Before/after images, medical imaging, etc.
data = {
    "image_before": ["img1_before.jpg", "img2_before.jpg"],
    "image_after": ["img1_after.jpg", "img2_after.jpg"],
    "treatment": ["method_A", "method_B"]
}

features = Features({
    'image_before': Image(),
    'image_after': Image(),
    'treatment': ClassLabel(names=['method_A', 'method_B'])
})

dataset = Dataset.from_dict(data, features=features)
dataset.push_to_hub("username/before-after-images")

注意：对于文本 + 图像，请考虑使用带有 metadata.csv 的 ImageFolder，它会自动处理此问题。

核心功能

Features 定义了数据集列的模式和数据类型。指定正确的 Features 可确保：

正确的数据处理和类型转换
数据集查看器功能（例如，图像/音频预览）
高效存储与加载
清晰记录您的数据结构

有关完整的功能文档，请参阅：数据集功能

特征类型概览

基本类型：

Value：标量值 - string、int64、float32、bool、binary 以及其他数值类型
ClassLabel：具有命名类别的分类数据
Sequence：任意特征类型的列表
LargeList：用于非常大的列表

媒体类型（启用数据集查看器预览）：

Image()：处理各种图像格式，返回 PIL Image 对象
Audio(sampling_rate=16000)：包含数组数据和可选采样率的音频
Video()：视频文件
Pdf()：支持文本提取的 PDF 文档

数组类型（用于张量/科学数据）：

Array2D、Array3D、Array4D、Array5D：固定长度或可变长度数组
示例：Array2D(shape=(224, 224), dtype='float32')
第一个维度可以为 None，以支持可变长度

翻译类型：

Translation：用于固定语言的翻译对
TranslationVariableLanguages：用于语言对不固定的翻译任务

注意：会定期添加新的功能类型。请查阅文档以了解最新添加的内容。

上传方法

Dataset 对象（使用 push_to_hub）：当你使用 datasets 库加载/转换数据时使用

dataset.push_to_hub("username/dataset", max_shard_size="5GB")

已有文件（使用 upload_folder / hf upload）：适用于您已准备好并整理好兼容 Hub 的文件（例如 Parquet 文件）的情况。

from huggingface_hub import HfApi
api = HfApi()
api.upload_folder(folder_path="./data", repo_id="username/dataset", repo_type="dataset")

# Or from the CLI:
hf upload username/dataset ./data --repo-type=dataset

重要：在上传之前，请确认文件符合仓库限制：

如果您可以访问文件，请检查文件夹结构：确保没有任何文件夹包含 >10k 个文件
请用户确认：“您的文件是否采用与 Hub 兼容的格式（Parquet/CSV/JSON），并且已妥善组织？”
对于非标准格式，建议先将其转换为 Dataset 对象，以确保兼容性

验证

考虑小幅调整格式：如果数据接近内置加载器的格式，建议进行细微修改：

重命名列（例如，将‘filename’重命名为‘file_name’以适配ImageFolder）
重新组织文件夹（例如，将图像移动到类别子文件夹中）
将文件重命名为符合预期模式的名称（例如，data.csv → train.csv）

上传前：

在本地测试：load_dataset("imagefolder", data_dir="./data")

验证功能是否正常工作：

# Test first example
print(dataset[0])

# For images: verify they load
if 'image' in dataset.features:
    dataset[0]['image']  # Should return PIL Image

# Check dataset size before upload
print(f"Size: {len(dataset)} examples")

检查 metadata.csv 是否包含 file_name 列
验证相对路径，无前置斜杠
确保没有文件夹包含超过 10k 个文件

上传后：

查看查看器：https://huggingface.co/datasets/username/dataset
测试加载：load_dataset("username/dataset")
验证保留的功能：print(dataset.features)

常见问题 → 解决方案

问题	解决方案
“未找到仓库”	运行 `hf auth login`
内存错误	使用 `max_shard_size="500MB"`
数据集查看器无法正常工作	等待 5-10 分钟，检查 README.md 配置
文件 >200GB	拆分为更小的文件
“未找到文件”	在元数据中使用相对路径

数据集查看器配置

注意：本节主要适用于直接上传到 Hub 的数据集（通过 UI、upload_folder 或 hf upload）。使用 push_to_hub() 上传的数据集通常会自动配置查看器。

自动检测何时有效

数据集查看器会自动检测标准结构：

文件名为：train.csv、test.json、validation.parquet
名为 train/、test/、validation/ 的目录
使用分隔符拆分名称：test-data.csv ✓（而非 testdata.csv ✗）

手动配置

对于自定义结构，请在您的 README.md 中添加 YAML：

---
configs:
  - config_name: default # Required even for single config!
    data_files:
      - split: train
        path: "data/train/*.parquet"
      - split: test
        path: "data/test/*.parquet"
---

多个配置示例：

---
configs:
  - config_name: english
    data_files: "en/*.parquet"
  - config_name: french
    data_files: "fr/*.parquet"
---

常见的查看器问题

上传后没有查看器：请等待 5-10 分钟以完成处理
“Config names error”：添加 config_name 字段（必填！）
未检测到文件：检查命名模式（需要分隔符）
查看器已禁用：从 README YAML 中移除 viewer: false

快速模板

# ImageFolder with metadata
dataset = load_dataset("imagefolder", data_dir="./images")
dataset.push_to_hub("username/dataset")

# Memory-efficient upload
dataset.push_to_hub("username/dataset", max_shard_size="500MB")

# Multiple CSV files
dataset = load_dataset('csv', data_files={'train': 'train.csv', 'test': 'test.csv'})
dataset.push_to_hub("username/dataset")

文档

核心文档：添加数据集 | 数据集查看器 | 存储限制 | 上传指南

数据集卡片

提醒用户添加数据集卡片（README.md），其中包含：

数据集描述与用法
许可证信息
引用详情

有关详细信息，请参阅数据集卡片指南。

附录：特殊情况

WebDataset 结构

用于流式传输大型媒体数据集：

创建 1-5GB 的 tar 分片
一致的内部结构
使用 hf upload 上传

科学数据

HDF5/NetCDF → 使用 Array 功能转换为 Parquet
时间序列 → Array2D(shape=(None, n))
复杂元数据 → 以 JSON 字符串形式存储

社区资源

对于非常专业或定制化的格式：

在 Hub 上搜索类似的数据集：https://huggingface.co/datasets
在 Hugging Face 论坛上寻求建议
加入 Hugging Face Discord 获取实时帮助
许多领域特定格式在 Hub 上已有示例

Update on GitHub

←摄取数据集下载数据集→