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

LeRobotDataset v2 と v3 の違い

ここでは LeRobotDataset のデータ形式バージョン を扱います。Hugging Face lerobot ソフトウェアのリリース番号 とは別物です。混同しないでください。

区分例意味
LeRobot ソフトウェアv0.4.0、v0.5.0lerobot Python パッケージのリリース
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：レガシーな「エピソード単位ファイル」レイアウトを前提とする学習スタック、または人手でファイル単位を見たい場合。例：OpenPI の Pi0/Pi0.5 は現状 v2.1 を要求することが多い。
  • v3.0：大規模データ・ファイル数削減・Hub ストリーミングを重視する場合。

比較表​

観点v2.0 / v2.1v3.0
格納エピソードごとにファイル群複数エピソードを少数の大きなファイルに集約し、メタデータで位置特定
表データdata/chunk-XXX/episode_YYYYYY.parquetdata/chunk-XXX/file-YYY.parquet
動画videos/chunk-XXX/{key}/episode_YYYYYY.mp4videos/{key}/chunk-XXX/file-YYY.mp4
エピソードメタmeta/episodes.jsonlmeta/episodes/ 配下の Parquet シャード
タスクメタmeta/tasks.jsonl公式は meta/tasks.jsonl を主と説明。一部ツールは meta/tasks.parquet を併用し得る
パス解決episode_index と chunks_size から導出meta/info.json のテンプレート＋エピソード行のロケータ
大規模ファイル数が膨らみやすい大規模データと Hub 向き

v3 の考え方：共有ファイルに書き込み、メタデータでエピソードビューを復元する。

ディレクトリ構造​

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

目視しやすい一方、エピソード数増加でファイルシステム負荷が上がります。

v3.0​

複数エピソードを共有 Parquet/MP4 に詰め、メタデータで位置を記録します。

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

公開ドキュメントでは meta/tasks.jsonl がタスクメタの主系 です。tasks.parquet は互換や補助として現れ得ますが、v3 の唯一の定義ファイルではありません。

メタデータの違い​

エピソードメタ​

v2 の meta/episodes.jsonl は 1 行 1 エピソードで、典型的に

  • episode_index
  • length
  • tasks / task_index

パスは多くの場合、行に直接は載せず episode_index と chunks_size から導出します。

v3 は meta/episodes/ の Parquet シャードに保存し、共有 parquet 内の行範囲や、データ／動画ファイルの座標、タイムスタンプ範囲などを保持します。これにより共有ファイルでもエピソード単位アクセスが可能です。

meta/info.json​

どちらの世代でも meta/info.json が最初に読むファイル です。codebase_version、fps、features、splits、パステンプレートなどが入ります。

codebase_version の意味：

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

v3 は テンプレート＋メタデータ定位 が強いため、info.json の制約がより重要です。公式 v3 ドキュメントでは data_path / video_path パターンも形式の一部とみなします。LeRobotDataset v3 ドキュメント

lerobot v0.5.0 は形式を変えるか？​

形式世代と機能強化を分けます。

形式世代​

  • LeRobotDataset の主線は v3.0 のまま
  • 新しい v3.1 はない
  • 破壊的なディレクトリ世代バンプはない

機能（v0.5.0）​

例：

  • ストリーミング動画エンコード（収録中にエンコードしエピソード間の待ちを削減）
  • 学習・エンコード性能の改善
  • データセットツールの拡充
  • サブタスク対応
  • 画像→動画変換

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

streaming_encoding は形式変更か？​

いいえ。 収録時のパフォーマンス最適化で、エンコードを「エピソード後バッチ」から「収録中インクリメンタル」へ寄せるものです。エンコードタイミング・CPU/GPU 負荷・待ち時間に影響しますが、新しい LeRobotDataset バージョンを定義するものではありません。ストリーミング動画エンコード

形式変換​

公式 v2.1 → v3.0​

Hub 上のデータ向けに、エピソード単位ファイルから共有ファイル＋ロケータへ移行する公式ユーティリティがあります。

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

LeRobot Studio で v2.1 ↔ v3.0​

ローカル／プライベートデータには LeRobot Studio が向きます。.tar.gz または展開フォルダを開き、再生とヘルス確認のうえエクスポートで目的バージョンを選びます。

推奨

可視化と変換を同時に進めたい場合、LeRobot Studio が手早いことが多いです。

検証の順番​

  1. meta/info.json の codebase_version
  2. ディレクトリがその世代と一致するか
  3. タスク・エピソード・動画の欠落がないか

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 があっても補助情報として扱い、形式世代の判定にだけ使わない方が安全です。

選び方の実務指針​

  • まずデータ形式：v2.1 か v3.0 か
  • 次に学習スタック：使うモデル・スクリプト・公式リリースがその形式をサポートするか

典型例：

  • Pi0 / OpenPI：多くの場合 v2.1
  • 現行 LeRobot の学習・データツール：v3.0 寄り

lerobot のソフトウェア番号だけでなく、目的の学習パイプラインとの互換性で選んでください。

さらに読む​