LeRobotDataset v3는 로봇의 상태·행동 같은 표 형식 신호를 Parquet에, 카메라 영상을 MP4에 저장하고, 여러 에피소드가 공유 파일 안에서 어디에 있는지를 메타데이터로 연결합니다. 파일 수를 줄이는 대신 오프셋과 시간축의 정확성이 더 중요해졌습니다. 이 글은 디렉터리 구조, 에피소드 복원, 기록 종료와 마이그레이션 검증을 설명합니다.
아래에서는 용어의 차이를 실제 시스템 경계, 실패 조건과 검증 순서로 나눠 살펴봅니다.
LeRobotDataset v3는 저장 파일과 사용자가 보는 에피소드 단위를 분리한다
Hugging Face LeRobotDataset v3 공식 문서는 v3를 다중 모달 시계열, 센서모터 신호, 다중 카메라 영상과 메타데이터를 통합해 접근하는 표준 형식으로 설명합니다. 여러 에피소드가 더 큰 파일을 공유해도 API는 에피소드 단위로 읽게 합니다.
로봇 행동 데이터가 무엇을 기록하는지 설명한다면, 이번 글은 그 기록을 v3 디렉터리와 파일, 오프셋으로 어떻게 저장하고 다시 에피소드로 복원하는지에 초점을 둡니다.
v2의 에피소드별 파일에서 v3의 파일 기반 shard로 바뀐 이유를 먼저 이해한다
에피소드마다 Parquet와 MP4 파일을 만들면 데이터가 커질수록 작은 파일 수가 폭발하고 초기화와 파일 시스템 메타데이터 처리 비용이 커집니다. v3는 여러 에피소드를 더 큰 파일에 이어 붙여 파일 수를 줄이고, 메타데이터가 각 에피소드 구간을 가리키게 합니다.
대신 파일명만 보고 에피소드를 찾을 수 없고, 시작·끝 오프셋과 길이가 정확해야 합니다. shard 하나가 손상될 때 여러 에피소드가 영향을 받을 수 있으므로 파일 해시와 복구 전략의 중요성도 커집니다.
| 구분 | v2 계열 | v3 | 운영 영향 |
|---|---|---|---|
| 데이터 파일 | 에피소드별 Parquet | 여러 에피소드/Parquet shard | 파일 수 감소·offset 필수 |
| 영상 파일 | 에피소드별 MP4 | 카메라별 MP4 shard | seek와 시간 매핑 중요 |
| 메타데이터 | 파일명 중심 연결 | 관계형 episode/task/offset | 무결성 검사 범위 확대 |
| 접근 | 파일 직접 탐색 용이 | API가 에피소드 뷰 복원 | 버전 호환성 확인 |
Parquet에는 상태·행동·타임스탬프처럼 고빈도 저차원 신호를 둔다
관절 위치와 속도, 로봇 상태, action, timestamp, episode index처럼 행과 열로 표현하기 좋은 신호가 Parquet에 들어갑니다. 각 feature의 이름, dtype, shape, 단위와 좌표계를 기록하지 않으면 숫자는 있어도 학습 가능한 행동이 되지 않습니다.
압축과 열 단위 접근은 필요한 feature만 읽는 데 유리하지만, 중첩 배열과 가변 길이 값을 무리하게 넣으면 도구 호환성이 떨어질 수 있습니다. 고정 shape와 명확한 결측 규칙을 정하고 실제 로더로 왕복 검증합니다.
MP4와 Parquet는 따로 저장되지만 메타데이터가 같은 에피소드 시간축으로 묶는다
카메라 프레임은 용량과 디코딩 효율 때문에 MP4로 인코딩하고, 관절·행동 신호는 Parquet에 둡니다. 사용자는 한 에피소드를 요청하지만 내부에서는 메타데이터가 데이터 행 구간과 각 카메라 영상의 시간 구간을 찾아 함께 반환합니다.
카메라 FPS가 제어 주기와 다르거나 프레임이 빠지면 단순 index 일치가 깨집니다. 원시 timestamp, 동기화 정책, 허용 지연과 누락 처리를 저장해야 행동과 관측이 실제 같은 순간을 가리킵니다.
info.json은 스키마와 경로 템플릿을 읽는 출발점이다
공식 문서는 meta/info.json에 feature 이름과 shape·dtype, FPS, 코드베이스 버전, data와 video shard를 찾는 경로 템플릿이 들어간다고 설명합니다. 로더는 이 정보를 기준으로 파일을 찾고 각 열을 해석합니다.
info.json만 복사해 데이터 열을 바꾸면 로더가 열리더라도 잘못된 shape나 의미를 반환할 수 있습니다. 데이터 생성 코드가 스키마를 단일 원천으로 쓰게 하고, 기록 시작 전에 센서와 action 형식을 고정합니다.
episode 메타데이터는 공유 파일 안의 시작과 끝을 복원하는 색인이다
v3에서 에피소드 경계는 파일 경계와 같지 않습니다. meta/episodes 아래의 레코드가 길이, task, 데이터와 영상의 frame·byte 또는 time offset을 가리켜 하나의 논리 에피소드를 만듭니다.
경계가 한 행만 밀려도 다음 에피소드의 첫 action이 앞 에피소드 관측과 짝지어질 수 있습니다. 연속된 두 에피소드의 끝과 시작이 겹치거나 비지 않는지, 마지막 프레임과 종료 상태가 올바른지 자동 검사합니다.
task와 stats는 학습 조건과 정규화를 연결하지만 원시 의미를 대신하지 않는다
task 메타데이터는 자연어 작업과 정수 색인을 연결하고, stats는 feature별 평균·표준편차·최솟값·최댓값처럼 정규화에 필요한 통계를 제공합니다. 같은 action 이름이라도 로봇과 좌표계가 다르면 stats만 맞춰서는 함께 학습할 수 없습니다.
로봇 학습 데이터 품질 검수에서 다룬 시간 동기화, 행동 좌표, 실패 라벨을 v3 메타데이터와 함께 확인해야 합니다. Action Chunking처럼 여러 미래 행동을 묶어 쓰는 모델은 episode 경계와 action 시간축 오류에 더 민감합니다. 형식 적합성은 의미 적합성의 필요조건일 뿐 충분조건이 아닙니다.
기록 과정에서는 frame 추가·episode 저장·전체 finalize의 책임을 구분한다
한 제어 프레임마다 상태·행동·카메라 참조를 추가하고, 작업이 끝나면 에피소드 경계를 저장합니다. 텔레옵 데이터처럼 사람 명령과 로봇 실행을 함께 기록할 때는 두 시간축의 지연도 저장해야 합니다. 모든 기록이 끝난 뒤에는 writer 버퍼와 메타데이터를 완전히 닫아 Parquet footer와 최종 통계를 확정합니다.
공식 v3 문서는 push 전에 dataset.finalize()를 호출하라고 강조합니다. finalize가 빠지면 버퍼가 남거나 Parquet footer가 완성되지 않아 업로드된 파일이 불완전할 수 있으므로, 종료를 예외 처리와 테스트에 포함합니다.
v2.1에서 v3로 옮길 때는 파일 합치기보다 에피소드 의미 보존을 검증한다
대규모 데이터셋 v3 포팅 공식 안내는 에피소드별 Parquet·MP4를 더 큰 파일로 모으고 episode 메타데이터와 오프셋을 갱신하는 구조를 설명합니다. 변환 도구를 돌린 뒤 개수만 맞는지 보는 것으로는 부족합니다.
변환 전후에 에피소드 수와 길이, task 매핑, 첫·중간·마지막 timestamp, 상태·행동 배열, 각 카메라의 첫·끝 프레임을 표본 비교합니다. stats도 다시 계산됐는지 확인하고 이전 값이 그대로 복사되지 않았는지 봅니다.
streaming은 전체 다운로드를 줄이지만 shard와 seek 패턴을 고려해야 한다
v3는 Hub에서 데이터셋을 스트리밍해 필요한 구간만 읽는 사용을 지원합니다. 그러나 무작위 에피소드 순서와 여러 카메라를 동시에 읽으면 같은 shard를 반복 요청하거나 MP4 seek 비용이 커질 수 있습니다.
학습 샘플러를 shard 친화적으로 묶고 로컬 캐시와 작업자 수를 조정합니다. 네트워크 실패 시 같은 에피소드가 중복되거나 빠지지 않도록 샘플 식별자와 재시도 정책도 로그에 남깁니다.
무결성 검사는 임의 에피소드를 실제로 복원하고 영상과 action을 함께 재생한다
파일 존재와 JSON 문법만 검사해서는 경계와 시간 오류를 찾지 못합니다. 첫·중간·마지막 shard에서 에피소드를 고르고, Parquet 행 수와 episode length, 카메라 프레임 수, timestamp 단조 증가, task와 종료 상태를 확인합니다.
영상 위에 action과 관절 상태를 시간순으로 겹쳐 보는 짧은 시각 QA가 효과적입니다. 그리퍼가 닫힌 action보다 영상이 늦거나 다른 에피소드 장면이 섞이면 offset 또는 동기화 문제가 바로 드러납니다.
형식 채택 여부는 규모·도구 호환성·복구 비용을 함께 보고 결정한다
작은 실험 데이터는 에피소드별 파일이 디버깅하기 쉬울 수 있지만, 수십만 에피소드로 커지면 v3의 적은 파일 수와 streaming 접근이 유리합니다. 사용하는 학습 코드와 시각화 도구가 v3 스키마와 버전을 지원하는지 먼저 확인합니다.
최종 검증은 schema, episode 경계, 영상 시간축, stats, task, finalize, Hub 재로드, 표본 시각화까지 포함합니다. Hugging Face LeRobot 공식 저장소의 구현 버전과 변환 코드 commit을 데이터 카드에 고정해야 나중에 같은 데이터셋을 다시 만들 수 있습니다.
| 검사 | 자동 확인 | 표본 확인 | 실패 시 영향 |
|---|---|---|---|
| 스키마 | feature·dtype·shape·경로 | 한 frame 값 해석 | 로더 오류·잘못된 좌표 |
| 에피소드 | length·offset 연속성 | 첫/끝 장면과 task | 다른 에피소드 혼입 |
| 시간축 | timestamp 증가·FPS | 영상-action 동시 재생 | 행동 지연 학습 |
| 완료 | footer·stats·재로드 | Hub에서 표본 로드 | 업로드 후 손상 발견 |
LeRobot Dataset v3 구조에서 자주 묻는 질문
v3에서는 에피소드마다 Parquet 파일이 하나씩 생기나요?
아닙니다. 여러 에피소드의 표 형식 데이터가 더 큰 Parquet shard를 공유하고, 메타데이터가 각 에피소드의 시작과 끝을 가리킵니다.
카메라 영상도 Parquet에 저장하나요?
일반적으로 카메라 프레임은 MP4로 인코딩하고 Parquet에는 상태·행동·timestamp 같은 신호를 둡니다. 메타데이터가 두 저장소의 같은 에피소드 구간을 연결합니다.
파일 수가 줄면 데이터 손상 위험도 줄어드나요?
작은 파일 관리 부담은 줄지만 shard 하나의 손상이 여러 에피소드에 영향을 줄 수 있습니다. 해시, 백업, 표본 복원과 경계 검사가 더 중요합니다.
기록 후 finalize를 왜 호출해야 하나요?
버퍼된 episode 메타데이터를 쓰고 Parquet writer와 footer를 완성하기 위해서입니다. 호출하지 않으면 업로드 후 파일이 불완전해 로드되지 않을 수 있습니다.
v2.1을 v3로 변환한 뒤 무엇을 비교해야 하나요?
에피소드 수·길이·task, 상태와 action, timestamp, 카메라 첫·끝 프레임, stats를 변환 전후 표본으로 비교하고 Hub에서 다시 로드해야 합니다.
LeRobot의 main 문서와 구현은 계속 바뀔 수 있습니다. 실제 데이터셋을 만들 때는 설치한 LeRobot 버전의 공식 문서와 스키마를 확인하고, codebase version·변환 코드 commit·데이터 카드 이력을 함께 고정해야 합니다.