LeRobot 文件
將大型資料集移植至 LeRobot Dataset v3.0
加入 Hugging Face 社群
並獲得增強的文件體驗
開始使用
將大型資料集移植至 LeRobot Dataset v3.0
本教學說明如何將大規模機器人資料集移植到 LeRobot Dataset v3.0 格式。我們將以 DROID 1.0.1 資料集作為主要範例，展示如何處理橫跨 SLURM 叢集、擁有數千個分片（shards）且達到數 TB 容量的資料集。
檔案組織：v2.1 與 v3.0 的比較
Dataset v3.0 從根本上改變了資料的組織與儲存方式
v2.1 結構（基於片段/Episode）:
dataset/ ├── data/chunk-000/episode_000000.parquet ├── data/chunk-000/episode_000001.parquet ├── videos/chunk-000/camera/episode_000000.mp4 └── meta/episodes.jsonl
v3.0 結構（基於檔案/File）:
dataset/
├── data/chunk-000/file-000.parquet # Multiple episodes per file
├── videos/camera/chunk-000/file-000.mp4 # Consolidated video chunks
└── meta/episodes/chunk-000/file-000.parquet # Structured metadata從單一片段檔案轉換為基於檔案的區塊（chunk）結構，能顯著提升效能並減少儲存開銷。
Dataset v3.0 的新功能
Dataset v3.0 在處理大型資料集方面引入了重大改進
🏗️ 強化的檔案組織
- 基於檔案的結構：片段（Episodes）現在被分組到區塊檔案（chunked files）中，而非個別的片段檔案。
- 可配置的檔案大小：適用於資料檔與影片檔。
- 提升儲存效率：更好的壓縮效果並減少了管理開銷。
📊 現代化中繼資料管理
- 基於 Parquet 的中繼資料：以高效的 Parquet 格式取代 JSON Lines。
- 結構化片段存取：透過
dataset.meta.episodes直接存取 pandas DataFrame。 - 單一片段統計：在片段層級提供更詳盡的統計追蹤。
🚀 效能增強
- 記憶體映射存取：透過 PyArrow 記憶體映射提升 RAM 使用效率。
- 載入速度提升：顯著縮短資料集初始化時間。
- 更好的擴充性：專為擁有數百萬片段的資料集而設計。
先修條件
在移植大型資料集之前，請確保您已完成以下準備：
- 安裝支援 v3.0 的 LeRobot。請參考我們的安裝指南。
- 足夠的儲存空間：原始資料集可能非常巨大（例如 DROID 需要 2TB）。
- 叢集存取權限（針對大型資料集推薦）：需具備 SLURM 或類似的作業調度系統。
- 特定資料集依賴項：例如 DROID 需要 TensorFlow Dataset 工具。
了解 DROID 資料集
DROID 1.0.1 是一個大規模機器人資料集的絕佳範例。
- 容量：1.7TB (RLDS 格式)，8.7TB (原始資料)。
- 結構：2048 個預定義的 TensorFlow 資料集分片。
- 內容：來自 Franka Emika Panda 機器人的 76,000 多個操作軌跡。
- 範圍：涵蓋多種環境與物體的真實世界操作任務。
- 格式：最初為 TensorFlow Records/RLDS 格式，需轉換為 LeRobot 格式。
- 託管：儲存於 Google Cloud Storage，可透過
gsutil公開存取。
該資料集包含多樣的操作示範，並具備：
- 多個攝影機視角（腕部攝影機、外部攝影機）
- 自然語言任務描述
- 機器人本體感覺狀態與動作
- 成功/失敗標註
DROID 特徵架構 (Schema)
DROID_FEATURES = {
# Episode markers
"is_first": {"dtype": "bool", "shape": (1,)},
"is_last": {"dtype": "bool", "shape": (1,)},
"is_terminal": {"dtype": "bool", "shape": (1,)},
# Language instructions
"language_instruction": {"dtype": "string", "shape": (1,)},
"language_instruction_2": {"dtype": "string", "shape": (1,)},
"language_instruction_3": {"dtype": "string", "shape": (1,)},
# Robot state
"observation.state.gripper_position": {"dtype": "float32", "shape": (1,)},
"observation.state.cartesian_position": {"dtype": "float32", "shape": (6,)},
"observation.state.joint_position": {"dtype": "float32", "shape": (7,)},
# Camera observations
"observation.images.wrist_left": {"dtype": "image"},
"observation.images.exterior_1_left": {"dtype": "image"},
"observation.images.exterior_2_left": {"dtype": "image"},
# Actions
"action.gripper_position": {"dtype": "float32", "shape": (1,)},
"action.cartesian_position": {"dtype": "float32", "shape": (6,)},
"action.joint_position": {"dtype": "float32", "shape": (7,)},
# Standard LeRobot format
"observation.state": {"dtype": "float32", "shape": (8,)}, # joints + gripper
"action": {"dtype": "float32", "shape": (8,)}, # joints + gripper
}方法一：單機移植
步驟一：安裝依賴項
針對 DROID 的特定設定
pip install tensorflow pip install tensorflow_datasets
針對其他資料集，請安裝適合您來源格式的讀取器。
步驟二：下載原始資料
使用 gsutil 從 Google Cloud Storage 下載 DROID
# Install Google Cloud SDK if not already installed
# https://cloud.google.com/sdk/docs/install
# Download the full RLDS dataset (1.7TB)
gsutil -m cp -r gs://gresearch/robotics/droid/1.0.1 /your/data/
# Or download just the 100-episode sample (2GB) for testing
gsutil -m cp -r gs://gresearch/robotics/droid_100 /your/data/大型資料集需要大量時間與儲存空間
- 完整 DROID (1.7TB)：根據頻寬，下載需數天時間。
- 處理時間：完整資料集進行本機移植需 7 天以上。
- 上傳時間：推送到 Hugging Face Hub 需 3 天以上。
- 本機儲存：處理後的 LeRobot 格式約需 400GB。
步驟三：移植資料集
python examples/port_datasets/port_droid.py \
--raw-dir /your/data/droid/1.0.1 \
--repo-id your_id/droid_1.0.1 \
--push-to-hub開發與測試
為了開發目的，您可以先移植單一分片。
python examples/port_datasets/port_droid.py \
--raw-dir /your/data/droid/1.0.1 \
--repo-id your_id/droid_1.0.1_test \
--num-shards 2048 \
--shard-index 0此方法適用於較小的資料集或測試，但大型資料集則需要叢集運算。
方法二：SLURM 叢集移植（推薦）
對於像 DROID 這樣的大型資料集，跨多個節點的平行處理能顯著縮短處理時間。
步驟一：安裝叢集依賴項
pip install datatrove # Hugging Face's distributed processing library步驟二：設定 SLURM 環境
尋找您的 partition 資訊
sinfo --format="%R" # List available partitions
sinfo -N -p your_partition -h -o "%N cpus=%c mem=%m" # Check resources選擇一個 CPU partition - 資料集移植不需要 GPU。
步驟三：啟動平行移植作業
python examples/port_datasets/slurm_port_shards.py \
--raw-dir /your/data/droid/1.0.1 \
--repo-id your_id/droid_1.0.1 \
--logs-dir /your/logs \
--job-name port_droid \
--partition your_partition \
--workers 2048 \
--cpus-per-task 8 \
--mem-per-cpu 1950M參數設定指南
--workers：平行作業數量（DROID 分片總數最多為 2048）。--cpus-per-task：建議使用 8 個 CPU，以加速影格編碼平行化。--mem-per-cpu：總共約 16GB RAM (8×1950M)，用於載入原始影格。
先使用較少的 worker（例如 100）測試您的叢集設定，再啟動數千個作業。
步驟四：監控進度
檢查執行中的作業
squeue -u $USER監控整體進度
jobs_status /your/logs
檢查個別作業記錄檔
less /your/logs/port_droid/slurm_jobs/JOB_ID_WORKER_ID.out
除錯失敗的作業
failed_logs /your/logs/port_droid
步驟五：聚合分片
待所有移植作業完成後
python examples/port_datasets/slurm_aggregate_shards.py \
--repo-id your_id/droid_1.0.1 \
--logs-dir /your/logs \
--job-name aggr_droid \
--partition your_partition \
--workers 2048 \
--cpus-per-task 8 \
--mem-per-cpu 1950M步驟六：上傳至 Hub
python examples/port_datasets/slurm_upload.py \
--repo-id your_id/droid_1.0.1 \
--logs-dir /your/logs \
--job-name upload_droid \
--partition your_partition \
--workers 50 \
--cpus-per-task 4 \
--mem-per-cpu 1950M上傳作業使用的 worker 較少（約 50 個），因為這是網路傳輸瓶頸而非運算瓶頸。
Dataset v3.0 檔案結構
完成後的資料集將具有此現代化結構
dataset/
├── meta/
│ ├── episodes/
│ │ └── chunk-000/
│ │ └── file-000.parquet # Episode metadata
│ ├── tasks.parquet # Task definitions
│ ├── stats.json # Aggregated statistics
│ └── info.json # Dataset information
├── data/
│ └── chunk-000/
│ └── file-000.parquet # Consolidated episode data
└── videos/
└── camera_key/
└── chunk-000/
└── file-000.mp4 # Consolidated video files這取代了舊版的「每個片段一個檔案」結構，採用高效且大小最佳化的區塊方式。
從 Dataset v2.1 進行遷移
如果您有現有的 v2.1 格式資料集，請使用遷移工具
python src/lerobot/datasets/v30/convert_dataset_v21_to_v30.py \
--repo-id your_id/existing_dataset此工具會自動執行：
- 將檔案結構轉換為 v3.0 格式
- 將中繼資料從 JSON Lines 遷移至 Parquet
- 聚合統計資訊並建立單一片段統計
- 更新版本資訊
效能優勢
Dataset v3.0 為大型資料集帶來顯著改進
- 更快的載入：初始化時間減少 3-5 倍
- 記憶體效率：透過記憶體映射改善 RAM 使用
- 可擴充的處理：高效處理數百萬個片段
- 儲存優化：減少檔案數量並提升壓縮效果