HDF5 数据格式详解:机器人学习里的示教数据容器

在机器人模仿学习、离线强化学习和科学计算中,经常会遇到 .hdf5 或 .h5 文件。它看起来只是一个文件,但里面可以同时保存轨迹、图像、动作、奖励、环境参数和各种元数据。

如果一句话概括:

HDF5 是一种适合保存大规模数组和层级结构数据的文件格式,可以把它理解成一个单文件版的小型文件系统。

对于 robomimic、Diffusion Policy、ACT 等机器人学习框架来说,HDF5 经常扮演“离线示教数据仓库”的角色。训练时,模型并不会直接和真实机器人交互,而是不断从 HDF5 文件里采样观测和动作,学习专家策略。

1. HDF5 是什么

HDF5 的全称是 Hierarchical Data Format version 5。它不是某一种算法,也不是某一个深度学习框架,而是一种通用的数据存储格式,特别适合保存大规模、多维数组和有层级关系的数据。

HDF5 文件内部最常见的三个概念是:

概念 可以类比成 作用
Group 文件夹 组织层级结构,例如 data/demo_0/obs
Dataset 数组文件 保存真正的数据,例如动作、图像、状态
Attribute 元数据 保存环境名称、轨迹长度、采样频率等小型信息

一个机器人示教数据集可能长这样:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
demo_dataset.hdf5
└── data
├── demo_0
│ ├── actions
│ ├── rewards
│ ├── dones
│ ├── obs
│ │ ├── robot0_eef_pos
│ │ ├── robot0_eef_quat
│ │ ├── robot0_gripper_qpos
│ │ └── agentview_image
│ └── next_obs
│ ├── robot0_eef_pos
│ ├── robot0_eef_quat
│ ├── robot0_gripper_qpos
│ └── agentview_image
├── demo_1
└── demo_2

这里的 demo_0、demo_1、demo_2 就是一条条示教轨迹。每条轨迹内部又保存了动作、奖励、终止标记、当前观测和下一时刻观测。

2. 为什么机器人学习喜欢用 HDF5

机器人数据有几个非常典型的特点:

  • 数据量大:一条轨迹可能有几十到几千个时间步,一个数据集可能包含几百到几百万步。
  • 模态复杂:同一时刻可能有机器人关节、末端位姿、夹爪状态、物体状态、相机图像、语言指令等信息。
  • 天然是数组:动作通常是 [T, action_dim],图像通常是 [T, H, W, C],状态通常是 [T, state_dim]。
  • 训练需要随机读取:DataLoader 经常随机采样某条轨迹、某个时间步,或者某段连续序列。

HDF5 正好适合这种场景:

  • 可以把大量数组放进一个文件,避免成千上万个小文件拖慢读取。
  • 支持类似文件夹的层级结构,很适合保存 demo_i/obs/actions 这样的轨迹数据。
  • 支持切片读取,不需要一次性把整个数据集加载进内存。
  • 支持压缩,图像数据可以显著节省磁盘空间。
  • 可以保存属性和元数据,方便记录实验环境与数据集信息。
  • Python 生态成熟,常用 h5py 读取,读出来基本就是 Numpy 数组。

3. 典型 robomimic 数据集结构

robomimic 风格的数据集通常围绕 data/demo_x 组织。一个 demo_x 就是一条完整轨迹,常见字段如下:

字段 常见形状 含义
actions [T, action_dim] 专家动作,也就是训练时要模仿的标签
rewards [T] 每个时间步的奖励
dones [T] 当前 transition 是否结束
states [T, ...] 仿真器内部状态,常用于回放或复现
obs group 当前时刻观测,里面包含多个 observation key
next_obs group 执行动作后的下一时刻观测
attrs attribute 环境名称、环境参数、轨迹长度等元数据

低维观测可能包括:

1
2
3
4
robot0_eef_pos
robot0_eef_quat
robot0_gripper_qpos
object

图像观测可能包括:

1
2
agentview_image
robot0_eye_in_hand_image

训练代码会根据配置决定读取哪些 observation keys。比如只训练低维策略时,可能读取末端位姿、夹爪状态和物体状态;训练视觉策略时,则会读取相机图像和机器人本体状态。

4. HDF5 在训练流程中的位置

在离线模仿学习或离线强化学习中,HDF5 文件通常就是训练数据源。完整流程可以理解成:

  1. 收集数据:人类通过遥操作控制机器人,系统记录每个时刻的观测和动作。
  2. 写入 HDF5:每条示教轨迹保存成一个 group,例如 data/demo_0。
  3. 建立索引:Dataset 类读取 HDF5 结构,统计每条轨迹长度、总样本数、训练/验证划分。
  4. 随机采样:DataLoader 从 HDF5 中采样 batch,可以是单步样本,也可以是连续片段。
  5. 送入模型:模型根据观测预测动作,并和专家动作计算损失。
  6. 更新参数:HDF5 本身不参与梯度计算,它只是高效地提供训练样本。
  7. 验证评估:验证集可以来自同一个文件里的不同轨迹,也可以由 mask/train、mask/valid 之类的索引记录。

对于行为克隆,训练样本可能是单步形式:

1
2
输入:obs_t
标签:action_t

对于 BC-RNN、Diffusion Policy、ACT 这类需要历史或未来窗口的模型,训练样本通常是连续片段:

1
2
obs[t : t + horizon]
action[t : t + horizon]

5. 最重要的规则:时间步对齐

理解机器人 HDF5 数据,最关键的一点是:同一条轨迹内部,不同数组的第一维都按照时间步对齐。

可以把每个 demo_i 看成一串 transition:

1
(obs_t, action_t, reward_t, done_t, next_obs_t)

在 HDF5 中,同一个时间步 t 的数据通过第一维索引对齐:

1
2
3
4
5
6
7
data/demo_0/actions[t]
data/demo_0/rewards[t]
data/demo_0/dones[t]
data/demo_0/obs/robot0_eef_pos[t]
data/demo_0/obs/agentview_image[t]
data/demo_0/next_obs/robot0_eef_pos[t]
data/demo_0/next_obs/agentview_image[t]

它们共同表示:

1
2
3
在 obs_t 下执行 action_t
环境返回 reward_t 和 done_t
执行后到达 next_obs_t

也就是说,actions[t] 和 obs[t] 对齐,而不是和 obs[t + 1] 对齐。next_obs[t] 才是执行 actions[t] 后得到的下一帧观测。

在同一条轨迹内部,通常有:

1
next_obs[t] ≈ obs[t + 1]

但很多数据集仍然会显式保存 next_obs[t],这样离线 RL 或 transition-based 算法可以直接读取完整 transition,不需要训练时再手动错位。

一个简化时间轴如下:

1
2
3
t=0: obs[0] --action[0]--> next_obs[0] ≈ obs[1], reward[0], done[0]
t=1: obs[1] --action[1]--> next_obs[1] ≈ obs[2], reward[1], done[1]
t=2: obs[2] --action[2]--> next_obs[2] ≈ obs[3], reward[2], done[2]

因此,在长度为 T 的 demonstration 中,常见 dataset 的第一维长度一般都对齐为 T:

1
2
3
4
5
actions:        [T, action_dim]
rewards: [T]
dones: [T]
obs/<key>: [T, ...]
next_obs/<key>: [T, ...]

6. 多模态和序列采样如何保持对齐

6.1 多模态观测

如果同一时刻有多个观测模态,例如末端位姿、夹爪状态、外部相机和腕部相机,它们也都使用同一个时间索引 t:

1
2
3
4
obs/robot0_eef_pos[t]
obs/robot0_gripper_qpos[t]
obs/agentview_image[t]
obs/robot0_eye_in_hand_image[t]

这些数据共同组成模型在时刻 t 看到的 observation。训练代码通常会按 obs_keys 读取它们,并拼成字典或张量结构:

1
2
3
4
5
obs_t = {
"robot0_eef_pos": obs/robot0_eef_pos[t],
"robot0_gripper_qpos": obs/robot0_gripper_qpos[t],
"agentview_image": obs/agentview_image[t],
}

如果原始传感器频率不同,HDF5 文件内部通常不会再保存复杂的时间戳对齐逻辑,而是假设写入前已经按照控制频率完成同步或重采样。换句话说,文件里的第 t 行就是第 t 个控制步对应的所有模态。

6.2 连续片段采样

对于 BC-RNN、Diffusion Policy、ACT 这类需要连续片段的模型,不仅单步要对齐,整个片段也必须来自同一条 demo 的连续时间段。

假设从 demo_0 的 t 开始采样长度为 L 的片段:

1
2
3
4
5
obs_seq      = obs[t : t + L]
action_seq = actions[t : t + L]
next_obs_seq = next_obs[t : t + L]
reward_seq = rewards[t : t + L]
done_seq = dones[t : t + L]

那么第 k 个样本仍然满足:

1
obs_seq[k] --action_seq[k]--> next_obs_seq[k]

采样器必须避免跨 demo 拼接。不能把 demo_0 的最后几帧和 demo_1 的前几帧连成一个序列,否则模型会看到物理上不连续的假轨迹。

6.3 Frame stack 和 padding

有些策略会使用历史帧,例如在时刻 t 输入最近 K 帧:

1
[obs[t - K + 1], ..., obs[t]]

标签通常仍然是当前动作:

1
action[t]

这表示模型根据过去一段历史判断当前应该执行什么动作。如果 t 太靠近轨迹开头,历史帧不足,Dataset 可以根据配置做 padding,例如重复第一帧:

1
2
3
4
5
t=0, K=3:
[obs[0], obs[0], obs[0]] -> action[0]

t=1, K=3:
[obs[0], obs[0], obs[1]] -> action[1]

这种 padding 仍然发生在同一条 demo 内,不应该跨轨迹补帧。

7. HDF5 对不同算法意味着什么

不同算法从 HDF5 中读取的数据不完全一样:

算法 需要的数据 HDF5 的作用
BC obs_t, action_t 提供监督学习样本,让策略模仿专家动作
BC-RNN 连续的 obs 和 action 序列 保留轨迹顺序,方便采样时间窗口
Diffusion Policy / ACT 历史观测、动作序列或动作块 提供连续片段和多模态观测
离线 RL obs_t, action_t, reward_t, next_obs_t, done_t 提供完整 transition,用于 Bellman backup

以离线 RL 为例,算法可能会用数据估计:

1
Q(obs_t, action_t) ≈ reward_t + gamma * Q(next_obs_t, next_action)

这里的 obs_t、action_t、reward_t、next_obs_t 和 done_t 都来自 HDF5。算法可以反复利用这些离线数据训练,但不能主动采集新的环境交互数据。

8. 和普通文件夹图片数据集有什么区别

如果不用 HDF5,直观做法可能是用普通文件夹保存:

1
2
3
4
5
6
7
8
demo_0/
image_0001.png
image_0002.png
actions.npy
demo_1/
image_0001.png
image_0002.png
actions.npy

这种方式容易理解,但在大规模训练中会有不少问题:

普通文件夹 HDF5
小文件数量多,文件系统访问压力大 大量数据集中在一个文件里,管理更方便
元数据容易散落在多个文件中 属性和数组可以放在同一个层级结构里
图像、动作、状态的对齐更容易出错 通过统一索引维护时间步对齐
随机读取大量文件时开销较高 支持对数组做切片读取
搬运和复现实验时容易漏文件 单文件或少量文件更容易分发

所以对于机器人轨迹、科学计算和多模态数组数据,HDF5 往往比“图片文件夹 + 若干 npy 文件”的方式更稳定。

9. 用 h5py 读取一个 HDF5 文件

Python 中最常用的 HDF5 读取库是 h5py:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import h5py

path = "demo_dataset.hdf5"

with h5py.File(path, "r") as f:
demo = f["data"]["demo_0"]

actions = demo["actions"][:] # [T, action_dim]
rewards = demo["rewards"][:] # [T]
dones = demo["dones"][:] # [T]

obs = demo["obs"]
eef_pos = obs["robot0_eef_pos"][:] # [T, 3]
image = obs["agentview_image"][:] # [T, H, W, C]

如果数据很大,训练时通常不会一次性把所有内容都读进内存,而是按 batch 需要读取切片:

1
2
3
4
5
start = 100
horizon = 16

obs_seq = demo["obs"]["robot0_eef_pos"][start : start + horizon]
action_seq = demo["actions"][start : start + horizon]

这也是 HDF5 对训练很友好的地方:文件可以很大,但读取可以很局部。

10. 使用 HDF5 训练时的注意事项

  1. 不要打乱轨迹边界

    对 RNN、Diffusion Policy、ACT 等序列模型,采样片段不能跨越两个不同 demo。跨轨迹拼接会制造不真实的时间连续性。

  2. 确认图像维度顺序

    图像可能是 [T, H, W, C],也可能在训练前被转换成 [T, C, H, W]。读取后要和模型期望的格式一致。

  3. 重视动作归一化

    机器人动作的不同维度可能有不同量纲。训练前通常需要计算动作均值、标准差或范围,再做 normalization。

  4. 训练/验证划分最好按轨迹划分

    不建议把同一条轨迹的不同时间步同时放进训练集和验证集,否则验证指标会偏乐观。

  5. 压缩会节省空间,也会增加解压开销

    图像压缩可以明显减少磁盘占用,但训练时会带来 CPU 解压成本。大规模视觉训练要在空间和读取速度之间权衡。

  6. 多进程读取要单独打开文件

    PyTorch 多进程 DataLoader 读取 HDF5 时,通常让每个 worker 单独打开文件,避免多个 worker 共享同一个文件句柄。

  7. 元数据要写清楚

    环境名称、控制频率、动作空间、相机参数、数据采集方式等信息,最好通过 attributes 或单独的 metadata 保存下来。否则数据集过一段时间后会很难复现。

11. 总结

HDF5 的核心价值不是“高级”,而是“适合”:它适合保存大规模数组,适合表达层级结构,适合按切片随机读取,也适合把轨迹数据和元数据放在同一个文件体系里。

放到机器人学习里看,HDF5 就是离线经验池或示教库:

1
2
3
4
5
6
7
8
9
10
11
人类遥操作机器人
↓
记录轨迹数据
↓
保存为 HDF5 文件
↓
DataLoader 读取 batch
↓
BC / BC-RNN / Diffusion Policy / ACT / 离线 RL 训练
↓
得到机器人控制策略

如果只记住一句话,可以这样理解:

HDF5 不是模型,也不是算法;它是把机器人示教轨迹高效、结构化、可随机访问地保存起来的数据容器。