`LeRobotDataset:v3.0`: Bringing large-scale datasets to `lerobot`

📝 요약

Hugging Face는 로봇 학습을 위한 표준화된 데이터셋 형식인 `LeRobotDataset`의 v3.0을 출시했습니다. 이 업데이트는 여러 에피소드를 단일 파일에 묶고 관계형 메타데이터를 사용하여 파일 시스템 확장성 문제를 해결하며, 대규모 데이터셋을 즉석에서 처리할 수 있는 스트리밍 모드를 지원합니다. `lerobot` 라이브러리를 통해 이 새로운 형식은 로봇 공학 데이터에 대한 액세스를 개선하고 커뮤니티가 대규모 데이터셋으로 훈련할 수 있도록 지원합니다.

---

TL;DR 오늘 LeRobotDataset:v3를 출시합니다! 이전 LeRobotDataset:v2 릴리스에서는 에피소드당 하나의 파일을 저장했는데, 수백만 개의 에피소드로 데이터셋을 확장할 때 파일 시스템 제한에 부딪혔습니다. LeRobotDataset:v3는 관계형 메타데이터를 사용하여 여러 에피소드 파일에서 개별 에피소드 수준의 정보를 검색하면서 여러 에피소드를 단일 파일에 묶습니다. 새 형식은 스트리밍 모드에서 데이터셋에 액세스하는 것을 기본적으로 지원하여 대규모 데이터셋을 즉석에서 처리할 수 있습니다. LeRobotDataset 형식의 모든 데이터셋을 새 형식으로 변환하는 한 줄 유틸리티를 제공하며, 다음 안정적인 릴리스 전에 이 이정표를 커뮤니티와 공유하게 되어 매우 기쁩니다!

LeRobotDataset, v3.0

LeRobotDataset은 로봇 학습의 특정 요구 사항을 해결하도록 설계된 표준화된 데이터셋 형식이며, 센서 운동 판독, 여러 카메라 피드 및 원격 조작 상태를 포함한 모달리티 전반에 걸쳐 로봇 공학 데이터에 대한 통합되고 편리한 액세스를 제공합니다. 또한 당사의 데이터셋 형식은 수집되는 데이터 방식에 대한 일반 정보(메타데이터)를 저장하며, 수행되는 작업에 대한 텍스트 설명, 사용된 로봇 종류 및 이미지와 로봇 상태 스트림이 샘플링되는 초당 프레임과 같은 측정 세부 정보가 포함됩니다. 메타데이터는 Hugging Face Hub에서 로봇 공학 데이터셋을 인덱싱하고 검색하는 데 유용합니다!

Hugging Face에서 개발 중인 로봇 공학 라이브러리인 lerobot 내에서 LeRobotDataset은 다중 모달, 시계열 데이터를 처리하기 위한 통합 인터페이스를 제공하며, Hugging Face 및 Pytorch 생태계와 원활하게 통합됩니다. 이 데이터셋 형식은 쉽게 확장 및 사용자 정의할 수 있도록 설계되었으며, SO-100 팔 및 ALOHA-2 설정과 같은 조작기 플랫폼, 실제 휴머노이드 데이터, 시뮬레이션 데이터셋, 심지어 자율 주행 자동차 데이터까지 광범위한 실체에서 공개적으로 사용 가능한 데이터셋을 이미 지원합니다! 데이터셋 시각화 도구를 사용하여 커뮤니티가 기여한 현재 데이터셋을 탐색할 수 있습니다! 🔗

이 LeRobotDataset의 새 릴리스는 규모 외에도 스트리밍 기능을 지원하여 디스크에 지나치게 큰 데이터 모음을 다운로드할 필요 없이 대규모 데이터셋에서 즉석으로 데이터 배치를 처리할 수 있습니다. 전용 StreamingLeRobotDataset 인터페이스를 사용하여 v3.0의 모든 데이터셋에 스트리밍 모드로 액세스하고 사용할 수 있습니다! 스트리밍 데이터셋은 로봇 학습에 대한 액세스를 높이는 데 중요한 이정표이며, 커뮤니티와 공유하게 되어 기쁩니다 🤗

에피소드 기반에서 파일 기반 데이터셋으로

Hugging Face Hub에서 즉석 처리를 위해 데이터셋 스트리밍을 직접 지원합니다.

lerobot 설치 및 데이터셋 기록

lerobot은 Hugging Face에서 개발한 엔드 투 엔드 로봇 공학 라이브러리로, 실제 로봇 공학 및 최첨단 로봇 학습 알고리즘을 지원합니다. 이 라이브러리를 사용하면 실제 로봇에서 로컬로 데이터셋을 직접 기록하고 Hugging Face Hub에 데이터셋을 저장할 수 있습니다. 현재 지원하는 로봇에 대해 여기에서 자세히 알아볼 수 있습니다!

LeRobotDataset:v3은 lerobot 라이브러리의 일부로 lerobot-v0.4.0부터 제공될 예정이며, 커뮤니티와 조기에 공유하게 되어 매우 기쁩니다. 다음 PyPI를 사용하여 이 새 데이터셋 형식을 지원하는 최신 lerobot-v0.3.x를 직접 설치할 수 있습니다:

pip install "https://github.com/huggingface/lerobot/archive/33cad37054c2b594ceba57463e8f11ee374fa93c.zip"  # This will affect your local lerobot installation!

커뮤니티의 라이브러리 안정적인 릴리스를 향한 진행 상황을 여기에서 팔로우하세요 🤗

새 데이터셋 형식을 지원하는 lerobot 버전을 설치한 후에는 다음과 같은 지침과 함께 원격 조작을 사용하여 시그니처 로봇 팔인 SO-101로 데이터셋을 기록할 수 있습니다:

lerobot-record \
    --robot.type=so101_follower \
    --robot.port=/dev/tty.usbmodem585A0076841 \
    --robot.id=my_awesome_follower_arm \
    --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}}" \
    --teleop.type=so101_leader \
    --teleop.port=/dev/tty.usbmodem58760431551 \
    --teleop.id=my_awesome_leader_arm \
    --display_data=true \
    --dataset.repo_id=${HF_USER}/record-test \
    --dataset.num_episodes=5 \
    --dataset.single_task="Grab the black cube"

사용 사례에 대한 데이터셋 기록 방법을 보려면 공식 문서로 이동하세요.

(새로운) 형식 디자인

LeRobotDataset의 핵심 디자인 선택은 기본 데이터 저장과 사용자 대면 API를 분리하는 것입니다. 이를 통해 효율적인 직렬화 및 저장과 동시에 데이터를 직관적이고 즉시 사용할 수 있는 형식으로 제공할 수 있습니다. 데이터셋은 세 가지 주요 구성 요소로 구성됩니다.

1. 테이블 데이터: 조인트 상태 및 액션과 같은 저차원, 고빈도 데이터는 효율적인 Apache Parquet 파일에 저장되며 일반적으로 성숙한 datasets 라이브러리로 오프로드되어 빠르고 메모리 매핑된 액세스 또는 스트리밍 기반 액세스를 제공합니다.
2. 시각 데이터: 대량의 카메라 데이터를 처리하기 위해 프레임이 연결되고 MP4 파일로 인코딩됩니다. 동일한 에피소드의 프레임은 항상 동일한 비디오로 그룹화되며, 여러 비디오는 카메라별로 그룹화됩니다. 파일 시스템에 대한 스트레스를 줄이기 위해 동일한 카메라 보기에 대한 비디오 그룹도 여러 하위 디렉토리로 나뉩니다.
3. 메타데이터: 데이터의 테이블 및 시각적 차원에 대한 관계형 대응 역할을 하는 데이터셋의 구조를 설명하는 JSON 파일 모음입니다. 메타데이터에는 다양한 기능 스키마, 프레임 속도, 정규화 통계 및 에피소드 경계가 포함됩니다.

잠재적으로 수백만 개의 에피소드(수억/수십억 개의 개별 프레임으로 이어짐)가 포함될 수 있는 데이터셋을 지원하기 위해 다른 에피소드의 데이터를 동일한 높은 수준의 구조로 병합합니다. 구체적으로 이는 주어진 테이블 컬렉션과 비디오가 단일 에피소드에 대한 정보만 포함하는 것이 아니라 여러 에피소드에서 사용 가능한 정보의 연결을 포함한다는 것을 의미합니다. 이는 로컬 및 Hugging Face와 같은 원격 저장소 제공 업체 모두에서 파일 시스템에 대한 압력을 관리 가능하게 유지합니다. 그런 다음 메타데이터를 활용하여 특정 에피소드 정보, 예를 들어 주어진 에피소드가 특정 비디오에서 시작하거나 끝나는 타임스탬프를 수집할 수 있습니다.

데이터셋은 다음과 같은 리포지토리로 구성됩니다.

• meta/info.json: 중앙 메타데이터 파일입니다. 모든 기능(예: observation.state, action), 해당 모양 및 데이터 유형을 정의하는 전체 데이터셋 스키마를 포함합니다. 또한 데이터 및 비디오 파일을 찾기 위한 경로 템플릿, 데이터셋의 초당 프레임(fps), 코드베이스 버전과 같은 중요한 정보도 저장합니다.
• meta/stats.json: 전체 데이터셋에서 각 기능의 집계 통계(평균, 표준 편차, 최소, 최대)를 저장합니다. 이는 데이터 정규화에 사용되며 dataset.meta.stats를 통해 액세스할 수 있습니다.
• meta/tasks.jsonl: 자연어 작업 설명과 정수 작업 인덱스 간의 매핑을 포함하며, 이는 작업 조건부 정책 훈련에 사용됩니다.
• meta/episodes/: 이 디렉토리에는 길이, 해당 작업 및 데이터가 저장된 위치에 대한 포인터와 같은 각 개별 에피소드에 대한 메타데이터가 포함되어 있습니다. 확장성을 위해 이 정보는 단일 대형 JSON 파일이 아닌 청크화된 Parquet 파일에 저장됩니다.
• data/: Parquet 파일에 있는 핵심 프레임별 테이블 데이터를 포함합니다. 성능을 개선하고 대규모 데이터셋을 처리하기 위해 여러 에피소드의 데이터가 더 큰 파일로 연결됩니다. 파일 크기를 관리 가능하게 유지하기 위해 이러한 파일은 청크화된 하위 디렉토리에 구성됩니다. 따라서 단일 파일에는 일반적으로 하나 이상의 에피소드에 대한 데이터가 포함됩니다.
• videos/: 모든 시각적 관찰 스트림에 대한 MP4 비디오 파일을 포함합니다. data/ 디렉토리와 유사하게 여러 에피소드의 비디오 영상이 단일 MP4 파일로 연결됩니다. 이 전략은 최신 파일 시스템에 더 효율적인 데이터셋의 파일 수를 크게 줄입니다. 경로 구조(/videos/<camera_key>/<chunk>/file_...mp4)를 통해 데이터 로더는 올바른 비디오 파일을 찾고 지정된 프레임에 대한 정확한 타임스탬프로 탐색할 수 있습니다.

v2.1 데이터셋을 v3.0으로 마이그레이션

LeRobotDataset:v3.0은 lerobot-v0.4.0과 함께 릴리스될 예정이며, Hugging Face Hub에 현재 호스팅된 모든 데이터셋을 새 v3.0으로 쉽게 변환할 수 있습니다.

python -m lerobot.datasets.v30.convert_dataset_v21_to_v30--repo-id=<HFUSER/DATASET_ID>

이 새 형식을 커뮤니티와 조기에 공유하게 되어 매우 기쁩니다! lerobot-v0.4.0을 개발하는 동안 최신 lerobot-v0.3.x를 사용하여 데이터셋을 새로 업데이트된 버전으로 계속 변환할 수 있으며, 이는 다음 PyPI를 통해 직접 지원됩니다.

pip install "https://github.com/huggingface/lerobot/archive/33cad37054c2b594ceba57463e8f11ee374fa93c.zip"  # This will affect your local lerobot installation!
python -m lerobot.datasets.v30.convert_dataset_v21_to_v30 --repo-id=<HFUSER/DATASET_ID>

이는 사전 릴리스이며 일반적으로 불안정한 버전임을 참고하세요. 다음 안정적인 릴리스 개발 상태를 여기에서 팔로우할 수 있습니다!

변환 스크립트 convert_dataset_v21_to_v30.py는 여러 에피소드 episode-0000.mp4, episode-0001.mp4, episode-0002.mp4, .../episode-0000.parquet, episode-0001.parquet, episode-0002.parquet, episode-0003.parquet, ...를 단일 파일 file-0000.mp4/file-0000.parquet로 집계하고 메타데이터를 적절히 업데이트하여 상위 수준 파일에서 특정 에피소드 정보를 검색할 수 있도록 합니다.

코드 예제: LeRobotDataset을 torch.utils.data.DataLoader와 함께 사용

세 가지 주요 기둥(테이블 및 시각 데이터, 관계형 메타데이터)을 모두 포함하는 Hugging Face Hub의 모든 데이터셋은 한 줄로 액세스할 수 있습니다.

강화 학습(RL) 또는 행동 복제(BC)를 기반으로 하는 대부분의 로봇 학습 알고리즘은 관찰 및 행동 스택에서 작동하는 경향이 있습니다. 예를 들어, RL 알고리즘은 일반적으로 이전 관찰의 기록 o_{t-H_o:t}을 사용하고, BC 알고리즘은 대신 여러 행동의 청크를 회귀하도록 훈련됩니다. 로봇 학습 훈련의 특정 사항을 수용하기 위해 LeRobotDataset은 기본 창 연산를 제공하며, 이를 통해 delta_timestamps 인수를 사용하여 특정 관찰 이전 및 이후의 초를 사용할 수 있습니다.

편리하게도 LeRobotDataset을 PyTorch DataLoader와 함께 사용하면 데이터셋의 개별 샘플 사전 모음을 자동으로 일괄 텐서의 단일 사전으로 집계할 수 있습니다.

from lerobot.datasets.lerobot_dataset import LeRobotDataset

repo_id = "yaak-ai/L2D-v3"

# Hugging Face Hub에서 로드 (로컬에 캐시됨)
dataset = LeRobotDataset(repo_id)

# 인덱스로 데이터셋의 100번째 프레임 가져오기
sample = dataset[100]
print(sample)
# 샘플은 텐서 사전입니다.
# {
#     'observation.state': tensor([...]),
#     'action': tensor([...]),
#     'observation.images. front_left': tensor([C, H, W]),
#     'timestamp': tensor(1.234),
#     ...
# }
delta_timestamps = {
    "observation.images.front_left": [-0.2, -0.1, 0.0]  # 관찰 전 0.2 및 0.1초
}
dataset = LeRobotDataset(
    repo_id
    delta_timestamps=delta_timestamps
)

# 이제 인덱스에 액세스하면 지정된 키에 대한 프레임 스택이 반환됩니다.
sample = dataset[100]

# 이미지 텐서에 이제 시간 차원이 있습니다.
# 'observation.images.wrist_camera'는 T=3인 [T, C, H, W] 형태입니다.
print(sample['observation.images.front_left'].shape)

batch_size=16
# 훈련 목적으로 배치로 처리하기 위해 데이터셋을 DataLoader로 래핑합니다.
data_loader = torch.utils.data.DataLoader(
    dataset,
    batch_size=batch_size
)

# 3. 훈련 루프에서 DataLoader를 반복합니다.
num_epochs = 1
device = "cuda" if torch.cuda.is_available() else "cpu"

for epoch in range(num_epochs):
    for batch in data_loader:
        # 'batch'는 각 값이 텐서 배치인 사전입니다.
        # 예를 들어, batch['action']은 [32, action_dim] 형태가 됩니다.

        # delta_timestamps를 사용하는 경우 배치 이미지 텐서의
        # 형태는 [32, T, C, H, W]가 될 수 있습니다.

        # 데이터를 적절한 장치(예: GPU)로 이동합니다.
        observations = batch['observation.state.vehicle'].to(device)
        actions = batch['action.continuous'].to(device)
        images = batch['observation.images.front_left'].to(device)

        # 다음으로 amazing_model.forward(batch)를 수행합니다.
        ...

스트리밍

데이터셋을 로컬에 다운로드하지 않고 v3.0 형식의 모든 데이터셋을 스트리밍 모드로 사용할 수도 있습니다. StreamingLeRobotDataset 클래스를 사용하면 됩니다.

from lerobot.datasets.streaming_dataset import StreamingLeRobotDataset
# 데이터셋을 디스크에 다운로드하거나 메모리에 로드하지 않고 Hugging Face Hub에서 직접 스트리밍
repo_id = "yaak-ai/L2D-v3"
dataset = StreamingLeRobotDataset(repo_id)

결론

LeRobotDataset v3.0은 LeRobot에서 지원하는 로봇 공학 데이터셋을 확장하기 위한 디딤돌입니다. 대규모 로봇 데이터 모음을 저장하고 액세스하는 형식을 제공함으로써 로봇 공학을 민주화하는 데 진전을 이루고 있으며, 커뮤니티가 데이터를 전혀 다운로드하지 않고도 수백만 개의 에피소드에 대해 훈련할 수 있도록 합니다!

최신 lerobot-v0.3.x를 설치하여 새 데이터셋 형식을 사용해 볼 수 있으며, GitHub 또는 Discord 서버에서 피드백을 공유해 주세요! 🤗

감사

LeRobotDataset:v3 개발 중 귀중한 지원과 피드백을 제공해 준 fantastic yaak.ai 팀에게 감사드립니다. Hugging Face Hub에서 해당 조직을 팔로우하세요! 우리는 항상 커뮤니티와 협력하고 초기 기능을 공유하기를 원합니다. 협업을 원하시면 문의해 주세요 😊

---

원문 출처: https://huggingface.co/blog/lerobot-datasets-v3