🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

LeRobotDataset v3.0은 여러 로봇 에피소드를 하나의 데이터·영상 파일로 묶고 관계형 메타데이터로 개별 에피소드를 찾아내는 구조를 도입해, 대규모 데이터셋의 파일 시스템 부담을 줄이고 스트리밍 처리를 지원합니다.

📌 핵심 요약

• 기존 v2의 에피소드당 파일 하나 구조는 에피소드가 수백만 개로 늘어날 때 파일 수가 폭증하는 한계가 있었으며, v3.0은 여러 에피소드의 표 형식 데이터와 영상을 더 큰 파일로 통합해 이를 해결합니다.
• 데이터셋은 저차원·고빈도 값을 담는 Parquet 기반 표 형식 데이터, 카메라 프레임을 인코딩한 MP4 영상, 스키마·통계·작업·에피소드 경계를 기록하는 관계형 메타데이터로 구성됩니다.
• 메타데이터에는 각 에피소드의 길이와 작업, 데이터 위치, 영상 시작·종료 시점 등이 기록되어 있어 여러 에피소드가 합쳐진 파일에서도 필요한 구간을 정확히 검색할 수 있습니다.
• v3.0은 StreamingLeRobotDataset을 통해 Hugging Face Hub의 대규모 데이터셋을 전부 로컬 디스크에 내려받지 않고도 순차적으로 처리할 수 있도록 지원합니다.
• 기존 v2.1 데이터셋은 제공된 변환 모듈로 v3.0 구조로 이전할 수 있으며, LeRobotDataset은 인덱스 접근, 시간 윈도잉, PyTorch DataLoader 배치 구성을 위한 통합 API를 제공합니다.

🧩 주요 포인트

1. 기존 v2의 에피소드당 파일 하나 구조는 에피소드가 수백만 개로 늘어날 때 파일 수가 폭증하는 한계가 있었으며, v3.0은 여러 에피소드의 표 형식 데이터와 영상을 더 큰 파일로 통합해 이를 해결합니다.
2. 데이터셋은 저차원·고빈도 값을 담는 Parquet 기반 표 형식 데이터, 카메라 프레임을 인코딩한 MP4 영상, 스키마·통계·작업·에피소드 경계를 기록하는 관계형 메타데이터로 구성됩니다.
3. 메타데이터에는 각 에피소드의 길이와 작업, 데이터 위치, 영상 시작·종료 시점 등이 기록되어 있어 여러 에피소드가 합쳐진 파일에서도 필요한 구간을 정확히 검색할 수 있습니다.
4. v3.0은 StreamingLeRobotDataset을 통해 Hugging Face Hub의 대규모 데이터셋을 전부 로컬 디스크에 내려받지 않고도 순차적으로 처리할 수 있도록 지원합니다.
5. 기존 v2.1 데이터셋은 제공된 변환 모듈로 v3.0 구조로 이전할 수 있으며, LeRobotDataset은 인덱스 접근, 시간 윈도잉, PyTorch DataLoader 배치 구성을 위한 통합 API를 제공합니다.

🧠 상세 정리

1. v3.0 공개 배경과 기존 형식의 확장성 한계

LeRobotDataset v3.0의 핵심 목적은 로봇 학습 데이터셋이 수백만 개의 에피소드로 확장될 때 발생하는 파일 시스템 한계를 해결하는 것입니다. 이전 v2 형식은 에피소드마다 별도의 데이터 파일과 영상 파일을 저장했기 때문에, 에피소드 수가 늘어날수록 로컬 파일 시스템과 Hugging Face 같은 원격 저장소가 관리해야 하는 파일 수도 함께 폭증했습니다. v3.0은 여러 에피소드의 내용을 하나의 상위 Parquet 파일과 MP4 파일에 연속적으로 저장하고, 개별 에피소드의 위치와 경계를 별도의 관계형 메타데이터로 관리합니다. 이 방식은 에피소드 단위 접근 능력을 유지하면서도 저장 파일의 총수를 크게 줄여, 수억 또는 수십억 개 프레임을 포함할 수 있는 데이터셋을 다룰 수 있도록 설계되었습니다. 또한 새 형식은 단순한 저장 구조 변경에 그치지 않고, 대규모 데이터셋을 내려받지 않은 채 처리하는 스트리밍 기능을 기본적으로 지원합니다.

2. 로봇 학습을 위한 표준화된 다중 모달 데이터 인터페이스

LeRobotDataset은 로봇 학습에 필요한 센서·운동 데이터, 여러 카메라 영상, 행동 값, 텔레오퍼레이션 상태를 하나의 표준 형식으로 다루기 위한 데이터셋 규격입니다. 데이터 자체뿐 아니라 수행한 작업의 자연어 설명, 사용한 로봇 종류, 영상과 로봇 상태가 측정된 초당 프레임 수 같은 수집 조건도 메타데이터로 보존합니다. 이러한 정보는 Hugging Face Hub에서 로봇 데이터셋을 색인하고 검색하는 데 사용되며, 서로 다른 플랫폼에서 수집한 데이터를 일관된 방식으로 찾고 해석할 수 있게 합니다. lerobot 라이브러리 안에서는 다중 모달 시계열 데이터를 다루는 통합 인터페이스를 제공하고, Hugging Face 생태계 및 PyTorch 기반 학습 과정과 연결됩니다. 현재 형식은 SO-100 계열 로봇 팔과 ALOHA-2, 실제 휴머노이드 데이터, 시뮬레이션 데이터, 자율주행 자동차 데이터처럼 서로 다른 형태의 공개 데이터셋을 지원하도록 확장 가능하게 구성되어 있습니다.

3. 스트리밍 지원과 데이터 기록 절차

v3.0에서는 StreamingLeRobotDataset 인터페이스를 통해 Hugging Face Hub에 있는 데이터셋을 스트리밍 방식으로 사용할 수 있습니다. 따라서 저장 용량이 매우 큰 데이터 컬렉션 전체를 먼저 로컬 디스크에 내려받지 않아도, 필요한 데이터를 순차적으로 읽어 배치 단위로 처리할 수 있습니다. 이 기능은 대규모 데이터셋의 로컬 저장 부담을 줄이고, Hub에서 직접 데이터를 공급받는 처리 흐름을 가능하게 하는 변화로 소개됩니다. v3.0은 정식으로 lerobot-v0.4.0에 포함될 예정이며, 글에서는 새 형식을 미리 사용하기 위한 특정 lerobot-v0.3.x 소스 설치 명령도 제공합니다. 설치 후에는 lerobot-record 명령에 SO-101 follower와 leader 포트, 카메라 설정, 작업 설명, 저장할 Hub 저장소 ID 및 에피소드 수를 지정해 실제 로봇의 텔레오퍼레이션 데이터를 기록할 수 있습니다.

4. 저장 구조와 사용자 API를 분리한 설계

새 형식의 중심 설계 원칙은 실제 데이터가 디스크에 직렬화되는 방식과 사용자가 데이터를 읽는 API를 분리하는 것입니다. 내부적으로는 저장 효율과 대규모 접근 성능에 적합한 파일 구성을 사용하지만, 사용자에게는 바로 학습에 투입할 수 있는 직관적인 샘플 인터페이스를 제공합니다. 전체 데이터셋은 표 형식 데이터, 시각 데이터, 관계형 메타데이터라는 세 축으로 구성됩니다. 관절 상태와 행동처럼 차원이 낮고 빈도가 높은 값은 Apache Parquet에 저장되어 메모리 매핑 또는 스트리밍 접근을 지원하고, 대용량 카메라 프레임은 연속적으로 결합한 뒤 MP4로 인코딩됩니다. JSON과 Parquet 기반 메타데이터는 두 데이터 축을 연결하면서 피처 스키마, 프레임률, 정규화 통계, 에피소드 경계 및 실제 파일 위치를 설명합니다.

5. 여러 에피소드를 하나의 파일에 통합하는 방식

v3.0에서는 하나의 표 형식 파일이나 영상 파일이 더 이상 단일 에피소드만을 나타내지 않으며, 여러 에피소드의 데이터를 순서대로 이어 붙인 내용을 담습니다. 영상의 경우 같은 에피소드에 속한 프레임은 동일한 비디오 안에 함께 배치되고, 같은 카메라 시점의 여러 비디오는 다시 그룹화되며, 파일 시스템의 부담을 줄이기 위해 여러 하위 디렉터리로 나뉩니다. 표 형식 데이터 역시 여러 에피소드의 프레임별 상태와 행동을 더 큰 Parquet 파일로 합친 뒤 관리 가능한 크기의 청크 디렉터리에 저장합니다. 개별 에피소드의 길이, 작업, 데이터가 저장된 파일, 영상에서의 시작·종료 시점은 메타데이터에 별도로 기록됩니다. 데이터 로더는 이 정보를 이용해 통합 파일을 찾고 정확한 행 범위나 영상 타임스탬프로 이동하므로, 물리적 저장 단위가 파일 중심으로 바뀌어도 논리적인 에피소드 단위 접근은 유지됩니다.

6. 저장소 디렉터리와 메타데이터의 역할

저장소의 meta/info.json은 전체 피처의 이름·형태·자료형을 정의하는 중심 스키마 파일이며, 데이터셋의 FPS, 코드베이스 버전, 데이터와 영상 파일을 찾기 위한 경로 템플릿도 담습니다. meta/stats.json은 각 피처의 평균, 표준편차, 최솟값, 최댓값 같은 전체 데이터셋 통계를 보관하고, 이 값은 dataset.meta.stats를 통해 정규화 과정에 사용할 수 있습니다. meta/tasks.jsonl은 자연어 작업 설명과 정수 작업 인덱스의 대응 관계를 기록해 작업 조건부 정책 학습에 활용됩니다. meta/episodes/에는 각 에피소드의 길이와 작업, 실제 데이터 위치를 가리키는 포인터가 저장되며, 확장성을 위해 하나의 거대한 JSON 대신 청크 형태의 Parquet 파일을 사용합니다. 실제 프레임별 값은 data/ 아래의 Parquet 파일에, 시각 관측은 videos/<camera_key>/<chunk>/file_...mp4 형태로 저장되어 로더가 올바른 파일과 정확한 영상 시점을 찾을 수 있습니다.

7. v2.1 데이터셋을 v3.0으로 변환하는 과정

기존 Hugging Face Hub의 v2.1 데이터셋은 lerobot.datasets.v30.convert_dataset_v21_to_v30 모듈에 저장소 ID를 전달하는 명령으로 새 형식에 맞게 변환할 수 있습니다. 변환 스크립트는 episode-0000.mp4, episode-0001.mp4처럼 에피소드마다 분리되어 있던 영상들을 file-0000.mp4와 같은 통합 파일로 묶습니다. 에피소드별 episode-0000.parquet, episode-0001.parquet 등의 표 형식 데이터도 마찬가지로 file-0000.parquet 같은 더 큰 파일로 집계합니다. 이때 단순히 파일만 합치는 것이 아니라, 통합된 상위 파일에서 각 에피소드의 정보를 다시 찾을 수 있도록 관련 메타데이터도 함께 갱신합니다. 글 작성 시점의 변환 기능은 차기 안정 버전에 앞서 공개된 사전 릴리스에 포함되어 있으며 일반적으로 불안정할 수 있다고 명시되어 있으므로, 제시된 개발 버전 설치가 기존 로컬 lerobot 설치에 영향을 준다는 주의 사항도 함께 안내됩니다.

8. LeRobotDataset API와 PyTorch 학습 데이터 구성

LeRobotDataset은 표 형식 데이터, 영상, 관계형 메타데이터라는 세 요소를 갖춘 Hub 데이터셋을 저장소 ID로 불러오는 통합 접근 방식을 제공합니다. 데이터셋을 생성한 뒤 정수 인덱스를 사용하면 해당 프레임의 observation.state, action, 카메라 이미지, 타임스탬프 등이 텐서 사전 형태로 반환됩니다. 로봇 학습에서는 강화학습이 이전 관측의 이력을 사용하거나 행동 복제가 여러 미래 행동을 하나의 청크로 예측하는 경우가 많기 때문에, API는 delta_timestamps를 이용한 시간 윈도잉을 기본 기능으로 제공합니다. 예를 들어 특정 카메라 키에 -0.2, -0.1, 0.0초를 지정하면 하나의 인덱스 접근으로 현재 관측과 그 이전 시점의 프레임 묶음을 받을 수 있고, 반환 영상에는 시간 차원이 추가됩니다. 이 데이터셋을 PyTorch DataLoader와 결합하면 개별 샘플의 사전들이 키별 배치 텐서로 자동 결합되어 강화학습이나 행동 복제 학습 과정에 사용할 수 있습니다.

🧾 핵심 주장 / 시사점

• v3.0의 핵심 변화는 에피소드를 독립 파일로 저장하는 규칙을 없앤 것이 아니라, 물리적 저장 단위를 여러 에피소드가 공유하는 파일로 바꾸고 메타데이터를 통해 논리적 에피소드 경계를 복원하도록 역할을 재배치한 데 있습니다.
• 표 형식 데이터와 영상은 대용량 처리에 적합한 Parquet·MP4로 저장하고, 검색과 해석에 필요한 스키마·통계·작업·경계 정보는 별도의 메타데이터로 관리함으로써 저장 효율과 사용자 접근성을 함께 유지합니다.
• 스트리밍, 시간 윈도잉, PyTorch 배치 구성이 동일한 데이터셋 인터페이스에 포함되어 있어, 대규모 원격 데이터 접근부터 로봇 학습용 시계열 샘플 구성까지 하나의 흐름으로 연결됩니다.

✅ 액션 아이템

• v2 에피소드당 파일 1개 구조가 만든 파일 수 폭증 한계를 v3.0 통합형 데이터·영상 파일 구조로 완화할 대상과 범위를 정한다.
• Parquet 표 데이터, MP4 영상, 관계형 메타데이터를 조합해 에피소드 길이·작업·영상 구간 조회 경로를 재현하고 정확도를 점검한다.
• v2.1 변환 모듈로 v3.0 이동 후 StreamingLeRobotDataset와 LeRobotDataset 인덱스·시간 윈도우·배치 API 통합 적합성을 비교한다.

❓ 열린 질문

• 메타데이터에서 에피소드 길이·작업·영상 시작·종료 시점을 어떤 조합 조건으로 조회하면 필요한 구간을 정확히 추출할 수 있는가?
• StreamingLeRobotDataset로 대규모 Hub 데이터셋을 순차 처리할 때 로컬 전체 동기화 없이도 성능 저하를 어느 수준까지 허용할 것인가?
• v3.0 전환 후 기존 PyTorch DataLoader 배치 동작과 시간 윈도우 해석이 동일하게 유지되는지 어떤 방식으로 확인할 수 있는가?