4. 回放工程基础

在 LeRobot 的策略评测流程中，训练只是前半程，真正决定结论可信度的是回放工程。回放不是简单地把模型跑一遍，而是把一次策略执行还原成可复现、可对比、可追溯的数据资产。它要回答三个问题：当时机器人看到了什么、策略输出了什么、环境实际发生了什么。只有这三者被同步记录并结构化存储，后续的指标计算、失败归因和可视化复盘才有意义。

一、回放系统架构：采集、执行、记录三层解耦

一个稳健的回放系统通常分为三层：执行层负责驱动仿真或真机，按固定控制周期下发动作；采集层负责从传感器、关节状态和相机读取观测；记录层负责把观测、动作、奖励、时间戳和元数据写入轨迹文件。三层解耦的关键在于：执行层不关心数据存到哪里，记录层不关心动作如何产生，二者通过一个带时间戳的消息总线连接。

这种架构带来两个直接收益。第一，策略可以是 LeRobot 的 ACT、Diffusion Policy，也可以是脚本控制器，回放系统无需改动。第二，记录格式可以独立演进，例如从逐帧 JSON 升级为分块 Parquet，而不影响执行逻辑。实际工程中，建议把策略推理也作为独立进程，通过队列与执行层通信，避免推理抖动污染控制周期。

二、数据记录：逐帧字段与元数据设计

回放记录的最小单元是帧。一帧至少包含：单调递增的 frame_index、采集时刻的 timestamp、观测 observation、策略动作 action、执行后状态 next_observation、奖励 reward 以及 done 标志。相机图像不要直接内嵌到主表，而应写入独立的分块文件，主表只保留引用路径和校验哈希，否则轨迹文件会迅速膨胀到 GB 级。

元数据同样关键。一次回放应记录策略名称、检查点哈希、环境版本、随机种子、任务描述和评测配置。缺少这些字段，三个月后你无法判断两条曲线为何不同。推荐在轨迹目录下放置 meta.json，与数据文件同生命周期管理。

episode_0007/
├── meta.json          # 策略、种子、环境、配置哈希
├── frames.parquet     # 逐帧状态、动作、奖励、时间戳
├── camera_front/      # 分块图像，按 chunk 命名
│   ├── chunk_0000.npy
│   └── chunk_0001.npy
└── index.json         # 帧号到图像块的映射与校验和

三、轨迹存储：分块、压缩与索引

轨迹存储的核心矛盾是写入速度与读取效率。逐帧写 JSON 简单但慢，且难以随机访问；一次性写大文件快，但崩溃时容易损坏。工程上常用折中方案：按固定帧数分块，例如每 500 帧一个 chunk，块内用列式格式压缩，块间用索引串联。这样既保证写入吞吐，又支持按帧号快速定位。

下表对比三种常见存储策略，便于根据评测规模选择。

四、时间同步：三类时钟与对齐策略

回放中最容易被忽视、却最影响结论的是时间同步。系统中至少存在三类时钟：仿真步进时钟、真实墙钟、以及相机等外设的硬件时钟。如果直接混用，会出现动作与观测错位，表现为策略“看起来反应迟钝”或“提前动作”。

推荐做法是：以执行层的控制周期为主时钟，所有观测在采集时打上主时钟时间戳，外设时间戳仅作为辅助字段保留。对于相机，记录曝光时刻而非传输完成时刻。回放时按主时钟重采样，而不是按数组下标硬对齐。若必须跨设备对齐，可使用线性插值或最近邻插值，并在元数据中注明对齐方法。

五、可视化基础：从轨迹到可读结论

可视化不是画得好看，而是让失败模式一眼可见。基础可视化至少包括四类：关节轨迹曲线用于观察动作平滑性；动作-观测叠加图用于检查响应延迟；相机关键帧序列用于定位抓取失败时刻；奖励与 done 时间线用于划分成功与失败片段。LeRobot 生态中可借助 Rerun 或 Matplotlib 快速搭建，但前提是轨迹字段命名统一、时间戳可信。

综上，回放工程的本质是把一次策略执行转化为可复现的数据契约。架构决定数据从哪里来，记录决定数据长什么样，存储决定数据能否被高效取回，时间同步决定数据是否可信，可视化决定数据能否被理解。五者缺一，评测结论就会失去工程价值。