LeRobot documentation

Học bắt chước trên robot thực

LeRobot

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.7.0).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Học bắt chước trên robot thực

Tutorial này sẽ giải thích cách huấn luyện một mạng nơ-ron để điều khiển một robot thực một cách tự chủ.

Bạn sẽ học được:

Cách ghi lại và trực quan hóa bộ dữ liệu của bạn.
Cách huấn luyện một chính sách bằng dữ liệu của bạn và chuẩn bị nó để đánh giá.
Cách đánh giá chính sách của bạn và trực quan hóa kết quả.

Bằng cách làm theo các bước này, bạn sẽ có thể tái hiện các tác vụ, chẳng hạn như nhặt một khối Lego và đặt nó vào một thùng chứa với tỷ lệ thành công cao, như được minh họa trong video bên dưới.

Video: pickup lego block task

Hướng dẫn này không gắn với một robot cụ thể: chúng tôi sẽ hướng dẫn bạn các lệnh và đoạn mã API có thể điều chỉnh cho bất kỳ nền tảng nào được hỗ trợ.

Trong quá trình thu thập dữ liệu, bạn sẽ sử dụng một thiết bị “teleoperation”, chẳng hạn như cánh tay dẫn hoặc bàn phím, để điều khiển robot từ xa và ghi lại các quỹ đạo chuyển động của nó.

Sau khi bạn đã thu thập đủ các quỹ đạo, bạn sẽ huấn luyện một mạng nơ-ron để bắt chước các quỹ đạo này và triển khai mô hình đã được huấn luyện để robot của bạn có thể thực hiện nhiệm vụ một cách tự chủ.

Nếu bạn gặp bất kỳ vấn đề nào ở bất kỳ thời điểm nào, hãy tham gia cộng đồng Discord của chúng tôi để được hỗ trợ.

Bạn muốn nhanh chóng có được các lệnh phù hợp với cấu hình của mình? notebook khởi động nhanh cho phép bạn cấu hình robot một lần và tạo ra tất cả các lệnh bên dưới sẵn sàng để dán.

Cài đặt và Hiệu chuẩn

Nếu bạn chưa thiết lập và hiệu chuẩn robot cùng thiết bị teleop của mình, hãy thực hiện theo hướng dẫn dành cho robot của bạn, ví dụ SO-101, OpenArm, Koch hoặc LeKiwi. Tất cả các robot được hỗ trợ đều được liệt kê dưới mục Robots ở thanh bên.

Điều khiển từ xa

Trong ví dụ này, chúng tôi sẽ minh họa cách điều khiển từ xa robot SO101. Với mỗi lệnh, chúng tôi cũng cung cấp một ví dụ API tương ứng.

Lưu ý rằng id liên quan đến một robot được sử dụng để lưu trữ tệp hiệu chuẩn. Việc sử dụng cùng một id khi điều khiển từ xa, ghi hình và đánh giá là rất quan trọng khi sử dụng cùng một cấu hình.

Lệnh

Ví dụ API

Lệnh teleoperate sẽ tự động:

Xác định các hiệu chuẩn còn thiếu và khởi động quy trình hiệu chuẩn.
Kết nối robot và thiết bị điều khiển từ xa, sau đó bắt đầu điều khiển từ xa.

Camera

Để thêm camera vào hệ thống của bạn, hãy làm theo Hướng dẫn này.

Điều khiển từ xa bằng camera

Với rerun, bạn có thể điều khiển từ xa một lần nữa trong khi đồng thời trực quan hóa các luồng camera và vị trí các khớp. Ví dụ này sử dụng hai camera, wrist và top; chúng ta sẽ giữ nguyên cấu hình camera này cho phần còn lại của hướng dẫn.

Lệnh

Ví dụ API

Ghi lại một bộ dữ liệu

Khi bạn đã quen thuộc với teleoperation, bạn có thể thu thập bộ dữ liệu đầu tiên của mình.

Chúng tôi sử dụng các tính năng của Hugging Face hub để tải lên bộ dữ liệu của bạn. Nếu bạn chưa từng sử dụng Hub trước đây, hãy đảm bảo rằng bạn có thể đăng nhập qua cli bằng một token có quyền ghi, token này có thể được tạo từ cài đặt Hugging Face.

Thêm token của bạn vào CLI bằng cách chạy lệnh này:

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

Sau đó, lưu tên kho Hugging Face của bạn vào một biến:

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

Bây giờ bạn có thể ghi lại một tập dữ liệu. Để ghi lại 5 episode và tải tập dữ liệu của bạn lên hub, hãy điều chỉnh đoạn mã bên dưới cho phù hợp với robot của bạn và thực thi lệnh hoặc ví dụ API.

Lệnh

Ví dụ 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()

Tên camera bạn chọn (ở đây là wrist và top) sẽ trở thành các khóa dữ liệu observation.images.wrist và observation.images.top. Một chính sách được huấn luyện trên tập dữ liệu này sẽ mong đợi cùng tên camera và độ phân giải khi triển khai, vì vậy hãy tái sử dụng cùng giá trị --robot.cameras trong mọi bước của hướng dẫn này. Nếu tên bắt buộc phải khác nhau, hãy xem Rename Map.

lerobot-record thêm ngày và giờ của phiên vào cuối --dataset.repo_id, nên mỗi bản ghi đều có tên duy nhất: ${HF_USER}/record-test được lưu dưới dạng ${HF_USER}/record-test_YYYYMMDD_HHMMSS (ví dụ record-test_20260929_143012). Tìm tên đầy đủ trên hồ sơ Hugging Face của bạn hoặc bằng ls ~/.cache/huggingface/lerobot/${HF_USER}, và dùng nó ở mọi nơi mà các lệnh bên dưới ghi record-test_YYYYMMDD_HHMMSS. Để giữ nguyên tên chính xác bạn đã truyền, thêm --dataset.no_stamp=true.

Tải lên bộ dữ liệu

Trên máy cục bộ, bộ dữ liệu của bạn được lưu trong thư mục này: ~/.cache/huggingface/lerobot/{repo-id}. Khi kết thúc quá trình ghi dữ liệu, bộ dữ liệu của bạn sẽ được tải lên trang Hugging Face của bạn (ví dụ: https://huggingface.co/datasets/${HF_USER}/record-test_YYYYMMDD_HHMMSS), bạn có thể lấy địa chỉ này bằng cách chạy:

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

Bộ dữ liệu của bạn sẽ được tự động gắn thẻ LeRobot để cộng đồng dễ dàng tìm thấy, và bạn cũng có thể thêm các thẻ tùy chỉnh, ví dụ --dataset.tags='["tutorial"]'.

Bạn có thể tìm các bộ dữ liệu LeRobot khác trên hub bằng cách tìm kiếm các thẻ LeRobot.

Bạn cũng có thể đẩy bộ dữ liệu cục bộ của mình lên Hub thủ công bằng cách chạy:

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

Hàm ghi

lerobot-record cung cấp một bộ công cụ để thu thập và quản lý dữ liệu trong quá trình vận hành robot:

1. Lưu trữ dữ liệu

Dữ liệu được lưu trữ bằng định dạng LeRobotDataset và được ghi xuống đĩa trong quá trình thu thập.
Mặc định, dataset sẽ được đẩy lên trang Hugging Face của bạn sau khi ghi lại.
- Để tắt việc tải lên, hãy sử dụng --dataset.push_to_hub=False.

2. Chấm kiểm tra và tiếp tục

Các checkpoint được tạo tự động trong quá trình ghi.
Nếu xảy ra sự cố hoặc bạn muốn ghi thêm các episode vào cùng một dataset, bạn có thể tiếp tục bằng cách chạy lại cùng một lệnh với --resume=true. Truyền tên đầy đủ của dataset, bao gồm timestamp của nó (--dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS). Khi tiếp tục ghi, --dataset.num_episodes phải được đặt thành số lượng episode bổ sung cần ghi, chứ không phải tổng số episode mục tiêu trong dataset! Hãy đảm bảo bạn cũng đặt --dataset.root="local_path", đây là đường dẫn cục bộ để lưu phần mới của dataset và là bắt buộc để tiếp tục.
Chạy lại lệnh mà không có --resume=true sẽ khởi tạo một bộ dữ liệu mới với dấu thời gian mới. Nếu bạn sử dụng --dataset.no_stamp=true, hãy xóa thư mục bộ dữ liệu hiện có trước.

3. Tham số ghi

Đặt luồng ghi dữ liệu bằng các đối số dòng lệnh:

--dataset.episode_time_s=60 Thời lượng của mỗi phiên ghi dữ liệu (mặc định: 60 giây).
--dataset.reset_time_s=60 Thời gian để đặt lại môi trường sau mỗi episode (mặc định: 60 giây).
--dataset.num_episodes=50 Tổng số episode cần ghi lại (mặc định: 50).

4. Điều khiển bằng bàn phím trong khi ghi âm

Điều khiển luồng ghi dữ liệu bằng các phím tắt trên bàn phím:

Nhấn Mũi tên phải (→) hoặc n: Dừng sớm episode hiện tại hoặc đặt lại thời gian và chuyển sang episode tiếp theo.
Nhấn Phím mũi tên trái (←) hoặc r: Hủy phiên hiện tại và thu âm lại.
Nhấn Escape (ESC) hoặc q: Dừng phiên ngay lập tức, mã hóa video và tải lên bộ dữ liệu.

Các phím tắt điều khiển luồng này hoạt động trên các phiên X11, Wayland và headless/SSH. Khi không có sẵn backend bàn phím toàn cục (Wayland, máy headless, hoặc macOS không có quyền Accessibility), lerobot-record sẽ tự động đọc cùng các phím đó từ terminal — hãy khởi chạy nó từ một terminal tương tác và giữ cho terminal luôn ở trạng thái tập trung. Bạn cũng có thể sử dụng các phím chữ tương đương n (tiếp theo, giống như →), r (ghi lại, giống như ←) và q (thoát, giống như ESC). Không cần thiết lập $DISPLAY.

Điều này chỉ áp dụng cho luồng điều khiển ghi hình. Teleoperation bằng bàn phím (điều khiển robot bằng bàn phím) vẫn cần một backend phím toàn cục, do đó nó chỉ hoạt động trên phiên X11, desktop Windows, hoặc macOS đã được cấp quyền Accessibility/Input Monitoring — không hoạt động trên Wayland hoặc các phiên headless.

Mẹo thu thập dữ liệu

Khi bạn đã quen với việc ghi lại dữ liệu, bạn có thể tạo một bộ dữ liệu lớn hơn để huấn luyện. Một tác vụ khởi đầu tốt là nắm một vật thể ở các vị trí khác nhau và đặt nó vào một thùng. Chúng tôi đề xuất ghi lại ít nhất 50 tập, với 10 tập cho mỗi vị trí. Giữ các camera cố định và duy trì hành vi nắm nhất quán trong suốt quá trình ghi. Ngoài ra, hãy đảm bảo rằng vật thể bạn đang thao tác có thể nhìn thấy trên các camera. Một quy tắc thực nghiệm tốt là bạn nên có thể tự thực hiện tác vụ đó chỉ bằng cách nhìn vào hình ảnh từ camera.

Trong các phần tiếp theo, bạn sẽ huấn luyện mạng nơ-ron của mình. Sau khi đạt được hiệu suất nắm bắt đáng tin cậy, bạn có thể bắt đầu đưa vào nhiều biến thể hơn trong quá trình thu thập dữ liệu, chẳng hạn như các vị trí nắm bổ sung, các kỹ thuật nắm khác nhau và thay đổi vị trí camera.

Tránh thêm quá nhiều biến thể quá nhanh, vì điều này có thể cản trở kết quả của bạn.

Nếu bạn muốn tìm hiểu sâu hơn về chủ đề quan trọng này, bạn có thể xem bài viết trên blog mà chúng tôi đã viết về những yếu tố tạo nên một bộ dữ liệu tốt.

Báo cáo nhịp độ

lerobot-record điều chỉnh nhịp của vòng lặp theo --dataset.fps và báo cáo những gì thực sự đạt được: một dòng tóm tắt cho mỗi episode bạn giữ lại, và một khối cho toàn bộ phiên khi kết thúc ghi hình — kể cả khi nhấn 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

Đây là nội dung đáng đọc trước khi bạn huấn luyện trên bộ dữ liệu. Con dấu thời gian của một khung hình được suy ra từ chỉ số của nó, nên một phiên chạy ở 25 Hz vẫn tạo ra bộ dữ liệu khẳng định là 30 — chuyển động được ghi lại đơn giản là nhanh hơn thực tế. Như trên, observe chiếm 74% khối lượng công việc của vòng lặp và worst của nó là 40 ms trong ngân sách 33,3 ms: chính các camera đã đẩy 16 tick vượt quá giới hạn. Dư địa nhịp độ gần bằng không nghĩa là không còn gì để hấp thụ một tick chậm.

Các pha reset giữa các episode được điều phối theo cách tương tự nhưng được cố ý không đưa vào các con số này, vì chúng không ghi nhận bất kỳ dữ liệu nào. lerobot-teleoperate và lerobot-replay báo cáo theo cách tương tự, và lerobot-rollout bổ sung các dòng riêng cho phép nội suy được mô tả trong Báo cáo nhịp độ.

Xử lý sự cố:

Trên Linux, các phím điều khiển luồng ghi hình (phím mũi tên, Escape) hoạt động trên X11, Wayland và các phiên headless/SSH miễn là lerobot-record chạy trong một terminal tương tác — không cần thiết lập $DISPLAY. Nếu các phím không có tác dụng, hãy đảm bảo bạn đang ở trong một terminal tương tác (TTY), không phải phiên piped/không-TTY, và terminal đó đang được tập trung; các phím chữ tương đương n / r / q cũng hoạt động. Teleoperation bằng bàn phím (khác với luồng điều khiển ghi hình) vẫn yêu cầu một backend phím toàn cục — một phiên X11, một desktop Windows, hoặc macOS với quyền Accessibility/Input Monitoring được cấp — và không khả dụng trên Wayland hoặc các máy headless. Xem giới hạn của pynput.

Trực quan hóa một tập dữ liệu

Bộ dữ liệu của bạn được tải lên Hub theo mặc định (trừ khi bạn đã truyền --dataset.push_to_hub=False), vì vậy bạn có thể mở nó ngay trong LeRobot Dataset Visualizer: nhập repo id của bạn trên trang chủ của công cụ này, hoặc truy cập trực tiếp vào episode đầu tiên bằng liên kết mà lệnh này in ra:

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

Đăng nhập vào trình trực quan hóa để mở một tập dữ liệu riêng tư. Xem Khám phá một tập dữ liệu trong trình duyệt để xem hướng dẫn chi tiết.

Phát lại một tập

Một tính năng hữu ích là hàm replay, cho phép bạn phát lại bất kỳ episode nào mà bạn đã ghi lại hoặc các episode từ bất kỳ dataset nào. Hàm này giúp bạn kiểm tra khả năng lặp lại các hành động của robot và đánh giá khả năng chuyển giao giữa các robot cùng model.

Bạn có thể phát lại tập đầu tiên trên robot của mình bằng lệnh bên dưới hoặc bằng ví dụ API:

Lệnh

Ví dụ API

Robot của bạn nên tái hiện các chuyển động tương tự như những gì bạn đã ghi lại. Ví dụ, hãy xem video này, trong đó chúng tôi sử dụng replay trên robot ALOHA của Trossen Robotics.

Huấn luyện một chính sách

Để huấn luyện một chính sách điều khiển robot của bạn, hãy sử dụng script lerobot-train. Một vài đối số là bắt buộc. Dưới đây là một lệnh ví dụ:

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

Hãy giải thích lệnh:

Chúng tôi đã cung cấp bộ dữ liệu được ghi lại trước đó dưới dạng đối số với --dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS (sử dụng tên đầy đủ của bộ dữ liệu, bao gồm dấu thời gian).
Chúng tôi đã cung cấp chính sách với policy.type=act. Điều này sẽ nạp cấu hình từ configuration_act.py. Quan trọng là, chính sách này sẽ tự động thích ứng với số lượng trạng thái động cơ, hành động động cơ và camera của robot của bạn (ví dụ: wrist và top) đã được lưu trong bộ dữ liệu của bạn.
Chúng tôi đã cung cấp policy.device=cuda vì chúng tôi đang huấn luyện trên GPU Nvidia, nhưng bạn có thể sử dụng policy.device=mps để huấn luyện trên Apple silicon.
Chúng tôi đã cung cấp trackio.enable=true để sử dụng Trackio cho việc trực quan hóa các biểu đồ huấn luyện. Đây là tùy chọn. Chạy trackio show --project lerobot để mở bảng điều khiển, hoặc truyền --trackio.space_id=<user>/<space> để đồng bộ hóa phiên chạy với một Hugging Face Space.
Chúng ta không đặt --steps, nên quá trình huấn luyện sẽ chạy với mặc định là 100.000 bước. Con số này thường lớn hơn mức cần thiết cho một bộ dữ liệu nhỏ: học mô phỏng thường hội tụ trong vòng 5–10 epoch trên dữ liệu. Xem Hướng dẫn Tính toán & Phần cứng để chuyển đổi số epoch thành giá trị --steps phù hợp với kích thước bộ dữ liệu và kích thước batch của bạn.

Quá trình huấn luyện sẽ mất vài giờ. Bạn sẽ tìm thấy các checkpoint trong outputs/train/act_so101_test/checkpoints.

Để tiếp tục huấn luyện từ một checkpoint, dưới đây là một lệnh ví dụ để tiếp tục từ checkpoint last của chính sách act_so101_test:

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

--config_path cũng chấp nhận một id kho Hub: nếu một run đã đẩy checkpoint của nó lên Hub (với --save_checkpoint_to_hub=true), bạn có thể tiếp tục trực tiếp từ kho đó — checkpoint mới nhất sẽ được tải xuống và quá trình huấn luyện tiếp diễn, khôi phục optimizer, scheduler, bộ đếm bước và thứ tự dữ liệu:

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

Nếu bạn không muốn đẩy mô hình của mình lên hub sau khi huấn luyện, hãy sử dụng --policy.push_to_hub=false.

Ngoài ra, bạn có thể cung cấp thêm các tags hoặc chỉ định license cho model của mình, hoặc đặt repo model thành private bằng cách thêm: --policy.private=true --policy.tags=\[so101,tutorial\] --policy.license=mit

Huấn luyện bằng Google Colab

Nếu máy tính cục bộ của bạn không có GPU mạnh, bạn có thể sử dụng Google Colab để huấn luyện mô hình của mình bằng cách làm theo notebook huấn luyện ACT.

Huấn luyện bằng Hugging Face Jobs

Hugging Face Jobs cho phép bạn dễ dàng chọn phần cứng và chạy huấn luyện trên đám mây. Vì vậy, nếu bạn không có GPU mạnh, cần thêm VRAM hoặc đơn giản là muốn huấn luyện mô hình nhanh hơn nhiều, hãy dùng HF Jobs! Mô hình thanh toán theo mức sử dụng, bạn chỉ trả tiền cho mỗi giây sử dụng, bạn có thể xem bảng giá và thông tin bổ sung tại đây.

lerobot-train chạy cục bộ theo mặc định. Để chạy trên GPU của HuggingFace, hãy truyền --job.target kèm theo tên loại phần cứng:

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

Danh sách các loại phần cứng và giá cả có sẵn với hf jobs hardware. Lệnh chạy sẽ truyền trực tiếp nhật ký của nó đến terminal của bạn; nhấn Ctrl-C để ngắt kết nối (công việc vẫn tiếp tục chạy trên đám mây). Kết nối lại hoặc hủy với:

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

Nếu dataset của bạn chỉ tồn tại cục bộ (chưa có trên Hub), nó sẽ được đẩy tự động lên một repo riêng tư trên Hub để job có thể tải xuống bằng repo_id (không có gì được công khai). Mô hình đã huấn luyện sẽ được đẩy lên repo mô hình vào cuối quá trình chạy. Để cũng đẩy mọi checkpoint trung gian lên Hub ngay khi chúng được lưu (để bạn có thể theo dõi tiến độ trong khi chạy), hãy thêm --save_checkpoint_to_hub=true — điều này yêu cầu một runtime image có chứa tính năng này.

Mọi job (và bất kỳ dataset nào được đẩy lên bởi run) đều được gắn thẻ lerobot để dễ dàng tìm thấy trên Hub. Bạn có thể thêm thẻ của riêng mình bằng --job.tags '["my-tag"]'.

Mặc định, công việc bị giới hạn ở 2d (48 giờ) theo thời gian thực. Bạn có thể ghi đè bằng chuỗi thời lượng của HF Jobs, ví dụ --job.timeout=4h để thất bại nhanh hơn hoặc --job.timeout=7d cho một lần chạy dài hơn.

Lưu ý: kho mô hình được tạo trước (nó chứa cấu hình huấn luyện đã chuẩn bị mà tác vụ sẽ chạy). Nếu một lần chạy thất bại trước khi mô hình được đẩy lên, kho đó sẽ được giữ lại trên Hub để bạn kiểm tra — nó không bị xóa tự động, nên các lần thất bại liên tiếp có thể để lại các kho trống. Xóa một kho bằng hf repos delete <repo-id>.

Điều kiện tiên quyết: chạy hf auth login trước khi gửi. Đối với Trackio, truyền --trackio.space_id=<user>/<space> — Space sẽ được tạo nếu chưa tồn tại và HF_TOKEN của job sẽ được chuyển tiếp tự động.

Tiếp tục trên một job. Thêm --job.target vào lệnh resume sẽ chạy việc tiếp tục trên cloud — cùng một lệnh hoạt động cả cục bộ lẫn từ xa. Kho checkpoint là nguồn sự thật, và các checkpoint mới sẽ tiếp tục dòng dõi trong cùng một kho:

# 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

Cấu hình công việc được lấy từ lệnh hiện tại, do đó hãy ghi đè --job.target, --job.timeout, v.v. khi cần; để lượt chạy được tiếp tục có thể tiếp tục được sau này, hãy giữ --save_checkpoint_to_hub=true.

Tải lên các checkpoint của chính sách

Khi quá trình huấn luyện hoàn tất, hãy tải lên checkpoint mới nhất bằng cách:

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

Bạn cũng có thể tải lên các checkpoint trung gian với:

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

Chạy suy luận và đánh giá chính sách của bạn

Sử dụng lerobot-rollout để triển khai chính sách đã được huấn luyện trên robot của bạn. Bạn có thể chọn các chiến lược khác nhau tùy theo nhu cầu.

Sử dụng cùng một --robot.id (để tìm thấy hiệu chuẩn), cùng một --robot.cameras và cùng mô tả tác vụ như trong bộ dữ liệu đã ghi. Các bộ dữ liệu được ghi bởi lerobot-rollout phải có tên bắt đầu bằng rollout_, và giống như lerobot-record, nó sẽ thêm dấu thời gian vào tên đó.

Các ví dụ bên dưới tải mô hình từ --policy.path. Để cố định một phiên bản đã đẩy cụ thể — hữu ích khi --save_checkpoint_to_hub=true đã cam kết nhiều checkpoint — hãy thêm --policy.pretrained_revision với một commit hash, branch hoặc tag. Mỗi checkpoint được đẩy đều được gắn tag với bước của nó (ví dụ --policy.pretrained_revision=010000), vì vậy bạn có thể khôi phục một checkpoint theo bước mà không cần tra cứu commit sha của nó.

Chế độ cơ bản (không ghi âm)

Chế độ Sentry (có ghi hình)

Cờ --strategy.type chọn chế độ thực thi:

base: Triển khai tự động không ghi lại dữ liệu (hữu ích cho đánh giá nhanh)
sentry: Ghi liên tục với tự động tải lên (hữu ích cho đánh giá quy mô lớn)
highlight: Ghi âm bằng bộ đệm vòng với phím tắt để lưu (hữu ích để ghi lại các sự kiện thú vị)
dagger: Thu thập dữ liệu có sự tham gia của con người (xem Thu thập dữ liệu HIL)
episodic: Ghi lại chính sách theo hướng tập (episode) với các pha đặt lại giữa các tập

Tất cả các chiến lược đều hỗ trợ --inference.type=rtc để thực thi mượt mà với các mô hình VLA chậm (Pi0, Pi0.5, SmolVLA). Xem Triển khai Policy để biết mọi chiến lược và cờ của chúng.

Update on GitHub

←Bảng tra cứu nhanh LeLab - Lerobot GUI→