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 通过元数据保留回合访问能力，而非文件边界。在每次录制、转换或中断最终完成后，验证偏移量、时间和语义。