Chuyển các bộ dữ liệu lớn sang LeRobot Dataset v3.0

Hướng dẫn này giải thích cách chuyển đổi các bộ dữ liệu robot quy mô lớn sang định dạng LeRobot Dataset v3.0. Chúng ta sẽ sử dụng bộ dữ liệu DROID 1.0.1 làm ví dụ chính, minh họa cách xử lý các bộ dữ liệu nhiều terabyte với hàng nghìn shard trên các cụm SLURM.

Tổ chức tệp: v2.1 so với v3.0

Dataset v3.0 thay đổi cơ bản cách dữ liệu được tổ chức và lưu trữ:

Cấu trúc v2.1 (Dựa trên tập):

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

Cấu trúc v3.0 (Dựa trên tệp):

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

Quá trình chuyển đổi từ các tệp episode riêng lẻ sang các chunk dựa trên tệp cải thiện hiệu suất đáng kể và giảm thiểu chi phí lưu trữ.

Những điểm mới trong Dataset v3.0

Dataset v3.0 giới thiệu các cải tiến đáng kể trong việc xử lý các bộ dữ liệu lớn:

🏗️ Tổ chức tệp được cải thiện

• Cấu trúc dựa trên tệp: Các tập (episodes) hiện được nhóm vào các tệp phân mảnh thay vì các tệp tập riêng lẻ
• Cấu hình kích thước tệp: dành cho tệp dữ liệu và tệp video
• Nâng cao hiệu quả lưu trữ: Nén tốt hơn và giảm thiểu chi phí phụ

📊 Quản lý Metadata hiện đại

• Metadata dựa trên Parquet: Thay thế JSON Lines bằng định dạng parquet hiệu quả
• Truy cập tập dữ liệu có cấu trúc: Truy cập trực tiếp DataFrame pandas thông qua dataset.meta.episodes
• Thống kê theo từng tập: Theo dõi thống kê nâng cao ở cấp độ tập

🚀 Nâng cao hiệu năng

• Truy cập ánh xạ bộ nhớ: Cải thiện việc sử dụng RAM thông qua ánh xạ bộ nhớ PyArrow
• Tải nhanh hơn: Giảm đáng kể thời gian khởi tạo bộ dữ liệu
• Khả năng mở rộng tốt hơn: Được thiết kế cho các bộ dữ liệu có hàng triệu tập

Yêu cầu tiên quyết

Trước khi chuyển các bộ dữ liệu lớn, hãy đảm bảo bạn có:

• LeRobot đã được cài đặt với hỗ trợ v3.0. Hãy làm theo Hướng dẫn cài đặt của chúng tôi.
• Đủ dung lượng lưu trữ: Dữ liệu thô có thể rất lớn (ví dụ: DROID yêu cầu 2TB)
• Truy cập cụm (khuyến nghị cho các bộ dữ liệu lớn): SLURM hoặc trình lập lịch công việc tương tự
• Các phụ thuộc cụ thể cho bộ dữ liệu: Đối với DROID, bạn sẽ cần các tiện ích TensorFlow Dataset

Hiểu về bộ dữ liệu DROID

DROID 1.0.1 là một ví dụ tuyệt vời về bộ dữ liệu robot quy mô lớn:

• Kích thước: 1.7TB (định dạng RLDS), 8.7TB (dữ liệu thô)
• Cấu trúc: 2048 shard dữ liệu TensorFlow được định nghĩa trước
• Nội dung: Hơn 76.000 quỹ đạo thao tác robot từ các robot Franka Emika Panda
• Phạm vi: Các thao tác thực tế trong nhiều môi trường và đối tượng
• Định dạng: Ban đầu ở định dạng TensorFlow Records/RLDS, cần chuyển đổi sang định dạng LeRobot
• Hosting: Google Cloud Storage với quyền truy cập công khai thông qua gsutil

Bộ dữ liệu chứa các bản demo thao tác đa dạng với:

• Nhiều góc nhìn từ camera (camera cổ tay, camera bên ngoài)
• Mô tả tác vụ ngôn ngữ tự nhiên
• Trạng thái cảm nhận bản thân và các hành động của robot
• Ghi chú thành công/thất bại

Sơ đồ tính năng 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
}

Cách tiếp cận 1: Chuyển đổi sang máy tính đơn

Bước 1: Cài đặt các phụ thuộc

Cụ thể đối với DROID:

pip install tensorflow
pip install tensorflow_datasets

Đối với các bộ dữ liệu khác, hãy cài đặt các trình đọc phù hợp với định dạng nguồn của bạn.

Bước 2: Tải xuống dữ liệu thô

Tải DROID từ Google Cloud Storage bằng 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/

Bộ dữ liệu lớn đòi hỏi thời gian và dung lượng lưu trữ đáng kể:

• Toàn bộ DROID (1,7TB): Mất vài ngày để tải xuống tùy thuộc vào băng thông
• Thời gian xử lý: 7+ ngày để chuyển đổi cục bộ toàn bộ bộ dữ liệu
• Thời gian tải lên: 3+ ngày để đẩy lên Hugging Face Hub
• Lưu trữ cục bộ: ~400GB cho định dạng LeRobot đã xử lý

Bước 3: Chuyển đổi Bộ dữ liệu

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

Phát triển và Kiểm thử

Để phát triển, bạn có thể chuyển đổi một shard duy nhất:

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

Cách tiếp cận này hoạt động tốt với các bộ dữ liệu nhỏ hoặc để kiểm thử, nhưng các bộ dữ liệu lớn đòi hỏi phải tính toán trên cụm (cluster computing).

Cách tiếp cận 2: Chuyển đổi sang cụm SLURM (Được khuyến nghị)

Đối với các bộ dữ liệu lớn như DROID, xử lý song song trên nhiều nút giúp giảm đáng kể thời gian xử lý.

Bước 1: Cài đặt các phụ thuộc của cụm

pip install datatrove  # Hugging Face's distributed processing library

Bước 2: Cấu hình môi trường SLURM của bạn

Tìm thông tin phân vùng của bạn:

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

Chọn một phân vùng CPU - không cần GPU để chuyển đổi bộ dữ liệu.

Bước 3: Khởi chạy các công việc chuyển đổi song song

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

Hướng dẫn về tham số

• --workers: Số lượng công việc chạy song song (tối đa 2048 đối với số shard của DROID)
• --cpus-per-task: Khuyến nghị 8 CPU để song song hóa mã hóa khung hình
• --mem-per-cpu: ~16GB RAM tổng (8×1950M) để nạp các khung hình thô

Bắt đầu với ít worker hơn (ví dụ: 100) để kiểm tra cấu hình cụm của bạn trước khi khởi chạy hàng nghìn tác vụ.

Bước 4: Theo dõi tiến độ

Kiểm tra các tác vụ đang chạy:

squeue -u $USER

Theo dõi tiến độ tổng thể:

jobs_status /your/logs

Kiểm tra nhật ký của từng công việc:

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

Gỡ lỗi các công việc thất bại:

failed_logs /your/logs/port_droid

Bước 5: Tổng hợp các Shard

Khi tất cả các công việc chuyển đổi hoàn tất:

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

Bước 6: Tải lên 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 sử dụng ít worker hơn (50) vì nó bị giới hạn bởi mạng lưới thay vì sức mạnh tính toán.

Cấu trúc tệp của Dataset v3.0

Bộ dữ liệu hoàn chỉnh của bạn sẽ có cấu trúc hiện đại như sau:

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

Điều này thay thế cấu trúc cũ mỗi tập một tệp bằng các khối có kích thước tối ưu và hiệu quả.

Chuyển đổi từ Dataset v2.1

Nếu bạn có các bộ dữ liệu hiện có ở định dạng v2.1, hãy sử dụng công cụ di chuyển:

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

Điều này tự động:

• Chuyển đổi cấu trúc tệp sang định dạng v3.0
• Chuyển đổi metadata từ JSON Lines sang parquet
• Tổng hợp thống kê và tạo thống kê cho từng tập
• Cập nhật thông tin phiên bản

Lợi ích về hiệu năng

Dataset v3.0 cung cấp những cải tiến đáng kể cho các bộ dữ liệu lớn:

• Tải nhanh hơn: Giảm 3-5 lần thời gian khởi tạo
• Hiệu quả bộ nhớ: Sử dụng RAM tốt hơn thông qua ánh xạ bộ nhớ
• Xử lý có khả năng mở rộng: Xử lý hiệu quả hàng triệu tập
• Tối ưu hóa lưu trữ: Giảm số lượng tệp và cải thiện nén