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)。若转换不切实际，可使用领域专属格式。	建议
兼容数据集查看器	结构需适配自动数据集查看器（从而适配 `load_dataset`），便于预览与探索。通常意味着使用支持的格式与良好的文件组织方式。后文提供验证步骤。	建议
合理组织数据	使用符合 Hub 规范的目录结构（如 train/test 切分）。如有需要，可通过 configs 定义不同配置，便于人类理解与自动加载。	建议
使用合适的 Features	使用 datasets 库时，需要准确指定特征类型（如 Image()、Audio()、ClassLabel()），确保正确的数据处理与查看器功能。这样还能启用类型特定优化与预览。	必须（使用 datasets 库时）
记录非标准数据集	若无法转换为 Hub 兼容格式而必须使用自定义格式，务必严格遵守仓库限制，并提供清晰文档说明如何下载与加载数据集（含使用示例及特殊要求）。	必须（当无法使用 datasets 库时）

无法直接访问文件时

当你无法直接访问用户文件（如通过网页界面协助）时，请让用户运行以下命令以了解数据集情况：

查看数据目录结构：

# 显示目录树（先安装：pip install tree 或 brew install tree）
tree -L 3 --filelimit 20

# 若没有 tree 命令：
find . -type f -name "*.csv" -o -name "*.json" -o -name "*.parquet" | head -20

检查文件大小：

# 数据集总大小
du -sh .

# 单个文件大小
ls -lh data/

快速查看数据格式：

# CSV/JSON 前几行
head -n 5 data/train.csv

# 查看图像文件夹结构
ls -la images/ | head -10

统计文件数量：

# 按类型统计文件数量
find . -name "*.jpg" | wc -l

关键约束

存储限制：

# 机器可读取的 Hub 限制
hub_limits:
  max_file_size_gb: 50 # LFS 强制限制
  recommended_file_size_gb: 20 # 推荐分片大小
  max_files_per_folder: 10000 # Git 性能阈值
  max_files_per_repo: 100000 # 仓库文件数上限
  recommended_repo_size_gb: 300 # 公共仓库软限制，如需更大请联系 HF
  viewer_row_size_mb: 2 # 数据集查看器单行约限制

人类可读摘要：

免费账号：100GB 私有数据集额度
PRO（个人）/ Team 或 Enterprise（组织）：每席位 1TB+ 私有存储（详见定价）
公共仓库：1TB（如需更大，请联系 [email protected]）
单个文件：最大 50GB，建议不超过 20GB
每个文件夹：少于 1 万个文件

最新的仓库大小与文件数建议，请参阅 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")`
大量文件/目录（>1 万）	使用 `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 等）	转换为带 Array 特征的 Parquet	参见科学数据章节
自定义/专有格式	若无法转换，务必详尽记录	使用 `upload_large_folder()` 并撰写完整 README

上传流程

✓ 收集数据集信息（如有必要）：
- 数据类型（图像、文本、音频、CSV 等）
- 数据组织方式（文件夹结构、单文件、多文件）
- 大致大小
- 文件格式
- 是否有特殊需求（如流式、私有访问）
- 是否已有 README 或文档描述
✓ 身份认证：
- CLI：hf auth login
- 或使用令牌：HfApi(token="hf_...") 或设置 HF_TOKEN 环境变量
✓ 识别数据类型：参阅前面的快速参考表
✓ 选择上传方式：
- 小文件（小于 1GB）且格式兼容：可使用 Hub UI 快速上传
- 有内置加载器：使用加载器 + push_to_hub()（参见快速参考表）
- 大型数据集或文件众多：使用 upload_large_folder()（适用于大于 100GB 或大于 1 万文件）
- 自定义格式：能转换则转换，否则需详尽记录

✓ 本地测试（若使用内置加载器）：

# 上传前先本地验证能正常加载
dataset = load_dataset("loader_name", data_dir="./your_data")
print(dataset)

✓ 上传至 Hub：

# 基础上传
dataset.push_to_hub("username/dataset-name")

# 针对大型数据集的选项
dataset.push_to_hub(
    "username/dataset-name",
    max_shard_size="5GB",  # 控制内存占用
    private=True             # 上传为私有数据集
)

✓ 验证上传结果：
- 检查数据集查看器：https://huggingface.co/datasets/username/dataset-name
- 测试加载：load_dataset("username/dataset-name")
- 若查看器报错，请参阅常见问题与解决方案

常见转换模式

当你的数据结构与内置加载器不匹配时，可利用 datasets 库作为兼容层。将数据转换为 Dataset 对象，再调用 push_to_hub()，获得最大灵活性与查看器兼容性。

从 DataFrame 转换

如果数据已在 pandas、polars 等 DataFrame 库中，可直接转换：

# 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")

# polars DataFrame（直接方法）
import polars as pl
from datasets import Dataset

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

# PyArrow Table（适合科学数据）
import pyarrow as pa
from datasets import Dataset

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

# Spark/Dask DataFrame，请参阅 https://huggingface.co/docs/hub/datasets-libraries

自定义格式转换

当内置加载器无法匹配你的数据格式时，请按照以下原则转换为 Dataset 对象：

设计原则

1. 优先选择宽/扁平结构，避免连接

将关系数据展平为单行，便于使用
每个示例都包含所有相关信息
倾向于使用更大的数据，但更易用 - Hugging Face 的基础设施使用先进的去重（XetHub）和 Parquet 优化来高效处理冗余

2. 使用 configs 定义逻辑数据集变体

除了 train/test/val 切分外，使用 configs 定义数据集的不同子集或视图
每个 config 可以有不同的特征或数据组织方式
示例：语言特定配置、任务特定视图或数据模态

转换方法

小型数据集（内存中可容纳） - 使用 Dataset.from_dict()：

# 将你的自定义格式解析为字典
data_dict = {
    "text": ["example1", "example2"],
    "label": ["positive", "negative"],
    "score": [0.9, 0.2]
}

# 创建具有适当特征的数据集
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():
    # 渐进式解析你的自定义格式
    for item in parse_large_file("data.custom"):
        yield {
            "text": item["content"],
            "label": item["category"],
            "embedding": item["vector"]
        }

# 为数据集查看器兼容性指定特征
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)) 后创建。

使用 Configs 定义数据集变体

# 推送数据集的不同配置
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")

# 用户可以加载特定配置
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")

每个示例包含多张图片：

# 图片前后对比，医学影像等
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 定义了数据集列的结构和数据类型。正确指定特征可确保：

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

有关完整功能文档，请参阅：Dataset Features

功能类型概览

基础类型：

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：用于具有可变语言对的翻译

注意：新功能类型会定期添加。请查看文档获取最新添加。

上传方法

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

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 之前，请验证文件是否符合仓库限制：

如果你有文件访问权限，请检查文件夹结构：确保没有文件夹包含 >1 万文件
请用户确认：“你的文件是否是 Hub 兼容格式（Parquet/CSV/JSON）且组织得当？”
对于非标准格式，建议先转换为 Dataset 对象以确保兼容性

验证

考虑小规模重构：如果数据接近内置加载器格式，建议进行轻微调整：

重命名列（例如，'filename' → 'file_name' 用于 ImageFolder）
重新组织文件夹（例如，将图像移入类别子文件夹）
重命名文件以匹配预期模式（例如，'data.csv' → 'train.csv'）

预上传：

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

验证功能是否正常：

# 测试第一个示例
print(dataset[0])

# 对于图像：验证它们是否加载
if 'image' in dataset.features:
    dataset[0]['image']  # 应返回 PIL 图像

# 检查数据集大小
print(f"Size: {len(dataset)} examples")

检查 metadata.csv 是否有 'file_name' 列
验证相对路径，无前导斜杠
确保没有文件夹 >1 万文件

后上传：

检查查看器：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	拆分为更小的文件
"文件未找到"	在 metadata 中使用相对路径

数据集查看器配置

注意：本节主要针对直接上传至 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 # 即使单个配置也需要！
    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 带 metadata
dataset = load_dataset("imagefolder", data_dir="./images")
dataset.push_to_hub("username/dataset")

# 内存高效上传
dataset.push_to_hub("username/dataset", max_shard_size="500MB")

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

文档

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

数据集卡片

提醒用户在 README.md 中添加数据集卡片（README.md）：

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

请参阅数据集卡片指南获取详细信息。

附录：特殊情况

WebDataset 结构

对于流式大型媒体数据集：

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

科学数据

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

社区资源

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

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

概览​

无法直接访问文件时​

关键约束​

按数据类型快速参考​

上传流程​

常见转换模式​

从 DataFrame 转换​

自定义格式转换​

设计原则​

转换方法​

使用 Configs 定义数据集变体​

多模态示例​

核心 Features​

功能类型概览​

上传方法​

验证​

常见问题 → 解决方案​

数据集查看器配置​

当自动检测成功时​

手动配置​

常见查看器问题​

快速模板​

文档​

数据集卡片​

附录：特殊情况​

WebDataset 结构​

科学数据​

社区资源​

概览