데이터 수집

로봇이 스스로 움직이게 하려면 먼저 사람이 시범을 보여 줘야 합니다. 데이터 탭 › 수집 은 리더암으로 팔로워를 조종하는 동안 카메라 영상과 관절 값을 그대로 기록해 학습용 데이터셋을 만듭니다. 사람의 시범을 따라 배우게 하는 이 방식을 모방 학습(imitation learning) 이라고 합니다. 이 페이지는 팔 로봇(SO-101 · SO-102)을 기준으로 새 수집 · 이어서 수집 · 업로드를 설명합니다.

학습 목표

  • 데이터셋 · 에피소드 · 태스크가 무엇이고, 한 프레임에 무엇이 담기는지 설명할 수 있다.
  • 새 데이터셋 수집 폼의 칸을 알맞게 채우고 녹화를 시작할 수 있다.
  • 녹화 중 버튼으로 에피소드를 다시 찍거나, 일찍 넘기거나, 수집을 끝낼 수 있다.
  • 기존 데이터셋에 이어서 수집하고, Hugging Face Hub 에 올릴지 정할 수 있다.

1. 데이터셋 · 에피소드 · 태스크

1.1. 용어

용어뜻
에피소드작업을 처음부터 끝까지 한 번 한 기록입니다. “큐브를 집어 상자에 넣기” 를 한 번 하면 에피소드 하나입니다
데이터셋같은 작업의 에피소드를 모은 묶음입니다. 이름은 사용자명/태스크 이름 입니다 (예: HueyWoo/pick_and_place)
태스크데이터셋이 담은 작업입니다. 짧은 태스크 이름(폴더 · 저장소 이름)과 한 문장짜리 태스크 설명을 정합니다
프레임에피소드를 이루는 한 순간입니다. 30 fps 면 1초에 프레임 30개를 기록합니다

15초짜리 에피소드는 30 fps 에서 프레임 450개입니다. 에피소드 20개를 모으면 9,000개의 관측 · 행동 쌍이 생기고, 모델은 이 시범들에서 공통된 움직임을 배웁니다.

1.2. 한 프레임에 담기는 것

항목내용
observation.images.<카메라 이름>카메라마다 영상 한 장. 이름은 로봇 설정 에서 붙인 카메라 이름입니다 (예: observation.images.front)
observation.state팔로워의 관절 위치. SO-101 은 6개, SO-102 는 7개입니다
action같은 개수의 목표값. 리더암이 보낸 명령입니다
task태스크 설명 문장

영상은 MP4 로, 나머지는 표 형식(parquet) 파일로 저장됩니다. LeKiwi 는 바퀴 속도 3개가 더해져 9개입니다 (7절).

1.3. 좋은 데이터의 조건

모델은 데이터에 있는 것만 배웁니다. 녹화를 시작하기 전에 다음을 정해 두세요.


2. 시작 전 준비

준비물설명
저장한 로봇로봇 설정 에서 follower · leader 포트를 고르고 로봇 저장 까지 마친 로봇 (로봇 설정)
보정팔로워 · 리더 모두 칼리브레이션 탭에서 보정한 상태 (칼리브레이션)
카메라로봇 설정 › 2. Camera 에 등록한 카메라. 등록하지 않으면 영상 없이 관절 값만 기록됩니다
기능 패키지로봇 제어 패키지 · 데이터 패키지. 데이터 탭을 처음 열면 설치 카드가 뜹니다 (기능 패키지 설치)
Hugging Face 토큰Hub 에 올릴 때만 필요합니다. 쓰기(Write) 권한 토큰 (2.2절)
연습텔레오퍼레이션 탭에서 리더로 팔로워를 움직여 보며 손에 익힙니다 (텔레오퍼레이션)

2.1. [앱] 데이터 탭 열기

사이드바 로봇 창고 에서 로봇 카드를 누르고, 위 탭 줄의 데이터 를 누릅니다. 아래 작은 탭 수집 이 이 페이지의 화면이고, 편집 은 데이터셋 창고와 같은 화면입니다.

SO-101 로봇의 데이터 탭 › 수집 첫 화면 — 새로운 데이터셋 수집하기 · 데이터셋 이어서 수집하기 카드 데이터 › 수집 첫 화면. 처음 모을 때는 왼쪽 카드, 있던 데이터셋에 더할 때는 오른쪽 카드를 누릅니다.

2.2. [PC] Hugging Face 토큰 준비 (업로드할 때만)

이 PC 에만 저장할 거라면 이 절은 건너뛰어도 됩니다.

  1. huggingface.co/join 에서 가입하고 이메일 인증을 마칩니다.
  2. huggingface.co/settings/tokens 에서 Create new token 을 누르고 종류를 Write 로 만듭니다. 만든 hf_... 글자는 창을 닫으면 다시 볼 수 없으니 바로 복사합니다.
  3. [앱] 사이드바 맨 아래 계정 버튼 › ⚙ 설정 › 일반 › API 키 › HuggingFace Access Token 의 토큰 칸에 붙여 넣고 저장 을 누릅니다 (설정).

토큰을 저장하면 데이터셋 이어서 수집하기 화면과 데이터셋 창고의 ☁ HuggingFace Hub 칸에 계정: HueyWoo 처럼 계정 이름이 보입니다. 이 이름을 아래 폼의 HuggingFace 사용자명 에 적습니다.

경고

토큰은 비밀번호와 같습니다. 다른 사람에게 보내거나 문서 · 코드에 적지 마세요. 앱은 토큰을 이 PC 의 OS 키링에만 저장합니다.


3. 새 데이터셋 수집하기

3.1. [앱] 폼 채우기

새로운 데이터셋 수집하기 를 누르면 새로운 데이터셋 수집 폼이 열립니다. 폼은 지난번 입력값을 기억해 미리 채워 둡니다.

새로운 데이터셋 수집 폼 — HuggingFace 사용자명 HueyWoo, 태스크 이름 pick_cube, 태스크 설명 영어 한 문장, 녹화 옵션 기본값, HuggingFace Hub 에 업로드 아니오 SO-101 의 새로운 데이터셋 수집 폼. 녹화 옵션은 기본값이고, 업로드는 아니오 입니다.

칸범위 · 기본값설명
HuggingFace 사용자명자유 입력데이터셋 이름의 앞부분. 본인 Hugging Face 계정 이름을 적습니다 (예: HueyWoo). 비우면 local-user 로 저장됩니다
태스크 이름필수데이터셋 이름의 뒷부분이자 폴더 이름 (예: pick_and_place)
태스크 설명필수작업을 설명하는 한 문장 (예: Pick the green cube and place it in the box.)
에피소드 수1~500 회, 기본 10이번에 녹화할 에피소드 수
에피소드 길이1~600 초, 기본 15에피소드 하나를 녹화하는 시간. 다 되면 자동으로 저장합니다
리셋 대기 시간0~120 초, 기본 3에피소드 사이에 물체를 제자리에 두는 시간. 이 시간은 녹화하지 않습니다
프레임 레이트5~60 fps, 기본 301초에 기록할 프레임 수. 카메라를 등록했으면 카메라 fps 중 가장 낮은 값으로 채워집니다
HuggingFace Hub 에 업로드아니오 · 예수집이 끝난 뒤 Hub 에 올릴지 정합니다 (3.5절)

3.2. 이름 정하는 규칙

3.3. 태스크 설명 쓰기

태스크 설명 은 데이터셋의 모든 프레임에 함께 저장됩니다. SmolVLA 같은 VLA(말로 지시를 받는) 모델은 이 문장을 지시문으로 배우고, 추론 때 지시문 (Instruction) 칸에 같은 문장을 넣습니다.

3.4. 시간과 FPS 정하기

칸정하는 법
에피소드 길이작업을 여유 있게 끝낼 수 있는 시간으로 잡습니다. 일찍 끝나면 ⏭ 로 넘기면 됩니다
리셋 대기 시간물체를 다음 시작 자리에 놓고 리더암을 시작 자세로 돌릴 시간입니다. 0 이면 쉬지 않고 이어서 녹화합니다
프레임 레이트보통 30 입니다. 카메라 fps 보다 높게 잡지 않습니다
에피소드 수한 번에 다 모으지 않아도 됩니다. 나중에 데이터셋 이어서 수집하기 로 더할 수 있습니다

팁

리셋 대기 시간에도 리더암으로 팔로워를 움직일 수 있습니다 (기록만 하지 않습니다). 이 시간에 팔을 시작 자세로 되돌려 두면 다음 에피소드 시작이 깔끔합니다.

3.5. HuggingFace Hub 에 업로드 — 예 / 아니오

선택수집이 끝나면
아니오올리지 않습니다. 이 PC 에만 저장하고, 나중에 데이터셋 창고에서 올릴 수 있습니다
예이 PC 에 저장한 뒤 HuggingFace 사용자명/태스크 이름 저장소로 올립니다. 저장한 토큰이 없으면 시작 전에 HuggingFace 토큰 없음 창이 뜹니다

Ubuntu 0.1.8 이하 · Windows 0.1.7 은 ‘아니오’ 여도 올라갑니다

HuggingFace 토큰이 저장돼 있으면 수집이 끝난 뒤 공개 저장소로 올립니다. Ubuntu 는 다운로드 페이지에서 0.2.0 으로 업데이트하세요. Windows 는 올리지 않을 데이터를 모으기 전에 API 키 에 저장된 HuggingFace 토큰을 모두 제거 해 둡니다 (하나만 지우면 남은 토큰이 활성이 됩니다). 이미 올라간 데이터셋은 데이터셋 창고의 ☁ HuggingFace Hub 칸에서 확인합니다.

3.6. [앱] 데이터셋 수집!! 누르기

  1. 리더암을 팔로워와 비슷한 자세로 들고, 팔로워 주변의 사람 · 물건을 치웁니다.
  2. 데이터셋 수집!! 을 누릅니다.
  3. 앱이 다른 탭의 로봇 연결을 먼저 끊고 팔로워 · 리더 · 카메라에 연결합니다. 연결하는 몇 초 동안은 상태가 대기 로 보입니다.
  4. 연결되면 곧바로 첫 에피소드 녹화가 시작됩니다 (녹화 중).

시작하는 순간 팔로워가 리더암 자세로 바로 움직입니다

SO-101 · SO-102 는 확인 창 없이 곧바로 따라갑니다. 리더암과 팔로워의 자세 차이가 크면 팔로워가 그만큼 빠르게 휘두르니, 두 팔의 자세를 맞춘 뒤 누르세요.

시작하기 전에 다음 창이 뜰 수 있습니다.

창뜻 · 할 일
포트 미설정로봇 설정에 follower/leader 포트가 저장되지 않았습니다. 로봇 설정 에서 포트를 고르고 로봇 저장 을 누릅니다
데이터셋 이름 중복같은 이름에 에피소드가 이미 있습니다. 데이터셋 이어서 수집하기 를 쓰거나 이름을 바꿉니다
이전 시작 잔여물 발견같은 이름으로 시작했다가 에피소드 없이 끝난 빈 폴더가 남아 있습니다. 정리하겠다고 답하면 지우고 새로 시작합니다

4. 녹화 화면

4.1. 화면 구성

위치보이는 것
왼쪽 위FRAMES(지금까지 저장한 프레임 수) · EPISODES(완료 / 목표) · FPS
그 아래상태 칩, 타이머 00:07 / 00:15 (지금 / 전체), 진행 막대
버튼 줄⏸ · ↶ · ⏭ · ■ (4.3절)
EPISODES 목록에피소드마다 한 줄. 녹화 중이면 ● 녹화 중, 저장되면 ✓ 450 frames 처럼 바뀝니다
오른쪽3D REPLAY(팔로워 자세) · 카메라 영상 · 아래 관절 그래프

에피소드 번호는 0부터 셉니다 (Episode 0, Episode 1 …).

4.2. 상태 칩과 에피소드의 흐름

상태 칩뜻
대기연결하는 중이거나 아직 시작 전입니다
녹화 중기록하고 있습니다. 리더암으로 작업을 합니다
에피소드 종료 중방금 끝난 에피소드를 저장하고 있습니다
리셋다음 에피소드를 준비하는 시간입니다 (기록하지 않음). 물체를 제자리에 둡니다
일시정지⏸ 로 멈춘 상태입니다

에피소드는 녹화 중(에피소드 길이) → 에피소드 종료 중 → 리셋(리셋 대기 시간) → 다음 녹화 중 순서로 돌아갑니다. 마지막 에피소드 뒤에는 리셋 없이 끝납니다. 스피커가 켜져 있으면 Recording episode 0, Reset the environment 같은 영어 음성 안내가 나올 수 있습니다.

4.3. 버튼

버튼툴팁하는 일
⏸ (멈추면 ▶)일시정지 / 재개녹화를 잠시 멈춥니다. 멈춘 시간도 에피소드 시간에 들어가고, 재개하면 팔로워가 그동안 움직인 리더 자세로 바로 따라갑니다
↶현재 에피소드 재녹화지금 에피소드를 버리고 곧바로 같은 번호로 다시 녹화합니다 (리셋 시간 없음)
⏭현재 에피소드 즉시 저장 후 다음시간이 남아도 지금 에피소드를 저장하고, 리셋을 거쳐 다음 에피소드로 넘어갑니다
■수집 세션 종료수집 종료 창에서 확인하면 수집을 끝냅니다. 저장된 에피소드는 남고, 녹화 중이던 에피소드는 버립니다

망쳤으면 ⏸ 보다 ↶

일시정지를 쓰면 멈춘 앞뒤 자세가 이어지지 않는 끊긴 데이터가 남습니다. 시범을 망쳤다면 그 에피소드를 버리고 다시 찍는 편이 학습에 좋습니다.

4.4. 끝나면 나오는 창

창뜻
데이터셋 수집 완료!업로드 아니오 — 이 PC 에 저장했습니다 (에피소드 수: N개)
HuggingFace Hub에 업로드 중... (화면 덮개)올리는 중입니다. 12 / 40 파일 처럼 파일 수가 올라갑니다
업로드 완료!Hub 에 올렸습니다
업로드 실패올리지 못했습니다. 이 PC 의 데이터는 그대로 있으니 데이터셋 창고에서 다시 올립니다
데이터셋 수집 완료 (업로드 건너뜀)인터넷이 없어 올리지 않았습니다 (6.3절)
수집 오류수집 중에 오류가 났습니다. 이유가 함께 나옵니다 (8절)

끝나면 팔로워의 힘이 빠집니다

수집이 끝나 로봇 연결이 끊기면 팔로워 모터의 토크가 꺼져 편 팔이 처집니다. 마지막 에피소드가 끝날 때쯤 리더로 팔로워를 안전한 자세로 내려 두세요.


5. 이어서 수집하기

5.1. [앱] 데이터셋 고르기

데이터셋 이어서 수집하기 를 누르면 데이터셋 선택 화면이 열립니다. 왼쪽 💾 로컬 은 이 PC 의 데이터셋, 오른쪽 ☁ HuggingFace Hub 는 토큰 계정의 데이터셋입니다. 더할 데이터셋의 로컬 카드를 누릅니다.

Hub 에만 있는 데이터셋을 누르면 로컬 데이터셋 없음 안내가 뜹니다. 데이터셋 창고에서 먼저 이 PC 로 내려받으세요.

5.2. [앱] 이어서 수집하기 폼

이어서 수집하기 폼 — 데이터셋 ID, 기존 에피소드 7 에피소드 · 2,343 프레임, FPS (고정) 30, 수집 옵션 칸 이어서 수집하기 폼. 그림은 LeKiwi 데이터셋이라 위에 로봇 상태 띠가 있고, 팔 로봇도 칸은 같습니다 (띠의 글은 촬영 당시 그 로봇의 상태입니다).

칸설명
데이터셋 ID고른 데이터셋 이름 (바꿀 수 없음)
기존 에피소드10 에피소드 · 4,500 프레임 처럼 지금 들어 있는 양
FPS (고정)데이터셋의 fps. 바꿀 수 없습니다
태스크 설명데이터셋에 저장된 문장이 채워집니다. 그대로 두는 것을 권합니다
추가할 에피소드 수1~500, 기본 10
에피소드 시간1~600 초, 기본 15
리셋 시간0~120 초, 기본 3
HuggingFace 업로드아니오 · 예. 예 면 끝난 뒤 데이터셋 전체를 올립니다

이어서 수집!! 을 누르면 녹화 화면이 열리고, EPISODES 는 10 / 20 처럼 기존 에피소드를 더해 셉니다. 버튼과 흐름은 4절과 같습니다.

5.3. 로봇 기종 불일치

이어 수집은 데이터셋을 모은 기종과 지금 로봇의 기종이 같은지 확인합니다. 다르면 로봇 기종 불일치 창이 뜨고 시작하지 않습니다. 예를 들어 SO-101 데이터셋에 LeKiwi 에피소드를 붙이면 관절 구성이 달라 수집 도중에 실패하기 때문입니다.

SO-101 데이터셋이 so_follower 로 막힐 때

이 앱으로 SO-101 에서 모은 데이터셋은 로봇 타입이 so_follower 로 기록되는데, 이어 수집 검사는 SO-101 을 so101_follower 와 비교합니다. 그래서 같은 SO-101 이어도 이 데이터셋은 so_follower 로 수집된 것입니다 … 지금 선택된 로봇은 so101_follower 입니다 가 뜨고 이어 수집이 막힙니다. 이때는 같은 fps · 같은 카메라로 새 이름의 데이터셋을 모은 뒤, 데이터셋 창고의 데이터셋 병합 으로 합치세요.


6. 저장 위치와 업로드

6.1. [PC] 저장 위치

모은 데이터셋은 이 PC 의 다음 폴더에 저장됩니다. ~ 는 홈 폴더이고, .cache 는 숨김 폴더라 파일 관리자에서 Ctrl+H 를 누르면 보입니다.

~/.cache/huggingface/lerobot/HueyWoo/pick_and_place/
├── meta/     데이터셋 정보 · 에피소드 목록 · 태스크 · 통계
├── data/     관절 상태와 행동 (parquet)
└── videos/   카메라 영상 (카메라마다 폴더, mp4)

정보

Windows 판(0.1.7)은 같은 모양으로 %USERPROFILE%\.cache\huggingface\lerobot\<사용자명>\<태스크 이름> 에 저장합니다. Windows 판은 SO-102 와 새 A-Go(ROS 2 LeKiwi)를 지원하지 않습니다.

6.2. 업로드는 공개 저장소로

6.3. 인터넷이 없을 때 (로봇 AP 모드 등)

업로드를 예 로 골랐어도, 수집이 끝날 때 Hub 에 닿지 않으면 업로드를 건너뜁니다. 이것은 실패가 아니라 안내입니다.

인터넷에 연결되어 있지 않아 HuggingFace 업로드를 건너뜁니다.
(로봇 AP 모드처럼 노트북이 로봇 와이파이에만 연결된 경우)

데이터셋은 이 PC 에 안전하게 저장되어 있습니다.
인터넷에 연결한 뒤 데이터 › 편집 › [데이터셋 업로드] 로 올리세요.

나중에 인터넷이 되는 와이파이(또는 유선)에 연결한 뒤 데이터셋 창고(= 데이터 › 편집)의 데이터셋 업로드 로 올립니다.

앱은 인터넷이 될 때 먼저 켜 두세요

Physical Labs 는 켤 때 인터넷으로 구글 로그인을 확인하므로, 인터넷 없이 켜면 로그인 화면에서 막힙니다. 노트북을 로봇 AP 처럼 인터넷이 없는 와이파이에 붙일 때는, 인터넷이 될 때 앱을 먼저 켜 두고 그다음 와이파이를 바꾸세요. 켜 둔 앱은 그대로 쓸 수 있습니다.


7. LeKiwi 로 수집할 때

A-Go(LeKiwi) 도 같은 데이터 › 수집 화면을 씁니다. 다른 점만 모았습니다.

LeKiwi 로봇의 데이터 › 수집 화면 — 위쪽 보라 띠에 로봇 상태 · 로봇 끄기 · 비상 정지 버튼 LeKiwi 의 데이터 › 수집 화면. 위쪽 보라 띠가 로봇 상태와 로봇 끄기 · 비상 정지 버튼입니다 (띠의 글은 촬영 당시 그 로봇의 상태입니다).

항목팔 로봇 (SO-101 · SO-102)LeKiwi
화면 위없음로봇 상태 띠 + ▶ 로봇 켜기 / ■ 로봇 끄기 · ⛔ 비상 정지. 로봇이 켜져 있어야 시작하고, 웹 화면이 조작 권한을 쥐고 있으면 막힙니다
비상 정지—⛔ 비상 정지 는 바퀴를 세우고 바퀴 · 팔 토크를 끄므로 편 팔이 떨어집니다
필요한 포트follower + leaderleader 만 (팔로워는 로봇 안에 있습니다)
시작할 때확인 창 없이 바로 움직임실물 로봇 수집 확인 창이 뜹니다
프레임 레이트5~60 fps최대 30 fps
키보드없음바퀴 W/S 앞뒤 · A/D 좌우 · Q/E 제자리 회전 · R/F 속도
데이터관절 6개 · 7개9개 (팔 6 + 바퀴 속도 3), 카메라 front · wrist
카메라 끊김—영상이 2초 넘게 끊기면 수집이 멈춥니다

로봇 켜기, AP 모드에서 모으기, 바퀴까지 넣은 수집 요령은 데이터 · 학습 · 추론에서 이어서 설명합니다.

정보

Windows 판(0.1.7)은 새 A-Go(ROS 2 LeKiwi)를 지원하지 않습니다. 새 A-Go 로 데이터를 모으려면 Ubuntu 판 0.2.0 을 쓰세요.


8. 문제 해결

증상확인할 것
데이터 탭에 설치 카드가 뜬다로봇 제어 패키지 · 데이터 패키지 가 필요합니다. 설치하기 를 누릅니다 (기능 패키지 설치)
포트 미설정로봇 설정 에서 follower · leader 포트를 고르고 로봇 저장 을 눌렀는지 확인합니다
수집 오류 에 보정 정보가 없습니다칼리브레이션 탭에서 팔로워 · 리더를 먼저 보정합니다
입력 오류 (태스크 이름)영문 · 숫자 · _ · - 만 씁니다. 띄어쓰기 · 한글 · 점은 안 됩니다
HuggingFace 토큰 없음설정 › 일반 › API 키 에 HuggingFace 토큰을 저장합니다. 올리지 않을 거면 업로드를 아니오 로 둡니다
데이터셋 이름 중복같은 이름에 에피소드가 있습니다. 이어서 수집하거나 이름을 바꿉니다
로봇 기종 불일치 (이어 수집)지금 로봇과 같은 기종으로 모은 데이터셋인지 확인합니다. SO-101 의 so_follower 경우는 5.3절
업로드 실패토큰에 쓰기(Write) 권한이 있는지, HuggingFace 사용자명 이 토큰 계정과 같은지, 인터넷이 되는지 확인합니다. 데이터는 이 PC 에 남아 있으니 데이터셋 창고에서 다시 올립니다
아니오 를 골랐는데 업로드되거나 업로드 실패 창이 뜬다Ubuntu 0.1.8 이하 · Windows 0.1.7 의 문제입니다. 데이터는 이 PC 에 저장돼 있습니다. Ubuntu 는 0.2.0 으로 업데이트하고, Windows 는 토큰을 모두 제거한 채 모읍니다 (3.5절)
데이터셋 수집 완료 (업로드 건너뜀)인터넷이 없어 건너뛴 것입니다. 연결한 뒤 데이터셋 창고에서 올립니다
카메라 칸에 등록된 카메라가 없습니다.로봇 설정 › 2. Camera 에 카메라를 추가하고 로봇 저장 을 누릅니다
수집 오류 에 lerobot 데이터셋 라이브러리를 불러오지 못했습니다앱을 다시 시작합니다. 원인에 torchcodec · FFmpeg 가 보이면 터미널에서 sudo apt install ffmpeg 를 실행합니다
시작하자마자 팔로워가 크게 움직인다리더암을 팔로워와 비슷한 자세로 든 뒤 시작합니다 (3.6절)
리셋 중 ↶ 를 눌렀더니 목록에서 에피소드가 사라졌다화면 목록만 지워진 것입니다. 데이터셋 창고에서 에피소드 수를 확인합니다
로컬 목록에 에피소드 정보 없음 데이터셋이 생겼다에피소드 없이 끝난 수집의 빈 폴더입니다. 데이터셋 창고에서 지우거나, 같은 이름으로 새로 수집하면 정리할지 묻습니다

9. 정리

다음으로 모은 에피소드를 하나씩 재생해 확인하고, 학습에 씁니다.