HDF5 数据集

HDF5（Hierarchical Data Format version 5）以组与数据集组织层级数据。平台将已标注的录制数据导出为 HDF5，供平台之外的训练框架读取。

定义

项	说明
存储单位	单个 `.hdf5` 文件，文件内为组与数据集构成的树
分组	按导出参数把原始文件分组，每组写入一个 `chunk_NNN.hdf5`
episode	标注任务对应 `/data` 下的一个组
帧对齐	同一 episode 内各数据集按帧下标逐一对应

规则与流程

入库导入

平台在预处理阶段把以下来源的 HDF5 录制转换为 MCAP 后入库。入库后可在平台内查看与标注，并再次导出为 HDF5。

来源	预处理动作
Agilex	`io_hdf5agilex2mcap`
Realman	`io_hdf5realman2mcap`
Dobot	`io_hdf5dobot2mcap`
Limx	`io_hdf5limx2mcap`
Unix	`io_hdf5unix2mcap`

导出规则

规则	说明
分组	每 `chunk_size` 个原始文件归入一个分块文件，分块编号从 1 起、三位补零
抽样	写入前按 `hz` 对每路消息做等间隔抽样
episode 划分	sidecar JSON 的每个 `subtasks` 项写入一个 `data/episode_NNN` 组；无 sidecar JSON 时整段录制写入一个 episode
转换来源	MCAP 输入经 `io_mcap2hdf5`；Agibot 解压目录经 `io_agibot2hdf5`
合并	转换产物由 `merge_chunks.py` 按 `chunk_size` 合并，分块编号保持连续
归档	全部分块文件打包为一个归档，默认 `tar.gz`

导出结果

导出任务完成后，可在导出记录中查看状态并下载归档。

导出任务状态

导出归档下载

参数与字段

导出参数

导出界面提供以下参数，写入依据为转换命令的 --chunk_size 与 --hz。

参数	类型	必填	默认值	取值范围	说明
`chunk_size`（分组数量）	整数	是	10	1–100	每个 HDF5 文件包含的原始文件数量；取 1 时原始文件与分块文件一一对应
`hz`（数据每秒刷新频率）	整数	是	30	1–60	写入前对每路消息做等间隔抽样；采样帧网格固定为 30 Hz，抽样频率只改变各帧取到的消息

数据选择与参数面板见下图。

在导出页选择数据

目录结构

chunk_001.hdf5
├── data/
│   ├── episode_001/
│   │   ├── action
│   │   ├── observation.gripper
│   │   ├── observation.images.<camera>
│   │   └── observation.state
│   └── episode_002/
└── meta/

每个 episode 组下按字段写入数据集，形状以帧数 T 开头。

数据集	形状	内容
`action`	(T, D)	下发的关节指令
`observation.state`	(T, D)	关节观测值
`observation.gripper`	(T, 2)	夹爪观测值，约定为 `[right_gripper, left_gripper]`
`observation.images.<camera>`	(T,)	每帧一张 JPEG 编码图像，元素为 uint8 变长数组

每个 episode 组附带以下属性。

属性	类型	说明
`task`	字符串	标注的自然语言任务描述
`task_zh`	字符串	任务描述的中文文本
`score`	数值	动作质量评分，缺省为 `-1`

/meta 组的内容随输入来源不同。

meta 内容	来源	说明
特征元数据	`io_mcap2hdf5`	各字段的 dtype、shape、names 写入 `meta` 组属性
机器人型号与 URDF	`io_agibot2hdf5`	`meta.robot_type` 属性与 `meta/urdf`
相机内外参	`io_agibot2hdf5`	`meta/camera/<camera>/intrinsic` 与 `extrinsic`（JSON 文本）

读取方法

h5py 可直接读取分块文件。

import h5py

with h5py.File("chunk_001.hdf5", "r") as f:
    episodes = list(f["data"].keys())          # episode_001, episode_002, ...
    episode = f["data/episode_001"]
    task = episode.attrs["task"].decode()      # 自然语言任务
    score = episode.attrs["score"]             # 动作质量评分
    actions = episode["action"][:]             # (T, D)
    state = episode["observation.state"][:]    # (T, D)
    frames = episode["observation.images.camera_01"][:]  # 每帧 JPEG 字节

口径与依据

项目	取值	依据
分块命名	`chunk_NNN.hdf5`	`tools/mcap2hdf5/mcap2hdf5.py`、`tools/agibot2hdf5/convert_to_hdf5.py`
`chunk_size` 默认值	10	`tools/mcap2hdf5/mcap2hdf5.py`（`--chunk_size`）
`hz` 默认值	30	`tools/mcap2hdf5/mcap2hdf5.py`（`--hz`）
界面取值范围	`chunk_size` 1–100、`hz` 1–60	`app/app/(dashboard)/(data)/export/hdf5/HDF5ExportClient.tsx`
episode 命名与属性	`episode_NNN`，属性 `task`、`task_zh`、`score`	`tools/mcap2hdf5/mcap2hdf5.py`、`tools/agibot2hdf5/convert_to_hdf5.py`
图像编码	JPEG，uint8 变长数组	`tools/mcap2hdf5/mcap2hdf5.py`、`tools/agibot2hdf5/convert_to_hdf5.py`
归档格式	`tar.gz`	`worker/src/workers/export.ts`
转换镜像	`io_mcap2hdf5`、`io_agibot2hdf5`	`worker/src/docker-check.ts`

使用限制

HDF5 数据的导入与导出受以下既有边界约束。

项目	限制	说明
入库来源	Agilex、Realman、Dobot、Limx、Unix	仅上述来源存在 HDF5 转 MCAP 的转换器，其他 HDF5 录制不支持导入
分组数量	1–100	每个分块文件包含的原始文件数量，为界面取值范围
抽样频率	1–60 Hz	采样帧网格固定为 30 Hz，抽样只改变各帧取到的消息
episode 划分	每个 `subtasks` 项对应一个 episode	无 sidecar JSON 时整段录制作为单个 episode
缺少可解码消息	文件转换失败	图像与关节消息均缺失时该文件报错并被跳过
图像编码	固定 JPEG	每帧按 JPEG 写入，不可更换编码
归档格式	`tar.gz`	全部分块打包为一个归档

定义​

规则与流程​

入库导入​

导出规则​

导出结果​

参数与字段​

导出参数​

目录结构​

读取方法​

口径与依据​

使用限制​

相关页面​

定义