실제 로봇에서의 Imitation Learning

이 튜토리얼에서는 신경망을 학습시켜 실제 로봇을 자율적으로 제어하는 방법을 설명합니다.

다음 내용을 학습합니다:

1. 데이터셋을 기록하고 시각화하는 방법
2. …
3. 정책을 평가하고 결과를 시각화하는 방법

이 단계를 따라 수행하면, 아래 비디오에 표시된 것처럼 레고 블록을 집어 바구니에 넣는 작업을 높은 성공률로 재현할 수 있습니다.

이 튜토리얼은 특정 로봇에 한정되지 않습니다: 지원되는 모든 플랫폼에 맞게 조정할 수 있는 명령어와 API 스니펫을 안내해 드립니다.

데이터 수집 과정에서 리더 암이나 키보드와 같은 원격 조작 장치를 사용하여 로봇을 원격으로 조작하고 그 운동 궤적을 기록합니다.

충분한 궤적을 수집한 후에는 이러한 궤적을 모방하도록 신경망을 학습하고, 학습된 모델을 배포하여 로봇이 작업을 자율적으로 수행할 수 있도록 합니다.

어떤 시점에서든 문제가 발생하면 Discord 커뮤니티로 문의해 주세요.

설정에 맞는 올바른 명령어를 빠르게 얻고 싶으신가요? quickstart notebook 을 사용하면 로봇을 한 번만 설정하면 아래 명령어들이 복사하여 바로 붙여넣을 수 있는 형태로 생성됩니다.

설정 및 보정

로봇과 텔레오프 장치를 아직 설정하고 보정하지 않았다면, SO-101, OpenArm, Koch 또는 LeKiwi와 같이 해당 로봇의 튜토리얼을 따라 설정 및 보정을 수행하세요. 지원되는 모든 로봇은 사이드바의 Robots 섹션에 나열되어 있습니다.

원격 조작

이 예제에서는 SO101 로봇을 원격 조작하는 방법을 보여줍니다. 각 명령에 대해 해당하는 API 예제도 함께 제공합니다.

로봇에 할당된 id는 보정 파일을 저장하는 데 사용됩니다. 동일한 설정을 사용하는 경우 텔레오퍼레이션, 녹화, 평가 시 동일한 id를 사용하는 것이 중요합니다.

lerobot-teleoperate \
    --robot.type=so101_follower \
    --robot.port=/dev/tty.usbmodem58760431541 \
    --robot.id=my_awesome_follower_arm \
    --teleop.type=so101_leader \
    --teleop.port=/dev/tty.usbmodem58760431551 \
    --teleop.id=my_awesome_leader_arm

from lerobot.teleoperators.so_leader import SO101Leader, SO101LeaderConfig
from lerobot.robots.so_follower import SO101Follower, SO101FollowerConfig

robot_config = SO101FollowerConfig(
    port="/dev/tty.usbmodem5AB90687491",
    id="my_follower_arm",
)

teleop_config = SO101LeaderConfig(
    port="/dev/tty.usbmodem5AB90689011",
    id="my_leader_arm",
)

robot = SO101Follower(robot_config)
teleop_device = SO101Leader(teleop_config)
robot.connect()
teleop_device.connect()

while True:
    action = teleop_device.get_action()
    robot.send_action(action)

teleoperate 명령은 자동으로 다음을 수행합니다:

1. 누락된 보정을 식별하고 보정 절차를 시작합니다.
2. 로봇과 텔레오프 장치를 연결하고 텔레오퍼레이션을 시작합니다.

카메라

카메라를 설정에 추가하려면 이 가이드를 따르세요.

카메라로 텔레오퍼레이션

rerun을 사용하면 카메라 피드와 관절 위치를 시각화하면서 동시에 텔레오퍼레이션을 다시 수행할 수 있습니다. 이 예제에서는 wrist와 top 두 개의 카메라를 사용하며, 튜토리얼의 나머지 부분에서도 동일한 카메라 구성을 유지합니다.

lerobot-teleoperate \
    --robot.type=so101_follower \
    --robot.port=/dev/tty.usbmodem5AB90687491 \
    --robot.id=my_follower_arm \
    --robot.cameras="{ wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}, top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}}" \
    --teleop.type=so101_leader \
    --teleop.port=/dev/tty.usbmodem5AB90689011 \
    --teleop.id=my_leader_arm \
    --display_data=true

import time
from lerobot.teleoperators.so_leader import SO101Leader, SO101LeaderConfig
from lerobot.robots.so_follower import SO101Follower, SO101FollowerConfig
from lerobot.cameras.opencv import OpenCVCameraConfig
from lerobot.utils.visualization_utils import init_visualization, log_visualization_data, shutdown_visualization

robot_config = SO101FollowerConfig(
    port="/dev/tty.usbmodem5AB90687491",
    id="my_follower_arm",
    cameras={
        "wrist": OpenCVCameraConfig(index_or_path=0, width=640, height=480, fps=30),
        "top": OpenCVCameraConfig(index_or_path=1, width=640, height=480, fps=30)
    }
)

teleop_config = SO101LeaderConfig(
    port="/dev/tty.usbmodem5AB90689011",
    id="my_leader_arm",
)

init_visualization("rerun", session_name="teleoperation")  # pass "foxglove" to stream to Foxglove instead

robot = SO101Follower(robot_config)
teleop_device = SO101Leader(teleop_config)
robot.connect()
teleop_device.connect()

TARGET_HZ = 30
TIME_PER_FRAME = 1.0 / TARGET_HZ

while True:
    start_time = time.perf_counter()

    observation = robot.get_observation()
    action = teleop_device.get_action()
    robot.send_action(action)
    log_visualization_data("rerun", observation=observation, action=action)

    elapsed_time = time.perf_counter() - start_time
    sleep_time = TIME_PER_FRAME - elapsed_time
    if sleep_time > 0:
        time.sleep(sleep_time)

데이터셋 기록

teleoperation에 익숙해지면 첫 번째 데이터셋을 기록할 수 있습니다.

데이터셋 업로드를 위해 Hugging Face hub 기능을 사용합니다. 이전에 Hub를 사용하지 않았다면, 쓰기 권한이 있는 토큰을 사용하여 cli로 로그인할 수 있는지 확인하세요. 이 토큰은 Hugging Face 설정에서 생성할 수 있습니다.

이 명령을 실행하여 CLI에 토큰을 추가하세요:

hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential

그런 다음 Hugging Face 저장소 이름을 변수에 저장합니다:

HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')
echo $HF_USER

이제 데이터셋을 기록할 수 있습니다. 5개의 에피소드를 기록하고 데이터셋을 허브에 업로드하려면, 아래 코드를 로봇에 맞게 수정한 후 명령어나 API 예시를 실행하세요.

lerobot-record \
    --robot.type=so101_follower \
    --robot.port=/dev/tty.usbmodem585A0076841 \
    --robot.id=my_awesome_follower_arm \
    --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}}" \
    --robot.cameras="{ wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}, top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}}" \
    --teleop.type=so101_leader \
    --teleop.port=/dev/tty.usbmodem58760431551 \
    --teleop.id=my_awesome_leader_arm \
    --display_data=true \
    --dataset.repo_id=${HF_USER}/record-test \
    --dataset.num_episodes=5 \
    --dataset.single_task="Grab the black cube" \
    --dataset.streaming_encoding=true \
    --dataset.encoder_threads=2
# Optional: --dataset.rgb_encoder.vcodec=auto

from lerobot.cameras.opencv import OpenCVCameraConfig
from lerobot.datasets.lerobot_dataset import LeRobotDataset
from lerobot.utils.feature_utils import hw_to_dataset_features
from lerobot.robots.so_follower import SO101Follower, SO101FollowerConfig
from lerobot.teleoperators.so_leader.config_so_leader import SO101LeaderConfig
from lerobot.teleoperators.so_leader.so_leader import SO101Leader
from lerobot.common.control_utils import init_keyboard_listener
from lerobot.utils.utils import log_say
from lerobot.utils.visualization_utils import init_visualization
from lerobot.scripts.lerobot_record import record_loop
from lerobot.processor import make_default_processors

NUM_EPISODES = 5
FPS = 30
EPISODE_TIME_SEC = 60
RESET_TIME_SEC = 10
TASK_DESCRIPTION = "My task description"

def main():
    # Create robot configuration
    robot_config = SO101FollowerConfig(
        port="/dev/tty.usbmodem5AB90687491",
        id="my_follower_arm",
        cameras={
            "wrist": OpenCVCameraConfig(index_or_path=0, width=640, height=480, fps=30),
            "top": OpenCVCameraConfig(index_or_path=1, width=640, height=480, fps=30)
        }
    )

    teleop_config = SO101LeaderConfig(
        port="/dev/tty.usbmodem5AB90689011",
        id="my_leader_arm",
    )

    # Initialize the robot and teleoperator
    robot = SO101Follower(robot_config)
    teleop = SO101Leader(teleop_config)

    # Configure the dataset features
    action_features = hw_to_dataset_features(robot.action_features, "action")
    obs_features = hw_to_dataset_features(robot.observation_features, "observation")
    dataset_features = {**action_features, **obs_features}

    # Create the dataset
    dataset = LeRobotDataset.create(
        repo_id="<hf_username>/<dataset_repo_id>",
        fps=FPS,
        features=dataset_features,
        robot_type=robot.name,
        use_videos=True,
        image_writer_threads=4,
    )

    # Initialize the keyboard listener and rerun visualization
    _, events = init_keyboard_listener()
    init_visualization("rerun", session_name="recording")

    # Connect the robot and teleoperator
    robot.connect()
    teleop.connect()

    # Create the required processors
    teleop_action_processor, robot_action_processor, robot_observation_processor = make_default_processors()

    episode_idx = 0
    while episode_idx < NUM_EPISODES and not events["stop_recording"]:
        log_say(f"Recording episode {episode_idx + 1} of {NUM_EPISODES}")

        record_loop(
            robot=robot,
            events=events,
            fps=FPS,
            teleop_action_processor=teleop_action_processor,
            robot_action_processor=robot_action_processor,
            robot_observation_processor=robot_observation_processor,
            teleop=teleop,
            dataset=dataset,
            control_time_s=EPISODE_TIME_SEC,
            single_task=TASK_DESCRIPTION,
            display_data=True,
        )

        # Reset the environment if not stopping or re-recording
        if not events["stop_recording"] and (episode_idx < NUM_EPISODES - 1 or events["rerecord_episode"]):
            log_say("Reset the environment")
            record_loop(
                robot=robot,
                events=events,
                fps=FPS,
                teleop_action_processor=teleop_action_processor,
                robot_action_processor=robot_action_processor,
                robot_observation_processor=robot_observation_processor,
                teleop=teleop,
                control_time_s=RESET_TIME_SEC,
                single_task=TASK_DESCRIPTION,
                display_data=True,
            )

        if events["rerecord_episode"]:
            log_say("Re-recording episode")
            events["rerecord_episode"] = False
            events["exit_early"] = False
            dataset.clear_episode_buffer()
            continue

        dataset.save_episode()
        episode_idx += 1

    # finalize dataset
    log_say("Finalizing dataset...")
    dataset.finalize()
    # Clean up
    log_say("Stop recording")
    robot.disconnect()
    teleop.disconnect()
    dataset.push_to_hub()


if __name__ == "__main__":
    main()

선택한 카메라 이름(여기서는 wrist와 top)가 데이터셋 키 observation.images.wrist와 observation.images.top가 됩니다. 이 데이터셋으로 학습된 정책은 배포 시에도 동일한 카메라 이름과 해상도를 기대하므로, 이 튜토리얼의 모든 단계에서 동일한 --robot.cameras 값을 재사용하세요. 이름이 달라야 하는 경우 Rename Map를 참조하세요.

lerobot-record는 세션의 날짜와 시간을 --dataset.repo_id의 끝에 추가하여 모든 녹화 파일에 고유한 이름을 부여합니다: ${HF_USER}/record-test는 ${HF_USER}/record-test_YYYYMMDD_HHMMSS로 저장됩니다(예: record-test_20260929_143012). 전체 이름은 Hugging Face 프로필에서 또는 ls ~/.cache/huggingface/lerobot/${HF_USER} 명령으로 확인할 수 있으며, 아래 명령에서 record-test_YYYYMMDD_HHMMSS라고 표시된 부분에 해당 이름을 사용하세요. 전달한 정확한 이름을 유지하려면 --dataset.no_stamp=true를 추가하세요.

Dataset 업로드

로컬에서는 데이터셋이 ~/.cache/huggingface/lerobot/{repo-id} 폴더에 저장됩니다. 데이터 기록이 끝나면 데이터셋은 Hugging Face 페이지(예: https://huggingface.co/datasets/${HF_USER}/record-test_YYYYMMDD_HHMMSS)에 업로드되며, 다음을 실행하여 해당 주소를 확인할 수 있습니다:

echo https://huggingface.co/datasets/${HF_USER}/record-test_YYYYMMDD_HHMMSS

데이터세트에는 커뮤니티가 쉽게 찾을 수 있도록 LeRobot 태그가 자동으로 부여되며, --dataset.tags='["tutorial"]'와 같이 사용자 정의 태그도 추가할 수 있습니다.

LeRobot 태그로 검색하여 허브에서 다른 LeRobot 데이터셋을 찾을 수 있습니다.

로컬 데이터셋을 Hub에 수동으로 업로드하려면 다음을 실행할 수 있습니다:

hf upload ${HF_USER}/record-test_YYYYMMDD_HHMMSS ~/.cache/huggingface/lerobot/${HF_USER}/record-test_YYYYMMDD_HHMMSS --repo-type dataset

Record 함수

lerobot-record는 로봇 작동 중 데이터를 수집하고 관리하기 위한 도구 모음을 제공합니다:

1. 데이터 저장

• 데이터는 LeRobotDataset 형식으로 저장되며, 녹화 중 디스크에 저장됩니다.
• 기본적으로 데이터셋은 녹화 후 Hugging Face 페이지에 업로드됩니다.
  • 업로드를 비활성화하려면 --dataset.push_to_hub=False를 사용하세요.

2. 체크포인트 생성 및 재개

• Checkpoints는 녹화 중에 자동으로 생성됩니다.
• 문제가 발생했거나 동일한 데이터셋에 추가 에피소드를 기록하려면 --resume=true 옵션을 추가하여 동일한 명령을 다시 실행하면 됩니다. 타임스탬프를 포함한 전체 데이터셋 이름을 전달해야 합니다(--dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS). 녹화를 재개할 때 --dataset.num_episodes는 데이터셋의 목표 총 에피소드 수가 아니라 추가로 기록할 에피소드 수로 설정해야 합니다! 또한 --dataset.root="local_path"도 반드시 설정해야 합니다. 이는 데이터셋의 새 부분을 저장할 로컬 경로이며 재개를 위해 필수적입니다.
• --resume=true 없이 명령을 다시 실행하면 새 타임스탬프를 가진 새로운 데이터셋이 시작됩니다. --dataset.no_stamp=true를 사용하는 경우, 먼저 기존 데이터셋 디렉터리를 삭제해야 합니다.

3. 기록 매개변수

명령줄 인수를 사용하여 데이터 기록 흐름을 설정합니다:

• --dataset.episode_time_s=60 각 데이터 기록 에피소드의 지속 시간(기본값: 60초).
• --dataset.reset_time_s=60 각 에피소드 후 환경을 재설정하는 시간(기본값: 60초).
• --dataset.num_episodes=50 기록할 에피소드의 총 개수 (기본값: 50).

4. 녹화 중 키보드 제어

키보드 단축키를 사용하여 데이터 기록 흐름을 제어합니다:

• 오른쪽 화살표 (→) 또는 n를 누르면: 현재 에피소드를 조기 종료하거나 시간을 초기화하고 다음으로 이동합니다.
• 왼쪽 화살표 (←) 또는 r를 눌러 현재 에피소드를 취소하고 다시 녹화합니다.
• Escape (ESC) 또는 q를 누르면: 세션을 즉시 중단하고, 비디오를 인코딩한 후, 데이터셋을 업로드합니다.

이 제어 흐름 단축키는 X11, Wayland, headless/SSH 세션에서 작동합니다. 전역 키보드 백엔드가 사용 불가능한 경우(Wayland, headless 머신, Accessibility 권한이 없는 macOS)에는 lerobot-record가 터미널에서 동일한 키를 자동으로 읽습니다. 인터랙티브 터미널에서 실행하고 해당 터미널에 포커스를 유지해 두세요. 또한 문자 대체키 n(다음, →와 동일), r(다시 녹화, ←와 동일), q(종료, ESC와 동일)도 사용할 수 있습니다. $DISPLAY 설정은 필요하지 않습니다.

이 내용은 녹화 제어 흐름에만 적용됩니다. 키보드 원격 조작(키보드로 로봇을 조종하는 것)은 여전히 전역 키 백엔드가 필요하므로, X11 세션, Windows 데스크톱, 또는 Accessibility/Input Monitoring 권한이 부여된 macOS에서만 작동하며, Wayland나 헤드리스 세션에서는 작동하지 않습니다.

데이터 수집 팁

데이터 기록에 익숙해지면 학습을 위한 더 큰 데이터셋을 만들 수 있습니다. 좋은 시작 과제는 물체를 서로 다른 위치에서 집어 바구니에 넣는 것입니다. 최소 50개의 에피소드를 기록하고, 위치당 10개씩 기록하는 것을 권장합니다. 카메라는 고정된 상태로 유지하고, 기록 전반에 걸쳐 일관된 그랩핑 동작을 유지하세요. 또한 조작하는 물체가 카메라에 잘 보이도록 하세요. 좋은 기준은 카메라 이미지만 보고도 본인이 해당 작업을 수행할 수 있을 정도여야 한다는 것입니다.

다음 섹션에서는 신경망을 학습합니다. 안정적인 그립 성능을 달성한 후에는 데이터 수집 단계에서 추가적인 그립 위치, 다양한 그립 기법, 카메라 위치 변경과 같은 더 많은 변형을 도입할 수 있습니다.

결과에 방해가 될 수 있으므로, 변형을 너무 빠르게 많이 추가하지 마세요.

이 중요한 주제를 더 깊이 파고들고 싶으시다면, 좋은 데이터셋의 조건에 대해 작성한 블로그 글을 확인해 보실 수 있습니다.

Cadence 보고

lerobot-record는 루프를 --dataset.fps에 맞춰 진행하며 실제로 달성한 성능을 보고합니다. 유지하는 각 에피소드에 대해 한 줄 요약과, 녹화가 끝날 때 전체 세션에 대한 블록을 출력합니다. Ctrl-C로 중단한 경우에도 마찬가지입니다.

Cadence (episode 0): 29.88 Hz vs 30 Hz target · 600 ticks, 20.0 s measured · 8/599 ticks over the 33.3 ms budget (work mean 18.4 ms, worst 45.1 ms)
Cadence (episode 1): 29.88 Hz vs 30 Hz target · 600 ticks, 20.0 s measured · 8/599 ticks over the 33.3 ms budget (work mean 18.4 ms, worst 45.1 ms)
Cadence summary — whole run, 2 episodes · target 30 Hz (33.3 ms budget per tick): 1200 ticks, 1198 judged
  effective cadence: 29.88 Hz over 40.1 s measured
  ticks over the 33.3 ms work budget: 16/1198 (1.3%) — work mean 18.4 ms, worst 45.1 ms
  loop-body steps (share of measured work):
    observe      mean  13.65 ms · worst  40.20 ms ·  74.4% of work · 1200 calls
    process_obs  mean   0.30 ms · worst   0.30 ms ·   1.6% of work · 1200 calls
    teleop       mean   1.80 ms · worst   1.80 ms ·   9.8% of work · 1200 calls
    send         mean   0.90 ms · worst   0.90 ms ·   4.9% of work · 1200 calls
    record       mean   1.70 ms · worst   1.90 ms ·   9.3% of work · 1200 calls
  pacing headroom: 15.1 ms slept per tick on average (max 16.7 ms) — near zero means the loop is saturated

이 데이터셋으로 학습하기 전에 읽어볼 가치가 있는 내용입니다. 프레임의 타임스탬프는 인덱스에서 유도되므로, 25 Hz로 실행된 세션도 30 Hz라고 주장하는 데이터셋을 생성합니다. 기록된 움직임은 단순히 현실보다 빠를 뿐입니다. 위에서 observe는 루프 작업의 74%를 차지하며, 33.3 ms 예산에서 worst가 40 ms입니다. 카메라가 그 16틱을 초과하게 만든 원인이었습니다. 페이스 헤드룸이 거의 0에 가깝다는 것은 느린 틱을 흡수할 여유가 더 이상 없다는 뜻입니다.

에피소드 사이의 리셋 단계는 동일한 방식으로 진행되지만, 아무것도 기록하지 않으므로 의도적으로 이 수치에 포함되지 않습니다. lerobot-teleoperate와 lerobot-replay는 동일한 방식으로 보고하며, lerobot-rollout는 Cadence Reporting에 설명된 보간 관련 항목을 추가합니다.

문제 해결:

• Linux에서 녹화 제어 플로우 키(화살표 키, Escape)는 lerobot-record가 인터랙티브 터미널에서 실행되는 한 X11, Wayland, 헤드리스/SSH 세션 모두에서 작동하며 $DISPLAY 설정이 필요하지 않습니다. 키가 반응하지 않으면 파이프/비-TTY 세션이 아닌 인터랙티브(TTY) 터미널에 있는지, 그리고 해당 터미널이 포커스되어 있는지 확인하십시오. 문자 대안 키 n / r / q도 작동합니다. 키보드 텔레오퍼레이션(녹화 제어 플로우와 달리)은 여전히 전역 키 백엔드, 즉 X11 세션, Windows 데스크톱, 또는 Accessibility/Input Monitoring 권한이 부여된 macOS가 필요하며 Wayland 또는 헤드리스 머신에서는 사용할 수 없습니다. pynput 제한 사항을 참조하십시오.

데이터셋 시각화

데이터셋은 기본적으로 Hub에 업로드됩니다(--dataset.push_to_hub=False를 전달한 경우를 제외하고) 따라서 LeRobot Dataset Visualizer에서 바로 열 수 있습니다. 홈 페이지에 리포지토리 ID를 입력하거나, 이 명령이 출력하는 링크를 통해 첫 번째 에피소드로 바로 이동할 수 있습니다:

echo "https://huggingface.co/spaces/lerobot/visualize_dataset?path=/${HF_USER}/record-test_YYYYMMDD_HHMMSS/episode_0"

비주얼라이저에 로그인하여 비공개 데이터셋을 엽니다. 단계별 안내는 브라우저에서 데이터셋 탐색을 참고하세요.

에피소드 재생

유용한 기능 중 하나는 replay 함수로, 기록한 에피소드나 외부 데이터셋의 에피소드를 재생할 수 있습니다. 이 함수는 로봇 동작의 재현성을 테스트하고, 동일한 모델의 로봇 간 이전 가능성을 평가하는 데 도움이 됩니다.

아래 명령어나 API 예제를 사용하여 로봇에서 첫 번째 에피소드를 재생할 수 있습니다:

lerobot-replay \
    --robot.type=so101_follower \
    --robot.port=/dev/tty.usbmodem58760431541 \
    --robot.id=my_awesome_follower_arm \
    --dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
    --dataset.episode=0 # choose the episode you want to replay

import time

from lerobot.datasets import LeRobotDataset
from lerobot.robots.so_follower import SO101Follower, SO101FollowerConfig
from lerobot.utils.robot_utils import precise_sleep
from lerobot.utils.utils import log_say

episode_idx = 0

robot_config = SO101FollowerConfig(port="/dev/tty.usbmodem5AB90687491", id="my_follower_arm")

robot = SO101Follower(robot_config)
robot.connect()

dataset = LeRobotDataset("<hf_username>/<dataset_repo_id>", episodes=[episode_idx])
actions = dataset.select_columns("action")

log_say(f"Replaying episode {episode_idx}")
for idx in range(dataset.num_frames):
    t0 = time.perf_counter()

    action = {
        name: float(actions[idx]["action"][i]) for i, name in enumerate(dataset.features["action"]["names"])
    }
    robot.send_action(action)

    precise_sleep(max(1.0 / dataset.fps - (time.perf_counter() - t0), 0.0))

robot.disconnect()

로봇은 녹화한 동작과 유사한 동작을 재현해야 합니다. 예를 들어, Trossen Robotics의 ALOHA 로봇에서 replay를 사용하는 이 영상을 확인해 보세요.

정책 학습

로봇을 제어하는 정책을 학습하려면 lerobot-train 스크립트를 사용하세요. 몇 가지 인수가 필요합니다. 아래는 예시 명령입니다:

lerobot-train \
  --dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
  --policy.type=act \
  --output_dir=outputs/train/act_so101_test \
  --job_name=act_so101_test \
  --policy.device=cuda \
  --trackio.enable=true \
  --policy.repo_id=${HF_USER}/my_policy

명령어를 설명해 보겠습니다:

1. 이전에 기록한 데이터셋을 --dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS 인수로 제공했습니다(타임스탬프를 포함한 데이터셋의 전체 이름을 사용하세요).
2. policy.type=act를 지정하여 정책을 제공했습니다. 이는 configuration_act.py에서 설정을 로드합니다. 중요한 점은, 이 정책이 데이터셋에 저장된 로봇의 모터 상태, 모터 동작 및 카메라(예: wrist 및 top)의 수에 자동으로 적응한다는 것입니다.
3. Nvidia GPU에서 학습하므로 policy.device=cuda를 제공했지만, Apple silicon에서 학습하려면 policy.device=mps를 사용할 수 있습니다.
4. 학습 플롯을 시각화하기 위해 Trackio를 사용하도록 trackio.enable=true를 제공했습니다. 이는 선택 사항입니다. 대시보드를 열려면 trackio show --project lerobot을 실행하거나, 실행을 Hugging Face Space에 동기화하려면 --trackio.space_id=<user>/<space>를 전달하세요.
5. --steps를 설정하지 않았으므로 학습은 기본값인 100,000 스텝 동안 실행됩니다. 이는 일반적으로 작은 데이터셋에 필요한 것보다 많습니다. 모방 학습은 데이터에 대해 5~10 에포크 내에 수렴하는 것이 일반적입니다. 데이터셋 크기와 배치 크기에 따라 에포크를 --steps 값으로 변환하는 방법은 Compute & Hardware Guide를 참고하세요.

학습에는 몇 시간이 걸립니다. 체크포인트는 outputs/train/act_so101_test/checkpoints에서 찾을 수 있습니다.

last 체크포인트에서 act_so101_test 정책의 학습을 재개하는 예시 명령은 다음과 같습니다:

lerobot-train \
  --config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
  --resume=true

--config_path은 Hub repo id도 허용합니다. 실행이 Hub에 체크포인트를 푸시한 경우(--save_checkpoint_to_hub=true), 해당 리포지토리에서 바로 재개할 수 있습니다. 최신 체크포인트가 다운로드되고 학습이 계속되며, 옵티마이저, 스케줄러, 스텝 카운터 및 데이터 순서가 복원됩니다:

lerobot-train --config_path=${HF_USER}/my_policy --resume=true

학습 후 모델을 허브에 푸시하지 않으려면 --policy.push_to_hub=false를 사용하세요.

추가로 tags를 제공하거나 license를 지정하거나, 다음을 추가하여 모델 저장소를 private으로 만들 수 있습니다: --policy.private=true --policy.tags=\[so101,tutorial\] --policy.license=mit

Google Colab을 사용하여 학습

로컬 컴퓨터에 고성능 GPU가 없다면 ACT 학습 노트북을 참고하여 Google Colab을 활용해 모델을 학습할 수 있습니다.

Hugging Face Jobs를 사용하여 학습

Hugging Face Jobs를 사용하면 하드웨어를 쉽게 선택하고 클라우드에서 학습을 실행할 수 있습니다. 따라서 고성능 GPU가 없거나 더 많은 VRAM이 필요하거나, 단순히 모델을 훨씬 더 빠르게 학습하고 싶다면 HF Jobs를 사용하세요. 사용량 과금 방식이며, 사용된 각 초에 대해 비용을 지불합니다. 가격 및 추가 정보는 여기에서 확인할 수 있습니다.

lerobot-train은 기본적으로 로컬에서 실행됩니다. HuggingFace GPU에서 실행하려면 하드웨어 플레버 이름을 지정하여 --job.target를 전달하세요:

lerobot-train \
  --dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
  --policy.type=act \
  --policy.repo_id=${HF_USER}/my_policy \
  --job.target=a10g-small

hf jobs hardware로 사용 가능한 flavor와 가격을 확인합니다. 실행 시 로그가 터미널에 스트리밍되며, Ctrl-C를 눌러 디태치할 수 있습니다(작업은 클라우드에서 계속 실행됩니다). 다시 연결하거나 취소하려면:

hf jobs logs <job-id>
hf jobs cancel <job-id>

데이터셋이 로컬에만 존재하는 경우(아직 Hub에 없는 경우), 작업이 repo_id로 다운로드할 수 있도록 private Hub 저장소로 자동으로 push됩니다(공개되지 않음). 학습된 모델은 실행이 끝날 때 모델 저장소로 push됩니다. 저장되는 모든 중간 체크포인트를 실행 중에도 진행 상황을 모니터링할 수 있도록 Hub에 push하려면 --save_checkpoint_to_hub=true를 추가하세요. 이 기능은 해당 기능이 포함된 런타임 이미지가 필요합니다.

모든 작업(그리고 런에 의해 업로드된 모든 데이터셋)은 Hub에서 쉽게 찾을 수 있도록 lerobot 태그가 지정됩니다. --job.tags '["my-tag"]'를 사용하여 사용자 정의 태그를 추가할 수 있습니다.

기본적으로 작업은 2d(48시간)의 wall-clock 시간으로 제한됩니다. HF Jobs duration 문자열로 이를 재정의할 수 있으며, 예를 들어 --job.timeout=4h를 사용하면 더 빠르게 실패하고, --job.timeout=7d를 사용하면 더 긴 시간 동안 실행할 수 있습니다.

참고: 모델 저장소는 사전에 생성됩니다(작업이 실행되는 스테이징된 학습 구성을 포함합니다). 모델이 push되기 전에 실행이 실패하면 해당 저장소는 Hub에 남아 있어 검사할 수 있습니다 — 자동으로 삭제되지 않으므로 반복적인 실패로 인해 빈 저장소가 남을 수 있습니다. hf repos delete <repo-id>을 사용하여 삭제할 수 있습니다.

사전 요구 사항: 제출하기 전에 hf auth login을 실행하세요. Trackio의 경우 --trackio.space_id=<user>/<space>를 전달하세요 — Space가 없으면 생성되며, 작업의 HF_TOKEN이 자동으로 전달됩니다.

작업에서 재개하기. 재개 명령에 --job.target를 추가하면 재개가 클라우드에서 실행됩니다. 동일한 명령이 로컬 또는 원격에서 모두 작동합니다. 체크포인트 저장소가 신뢰할 수 있는 출처(source of truth)이며, 새로운 체크포인트는 동일한 저장소에서 계보를 이어갑니다:

# resume a Hub run on a job (its checkpoints are already on the Hub)
lerobot-train --config_path=${HF_USER}/my_policy --resume=true --job.target=a10g-small

# resume a LOCAL run on a job — the checkpoint is uploaded to a private Hub repo first,
# then the job resumes from it (a local-only dataset is uploaded the same way)
lerobot-train \
  --config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
  --resume=true \
  --job.target=a10g-small

Job 설정은 현재 명령에서 가져오므로 필요에 따라 --job.target, --job.timeout 등을 오버라이드하세요. 재개된 실행이 나중에 다시 재개될 수 있도록 하려면 --save_checkpoint_to_hub=true를 유지하세요.

Upload policy checkpoints

학습이 완료되면 최신 체크포인트를 다음 명령어로 업로드합니다:

hf upload ${HF_USER}/act_so101_test \
  outputs/train/act_so101_test/checkpoints/last/pretrained_model

다음과 같이 중간 체크포인트를 업로드할 수도 있습니다:

CKPT=010000
hf upload ${HF_USER}/act_so101_test${CKPT} \
  outputs/train/act_so101_test/checkpoints/${CKPT}/pretrained_model

추론을 실행하고 정책을 평가합니다

lerobot-rollout를 사용하여 로봇에 학습된 정책을 배포할 수 있습니다. 필요에 따라 다양한 전략을 선택할 수 있습니다.

동일한 --robot.id(교정이 발견되도록), 동일한 --robot.cameras, 그리고 녹화된 데이터셋과 동일한 작업 설명을 사용하세요. lerobot-rollout로 녹화된 데이터셋은 이름이 rollout_로 시작해야 하며, lerobot-record와 마찬가지로 해당 이름에 타임스탬프를 추가합니다.

아래 예시에서는 --policy.path에서 모델을 로드합니다. --save_checkpoint_to_hub=true로 여러 체크포인트가 커밋된 후 특정 푸시된 버전을 고정하려면, 커밋 해시, 브랜치 또는 태그를 --policy.pretrained_revision에 추가하세요. 각 푸시된 체크포인트에는 해당 스텝이 태그로 지정되어 있으므로(예: --policy.pretrained_revision=010000), 커밋 sha를 조회하지 않고도 스텝으로 체크포인트를 복구할 수 있습니다.

lerobot-rollout \
  --strategy.type=base \
  --policy.path=${HF_USER}/my_policy \
  --robot.type=so101_follower \
  --robot.port=/dev/tty.usbmodem5AB90687491 \
  --robot.id=my_follower_arm \
  --robot.cameras="{ wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}, top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}}" \
  --task="Grab the black cube" \
  --duration=60

lerobot-rollout \
  --strategy.type=sentry \
  --strategy.upload_every_n_episodes=5 \
  --policy.path=${HF_USER}/my_policy \
  --robot.type=so101_follower \
  --robot.port=/dev/tty.usbmodem5AB90687491 \
  --robot.id=my_follower_arm \
  --robot.cameras="{ wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}, top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}}" \
  --dataset.repo_id=${HF_USER}/rollout_so101_test \
  --dataset.single_task="Grab the black cube" \
  --duration=600

--strategy.type 플래그는 실행 모드를 선택합니다:

• base: 데이터 기록 없이 자율 롤아웃 수행(빠른 평가에 유용)
• sentry: 자동 업로드를 지원하는 연속 기록(대규모 평가에 유용)
• highlight: 키보드 입력으로 저장하는 링 버퍼 녹화(흥미로운 이벤트를 캡처하는 데 유용)
• dagger: Human-in-the-loop 데이터 수집(자세한 내용은 HIL Data Collection을 참조)
• episodic: 에피소드 간 리셋 단계를 포함하는 에피소드 중심 정책 기록

모든 전략은 느린 VLA 모델(Pi0, Pi0.5, SmolVLA)의 원활한 실행을 위해 --inference.type=rtc를 지원합니다. 모든 전략과 해당 플래그는 정책 배포를 참고하세요.