Hugging Face 数据集上传决策指南

本指南主要为大型语言模型（LLM）设计，旨在帮助用户以最兼容的格式将数据集上传到 Hugging Face Hub。用户也可以参考本指南，了解上传过程和最佳实践。

将数据集上传到 Hugging Face Hub 的决策指南。针对数据集查看器兼容性和与 Hugging Face 生态系统的集成进行了优化。

概述

你的目标是帮助用户将数据集上传到 Hugging Face Hub。理想情况下，数据集应与数据集查看器（以及 `load_dataset` 函数）兼容，以确保易于访问和使用。你应努力满足以下标准：

标准	描述	优先级
遵守存储库限制	确保数据集符合 Hugging Face 对文件大小、存储库大小和文件数量的存储限制。具体限制请参阅下面的关键约束部分。	必需
使用 Hub 兼容格式	尽可能使用 Parquet 格式（最佳压缩、丰富类型、支持大型数据集）。对于较小的数据集（<几 GB），JSON/JSONL 或 CSV 也可以接受。原始文件在尊重存储库限制的情况下适用于较小数据集中的图像/音频。对于大型媒体集合，请使用 WebDataset (.tar)。当转换不切实际时，可以使用特定领域格式。	期望
数据集查看器兼容性	构建数据以与自动数据集查看器配合使用，从而实现预览和轻松探索。这通常意味着使用受支持的格式和适当的文件组织。本指南后面提供了验证步骤。	期望
合理组织数据	使用符合 Hub 约定（例如，训练/测试分割）的逻辑文件夹结构。配置可用于定义数据集的不同配置。这有助于人类理解和自动数据加载。	期望
使用适当的特征	使用数据集库时，指定正确的特征类型（例如，Image()、Audio()、ClassLabel()）以确保正确的数据处理和查看器功能。这可以实现特定类型的优化和预览。	必需（使用数据集库时）
记录非标准数据集	如果无法转换为 Hub 兼容格式且必须使用自定义格式，请确保严格遵守存储库限制，并提供有关如何下载和加载数据集的清晰文档。包括使用示例和任何特殊要求。	必需（当数据集库不兼容时）

没有文件访问权限时的工作

当你无法直接访问用户文件时（例如，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

关键约束

存储限制:

# Machine-readable Hub limits
hub_limits:
  max_file_size_gb: 50 # absolute hard stop enforced by LFS
  recommended_file_size_gb: 20 # best-practice shard size
  max_files_per_folder: 10000 # Git performance threshold
  max_files_per_repo: 100000 # Repository file count limit
  recommended_repo_size_gb: 300 # public-repo soft cap; contact HF if larger
  viewer_row_size_mb: 2 # approximate per-row viewer limit

人类可读摘要:

免费：100GB 私有数据集
Pro（个人）| 团队或企业（组织）：每个席位 1TB+ 私有存储（参见定价）
公共：300GB（更大容量请联系 datasets@huggingface.co）
每个文件：最大 50GB，推荐 20GB
每个文件夹：<10k 个文件

有关存储库大小和文件数量的当前限制和建议，请参阅 https://huggingface.co/docs/hub/storage-limits#repository-limitations-and-recommendations。

按数据类型快速参考

你的数据	推荐方法	快速命令
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_large_folder 避免 Git 限制	`api.upload_large_folder(folder_path="./data", repo_id="username/dataset", repo_type="dataset")`
流式传输大型媒体	WebDataset 格式，实现高效流式传输	创建 .tar 分片，然后 `upload_large_folder()`
科学数据（HDF5, NetCDF）	转换为具有数组特征的 Parquet	参见科学数据部分
自定义/专有格式	如果无法转换，请彻底记录	带有全面 README 的 `upload_large_folder()`

上传工作流程

✓ 收集数据集信息（如果需要）
- 什么类型的数据？（图像、文本、音频、CSV 等）
- 如何组织？（文件夹结构、单个文件、多个文件）
- 大概多大？
- 文件是什么格式？
- 有什么特殊要求？（例如，流媒体、私有访问）
- 检查描述数据集的现有 README 或文档文件
✓ 认证
- CLI: `hf auth login`
- 或使用令牌：`HfApi(token="hf_...")` 或设置 `HF_TOKEN` 环境变量
✓ 识别您的数据类型：查看上面的快速参考表
✓ 选择上传方法
- 小型文件（<1GB）且兼容 Hub 格式：可使用 Hub UI 进行快速上传
- 内置加载器可用：使用加载器 + `push_to_hub()`（参见快速参考表）
- 大型数据集或文件数量多：对于大于 100GB 或超过 10k 个文件的文件，使用 `upload_large_folder()`
- 自定义格式：如果可能，转换为 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")`
- 如果查看器显示错误，请查看故障排除部分

常见转换模式

当内置加载器不符合您的数据结构时，请使用数据集库作为兼容层。将您的数据转换为 Dataset 对象，然后使用 `push_to_hub()` 以获得最大的灵活性和数据集查看器兼容性。

从数据帧

如果您已经拥有在 pandas、polars 或其他数据帧库中处理的数据，则可以直接转换

# 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，它会自动处理。

基本特征

特征定义数据集列的架构和数据类型。指定正确的特征可确保：

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

有关完整特征文档，请参阅：数据集特征

特征类型概述

基本类型:

`Value`：标量值 - `string`、`int64`、`float32`、`bool`、`binary` 和其他数字类型
`ClassLabel`：带命名类别的分类数据
`Sequence`：任何特征类型的列表
`LargeList`：用于超大型列表

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

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

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

`Array2D`、`Array3D`、`Array4D`、`Array5D`：固定或可变长度数组
示例：`Array2D(shape=(224, 224), dtype='float32')`
第一维对于可变长度可以是 `None`

翻译类型:

`Translation`：用于固定语言的翻译对
`TranslationVariableLanguages`：用于不同语言对的翻译

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

上传方法

数据集对象（使用 push_to_hub）：当您使用数据集库加载/转换数据时使用

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

现有文件（使用 upload_large_folder）：当您已准备好并组织好 Hub 兼容文件（例如 Parquet 文件）时使用

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

重要提示：在使用 `upload_large_folder` 之前，请验证文件是否符合存储库限制

如果您有文件访问权限，请检查文件夹结构：确保没有文件夹包含超过 10k 个文件
请用户确认：“您的文件是否为 Hub 兼容格式（Parquet/CSV/JSON）且组织得当？”
对于非标准格式，请考虑首先转换为数据集对象以确保兼容性

验证

考虑小幅重构：如果数据接近内置加载器格式，建议进行小幅更改

重命名列（例如，'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 配置
超时错误	使用 `multi_commits=True`
文件大于 50GB	分割成更小的文件
“文件未找到”	在元数据中使用相对路径

数据集查看器配置

注意：本节主要适用于直接上传到 Hub 的数据集（通过 UI 或 `upload_large_folder`）。使用 `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_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 分片
一致的内部结构
使用 `upload_large_folder` 上传

科学数据

HDF5/NetCDF → 转换为带数组特征的 Parquet
时间序列 → Array2D(shape=(None, n))
复杂元数据 → 存储为 JSON 字符串

社区资源

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

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

< > 在 GitHub 上更新