LeRobot v2 与 v3 格式差异

LeRobot 目前同时存在 v2.0/v2.1 和 v3.0 两套格式。了解差异有助于选型、迁移和对接训练。

若需在本地做格式转换或可视化校验，可使用 LeRobot Studio：打开 v2 或 v3 数据集后，在导出时选择目标版本（v2.1 或 v3.0）即可完成双向转换，无需 Python 或 Hugging Face 命令行。

核心差异一览

维度	v2.0 / v2.1	v3.0
存储方式	每个 episode 一个文件	多个 episode 合并成少量大文件，靠元数据定位
表格数据	`data/chunk-XXX/episode_YYYYYY.parquet`	`data/chunk-XXX/file-YYY.parquet`（按行区间取）
视频	`videos/chunk-XXX/{key}/episode_YYYYYY.mp4`	`videos/{key}/chunk-XXX/file-YYY.mp4`（按时间戳区间取）
Episode 元数据	`meta/episodes.jsonl`（每行一个 JSON）	`meta/episodes/` 下的分块 Parquet
任务	`meta/tasks.jsonl`	`meta/tasks.jsonl` 或 `meta/tasks.parquet`
路径	用 chunk、episode 编号算路径	`info.json` 里可配路径模板
扩展性	文件多，列举慢	支持 Hub 流式（`StreamingLeRobotDataset`），适合大规模

v3 的思路是：存的时候用少量大文件，读的时候靠元数据里的行号、时间戳还原成“按 episode”的视图，这样文件少、更适合云端流式。

目录结构

v2

meta/info.json：含 codebase_version（v2.0 或 v2.1）、chunks_size
meta/episodes.jsonl：每行一个 episode 的 JSON
meta/tasks.jsonl：任务索引和描述
data/chunk-{chunk}/episode_{episode}.parquet：一个 episode 一个 Parquet
videos/chunk-{chunk}/{featureKey}/episode_{episode}.mp4：一个 episode 一个 MP4

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
      ...

v3

meta/info.json：codebase_version 为 v3.0，可配 splits、路径模板
meta/stats.json（可选）：归一化用统计
meta/episodes/：分块 Parquet，每行一个 episode 及其在 data/视频中的位置
meta/tasks.jsonl 或 meta/tasks.parquet：任务
data/chunk-{chunk}/file-{file}.parquet：多 episode 合在一个文件里
videos/{featureKey}/chunk-{chunk}/file-{file}.mp4：多 episode 合在一个视频里，边界在元数据里用时间戳标出

meta/
  info.json
  stats.json          # 可选
  episodes/
    chunk-000/
      file-000.parquet
  tasks.jsonl         # 或 tasks.parquet
data/
  chunk-000/
    file-000.parquet
videos/
  observation.images.front/
    chunk-000/
      file-000.mp4

元数据差异

Episode：

v2：episodes.jsonl 每行有 episode_index、length、tasks、可选 task_index。路径用 episode_index 和 chunks_size 算，元数据里不存路径。
v3：Parquet 每行除上述外，还有 dataset_from_index、dataset_to_index（表格行区间），以及 data/chunk_index、data/file_index，和每个视频的 videos/{key}/chunk_index、file_index、from_timestamp、to_timestamp。读的时候按这些字段定位到对应文件和区间。

info.json：

v2：必须要有 chunks_size 和 codebase_version（v2.0 或 v2.1）。
v3：codebase_version 为 v3.0，可带 splits、data_path、video_path 等。路径和默认模板不一致时，校验会告警，但读取可适配。

格式转换

官方 v2.1 → v3.0

Hugging Face 提供 Python 脚本：把 v2.1 的“每 episode 一个 parquet/mp4”合并成 v3 的大文件，并写好 meta/episodes/* 里的偏移和时间戳。适合已经放在 Hub 上的数据集。

说明与命令：官方文档 - Migrate v2.1 → v3.0
需要从 main 或预发布安装 lerobot，然后执行：
python -m lerobot.datasets.v30.convert_dataset_v21_to_v30 --repo-id=...

用 LeRobot Studio 做 v2.1 ↔ v3.0 双向转换

LeRobot Studio 在浏览器里同时支持 v2 和 v3 的打开、预览和导出。导出时选目标版本（v2.1 或 v3.0），即可在本地完成转换，无需 Python 或 Hub。

数据：v2→v3 时把同 chunk 的 episode Parquet 合并成 file-*.parquet；v3→v2 时按行区间切成每 episode 一个 parquet。
视频：v2→v2 直接拷贝；v2→v3 / v3→v3 按时间戳分段转码进共享 MP4；v3→v2 按时间截成每 episode 一个 MP4。
适合：本地或私有数据、不想用命令行时，用 Studio 做预览和转换；若用艾欧数据平台，也可在平台里导出后再用 Studio 验收。

校验与兼容

必备文件：

v2：meta/info.json（codebase_version 以 v2 开头）、meta/episodes.jsonl、meta/tasks.jsonl。缺 chunks_size 会用默认值并告警。
v3：meta/info.json（以 v3 开头）、meta/episodes/ 下至少有一份 Parquet。任务可用 tasks.jsonl 或 tasks.parquet。

自检时看 meta/info.json 的 codebase_version 确认版本，再对照上表看目录和文件是否齐全。

训练选型： v3 支持从 Hub 流式读，适合大规模；v2.1 仍被很多框架使用（如本仓库的 Pi0/OpenPI 流程）。选 v2.1 还是 v3.0 以你的训练框架或平台要求为准。

小结

选 v2：要兼容只支持 v2 的训练框架，或数据量不大、不关心文件数量，追求清晰易查。
选 v3：要采用 lerobot 最新的训练框架，或数据量大，需要流式加载、减少文件数、做大规模或云上训练。

本地做 v2/v3 预览和转换可直接用 LeRobot Studio。

延伸阅读： LeRobot Dataset v3.0 官方文档、本目录 LeRobot Studio 数据可视化、LeRobot 数据集。

核心差异一览​

目录结构​

v2​

v3​

元数据差异​

格式转换​

官方 v2.1 → v3.0​

用 LeRobot Studio 做 v2.1 ↔ v3.0 双向转换​

校验与兼容​

小结​