5.3 LeRobotDataset v3 설계

Hugging Face의 LeRobotDataset v3 문서는 v3의 핵심을 storage와 user-facing episode API의 분리로 설명한다. v2 계열의 episode당 파일 구조와 달리 v3는 여러 episode를 큰 Parquet/MP4 파일에 묶어 파일 수를 줄이고 metadata로 경계를 복원한다.

5.3.1 세 개의 기둥

1. Tabular data: state, action, timestamp처럼 저차원·고주파 신호를 Parquet에 저장한다.
2. Visual data: 카메라별 frame을 MP4 shard로 저장한다.
3. Relational metadata: schema, stats, task, episode 경계, file/row/video offset을 저장한다.

간소화한 구조는 다음과 같다.

dataset/
├── meta/
│   ├── info.json
│   ├── stats.json
│   ├── tasks.parquet
│   └── episodes/chunk-000/file-000.parquet
├── data/chunk-000/file-000.parquet
└── videos/
    ├── observation.images.top/chunk-000/file-000.mp4
    └── observation.images.wrist/chunk-000/file-000.mp4

문서 revision에 따라 tasks.jsonl처럼 이전 이름이 검색될 수 있으므로 경로를 직접 조립하지 말고 설치 버전의 API와 meta/info.json path template을 사용한다.

5.3.2 feature schema

예시 feature는 다음과 같다.

key	shape 예	dtype	의미
observation.state	[6]	float32	현재 관절/그리퍼 상태
action	[6]	float32	다음 target joint 또는 delta
observation.images.top	[3,H,W]	video	외부 카메라
observation.images.wrist	[3,H,W]	video	손목 카메라
timestamp	scalar	float64	episode 내 시간
episode_index	scalar	int	episode 식별자
task_index	scalar	int	언어 task 연결

shape만으로 충분하지 않다. joint order, unit, absolute/delta, camera color order, resize/crop, gripper sign convention을 dataset card에 기록한다.

5.3.3 episode 경계와 split

v3에서는 한 Parquet/MP4 shard 안에 여러 episode가 들어갈 수 있다. 파일 이름을 episode ID로 해석하면 안 된다. meta/episodes의 row range와 video offset으로 episode를 찾는다.

train/validation/test는 frame이 아니라 episode 단위로 분할한다. 같은 episode의 인접 frame이 train과 validation에 나뉘면 거의 동일한 이미지가 양쪽에 들어가 성능이 과대평가된다. 더 엄격한 일반화를 평가하려면 물체 위치, 배경, 작업자, 날짜 같은 group 단위로 분할한다.

5.3.4 finalize의 의미

v3 writer는 incremental Parquet writing과 metadata buffer를 사용한다. 수집 종료 후 finalize()를 호출해야 buffer를 flush하고 Parquet footer를 완성한다. 프로그램이 비정상 종료되면 최근 episode가 불완전할 수 있다. 공식 Dataset API는 finalize()를 생략한 dataset이 유효하지 않을 수 있다고 명시한다.