🧪 새 튜토리얼이 계속 업데이트 중 — 로봇 팔부터 센서까지
Juxi Technology Wiki

한국어

English
简体中文
繁體中文
日本語
Deutsch
Français
Español
Italiano
Português (Brasil)
Português (Portugal)

한국어

English
简体中文
繁體中文
日本語
Deutsch
Français
Español
Italiano
Português (Brasil)
Português (Portugal)

화면 모드

🤗스토어
/
공식 웹사이트

단계 4: 데이터 수집(Linux) ​

본 단계에서는 원격 조작 데이터셋을 기록합니다: 사람이 조작하는 가운데 "관절각 + 카메라 이미지" 샘플을 수집하여 이후 학습에 사용합니다. 데이터셋 품질이 정책의 효과를 직접 좌우하므로, 조작은 규범적이고 일관되어야 합니다. 본 단계는 전 과정을 로컬에서 기록하며 HF 로그인이 필요 없습니다.

사전 조건 ​

  • 단계 3: 원격 조작을 완료하고 방향이 올바른지 검증함

  • 카메라를 연결하고 인덱스를 기록함(lerobot-find-cameras)

  • 로컬 데이터셋 저장 경로를 결정함(본문 예시는 ~/lerobot_data, 사용자 정의 가능)

단계 1: 카메라 인덱스 확인 ​

Bash
lerobot-find-cameras

카메라 번호를 기록합니다. 예를 들어:

  • 0번: 손목 카메라(wrist)

  • 1번: 상단 카메라(top)

⚠️ 주의(카메라 인덱스)：index_or_path는 카메라 인덱스(0/1/2...) 또는 비디오 스트림 경로입니다. PC마다 번호가 다르므로 반드시 먼저 확인하세요.

단계 2: 데이터셋 기록(로컬 저장, 로그인 불필요) ​

Bash
lerobot-record \
  --robot.type=so101_amazing_hand \
  --robot.port=<follower_arm_port> \
  --robot.hand_port=<hand_port> \
  --robot.id=amazing_hand_follower \
  --robot.cameras='{
    wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"},
    top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30, fourcc: "MJPG"}
  }' \
  --teleop.type=so101_leader \
  --teleop.port=<leader_arm_port> \
  --teleop.id=amazing_hand_leader \
  --dataset.repo_id=soarm_amazing_hand_pick \
  --dataset.root=~/lerobot_data \
  --dataset.push_to_hub=false \
  --dataset.num_episodes=20 \
  --dataset.single_task="Pick up the cube with the dexterous hand" \
  --display_data=true

<follower_arm_port> / <hand_port> / <leader_arm_port>를 실제 경로로 교체합니다; 카메라 index_or_path를 사용자의 카메라 인덱스로 교체합니다.

💡 설명：

  • --dataset.root=~/lerobot_data：데이터셋을 지정한 로컬 경로에 저장하며, HF 로그인이 필요 없습니다(작성하지 않으면 기본적으로 ~/.cache/huggingface/lerobot/datasets/...에 저장됩니다).

  • --dataset.push_to_hub=false：업로드를 비활성화합니다(기본적으로 HF로 푸시를 시도하며 로그인이 필요합니다). 데이터셋을 공유해야 할 때만 true로 변경합니다.

  • --dataset.repo_id=soarm_amazing_hand_pick：데이터셋 이름입니다. 학습 시 동일한 이름으로 참조합니다.

  • --display_data=true에는 rerun이 필요하며(미설치 시 pip install "rerun-sdk>=0.24.0,<0.34.0") 그래픽 환경이 필요합니다. 또는 해당 인자를 제거합니다(기록에는 영향 없음).

매개변수 설명 ​

매개변수설명
--robot.cameras카메라 설정. index_or_path는 카메라 인덱스, width/height/fps는 필수
--dataset.repo_id데이터셋 이름(로컬 식별용)
--dataset.root데이터셋 로컬 저장 경로. 순수 로컬 기록 시 반드시 추가하여 기본 경로가 제어 불가능해지는 것을 방지
--dataset.push_to_hubfalse=로컬만(기본 권장); true=HF로 푸시(로그인 필요)
--dataset.num_episodes기록 에피소드 수
--dataset.episode_time_s에피소드당 최대 기록 초(기본 60). 작업이 일찍 끝나면 Enter로 조기 종료할 수 있고, 초과하면 해당 에피소드가 자동 종료됨
--dataset.single_task작업 설명. 데이터셋 메타데이터에 기록됨
--display_data=true기록 화면을 실시간 표시(선택)

기록 조작 규범 ​

에피소드별 흐름：

  1. 로봇 암 + 핸드를 시작 위치로 리셋

  2. 터미널에서 Enter를 눌러 기록 시작

  3. 리더 암을 조작하여 작업 수행(예: 블록 집기). 동작은 느리고 일관되게

  4. 작업 완료 후 Enter를 눌러 이 에피소드를 종료(누르지 않으면 최대 60초 기록되며, --dataset.episode_time_s로 제어되고 시간이 되면 자동 종료)

  5. num_episodes에 도달할 때까지 반복

⚠️ 주의 1(시작 위치 일치)：각 에피소드는 동일한 시작 위치에서 시작하여 데이터 분포의 혼란을 방지합니다. 고정된 리셋 자세를 정하는 것을 권장합니다.

⚠️ 주의 2(동작 일관성)：동일한 작업에는 유사한 조작 궤적(접근 각도, 파지 위치, 속도)을 사용하면 정책이 더 빠르고 안정적으로 학습합니다.

⚠️ 주의 3(기록 품질)：품질이 낮은 것을 많이 기록하기보다 고품질을 적게 기록하는 편이 낫습니다. 20 에피소드는 ACT의 출발점이며, 복잡한 작업은 30-50 에피소드를 권장합니다.

⚠️ 주의 4(카메라 실시간성)：기록 시 카메라 가림이나 강한 빛 변화를 피하세요. 이미지 일관성이 일반화에 영향을 줍니다.

데이터 저장 ​

  • 로컬 기록：데이터는 --dataset.root로 지정한 디렉터리에 저장됩니다(예시 ~/lerobot_data/soarm_amazing_hand_pick).

  • 학습 참조：학습 시 **동일한 --dataset.repo_id + **--dataset.root 를 사용하면 되며, 수동으로 파일을 옮길 필요가 없습니다:

Bash
lerobot-train --dataset.repo_id=soarm_amazing_hand_pick --dataset.root=~/lerobot_data ...
  • HF 로그인 시나리오(선택)：데이터셋을 클라우드에 공유해야 할 때 --dataset.push_to_hub=true로 변경합니다(huggingface-cli login 필요). 로컬 학습만이라면 필요하지 않습니다.

⚠️ 주의(로컬 vs 클라우드)：기본 튜토리얼은 전 과정 로컬이며, --dataset.push_to_hub=false로 HF 로그인이 트리거되지 않음을 보장합니다. 데이터셋을 공유하고 싶을 때만 true를 추가합니다.

단계 3: 재생 검증(선택이지만 권장) ​

기록 완료 후 lerobot-replay로 특정 에피소드의 데이터를 재생하여 데이터 품질 + 로봇 동작 기록이 올바른지를 검증할 수 있습니다. 재생 시 로봇이 해당 에피소드의 동작(핸드 개폐 포함)을 자동으로 재현합니다.

Bash
lerobot-replay \
  --robot.type=so101_amazing_hand \
  --robot.port=<follower_arm_port> \
  --robot.hand_port=<hand_port> \
  --robot.id=amazing_hand_follower \
  --dataset.repo_id=soarm_amazing_hand_pick \
  --dataset.root=~/lerobot_data \
  --dataset.episode=0

<follower_arm_port> / <hand_port>를 실제 경로로 교체합니다; --dataset.episode는 재생할 에피소드 번호입니다(0부터 시작, 예를 들어 20 에피소드를 기록했다면 0~19).

💡 설명：재생 전에 팔로워 암 + 핸드를 시작 위치로 되돌려 동작 충돌을 방지합니다; 재생 중에는 로봇이 스스로 움직이므로 수동으로 개입하지 마세요. 재생 동작이 기록 시와 명백히 다르면 데이터 품질에 문제가 있는 것이므로 해당 에피소드를 다시 기록하는 것을 권장합니다.

본 단계를 완료한 후 단계 5: 모델 학습으로 진행합니다.

문제 해결 ​

현상원인해결
카메라를 찾을 수 없음인덱스 오류/권한/드라이버 누락lerobot-find-cameras로 확인; /dev/video* 권한 확인(video 그룹에 추가)
기록 중단시리얼 포트 타임아웃3개 장치의 시리얼 포트가 점유되지 않았는지 확인 후 재시도
이미지가 전부 검정/깨짐카메라 설정 오류index_or_path/fps 확인
/dev/video* 권한 없음사용자가 video 그룹에 없음sudo usermod -a -G video $USER 후 다시 로그인
데이터셋이 비어 있음정상적으로 기록되지 않음각 에피소드에서 Enter로 시작/종료했는지 확인

관련 제품

SO-ARM101 개발 키트→AmazingHand 4손가락 정교 손→