Porting Dataset Besar ke LeRobot Dataset v3.0

Tutorial ini menjelaskan cara memindahkan dataset robotika berskala besar ke format LeRobot Dataset v3.0. Kami akan menggunakan dataset DROID 1.0.1 sebagai contoh utama, yang menunjukkan penanganan dataset multi-terabyte dengan ribuan shard di klaster SLURM.

Organisasi File: v2.1 vs v3.0

Dataset v3.0 secara fundamental mengubah cara data diorganisasi dan disimpan:

Struktur v2.1 (Berdasarkan Episode):

dataset/
├── data/chunk-000/episode_000000.parquet
├── data/chunk-000/episode_000001.parquet
├── videos/chunk-000/camera/episode_000000.mp4
└── meta/episodes.jsonl

Struktur v3.0 (Berdasarkan 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

Transisi dari file episode individual ke chunk berbasis file ini secara drastis meningkatkan kinerja dan mengurangi overhead penyimpanan.

Apa yang Baru di Dataset v3.0

Dataset v3.0 memperkenalkan peningkatan signifikan untuk menangani dataset besar:

🏗️ Organisasi File yang Ditingkatkan

• Struktur berbasis file: Episode kini dikelompokkan ke dalam file berchunk, bukan lagi file episode individual
• Ukuran file yang dapat dikonfigurasi: untuk file data dan video
• Penyimpanan yang lebih efisien: Kompresi yang lebih baik dan overhead yang dikurangi

📊 Manajemen Metadata Modern

• Metadata berbasis Parquet: Mengganti JSON Lines dengan format parquet yang efisien
• Akses episode terstruktur: Akses langsung ke DataFrame pandas melalui dataset.meta.episodes
• Statistik per episode: Pelacakan statistik yang ditingkatkan pada level episode

🚀 Peningkatan Performa

• Akses memory-mapped: Penggunaan RAM yang ditingkatkan melalui pemetaan memori PyArrow
• Pemmuatan lebih cepat: Waktu inisialisasi dataset berkurang secara signifikan
• Skalabilitas yang lebih baik: Dirancang untuk dataset dengan jutaan episode

Prasyarat

Sebelum memindahkan dataset besar, pastikan Anda memiliki:

• LeRobot terpasang dengan dukungan v3.0. Ikuti Panduan Instalasi kami.
• Penyimpanan yang memadai: Dataset mentah dapat berukuran sangat besar (misalnya, DROID membutuhkan 2TB)
• Akses klaster (disarankan untuk dataset besar): SLURM atau penjadwal tugas serupa
• Dependensi spesifik dataset: Untuk DROID, Anda memerlukan utilitas Dataset TensorFlow

Memahami Dataset DROID

DROID 1.0.1 adalah contoh yang sangat baik dari dataset robotika berskala besar:

• Ukuran: 1,7TB (format RLDS), 8,7TB (data mentah)
• Struktur: 2048 shard dataset TensorFlow yang telah ditentukan
• Isi: 76.000+ trajektori manipulasi robot dari robot Franka Emika Panda
• Cakupan: Tugas manipulasi dunia nyata di berbagai lingkungan dan objek
• Format: Awalnya dalam format TensorFlow Records/RLDS, memerlukan konversi ke format LeRobot
• Hosting: Google Cloud Storage dengan akses publik melalui gsutil

Dataset ini berisi demonstrasi manipulasi yang beragam dengan:

• Beberapa sudut pandang kamera (kamera pergelangan tangan, kamera eksternal)
• Deskripsi tugas bahasa alami
• Keadaan dan aksi proprioseptif robot
• Anotasi keberhasilan/gagal

Skema Fitur DROID

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": "video", "shape": (180, 320, 3), "names": ["height", "width", "channels"]},
    "observation.images.exterior_1_left": {"dtype": "video", "shape": (180, 320, 3), "names": ["height", "width", "channels"]},
    "observation.images.exterior_2_left": {"dtype": "video", "shape": (180, 320, 3), "names": ["height", "width", "channels"]},

    # 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
}

Pendekatan 1: Porting ke Satu Komputer

Langkah 1: Instal Dependensi

Khusus untuk DROID:

pip install tensorflow
pip install tensorflow_datasets

Untuk dataset lain, instal pembaca yang sesuai untuk format sumber Anda.

Langkah 2: Unduh Data Mentah

Unduh DROID dari Google Cloud Storage menggunakan gsutil:

# 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/

Dataset besar membutuhkan waktu dan penyimpanan yang signifikan:

• Full DROID (1.7TB): Beberapa hari untuk mengunduh tergantung pada bandwidth
• Waktu pemrosesan: 7+ hari untuk porting lokal dataset lengkap
• Waktu unggah: 3+ hari untuk mendorong ke Hugging Face Hub
• Penyimpanan lokal: ~400GB untuk format LeRobot yang diproses

Langkah 3: Port Dataset

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

Pengembangan dan Pengujian

Untuk pengembangan, Anda dapat memindahkan satu shard:

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

Pendekatan ini berfungsi untuk dataset yang lebih kecil atau pengujian, tetapi dataset besar memerlukan komputasi klaster.

Pendekatan 2: Porting Klaster SLURM (Disarankan)

Untuk dataset besar seperti DROID, pemrosesan paralel di beberapa node secara drastis mengurangi waktu pemrosesan.

Langkah 1: Instal Dependensi Klaster

pip install datatrove  # Hugging Face's distributed processing library

Langkah 2: Konfigurasikan Lingkungan SLURM Anda

Temukan informasi partisi Anda:

sinfo --format="%R"  # List available partitions
sinfo -N -p your_partition -h -o "%N cpus=%c mem=%m"  # Check resources

Pilih partisi CPU - tidak perlu GPU untuk porting dataset.

Langkah 3: Luncurkan Pekerjaan Porting Paralel

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

Panduan Parameter

• --workers: Jumlah pekerjaan paralel (maksimum 2048 untuk jumlah shard DROID)
• --cpus-per-task: 8 CPU disarankan untuk paralelisasi enkoding frame
• --mem-per-cpu: total RAM ~16GB (8×1950M) untuk memuat frame mentah

Mulai dengan jumlah worker yang lebih sedikit (misalnya, 100) untuk menguji konfigurasi cluster Anda sebelum meluncurkan ribuan job.

Langkah 4: Pantau Kemajuan

Periksa pekerjaan yang sedang berjalan:

squeue -u $USER

Pantau kemajuan keseluruhan:

jobs_status /your/logs

Periksa log pekerjaan individual:

less /your/logs/port_droid/slurm_jobs/JOB_ID_WORKER_ID.out

Debug pekerjaan yang gagal:

failed_logs /your/logs/port_droid

Langkah 5: Agregasi Shard

Setelah semua pekerjaan porting selesai:

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

Langkah 6: Unggah ke 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

Upload menggunakan lebih sedikit worker (50) karena dibatasi oleh jaringan, bukan komputasi.

Struktur File Dataset v3.0

Dataset yang Anda selesaikan akan memiliki struktur modern ini:

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

Ini menggantikan struktur episode-per-file lama dengan chunk berukuran optimal yang efisien.

Migrasi dari Dataset v2.1

Jika Anda memiliki dataset yang sudah ada dalam format v2.1, gunakan alat migrasi:

python src/lerobot/scripts/convert_dataset_v21_to_v30.py \
    --repo-id your_id/existing_dataset

Hal ini secara otomatis:

• Mengonversi struktur file ke format v3.0
• Migrasi metadata dari JSON Lines ke parquet
• Mengumpulkan statistik dan membuat statistik per episode
• Memperbarui informasi versi

Manfaat Kinerja

Dataset v3.0 menyediakan peningkatan signifikan untuk dataset besar:

• Pemmuatan lebih cepat: pengurangan waktu inisialisasi 3-5x
• Efisiensi memori: Penggunaan RAM yang lebih baik melalui pemetaan memori
• Pemrosesan yang dapat diskalakan: Menangani jutaan episode secara efisien
• Optimasi penyimpanan: Jumlah file berkurang dan kompresi ditingkatkan