跳到主要内容

LeRobot v2 与 v3 格式差异

本文讨论的是 LeRobotDataset 格式版本，不是 lerobot 软件发布版本。两者需要严格区分：

类别示例版本含义
LeRobot 软件版本v0.4.0、v0.5.0Hugging Face lerobot 代码库的发布版本
LeRobotDataset 格式版本v2.1、v3.0数据集目录结构、元数据组织方式与读取方式的版本

截至官方 lerobot v0.5.0 发布，数据格式主线仍为 LeRobotDataset v3.0，未出现新的 v3.1 或新的格式代际。v0.5.0 的数据集相关变化主要集中在录制性能、数据处理工具和编辑能力，不属于格式代际升级。LeRobot v0.4.0 LeRobotDataset v3.0

若需在本地执行 格式转换 或 可视化校验，可使用 LeRobot Studio：打开数据集后选择目标版本（v2.1 或 v3.0）即可导出。

版本差异选择​

  • 选择 v2.1：适用于依赖旧版目录结构的训练流程，或需要“一个 episode 一个文件”以便人工检查的场景。比如 openpi 的 pi0/pi05 训练目前还只支持 v2.1 格式。
  • 选择 v3.0：适用于大规模数据集、需要降低文件数量、或需要从 Hugging Face Hub 流式读取的场景。

核心差异一览​

维度v2.0 / v2.1v3.0
存储方式每个 episode 一个文件多个 episode 合并成少量大文件，靠元数据定位
表格数据data/chunk-XXX/episode_YYYYYY.parquetdata/chunk-XXX/file-YYY.parquet
视频videos/chunk-XXX/{key}/episode_YYYYYY.mp4videos/{key}/chunk-XXX/file-YYY.mp4
Episode 元数据meta/episodes.jsonlmeta/episodes/ 下的分块 Parquet
任务元数据meta/tasks.jsonl官方文档以 meta/tasks.jsonl 为主；部分工具链也会兼容或补充 meta/tasks.parquet
路径解析用 episode_index 和 chunks_size 推导在 meta/info.json 中配置路径模板，并在 episode 元数据中记录定位信息
大规模场景文件数量增长快更适合大规模数据和 Hub 流式读取

v3 的核心设计是：写入阶段按共享文件组织，读取阶段通过元数据恢复 episode 级视图。

目录结构​

v2.1​

v2.1 采用“一个 episode 对应一组文件”的组织方式，目录结构较直观。

meta/
  info.json
  episodes.jsonl
  tasks.jsonl
data/
  chunk-000/
    episode_000000.parquet
    episode_000001.parquet
    ...
videos/
  chunk-000/
    observation.images.front/
      episode_000000.mp4
      episode_000001.mp4
      ...

该结构便于手工检查，但当 episode 数量显著增加时，文件系统压力也会随之上升。

v3.0​

v3.0 将多个 episode 合并到共享的 Parquet/MP4 文件中，再通过元数据记录 episode 在共享文件中的位置。

meta/
  info.json
  stats.json
  tasks.jsonl
  episodes/
    chunk-000/
      file-000.parquet
  # 某些工具链还可能额外生成 tasks.parquet
data/
  chunk-000/
    file-000.parquet
videos/
  observation.images.front/
    chunk-000/
      file-000.mp4

根据官方公开文档，v3 的任务元数据仍以 meta/tasks.jsonl 为主；部分工具链或校验器可能同时兼容 tasks.parquet。因此更稳妥的表述是：tasks.jsonl 是官方主线描述，tasks.parquet 是兼容或补充形式，不应写成 v3 的唯一标准文件。

元数据差异​

Episode 元数据​

v2 的 meta/episodes.jsonl 每行对应一个 episode，通常包含：

  • episode_index
  • length
  • tasks / task_index

路径通常不直接记录在 episode 元数据中，而是通过 episode_index 与 chunks_size 推导。

v3 将 episode 元数据存放在 meta/episodes/ 的分块 Parquet 中。除长度、任务等基础信息外，还会记录：

  • 这个 episode 在共享 parquet 中的全局行范围
  • 它对应的数据文件位置，如 data/chunk_index、data/file_index
  • 它对应的视频文件位置和时间范围，如 from_timestamp、to_timestamp

这也是 v3 能够在共享文件结构下保留 episode 级访问能力的原因。

meta/info.json​

无论 v2 还是 v3，meta/info.json 都是最优先检查的文件，因为它定义了：

  • codebase_version
  • fps
  • features
  • splits
  • 路径模板

其中最关键的字段是 codebase_version：

  • v2.0 / v2.1 表示旧版 dataset 结构
  • v3.0 表示新版 dataset 结构

与 v2 相比，v3 更强调“路径模板 + 元数据定位”的组合，因此 info.json 的约束更重要。官方 v3 文档也明确将 data_path、video_path 视为格式定义的一部分。官方 v3 文档

v0.5.0 对数据格式有没有影响？​

可以分为格式层面和能力层面两部分来看。

格式层面​

  • LeRobotDataset 主线仍是 v3.0
  • 没有新的 v3.1
  • 没有新的破坏性目录代际

能力层面​

lerobot v0.5.0 的数据集相关更新主要是这些：

  • Streaming video encoding：录制时实时编码视频，减少 episode 之间的等待
  • 更快的训练和编码性能
  • 更多 dataset tools
  • subtask support
  • image-to-video conversion

这些变化会影响录制、转换、编辑与训练流程，但 不会改变 v3.0 的格式代际。LeRobot v0.5.0 Streaming Video Encoding Guide

streaming_encoding 是格式变化吗？​

不是。

streaming_encoding 是录制阶段的性能优化选项，用于将视频编码从“episode 结束后集中处理”改为“录制过程中实时编码”。它主要影响：

  • 编码时机
  • CPU / GPU 资源占用
  • 录制等待时间

它 不对应新的 dataset 版本，也不意味着目录结构从 v3.0 升级到其他格式。Streaming Video Encoding Guide

格式转换​

官方 v2.1 -> v3.0​

Hugging Face 官方提供了迁移脚本，用于将 v2.1 的“每 episode 一个 parquet/mp4”结构转换为 v3.0 的共享文件布局，并补齐 episode 定位元数据。

python -m lerobot.datasets.v30.convert_dataset_v21_to_v30 --repo-id=your-name/your-dataset

该方式更适合已经托管在 Hugging Face Hub 上的数据集。

用 LeRobot Studio 做 v2.1 <-> v3.0 双向转换​

LeRobot Studio 更适合本地或私有数据：

  • 直接打开 .tar.gz 或解压后的目录
  • 先看回放和健康检查
  • 导出时切换目标版本

常见用法：

  • v2.1 -> v3.0：把按 episode 的 parquet / mp4 合并成共享文件
  • v3.0 -> v2.1：把共享文件重新切回“一个 episode 一组文件”
推荐

如果需要同时完成可视化检查与格式转换，LeRobot Studio 通常是更直接的方案。

校验时看什么？​

建议按以下顺序检查：

  1. 打开 meta/info.json，确认 codebase_version
  2. 再看目录是否和该版本匹配
  3. 最后确认任务、episode、视频文件是否齐全

v2.1 至少要有​

  • meta/info.json
  • meta/episodes.jsonl
  • meta/tasks.jsonl
  • data/chunk-*/episode_*.parquet
  • videos/chunk-*/.../episode_*.mp4

v3.0 至少要有​

  • meta/info.json
  • meta/episodes/ 下至少一份 Parquet
  • data/chunk-*/file-*.parquet
  • videos/.../chunk-*/file-*.mp4
  • meta/tasks.jsonl

如果某个工具额外生成了 meta/tasks.parquet，通常可以视为补充信息，不应据此误判格式版本。

选型建议​

训练侧需要分别判断“数据格式版本”和“训练框架支持范围”。

  • 先看 dataset 版本：你的数据是 v2.1 还是 v3.0
  • 再看训练框架支持：当前要用的模型、脚本、官方 release 是否支持这个格式

常见情况如下：

  • Pi0 / OpenPI 流程：很多时候仍会要求 v2.1
  • LeRobot 新版训练与数据工具：更偏向 v3.0

因此，v2.1 与 v3.0 的选择依据应是 当前数据格式 与 目标训练流程的兼容性，而不是单纯依据 lerobot 软件发布版本。

延伸阅读​