Hugging Face's logo

LeRobot documentation

대형 데이터셋을 LeRobot Dataset v3.0으로 이식하기

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.6.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

대형 데이터셋을 LeRobot Dataset v3.0으로 이식하기

이 튜토리얼은 대규모 로봇 데이터셋을 LeRobot Dataset v3.0 형식으로 이식하는 방법을 설명합니다. 수천 개의 샤드가 SLURM 클러스터에 걸쳐 있는 테라바이트급 데이터셋을 처리하는 방법을 보여주는 DROID 1.0.1 데이터셋을 주요 예제로 사용합니다.

파일 구성: v2.1 vs v3.0

Dataset v3.0은 데이터의 조직 및 저장 방식을 근본적으로 변경합니다:

v2.1 구조(에피소드 기반):

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 구조(파일 기반):

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

개별 에피소드 파일에서 파일 기반 청크로의 전환은 성능을 크게 향상시키고 저장 오버헤드를 줄입니다.

Dataset v3.0의 새로운 기능

Dataset v3.0은 대규모 데이터셋 처리를 위한 상당한 개선 사항을 도입합니다:

🏗️ 향상된 파일 구성

  • 파일 기반 구조: 에피소드가 개별 에피소드 파일이 아닌 청크된 파일로 그룹화됩니다
  • 구성 가능한 파일 크기: 데이터 및 비디오 파일용
  • 저장 효율 향상: 더 나은 압축 및 오버헤드 감소

📊 현대적인 메타데이터 관리

  • Parquet 기반 메타데이터: JSON Lines를 효율적인 parquet 형식으로 대체
  • 구조화된 에피소드 접근: 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 포맷으로 변환이 필요합니다
  • 호스팅: gsutil을 통해 공개 액세스가 가능한 Google Cloud Storage

데이터셋에는 다음과 같은 다양한 조작 데모가 포함되어 있습니다:

  • 여러 카메라 뷰(손목 카메라, 외부 카메라)
  • 자연어 작업 설명
  • 로봇의 고유수용성 상태와 동작
  • 성공/실패 주석

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
}

접근 방식 1: 단일 컴퓨터 이식

1단계: 종속성 설치

DROID의 경우:

pip install tensorflow
pip install tensorflow_datasets

다른 데이터셋의 경우, 소스 형식에 맞는 적절한 리더를 설치하세요.

2단계: 원시 데이터 다운로드

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

3단계: 데이터셋 이식

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

이 접근법은 작은 데이터셋이나 테스트에는 적합하지만, 큰 데이터셋에는 클러스터 컴퓨팅이 필요합니다.

접근 방식 2: SLURM 클러스터 이식 (권장)

DROID와 같은 대규모 데이터셋의 경우, 여러 노드에 걸친 병렬 처리를 통해 처리 시간을 크게 줄일 수 있습니다.

1단계: 클러스터 종속성 설치

pip install datatrove  # Hugging Face's distributed processing library

2단계: SLURM 환경 구성

파티션 정보를 확인하세요:

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

GPU 없이 데이터셋 이식이 가능하므로 CPU 파티션을 선택합니다.

3단계: 병렬 포트링 작업 시작

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)

수천 개의 작업을 시작하기 전에 클러스터 구성을 테스트하려면 워커 수를 적게(예: 100개) 설정하여 시작하세요.

4단계: 진행 상황 모니터링

실행 중인 작업 확인:

squeue -u $USER

전체 진행 상황 모니터링:

jobs_status /your/logs

개별 작업 로그를 확인합니다:

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

Debug failed jobs:

failed_logs /your/logs/port_droid

5단계: 샤드 집계

모든 포트링 작업이 완료되면:

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

6단계: 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은 계산이 아닌 네트워크에 의존적이므로 더 적은 워커(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/scripts/convert_dataset_v21_to_v30.py \
    --repo-id your_id/existing_dataset

이것은 자동으로 다음을 수행합니다:

  • 파일 구조를 v3.0 형식으로 변환합니다
  • JSON Lines에서 parquet로 메타데이터를 마이그레이션합니다
  • 통계를 집계하고 에피소드별 통계를 생성합니다
  • 버전 정보 업데이트

성능 이점

Dataset v3.0은 대규모 데이터셋에 대해 상당한 개선 사항을 제공합니다:

  • 더 빠른 로딩: 초기화 시간 3~5배 단축
  • 메모리 효율성: 메모리 매핑을 통한 더 나은 RAM 사용
  • 확장 가능한 처리: 수백만 개의 에피소드를 효율적으로 처리합니다
  • 스토리지 최적화: 파일 수 감소 및 압축률 향상
Update on GitHub

←학습 데이터 스트리밍 Dataset Tools 사용→