LeRobotDataset v3 是一种机器人学习数据格式，将高频低维信号存储在 Parquet，摄像头流存储在 MP4，模式和回合分割存储在元数据中。多个回合可以共享更大的文件，而 API 则重建回合级别的访问。
该设计降低了文件系统压力，支持Hub原生流媒体，但使偏移量、时间戳和最终处理变得至关重要。仅仅因为每个Parquet或视频文件独立打开，数据集并不有效。
官方 LeRobotDataset v3 文档 会随着代码库的扩展而演进。先钉住已安装的版本和文档版本，然后结合机器人 动作数据指南 和 数据质量审计使用本指南。
将存储文件与回合访问分开
版本3从每集一个文件存储转向更大的共享Parquet和MP4碎片。回合边界是从元数据恢复的，而非从文件名推断。训练代码仍可请求样本和时间窗口，无需手动打开每个碎片。
这种分离提升了规模，但增加了对关系一致性的依赖。仅复制数据文件或重命名分片而不更新元数据，可能导致完整片段无法访问或错位。
在Parquet中放入表式时间序列
机器人状态、动作、时间戳及其他低维高速率特征应包含Parquet，并声明名称、类型和形状。单元、框架和控制意义不由容器创建，必须保持文档化。
检查行顺序、时间戳单调性、缺失值以及每集和每台机器人的功能范围。可读的表格仍可包含移动一帧的动作或静默变化的单元。
| 组成部分 | 商店 | 批评关系 | 失效示例 |
|---|---|---|---|
| 元/info.json | 模式、帧数、版本、路径 | 描述所有特征和碎片 | 错误的d类型 |
| data/*.parquet | 状态、动作、时间戳 | 行映射到回合 | 偏移量变化 |
| 视频/*.mp4 | 摄像机帧 | 帧与时间对齐 | 掉帧 |
| 元回合/回合 | 长度、任务、偏移量 | 重建边界 | 交叉集 |
| 元/属性 | 功能统计 | 比赛单位与分组 | 泄漏或过时统计 |
把摄像头流保存在MP4碎片里
每帧被编码成视频碎片，而不是以数组存储在Parquet中。编解码器、帧率、关键帧和相机身份都会影响随机访问和流媒体成本。保留原始时序，而不是仅假设帧索引就是通用时间。
从每个摄像头中解码采样的间隔，并与表格观察进行对比帧数和时间戳。训练前测试缺失、冻结和可变视频行为。
用info.json作为模式的入口点
官方 v3 文档将 meta/info.json 描述为特征、形状、 dtype、 FPS、代码库版本和路径模板的规范模式位置。将其视为记录、转换和训练之间的合同。
验证所需密钥，并早期拒绝不兼容的模式变更。保留自定义特征定义和处理代码，因为像 observation.state 这样的名称本身无法识别联合顺序、单元或帧。
从关系元数据重建回合
每集记录提供共享数据和视频文件的长度、任务和偏移量。验证首集、末集和随机集数，包括跨越分片边界或靠近文件过渡的集数。
不要仅仅相信汇总行数。重建每个采样的集数，确认开始和结束观察、任务标签、动作序列和摄像机片段属于同一试验。
将任务和统计数据视为派生元数据
任务记录将自然语言描述与条件策略使用的标识符连接起来。统计数据支持归一化，但两者都不能替代原始语义。相同的数值范围可以表示联合弧度、笛卡尔米或归一化的抓握器命令。
计算预期训练分段的统计数据，并在需要时保留每个数据集或每个具体版本。避免通过全局统计泄露验证或测试信息。
在出版前确定作者
当前主要文档说，最终完成会关闭 Parquet 写入者，清除缓冲的回合元数据，并写入所需的页脚信息。跳过它可能会导致文件不完整，即使有些字节存在也无法加载。
最终确定后，在新进程中重新打开数据集，并运行结构性和语义检查。将录制中断视为带有明确保留或隔离的恢复案例，而非隐式成功完成。
验证v2.1到v3迁移的意义
迁移会将回合级别的Parquet和MP4文件聚合成更大的分片，并写入新的回合偏移量。比较源节点和目标之间的回合数量、帧数、任务、时间戳、功能值、摄像机片段和成功标签。
请使用已安装版本的官方 大数据集移植指南。转换器完成且无例外，不足以证明动作和视频语义被保留。
分别测试流媒体和随机访问
流式传输避免了完全本地下载，并能改善对大型集线中心数据集的访问。其性能依赖于分片大小、寻道模式、缓存、网络和时间窗口请求。顺序吞吐量不预测随机集数访问。
基准测试代表培训人员和故障恢复。确认网络重试或截断范围不会返回一个合理但不完整的事件。
邮编和文档版本
当前文档页面将 main 标识为源代码-安装分支，并指向稳定版本。 API 和示例在不同版本之间可能有所不同。记录 LeRobot 包的版本、提交、数据集依赖性和转换器版本。
未经检查兼容性，不要将 main 命令复制到旧安装包中。将数据集代码库版本和迁移历史与工件一起保存。
运行结构、时间和语义完整性测试
结构测试验证文件、模式、偏移量和可解码性。时间测试检查单调时间、对齐窗口和帧覆盖情况。语义测试重放事件，验证观察到的动作、运动和任务在物理上是否一致。
当数据来源于ROS 2时，将失败链接到记录和重放指南。维护校验和和不可变清单，用于源代码、转换和发布版本。
| 测试层 | 运营 | 通过条件 | 失效暴露 |
|---|---|---|---|
| 结构 | 加载元数据 | 预期名称、形状、类型 | 不兼容的功能 |
| 索引 | 样本边界 | 正确的分片和偏移量 | 交叉集数 |
| 时间 | 比较不同模态 | 有界偏斜与覆盖 | 行动转移 |
| 重赛 | 渲染状态、动作、视频 | 物理序列一致 | 错误的相机或任务 |
| 培训 | 加载时序批次 | 稳定通道与口罩 | 寻道或填充错误 |
发布时附带数据集接受检查清单
文档版本、模式、单元、帧、任务、回合索引、视频编码、最终化、转换、校验和分割统计。保存源头到出版的血统记录和可复现的验证器。
通过以下清单进行验证。
评估“LeRobot数据集v3格式”时，还应保存模型版本、机器人配置、标定文件、测试日期和全部试验记录。把成功、失败、恢复与人工介入放在同一份数据中，才能区分模型能力、系统接口和现场流程造成的差异。
成本评估除了设备与算力，还要记录数据采集、工程调试、安全措施、维护、停机和人员培训。只有把这些持续投入与单位成功任务的价值比较，才能判断方案是否适合扩大。
上线后仍要持续检查分布变化、传感器漂移、机械磨损和人工接管原因。监测结果应能触发降级、停止与重新验证流程，并为下一轮数据采集和模型更新留下可追溯记录。
最终结论应明确写出已知限制、尚未验证的场景和下一项可证伪的实验，使后续团队能够沿着证据继续推进。
实际项目还应指定数据、模型、控制器和安全流程的负责人，并预先定义回滚条件。责任边界、审批记录与变更日志越清楚，故障发生后越容易停止扩散、定位原因并安全恢复。
把任务拆成感知、决策、动作执行和结果确认，可以更准确地定位瓶颈。每一阶段都应有独立指标与失败示例，避免用端到端成功率掩盖偶发但严重的风险。
- 把LeRobot的代码、文档和数据集版本钉住。
- 验证Parquet、 MP4和元数据的关联。
- 在分片边界上重建随机回合。
- 比较迁移后的 v2.1 和 v3 语义。
- 敲定、重新开放、直播并在干净的环境中进行培训。
常见问题
v3 是不是每集都创建一个 Parquet 文件？
不会。多个回合可以共享更大的Parquet和MP4碎片，元数据会恢复回合边界。
相机图像会存储在Parquet中吗？
标准v3设计将摄像机帧存储在MP4碎片中，低维信号存储在Parquet中。
文件越少，损坏风险就越低吗？
不会。它减少了文件系统的压力，但共享分片使得元数据、偏移量和最终化变得更重要。
为什么必须被打电话？
它会清除缓冲的元数据并关闭 Parquet 写入器，确保所需文件信息完整且可加载。
v2.1 迁移后应该比较哪些内容？
比较回合和帧数、任务、时间戳、专题、视频、统计数据以及有物理意义的回放。
回合语义与碎片完整性边界
LeRobotDataset v3 通过元数据保留回合访问能力，而非文件边界。在每次录制、转换或中断最终完成后，验证偏移量、时间和语义。