LeRobot v2 と v3 の形式差異
本ページでは LeRobotDataset の形式バージョン、すなわちデータセットのディレクトリ構造、メタデータの構成、読み取り方法を扱います。lerobot コードベースのソフトウェアリリースバージョンではありません。
定義
| 種別 | 例 | 意味 |
|---|---|---|
| LeRobot ソフトウェアバージョン | v0.4.0、v0.5.0 | Hugging Face lerobot コードベースのリリースバージョン |
| LeRobotDataset 形式バージョン | v2.0、v2.1、v3.0 | データセットのディレクトリ構造、メタデータの構成、読み取り方法のバージョン |
LeRobotDataset v3.0 は lerobot v0.4.0 で導入されました。lerobot v0.5.0 の時点で meta/info.json の codebase_version は v3.0 であり、形式のメインラインは依然として v3.0 で、新しい形式世代は登場していません。
バージョン間の差異
形式の比較
2 つの形式の中心的な違いは episode のファイル構成です。v2 は 1 つの episode を独立したファイル群に書き込み、v3 は episode を共有ファイルに統合したうえで、メタデータから episode 単位のビューを復元します。
| 観点 | v2.0 / v2.1 | v3.0 |
|---|---|---|
| バージ ョンの識別 | codebase_version が v2.0 または v2.1 | codebase_version が v3.0 |
| テーブルデータのパス | data/chunk-XXX/episode_YYYYYY.parquet。テーブル全体が 1 つの episode | data/chunk-XXX/file-YYY.parquet。episode は行範囲で分割 |
| 動画のパス | videos/chunk-XXX/{feature_key}/episode_YYYYYY.mp4。1 episode につき 1 つの mp4 | videos/{feature_key}/chunk-XXX/file-YYY.mp4。時間範囲で分割 |
| episode の構成 | 1 つの episode が parquet と mp4 のファイル群に対応 | episode を共有ファイルに統合。書き込みは chunks_size（既定 1000）とファイルサイズで分割され、ファイル数は episode の増加に対して緩やかにしか増えない |
| episode メタデータ | meta/episodes.jsonl。1 行につき 1 episode | meta/episodes/chunk-XXX/file-YYY.parquet。列指向ストレージ |
| タスクメタデータ | meta/tasks.jsonl | meta/tasks.parquet（公式の既定） |
| 統計メタデータ | グローバルな meta/stats.json。episode ごとに meta/episodes_stats.jsonl を別途保存 | グローバルな meta/stats.json。episode ごとの統計は stats/<feature>/... 列として meta/episodes/*.parquet に書き込み |
| パスの解決 | episode_index と chunks_size（既定 1000）から chunk_index を導出し、パステンプレートに代入 | episode メタデータの data/chunk_index、data/file_index と行範囲・時間範囲で決定 |
| パステンプレート | data_path と video_path を meta/info.json に記述。プレースホルダーは {episode_chunk}、{episode_index}、{video_key} | data_path と video_path を meta/info.json に記述。プレースホルダーは {chunk_index}、{file_index}、{video_key} |
| episode の位置指定フィールド | episode_index、length、tasks、task_index | episode_index、length、tasks、dataset_from_index、dataset_to_index、data/chunk_index、data/file_index、videos/<key>/from_timestamp、videos/<key>/to_timestamp |
| 動画エンコードメタデータ | 動画 feature の info に video.codec、video.pix_fmt、video.fps、video.width、video.height、video.channels を記録 | v2 と同様で、フィールドの位置も一致 |
| 大規模な利用 | ファイル数が episode に比例して増加 | ファイル数が少なく、オブジェクトストレージや Hub のストリーミング読み取りに適する |
公式の既定動画エンコーダーは libsvtav1（AV1）で、vcodec には h264、hevc、libsvtav1、auto を指定できます。meta/info.json の動画 feature の info に、実際に使用したエンコーダーが記録されます。プラットフォームの LeRobot Studio が v3.0 をエクスポートする際は、meta/tasks.jsonl と meta/tasks.parquet の両方を書き込みます。
バージョンの判定
meta/info.json の codebase_version が形式バージョンの唯一の判定基準です。ローダーはこのフィールドで v2 または v3 のパーサーを選択し、値が一致しない場合は VERSION_MISMATCH または VERSION_MISMATCH_V3 を報告します。
パスの解決
v2 と v3 のパス解決手順：
v3 の dataset_from_index、dataset_to_index はデータセット間の連結後のグローバル行番号であり、単一の parquet ファイルを読み取る際はファイル内のローカル行番号に換算する必要があります。動画は episode メタデータの時間範囲に従って読み取ります。
確認チェックリスト
| 形式バージョン | 主要ファイル |
|---|---|
v2.1 | meta/info.json、meta/stats.json、meta/episodes.jsonl、meta/episodes_stats.jsonl、meta/tasks.jsonl、data/chunk-*/episode_*.parquet、videos/chunk-*/<key>/episode_*.mp4 |
v3.0 | meta/info.json、meta/stats.json、meta/episodes/chunk-*/file-*.parquet、data/chunk-*/file-*.parquet、videos/<key>/chunk-*/file-*.mp4、meta/tasks.parquet（または meta/tasks.jsonl） |
meta/episodes.jsonl と meta/episodes/ の episode 数は meta/info.json の total_episodes と一致させる必要があり、一致しない場合はヘルスチェックが警告を出します。v3 の splits には train キーを含める必要があります。
根拠
| 項目 | 値 | 根拠 |
|---|---|---|
| 対応する形式バージョン | v2.0、v2.1、v3.0 | lerobot/src/services/versioning/versionRegistry.ts |
| プラットフォームが対応するトレーニングデータセットバージョン | v2、v3 | train/app/services/training_capabilities.py |
v2 の既定データパステンプレート | data/chunk-{episode_chunk:03d}/episode_{episode_index:06d}.parquet | lerobot v0.3.3 datasets/utils.py |
v2 の既定動画パステンプレート | videos/chunk-{episode_chunk:03d}/{video_key}/episode_{episode_index:06d}.mp4 | lerobot v0.3.3 datasets/utils.py |
v3 の既定データパステンプレート | data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet | lerobot/src/services/versioning/v3FormatValidator.ts |
v3 の既定動画パステンプレート | videos/{video_key}/chunk-{chunk_index:03d}/file-{file_index:03d}.mp4 | lerobot/src/services/versioning/v3FormatValidator.ts |
v2 の既定 chunks_size | 1000 | lerobot/src/services/versioning/v2Adapter.ts、lerobot v0.3.3 datasets/utils.py |
v3 の episode 必須列 | episode_index、length、dataset_from_index、dataset_to_index | lerobot/src/services/versioning/v3FormatValidator.ts |
v3 の既定タスクパス | meta/tasks.parquet | lerobot v0.5.0 datasets/utils.py |
v2 のタスクパス | meta/tasks.jsonl | lerobot v0.3.3 datasets/utils.py |
| 公式の既定動画エンコーダー | libsvtav1 | lerobot v0.5.0 datasets/video_utils.py |
移行と互換性
| 方向 | 方法 | 制約 |
|---|---|---|
v2.1 → v3.0 | 公式スクリプト lerobot.scripts.convert_dataset_v21_to_v30 で、episode ごとのファイルを共有ファイルに統合し、episode の位置指定メタデータを補完 | Hugging Face Hub でホスト済みのデータセットに適用 |
v2.1 と v3.0 の双方向 | LeRobot Studio でエクスポート時にターゲットバージョンを切り替え | ローカルまたはプライベートデータに適用。データセットを開いてプレビューしてからエクスポート可能 |
| トレーニング接続 | プラットフォームはトレーニングデータセットバージョン v2 と v3 の両方に対応 | 各モデルが対応するデータセットバージョンの範囲は該当モデルのページを参照 |
使用上の制限
形式の解析と検証は、以下の既存の境界に従います。
| 項目 | 制限 | 説明 |
|---|---|---|
| 対応する形式バージョン | v2.0、v2.1、v3.0 | codebase_version の接頭辞が v2 でも v3 でもない場合はパーサーを選択不可 |
| バージョンの判定 | meta/info.json の codebase_version のみ | パーサーと一致しない場合は検証が VERSION_MISMATCH または VERSION_MISMATCH_V3 を報告 |
v3.0 の episode 必須列 | episode_index、length、dataset_from_index、dataset_to_index | 欠落時はヘルスチェックが警告 |
v3.0 の splits | train を含む必要がある | 欠落時はヘルスチェックが警告 |
v3.0 のパステンプレート | 既定の data_path、video_path を使用 | 既定以外のテンプレートではヘルスチェックが警告 |
| feature dtype | 固定のホワイトリスト | ホワイトリスト外の値は検証に失敗 |
| feature shape | 正の整数の配列 | 空配列または非正整数を含む場合は検証に失敗 |
| feature names | 長さが shape の最終次元と等しい | 不一致時は警告 |
| サブタスクメタデータ | v3.0 のみ | v2.1 には meta/subtasks.parquet がない |
v2.1 → v3.0 の移行 | 公式スクリプトは Hugging Face Hub でホスト済みのデータセットに限定 | ローカルまたはプライベートデータはエクスポート時にターゲットバージョンを切り替え |
関連ページ
| ページ | 用途 |
|---|---|
| LeRobot データ可視化 | ブラウザ内でのプレビューとヘルスチェック |
| LeRobot データセットとトレーニング | エクスポートとトレーニングの概要 |
| LeRobot のインストール | 公式トレーニングスタックのローカルインストール |