HDF5数据格式详解
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 | demo_dataset.hdf5 |
这里的 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 | robot0_eef_pos |
图像观测可能包括:
1 | agentview_image |
训练代码会根据配置决定读取哪些 observation keys。比如只训练低维策略时,可能读取末端位姿、夹爪状态和物体状态;训练视觉策略时,则会读取相机图像和机器人本体状态。
4. HDF5 在训练流程中的位置
在离线模仿学习或离线强化学习中,HDF5 文件通常就是训练数据源。完整流程可以理解成:
- 收集数据:人类通过遥操作控制机器人,系统记录每个时刻的观测和动作。
- 写入 HDF5:每条示教轨迹保存成一个 group,例如
data/demo_0。 - 建立索引:Dataset 类读取 HDF5 结构,统计每条轨迹长度、总样本数、训练/验证划分。
- 随机采样:DataLoader 从 HDF5 中采样 batch,可以是单步样本,也可以是连续片段。
- 送入模型:模型根据观测预测动作,并和专家动作计算损失。
- 更新参数:HDF5 本身不参与梯度计算,它只是高效地提供训练样本。
- 验证评估:验证集可以来自同一个文件里的不同轨迹,也可以由
mask/train、mask/valid之类的索引记录。
对于行为克隆,训练样本可能是单步形式:
1 | 输入:obs_t |
对于 BC-RNN、Diffusion Policy、ACT 这类需要历史或未来窗口的模型,训练样本通常是连续片段:
1 | obs[t : t + horizon] |
5. 最重要的规则:时间步对齐
理解机器人 HDF5 数据,最关键的一点是:同一条轨迹内部,不同数组的第一维都按照时间步对齐。
可以把每个 demo_i 看成一串 transition:
1 | (obs_t, action_t, reward_t, done_t, next_obs_t) |
在 HDF5 中,同一个时间步 t 的数据通过第一维索引对齐:
1 | data/demo_0/actions[t] |
它们共同表示:
1 | 在 obs_t 下执行 action_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 | t=0: obs[0] --action[0]--> next_obs[0] ≈ obs[1], reward[0], done[0] |
因此,在长度为 T 的 demonstration 中,常见 dataset 的第一维长度一般都对齐为 T:
1 | actions: [T, action_dim] |
6. 多模态和序列采样如何保持对齐
6.1 多模态观测
如果同一时刻有多个观测模态,例如末端位姿、夹爪状态、外部相机和腕部相机,它们也都使用同一个时间索引 t:
1 | obs/robot0_eef_pos[t] |
这些数据共同组成模型在时刻 t 看到的 observation。训练代码通常会按 obs_keys 读取它们,并拼成字典或张量结构:
1 | obs_t = { |
如果原始传感器频率不同,HDF5 文件内部通常不会再保存复杂的时间戳对齐逻辑,而是假设写入前已经按照控制频率完成同步或重采样。换句话说,文件里的第 t 行就是第 t 个控制步对应的所有模态。
6.2 连续片段采样
对于 BC-RNN、Diffusion Policy、ACT 这类需要连续片段的模型,不仅单步要对齐,整个片段也必须来自同一条 demo 的连续时间段。
假设从 demo_0 的 t 开始采样长度为 L 的片段:
1 | obs_seq = obs[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 | t=0, K=3: |
这种 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 | demo_0/ |
这种方式容易理解,但在大规模训练中会有不少问题:
| 普通文件夹 | HDF5 |
|---|---|
| 小文件数量多,文件系统访问压力大 | 大量数据集中在一个文件里,管理更方便 |
| 元数据容易散落在多个文件中 | 属性和数组可以放在同一个层级结构里 |
| 图像、动作、状态的对齐更容易出错 | 通过统一索引维护时间步对齐 |
| 随机读取大量文件时开销较高 | 支持对数组做切片读取 |
| 搬运和复现实验时容易漏文件 | 单文件或少量文件更容易分发 |
所以对于机器人轨迹、科学计算和多模态数组数据,HDF5 往往比“图片文件夹 + 若干 npy 文件”的方式更稳定。
9. 用 h5py 读取一个 HDF5 文件
Python 中最常用的 HDF5 读取库是 h5py:
1 | import h5py |
如果数据很大,训练时通常不会一次性把所有内容都读进内存,而是按 batch 需要读取切片:
1 | start = 100 |
这也是 HDF5 对训练很友好的地方:文件可以很大,但读取可以很局部。
10. 使用 HDF5 训练时的注意事项
不要打乱轨迹边界
对 RNN、Diffusion Policy、ACT 等序列模型,采样片段不能跨越两个不同 demo。跨轨迹拼接会制造不真实的时间连续性。
确认图像维度顺序
图像可能是
[T, H, W, C],也可能在训练前被转换成[T, C, H, W]。读取后要和模型期望的格式一致。重视动作归一化
机器人动作的不同维度可能有不同量纲。训练前通常需要计算动作均值、标准差或范围,再做 normalization。
训练/验证划分最好按轨迹划分
不建议把同一条轨迹的不同时间步同时放进训练集和验证集,否则验证指标会偏乐观。
压缩会节省空间,也会增加解压开销
图像压缩可以明显减少磁盘占用,但训练时会带来 CPU 解压成本。大规模视觉训练要在空间和读取速度之间权衡。
多进程读取要单独打开文件
PyTorch 多进程 DataLoader 读取 HDF5 时,通常让每个 worker 单独打开文件,避免多个 worker 共享同一个文件句柄。
元数据要写清楚
环境名称、控制频率、动作空间、相机参数、数据采集方式等信息,最好通过 attributes 或单独的 metadata 保存下来。否则数据集过一段时间后会很难复现。
11. 总结
HDF5 的核心价值不是“高级”,而是“适合”:它适合保存大规模数组,适合表达层级结构,适合按切片随机读取,也适合把轨迹数据和元数据放在同一个文件体系里。
放到机器人学习里看,HDF5 就是离线经验池或示教库:
1 | 人类遥操作机器人 |
如果只记住一句话,可以这样理解:
HDF5 不是模型,也不是算法;它是把机器人示教轨迹高效、结构化、可随机访问地保存起来的数据容器。





