LeRobot v2 と v3 フォーマットの違い

LeRobot には現在 v2.0/v2.1 と v3.0 の2種類のフォーマットがあります。違いを把握すると、フォーマット選定・移行・訓練パイプライン連携に役立ちます。

フォーマット変換や可視化による検証をローカルで行う場合は、LeRobot Studio が使えます。v2 または v3 のデータセットを開き、エクスポート時にターゲットバージョン（v2.1 または v3.0）を選べば双方向に変換でき、Python や Hugging Face の CLI は不要です。

主な違い

項目	v2.0 / v2.1	v3.0
保存形式	1 episode につき 1 ファイル	複数 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`（1行1JSON）	`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: 1 episode につき 1 行の JSON
meta/tasks.jsonl: タスクインデックスと説明
data/chunk-{chunk}/episode_{episode}.parquet: 1 episode につき 1 Parquet
videos/chunk-{chunk}/{featureKey}/episode_{episode}.mp4: 1 episode ・1 特徴につき 1 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。1 行が 1 episode と data/動画内の位置
meta/tasks.jsonl または meta/tasks.parquet: タスク
data/chunk-{chunk}/file-{file}.parquet: 複数 episode を 1 ファイルに集約
videos/{featureKey}/chunk-{chunk}/file-{file}.mp4: 複数 episode を 1 動画に集約。境界はメタデータのタイムスタンプで指定

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 の「1 episode 1 parquet/mp4」を v3 の大ファイルにまとめ、meta/episodes/* にオフセットとタイムスタンプを書き込みます。すでに Hub 上にあるデータセット向けです。

説明とコマンド: 公式ドキュメント - Migrate v2.1 → v3.0
lerobot を main またはプレリリースからインストールし、実行:
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 は行範囲でスライスして 1 episode 1 parquet に出力。
動画: v2→v2 はそのままコピー。v2→v3 / v3→v3 はタイムスタンプで区切って共有 MP4 に変換。v3→v2 は時間で区切って 1 episode 1 MP4 に出力。
向いている場面: ローカルや非公開データで CLI を使いたくない場合に 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 が 1 つ以上。タスクは 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 双方向変換​

検証と互換性​

まとめ​