メインコンテンツまでスキップ

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 / Pi0.5 の学習は現時点で v2.1 のみ を想定しています。
  • v3.0：大規模データ、ファイル数削減、Hugging Face Hub からのストリーミング読み込みが必要な場合。

主な違い​

項目v2.0 / v2.1v3.0
保存単位1 episode あたり 1 組のファイル複数 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 は 1 episode につき 1 組のファイルという構成で、ツリーが分かりやすいです。

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 が主です。検証器やエクスポータが meta/tasks.parquet にも対応する場合があります。tasks.jsonl を正とし、tasks.parquet は互換・補助として扱い、v3 の唯一の必須ファイルとみなさないのが安全です。

メタデータの違い​

Episode メタデータ​

v2 の meta/episodes.jsonl は 1 行 1 episode で、典型的には次を含みます。

  • episode_index
  • length
  • tasks / task_index

パスは通常 episode メタデータに直接は書かず、episode_index と chunks_size から導出します。

v3 では episode 行を meta/episodes/ 以下のチャンク Parquet に格納します。長さ・タスクに加え、次のような情報を持ちます。

  • 共有 parquet 上での episode のグローバル行範囲
  • データシャード位置（例：data/chunk_index、data/file_index）
  • 動画シャード位置と時間範囲（例：from_timestamp、to_timestamp）

共有ファイル構造のまま episode 単位アクセスを維持するための仕組みです。

meta/info.json​

v2 / v3 いずれでも、最初に確認すべきは meta/info.json です。次を定義します。

  • codebase_version
  • fps
  • features
  • splits
  • パステンプレート

特に重要なのは codebase_version です。

  • v2.0 / v2.1 → 旧レイアウト
  • v3.0 → 新レイアウト

v3 は パステンプレート + メタデータによる位置指定 の比重が高く、info.json の制約も強くなります。公式 v3 ドキュメントでは data_path と video_path をフォーマット定義の一部としています。公式 v3 ドキュメント

v0.5.0 はデータフォーマットに影響するか​

フォーマット面と機能面に分けて整理します。

フォーマット面​

  • LeRobotDataset の主軸は v3.0 のまま
  • 新しい v3.1 はない
  • レイアウト世代を切り替える破壊的変更はない

機能面​

lerobot v0.5.0 のデータセット関連の主な更新例：

  • ストリーミング動画エンコード（録画中のリアルタイムエンコード、episode 間の待ち時間低減）
  • 学習・エンコード性能の向上
  • データセットツールの拡充
  • サブタスク対応
  • 画像から動画への変換

これらは録画・変換・編集・学習フローに影響しますが、v3.0 を超えるフォーマット世代にはしません。LeRobot v0.5.0 · ストリーミング動画エンコード

streaming_encoding はフォーマット変更か​

いいえ。 録画時の性能最適化オプションであり、「episode 終了後の一括エンコード」から「録画中の逐次エンコード」へ処理タイミングを変えるものです。エンコードタイミング、CPU/GPU 負荷、録画待ち時間に影響しますが、新しい LeRobotDataset バージョンを定義するものではありません。ストリーミング動画エンコード

フォーマット変換​

公式 v2.1 → v3.0​

Hugging Face が提供する移行スクリプトで、episode 単位の parquet/mp4 を v3.0 の共有シャードにまとめ、episode 位置情報のメタデータを書き込みます。

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

Hub 上のデータセット向けの手順です。

LeRobot Studio による双方向変換（v2.1 ↔ v3.0）​

LeRobot Studio はローカル／非公開データ向けです。

  • .tar.gz または展開済みフォルダを開く
  • 再生とヘルスチェック
  • エクスポートでターゲットバージョンを選択

典型例：

  • v2.1 → v3.0：episode 単位ファイルを共有シャードへ統合
  • 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/ 以下に少なくとも 1 つの Parquet
  • data/chunk-*/file-*.parquet
  • videos/.../chunk-*/file-*.mp4
  • meta/tasks.jsonl

ツールが meta/tasks.parquet を追加した場合は補助情報として扱い、それだけでフォーマットバージョンを誤判定しないでください。

学習時の選定​

次を別々に判断します。

  1. データセットフォーマット（v2.1 か v3.0 か）
  2. そのフォーマットを学習スタックがサポートするか（モデルスクリプト、固定した lerobot リリース）

よくある例：

  • Pi0 / OpenPI：多くの場合 v2.1 が前提
  • 現行の LeRobot 学習・データツール：v3.0 向け

したがって、v2.1 / v3.0 の選択は lerobot のリリース見出しではなく、データ互換性と学習パイプラインの要件に基づきます。

参考リンク​