LeRobot v2 与 v3 格式差异
本文讨论 LeRobotDataset 的格式版本，即数据集的目录结构、元数据组织与读取方式，而不是 lerobot 代码库的软件发布版本。
定义
| 类别 | 示例 | 含义 |
|---|---|---|
| LeRobot 软件版本 | v0.4.0、v0.5.0 | Hugging Face lerobot 代码库的发布版本 |
| LeRobotDataset 格式版本 | v2.0、v2.1、v3.0 | 数据集目录结构、元数据组织与读取方式的版本 |
LeRobotDataset v3.0 自 lerobot v0.4.0 引入。截至 lerobot v0.5.0，meta/info.json 的 codebase_version 为 v3.0，格式主线仍为 v3.0，未出现新的格式代际。
版本差异
格式对照
两个格式的核心差异是 episode 的文件组织方式：v2 将一个 episode 写入一组独立文件，v3 将 episode 合并进共享文件，再通过元数据恢复 episode 级视图。
| 维度 | v2.0 / v2.1 | v3.0 |
|---|---|---|
| 版本标识 | codebase_version 为 v2.0 或 v2.1 | codebase_version 为 v3.0 |
| 表格数据路径 | data/chunk-XXX/episode_YYYYYY.parquet，整表即一个 episode | data/chunk-XXX/file-YYY.parquet，episode 按行范围切分 |
| 视频路径 | videos/chunk-XXX/{feature_key}/episode_YYYYYY.mp4，一个 episode 一个 mp4 | videos/{feature_key}/chunk-XXX/file-YYY.mp4，按时间范围切分 |
| episode 组织 | 一个 episode 对应一组 parquet 与 mp4 文件 | episode 合并进共享文件；写入按 chunks_size（默认 1000）与文件大小切分，文件数随 episode 增长更慢 |
| episode 元数据 | meta/episodes.jsonl，每行一个 episode | meta/episodes/chunk-XXX/file-YYY.parquet，列式存储 |
| 任务元数据 | meta/tasks.jsonl | meta/tasks.parquet（官方默认） |
| 统计元数据 | 全局 meta/stats.json；每 episode 另存 meta/episodes_stats.jsonl | 全局 meta/stats.json；每 episode 统计以 stats/<feature>/... 列写入 meta/episodes/*.parquet |
| 路径解析 | 由 episode_index 与 chunks_size（默认 1000）推导 chunk_index，再代入路径模板 | 由 episode 元数据的 data/chunk_index、data/file_index 与行范围、时间范围确定 |
| 路径模板 | data_path 与 video_path 写入 meta/info.json，占位符为 {episode_chunk}、{episode_index}、{video_key} | data_path 与 video_path 写入 meta/info.json，占位符为 {chunk_index}、{file_index}、{video_key} |
| episode 定位字段 | episode_index、length、tasks、task_index | episode_index、length、tasks、dataset_from_index、dataset_to_index、data/chunk_index、data/file_index、videos/<key>/from_timestamp、videos/<key>/to_timestamp |
| 视频编码元数据 | 视频 feature 的 info 记录 video.codec、video.pix_fmt、video.fps、video.width、video.height、video.channels | 同 v2，字段位置一致 |
| 大规模场景 | 文件数量随 episode 线性增长 | 文件数量少，适配对象存储与 Hub 流式读取 |
官方默认视频编码器为 libsvtav1（AV1），vcodec 可取 h264、hevc、libsvtav1 或 auto；meta/info.json 的视频 feature info 记录实际使用的编码器。平台 LeRobot Studio 导出 v3.0 时同时写入 meta/tasks.jsonl 与 meta/tasks.parquet。
版本判定
meta/info.json 的 codebase_version 是唯一的格式版本判据。加载器按该字段选择 v2 或 v3 解析器，并在值不匹配时报告 VERSION_MISMATCH 或 VERSION_MISMATCH_V3。
路径解析
v2 与 v3 的路径解析流程：
v3 的 dataset_from_index、dataset_to_index 是跨数据集拼接后的全局行号，读取单个 parquet 文件时需换算为文件内局部行号；视频则按 episode 元数据中的时间范围读取。
校验清单
| 格式版本 | 关键文件 |
|---|---|
v2.1 | meta/info.json、meta/stats.json、meta/episodes.jsonl、meta/episodes_stats.jsonl、meta/tasks.jsonl、data/chunk-*/episode_*.parquet、videos/chunk-*/<key>/episode_*.mp4 |
v3.0 | meta/info.json、meta/stats.json、meta/episodes/chunk-*/file-*.parquet、data/chunk-*/file-*.parquet、videos/<key>/chunk-*/file-*.mp4、meta/tasks.parquet（或 meta/tasks.jsonl） |
meta/episodes.jsonl 与 meta/episodes/ 的 episode 数量应与 meta/info.json 的 total_episodes 一致；不一致时健康检查给出警告。v3 的 splits 应包含 train 键。
口径与依据
| 项目 | 取值 | 依据 |
|---|---|---|
| 支持的格式版本 | v2.0、v2.1、v3.0 | lerobot/src/services/versioning/versionRegistry.ts |
| 平台支持的训练数据集版本 | v2、v3 | train/app/services/training_capabilities.py |
v2 默认数据路径模板 | data/chunk-{episode_chunk:03d}/episode_{episode_index:06d}.parquet | lerobot v0.3.3 datasets/utils.py |
v2 默认视频路径模板 | videos/chunk-{episode_chunk:03d}/{video_key}/episode_{episode_index:06d}.mp4 | lerobot v0.3.3 datasets/utils.py |
v3 默认数据路径模板 | data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet | lerobot/src/services/versioning/v3FormatValidator.ts |
v3 默认视频路径模板 | videos/{video_key}/chunk-{chunk_index:03d}/file-{file_index:03d}.mp4 | lerobot/src/services/versioning/v3FormatValidator.ts |
v2 默认 chunks_size | 1000 | lerobot/src/services/versioning/v2Adapter.ts；lerobot v0.3.3 datasets/utils.py |
v3 episode 必需列 | episode_index、length、dataset_from_index、dataset_to_index | lerobot/src/services/versioning/v3FormatValidator.ts |
v3 默认任务路径 | meta/tasks.parquet | lerobot v0.5.0 datasets/utils.py |
v2 任务路径 | meta/tasks.jsonl | lerobot v0.3.3 datasets/utils.py |
| 官方默认视频编码器 | libsvtav1 | lerobot v0.5.0 datasets/video_utils.py |
迁移与兼容
| 方向 | 方式 | 约束 |
|---|---|---|
v2.1 → v3.0 | 官方脚本 lerobot.scripts.convert_dataset_v21_to_v30，将每 episode 文件合并为共享文件并补齐 episode 定位元数据 | 适用于已托管在 Hugging Face Hub 的数据集 |
v2.1 与 v3.0 双向 | 在 LeRobot Studio 导出时切换目标版本 | 适用于本地或私有数据；打开数据集后可先预览再导出 |
| 训练接入 | 平台对训练数据集版本 v2 与 v3 均受支持 | 具体模型对数据集版本的兼容范围见对应模型页 |
使用限制
格式解析与校验受以下既有边界约束。
| 项目 | 限制 | 说明 |
|---|---|---|
| 支持的格式版本 | v2.0、v2.1、v3.0 | codebase_version 前缀非 v2 或 v3 时无法选择解析器 |
| 版本判据 | 仅 meta/info.json 的 codebase_version | 与解析器不符时校验报 VERSION_MISMATCH 或 VERSION_MISMATCH_V3 |
v3.0 episode 必需列 | episode_index、length、dataset_from_index、dataset_to_index | 缺失时健康检查告警 |
v3.0 splits | 需包含 train | 缺少时健康检查告警 |
v3.0 路径模板 | 使用默认 data_path、video_path | 非默认模板时健康检查告警 |
| feature dtype | 固定白名单 | 超出白名单的取值校验失败 |
| feature shape | 正整数数组 | 空数组或含非正整数时校验失败 |
| feature names | 长度等于 shape 末维 | 不一致时告警 |
| 子任务元数据 | 仅 v3.0 | v2.1 不含 meta/subtasks.parquet |
v2.1 → v3.0 迁移 | 官方脚本限已托管于 Hugging Face Hub 的数据集 | 本地或私有数据用导出时切换目标版本 |
相关页面
| 页面 | 用途 |
|---|---|
| LeRobot 数据可视化 | 浏览器内预览与健康检查 |
| LeRobot 数据集与训练 | 导出与训练总览 |
| 安装 LeRobot | 本地安装官方训练栈 |