一文读懂GigaDatasets核心概念:Dataset、Writer与config.json配置体系
一文读懂GigaDatasets核心概念:Dataset、Writer与config.json配置体系
GigaDatasets 是一个统一且轻量级的 Python 数据处理框架,面向数据集整理(Curation)、加载、评估与可视化。本文不堆代码,带你一次讲清它的三大核心概念:Dataset、Writer 与 config.json 配置体系,看完即可上手。
🎯 为什么大数据集需要统一标准
当你手里有几千张图片、几千份散落的 JSON 标注时,通常要面对三个难题:
- 文件分散、命名规则不统一,读取代码难以复用;
- 标注和图片的对应关系全靠"约定",换个机器就乱套;
- 小文件数量巨大,训练时 IO 成为瓶颈。
GigaDatasets 的思路是把"打包 → 加载 → 评估 → 可视化"统一成一套标准:一个数据集 = 一个目录 + 一份 config.json。读和写分别由 Dataset 与 Writer 两类接口完成。
1️⃣ Dataset:所有数据的统一读取接口
GigaDatasets 中所有数据集都继承自 BaseDataset(它本身继承 PyTorch 的 torch.utils.data.Dataset),有三个设计亮点:
- 懒加载 open/close:底层存储(LMDB、pickle、视频 reader 等)只在第一次执行
dataset[i]时才真正打开,用完统一close(),内存占用可控; - 可插拔 transform:通过
set_transform(...)挂一个预处理函数,读取时自动应用; - 批量索引:
dataset[[0, 2, 5]]支持一次取多条样本。
内置的数据集类型一览(源码位于 giga_datasets/datasets/):
| 类 | 作用 | 适用场景 | 源码 |
|---|---|---|---|
Dataset |
组合数据集:按 data_index 合并多个子数据集 |
图片+标注等多路对齐 | dataset.py |
ConcatDataset |
将多个数据集首尾拼接 | 多批次数据合训 | dataset.py |
FileDataset |
直接读取散落文件目录 | 中小规模原始文件 | file_dataset.py |
PklDataset |
读取单个 data.pkl 列表 |
小规模结构化标注 | pkl_dataset.py |
LmdbDataset |
读取 LMDB 数据库 | 海量图片/视频,读取最快 | lmdb_dataset.py |
LeRobotDataset |
包装 LeRobot 操作数据 | 机器人/具身智能数据 | lerobot_dataset.py |
多子数据集对齐的关键:data_index
内置的 demo 数据 把"标注"和"图片"拆成两个子数据集存放。读取时,Dataset 会先取第一个子数据集的样本,再用其中的 data_index 字段去其余子数据集中定位同一行,最终合并成一个完整的样本字典——这就是多路数据"自动对齐"的机制。
2️⃣ Writer:把原始数据打包成结构化数据集的三步曲
面对一堆散落的原始文件,GigaDatasets 提供三种 Writer,负责"写":
| Writer | 落盘格式 | 最适合 |
|---|---|---|
PklWriter |
单个 data.pkl |
小规模结构化标注(dict) |
LmdbWriter |
LMDB 数据库(data.mdb) |
海量图片/视频二进制,读取性能高 |
FileWriter |
data/ 目录 + 索引 data.pkl |
中等规模文件,或需要保留独立文件 |
无论哪种 Writer,使用节奏固定为三步:
write_xxx():逐条写样本(图片、视频、numpy、dict 等);write_config():自动生成该目录的config.json;close():落盘缓冲、提交事务。
官方打包示例 getting_started/pack_images.py 的核心逻辑:
label_writer = PklWriter(os.path.join(save_dir, 'labels')) # 标注 → pickle
image_writer = LmdbWriter(os.path.join(save_dir, 'images')) # 图片 → LMDB
for idx in ...:
label_writer.write_dict(label_dict)
image_writer.write_image(idx, image_paths[idx])
label_writer.write_config(); label_writer.close()
image_writer.write_config(); image_writer.close()
示例使用的原始数据在 getting_started/raw_data/:每个样本由一张图片加一份同名 .json 标注(内含图片描述 prompt)组成,例如第一条样本的图片:
打包完成后,目录变成标准布局:labels/ 与 images/ 各自包含 config.json 和数据文件(data.pkl / data.mdb),再调用 dataset.save(save_dir) 会额外生成一份引用两个子配置的顶层 config.json。
💡 视频打包可参考 getting_started/pack_videos.py,支持三种模式:复制视频、打包进 LMDB(
--pack-lmdb)、只存元数据与绝对路径(--only_path);给已有数据集新增派生字段(如 Canny 边缘图)可参考 getting_started/add_new_filed.py。
3️⃣ config.json 配置体系:框架如何"认识"你的数据集
GigaDatasets 数据集中,config.json 就是数据集的"身份证",核心字段如下:
| 字段 | 作用 | 示例 |
|---|---|---|
_class_name |
决定用哪个 Dataset 类加载 | PklDataset、LmdbDataset、Dataset |
_key_names |
该数据集提供的字段名集合 | ["data_index", "prompt"] |
data_size |
样本数量,用于一致性校验 | 5 |
data_type |
数据类型(LMDB/File 数据集) | image、video、numpy、dict |
data_name |
读取时数据挂载的字段名 | image |
config_paths |
子配置路径(仅组合 Dataset) |
["labels/config.json", "images/config.json"] |
demo 中的三份真实配置分别是顶层 giga_data/config.json:
{
"_class_name": "Dataset",
"config_paths": ["labels/config.json", "images/config.json"]
}
标注子配置 labels/config.json 声明了 _class_name: PklDataset 与字段 _key_names: <a href="https://link.gitcode.com/i/aed1f0efc581264edb7523058965920a" target="_blank">"data_index", "prompt"];图片子配置 [images/config.json 声明了 _class_name: LmdbDataset、data_type: image。
加载入口 load_dataset() 的工作流程:
- 传入目录或配置路径,自动读取其中的
config.json; - 根据
_class_name在注册表中找到对应类(通过@register_dataset注册,也可注册自定义类); - 若为组合
Dataset,则递归加载config_paths,并自动把含data_index的数据集排到最前,保证对齐顺序正确; - 若传入的是路径列表,则自动构造
ConcatDataset进行拼接。
4️⃣ 三步快速上手:加载 demo 数据集
安装:
pip3 install giga-datasets
加载并取数只需几行(完整可运行脚本见 getting_started/load_dataset.py):
from giga_datasets import load_dataset
dataset = load_dataset('./getting_started/giga_data')
print(len(dataset)) # 5
print(dataset[0]) # 返回 image + prompt 等字段的字典
demo 数据集的第二条样本就是一张长颈鹿的自然场景图片:
📌 核心概念速查表
| 概念 | 一句话理解 | 出处 |
|---|---|---|
Dataset |
把各种存储格式统一成 PyTorch 标准读取接口 | giga_datasets/datasets/ |
Writer |
按"目录 + config.json"标准布局写出数据集 | PklWriter / LmdbWriter / FileWriter |
config.json |
数据集"身份证":类型、字段、数量 | giga_data/config.json |
data_index |
多子数据集之间的对齐键 | dataset.py |
load_dataset |
一行代码加载任意 GigaDatasets 数据集 | dataset.py |
Dataset 负责读、Writer 负责写、config.json 把二者串起来——理解这三者,你就掌握了 GigaDatasets 数据集整理、评估与可视化的核心骨架。

