一文读懂GigaDatasets核心概念:Dataset、Writer与config.json配置体系

原创2026-11-07 10:26:001,627 阅读

一文读懂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,使用节奏固定为三步:

  1. write_xxx():逐条写样本(图片、视频、numpy、dict 等);
  2. write_config():自动生成该目录的 config.json;
  3. 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)组成,例如第一条样本的图片:

GigaDatasets数据集demo的原始图片样本,一份图片配一份JSON标注,用于说明Writer打包流程

打包完成后,目录变成标准布局: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() 的工作流程:

  1. 传入目录或配置路径,自动读取其中的 config.json;
  2. 根据 _class_name 在注册表中找到对应类(通过 @register_dataset 注册,也可注册自定义类);
  3. 若为组合 Dataset,则递归加载 config_paths,并自动把含 data_index 的数据集排到最前,保证对齐顺序正确;
  4. 若传入的是路径列表,则自动构造 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 数据集的第二条样本就是一张长颈鹿的自然场景图片:

GigaDatasets数据集demo原始图片样本,长颈鹿照片配有JSON标注描述,展示load_dataset加载效果

📌 核心概念速查表

概念 一句话理解 出处
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 数据集整理、评估与可视化的核心骨架。

登录后查看全文
giga-datasets