Triển khai chính sách (lerobot-rollout)

lerobot-rollout là CLI duy nhất để triển khai các chính sách đã được huấn luyện trên robot thực. Nó hỗ trợ nhiều chiến lược thực thi và backend suy luận, từ đánh giá nhanh đến ghi liên tục và thu thập dữ liệu có sự tham gia của con người.

Bắt đầu nhanh

Không cần thêm bất kỳ phụ thuộc nào ngoài các phần mở rộng cho robot và chính sách của bạn.

lerobot-rollout \
    --strategy.type=base \
    --policy.path=lerobot/act_koch_real \
    --robot.type=koch_follower \
    --robot.port=/dev/ttyACM0 \
    --task="pick up cube" \
    --duration=30

Điều này chạy chính sách trong 30 giây mà không ghi lại.

Chọn thiết bị

Truyền --device=cpu hoặc --device=cuda để ghi đè thiết bị checkpoint trên host có thiết bị đó khả dụng. Thiết bị đã được xác định sẽ được áp dụng cho cấu hình policy trước khi tải policy và xây dựng các processor của nó. Ví dụ, thêm --device=cpu vào lệnh ở trên để chạy checkpoint được huấn luyện bằng CUDA trên host chỉ có CPU, nếu policy hỗ trợ thực thi trên CPU. Kiểm tra xem suy luận trên CPU có đáp ứng được tốc độ điều khiển yêu cầu của bạn trước khi triển khai trên robot.

Khi --device bị bỏ qua, rollout sẽ sử dụng thiết bị trong cấu hình policy nếu đã được đặt, nếu không sẽ tự động chọn một thiết bị khả dụng. Hành vi tương tự cũng áp dụng cho RolloutConfig(device=...) với build_rollout_context.

Các chiến lược

Chọn một chiến lược bằng --strategy.type=<name>. Mỗi chiến lược định nghĩa một vòng lặp điều khiển khác nhau với các ngữ nghĩa ghi nhận và tương tác riêng.

Cơ bản ( --strategy.type=base )

Thực thi chính sách tự động mà không ghi lại dữ liệu. Sử dụng chế độ này để đánh giá nhanh, trình diễn, hoặc khi bạn chỉ cần quan sát robot.

lerobot-rollout \
    --strategy.type=base \
    --policy.path=${HF_USER}/my_policy \
    --robot.type=so100_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
    --task="Put lego brick into the box" \
    --duration=60

Sentry ( --strategy.type=sentry )

Ghi âm tự động liên tục với tải lên Hugging Face Hub định kỳ. Ranh giới tập được tự động tính toán từ độ phân giải camera và FPS để mỗi tập được lưu tạo ra một tệp video hoàn chỉnh, giúp quá trình tải lên hiệu quả.

Trạng thái của Policy (hidden state, hàng đợi RTC) được duy trì xuyên qua ranh giới giữa các episode: robot không được đặt lại giữa các episode.

lerobot-rollout \
    --strategy.type=sentry \
    --strategy.upload_every_n_episodes=5 \
    --policy.path=${HF_USER}/my_policy \
    --robot.type=so100_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
    --dataset.repo_id=${HF_USER}/rollout_eval_data \
    --dataset.single_task="Put lego brick into the box" \
    --duration=3600

Nổi bật ( --strategy.type=highlight )

Triển khai tự động với ghi hình theo yêu cầu thông qua bộ đệm vòng có giới hạn bộ nhớ. Bộ đệm ghi lại N giây cuối cùng của dữ liệu giám sát. Nhấn phím lưu để xả bộ đệm và bắt đầu ghi hình trực tiếp; nhấn lại để lưu phiên. Với backend bất đồng bộ, mỗi lần bật/tắt sẽ tạm dừng suy luận, vô hiệu hóa chuyển động đã xếp hàng/được nội suy và yêu cầu giữ cục bộ được hỗ trợ trước khi xả hoặc lưu theo kiểu chặn. Một lần chạy ổn định sẽ tiếp tục từ một bản ghi mới sau đó.

lerobot-rollout \
    --strategy.type=highlight \
    --strategy.ring_buffer_seconds=30 \
    --strategy.save_key=s \
    --strategy.push_key=h \
    --policy.path=${HF_USER}/my_policy \
    --robot.type=koch_follower \
    --robot.port=/dev/ttyACM0 \
    --dataset.repo_id=${HF_USER}/rollout_highlight_data \
    --dataset.single_task="Pick up the red cube"

Điều khiển bằng bàn phím:

DAgger ( --strategy.type=dagger )

Thu thập dữ liệu có sự tham gia của con người. Xen kẽ giữa việc thực thi chính sách tự chủ và sự can thiệp của con người thông qua người vận hành từ xa. Các khung hình can thiệp được gắn thẻ intervention=True. Yêu cầu có người vận hành từ xa (--teleop.type).

Xem hướng dẫn Thu thập dữ liệu có sự tham gia của con người để có quy trình chi tiết.

Chế độ chỉ sửa lỗi (mặc định): Chỉ ghi lại các cửa sổ sửa lỗi của con người. Mỗi lần sửa lỗi tạo thành một tập.

lerobot-rollout \
    --strategy.type=dagger \
    --strategy.num_episodes=20 \
    --policy.path=outputs/pretrain/checkpoints/last/pretrained_model \
    --robot.type=bi_openarm_follower \
    --teleop.type=bi_openarm_mini \
    --dataset.repo_id=${HF_USER}/rollout_hil_data \
    --dataset.single_task="Fold the T-shirt"

Chế độ ghi liên tục (--strategy.record_autonomous=true): Cả khung hình tự chủ và khung hình hiệu chỉnh đều được ghi lại với việc xoay vòng tập dữ liệu dựa trên thời gian (giống như Sentry).

lerobot-rollout \
    --strategy.type=dagger \
    --strategy.record_autonomous=true \
    --strategy.num_episodes=50 \
    --policy.path=${HF_USER}/my_policy \
    --robot.type=so100_follower \
    --robot.port=/dev/ttyACM0 \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1 \
    --dataset.repo_id=${HF_USER}/rollout_dagger_data \
    --dataset.single_task="Grasp the block"

Điều khiển bằng bàn phím (thiết bị nhập mặc định):

Đầu vào bàn đạp chân cũng được hỗ trợ thông qua --strategy.input_device=pedal. Cấu hình mã bàn đạp bằng các cờ --strategy.pedal.*.

Khi robot hỗ trợ giữ vị trí rollout, một lệnh tạm dừng sẽ làm mới lại mục tiêu vị trí cuối cùng thực sự được áp dụng bởi driver, bao gồm cả việc cắt (clipping) và mục tiêu của kẹp (gripper). Trước lệnh đầu tiên, một tư thế đo đã được xác thực sẽ cung cấp mục tiêu. Điều này giữ nguyên sai số vị trí được lệnh thay vì thay đổi mục tiêu sang tư thế đo; robot có thể hoàn tất việc ổn định về phía mục tiêu đó trong khi việc tiến triển quỹ đạo chính sách (policy trajectory) bị dừng lại. Hãy xác thực hành vi của cánh tay đã tải và kẹp trên robot thực tế; chế độ giữ bằng phần mềm này không đảm bảo việc giữ chặt vật hoặc sự bất động vật lý.

Episodic ( --strategy.type=episodic )

Ghi hình theo từng episode, mô phỏng hành vi của lerobot-record. Policy điều khiển robot cho mỗi episode; một teleoperator tùy chọn có thể điều khiển robot trong giai đoạn reset giữa các episode.

lerobot-rollout \
    --strategy.type=episodic \
    --policy.path=${HF_USER}/my_policy \
    --robot.type=so100_follower \
    --robot.port=/dev/ttyACM0 \
    --teleop.type=so100_leader \
    --teleop.port=/dev/ttyACM1 \
    --dataset.repo_id=${HF_USER}/rollout_eval_data \
    --dataset.num_episodes=20 \
    --dataset.episode_time_s=30 \
    --dataset.reset_time_s=10 \
    --dataset.single_task="Pick up the red cube"

Teleop là tùy chọn — nếu bỏ qua, robot sẽ giữ nguyên vị trí trong giai đoạn đặt lại.

Điều khiển bằng bàn phím:

Mang chiến lược của riêng bạn

--strategy.type chấp nhận bất kỳ chiến lược nào được đăng ký trong môi trường, không chỉ các chiến lược tích hợp nêu trên. Một chiến lược là hai lớp trong một gói có thể cài đặt bằng pip: một cấu hình được đăng ký trên RolloutStrategyConfig, và một lớp kế thừa RolloutStrategy được đặt tên theo nó nhưng không có hậu tố Config — cùng quy ước SomethingConfig/Something như phần cứng tùy chỉnh, được phân giải từ module hoặc gói của cấu hình.

from dataclasses import dataclass
from typing import ClassVar

from lerobot.rollout import RolloutContext, RolloutStrategy, RolloutStrategyConfig


@RolloutStrategyConfig.register_subclass("patrol")
@dataclass
class PatrolStrategyConfig(RolloutStrategyConfig):
    dataset_mode: ClassVar[str] = "required"  # the engine creates the dataset for you
    legs: int = 2  # becomes --strategy.legs


class PatrolStrategy(RolloutStrategy):
    def run(self, ctx: RolloutContext) -> None:
        ...  # the paced control loop: see the contract on RolloutStrategy.run

    def teardown(self, ctx: RolloutContext) -> None:
        ctx.data.dataset.finalize()
        self._teardown_hardware(ctx.hardware, ctx.runtime.cfg.return_to_initial_position)

Cấu hình khai báo những gì mà engine sắp xếp thay cho chiến lược, do đó không có gì trong LeRobot cần biết kiểu của nó:

Đặt tên phân phối là lerobot_strategy_<name> và lerobot-rollout sẽ import gói trước khi phân tích CLI — chỉ có __init__.py được thực thi, vì vậy hãy import cấu hình tại đó. Một gói có bất kỳ tên nào khác sẽ được nạp, bao gồm cả các submodule, bằng --strategy.discover_packages_path=<package>. Các trường dataclass của chiến lược sẽ trở thành các cờ --strategy.*:

lerobot-rollout \
    --strategy.type=patrol \
    --strategy.legs=3 \
    --policy.path=${HF_USER}/my_policy \
    --robot.type=so100_follower \
    --robot.port=/dev/ttyACM0 \
    --dataset.repo_id=${HF_USER}/rollout_patrol \
    --dataset.single_task="patrol the aisle"

SentryStrategy (ghi lại, an toàn cho tương tác) và BaseStrategy (không ghi lại) là các cài đặt tham chiếu để sao chép; send_next_action, safe_push_to_hub và estimate_max_episode_seconds từ lerobot.rollout.strategies là các hàm trợ giúp mà chúng dựa vào.

Đối với các backend bất đồng bộ, hợp đồng dispatch là bắt buộc. Công bố mỗi quan sát đã bắt được bằng engine.notify_observation(obs_processed), gọi send_next_action(...) trên mỗi tick động cơ tự trị, bao gồm cả các tick nội suy và giữ, sau đó gọi engine.pump_query(obs_processed). Chỉ gọi engine.get_action() sẽ bỏ qua bắt tay về quyền và giữ: một truy vấn văn bản đã lập kế hoạch có thể chờ vô hạn, và một lỗi cuối cùng có thể không bao giờ báo hiệu việc tắt hệ thống.

Chiến lược bên thứ ba có thể gọi self._tick(timer, new_cycle=interpolator.needs_new_action()) thay cho timer.tick(...) để bao gồm báo cáo sức khỏe định kỳ sau _init_engine(ctx).

send_next_action được xây dựng dựa trên lerobot.inference.dispatch_tick và các thành phần của nó (next_interpolated_action, commit_action, dispatch_permitted), vốn mã hóa trình tự đó một lần duy nhất: dispatch_allowed() trước và sau khi lấy một action, và một lần nữa trước khi gửi, việc vô hiệu hóa nội suy cùng với một local hold được hỗ trợ và acknowledge_hold() khi bị từ chối, và record_dispatch() sau khi gửi. Một hold bị thất bại sẽ không bao giờ được xác nhận. Hãy sử dụng các helper đó thay vì tự triển khai lại trình tự; send_next_action chỉ bổ sung thêm dataset frame, action processor phía robot và việc tính toán nhịp độ. Các ngữ cảnh remote có ctx.policy.policy, preprocessor và postprocessor được đặt thành None; hãy sử dụng ctx.policy.inference và các pipeline phía robot trong ctx.processors.

Bọc các công việc ghi hình chặn (blocking) đã biết trong quá trình chạy bằng self._pause_for_recording(ctx), bao gồm cả việc xả (drain) ring-buffer và hoàn tất episode. Thao tác này sẽ vô hiệu hóa chuyển động bất đồng bộ trước khi ghi hình bị dừng và chỉ tiếp tục nếu run vẫn khỏe mạnh và đang hoạt động. Các chiến lược có các pha do operator kiểm soát phải truyền quyền cho phép chuyển động hiện tại của chúng dưới dạng resume_allowed. Hành động tiếp theo phải đến từ một quan sát mới; công việc đã lưu không được phép làm sống lại một run đang tạm dừng, đã dừng hoặc gặp lỗi.

Trực quan hóa dự đoán của chính sách

Với --display_data, trình xem cũng hiển thị những gì chính sách dự đoán ngoài các hành động: các khung hình camera do mô hình thế giới tưởng tượng ra, một nhiệm vụ con được dự đoán, các hộp bao quanh được vẽ trên camera. Mỗi chính sách tự quyết định những gì nó dự đoán và bật chúng thông qua cấu hình riêng của mình, ví dụ --policy.return_predicted_video=true cho LingBot-VA. Một dự đoán được đặt tên theo thứ mà nó dự đoán: Rerun hiển thị observation.images.top được dự đoán dưới dạng prediction.images.top, một nhiệm vụ con được dự đoán dưới dạng prediction.subtask, và các hộp bao quanh dưới camera của chúng (<camera>/prediction); Foxglove công bố chúng trên các chủ đề /prediction/... và chú thích hình ảnh <camera topic>/prediction. Với RTC, dự đoán được làm mới một lần mỗi chunk. Xem Mang chính sách của bạn để trả về một dự đoán từ một chính sách.

Các nền tảng suy luận

Chọn một backend bằng --inference.type=<name>. Suy luận đồng bộ cục bộ và suy luận RTC sử dụng chính sách được cấu hình bên dưới. backend từ xa nhận hợp đồng chính sách từ máy chủ và không tải trọng số lên máy tính của robot.

Đồng bộ (mặc định)

Một lần gọi chính sách cho mỗi nhịp điều khiển. Vòng lặp chính sẽ chặn cho đến khi hành động được tính toán.

Hoạt động với tất cả các chính sách. Không cần cờ bổ sung.

Phân đoạn thời gian thực ( --inference.type=rtc )

Một luồng nền tạo ra các khối hành động một cách bất đồng bộ. Vòng lặp điều khiển chính sẽ kiểm tra hành động tiếp theo đã sẵn sàng trong khi chính sách tính toán khối tiếp song song.

Sử dụng RTC với các mô hình VLA tương thích (Pi0, Pi0.5, SmolVLA) để chồng lấp suy luận và chuyển động. Việc thực thi liên tục vẫn cần đủ thời lượng phát hành động khả dụng để bao phủ độ trễ suy luận và sự biến động của nó.

lerobot-rollout \
    --strategy.type=base \
    --inference.type=rtc \
    --inference.rtc.execution_horizon=10 \
    --inference.rtc.max_guidance_weight=10.0 \
    --policy.path=${HF_USER}/pi0_policy \
    --robot.type=so100_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
    --task="Pick up the cube" \
    --duration=60 \
    --device=cuda

Xem hướng dẫn Real-Time Chunking để biết chi tiết về việc tinh chỉnh các tham số RTC.

Local RTC chạy trong một luồng nền của tiến trình rollout, không có transport. Một server và client trên cùng một máy tính sẽ sử dụng --inference.type=remote thay thế. Xem hướng dẫn remote để biết về việc căn chỉnh/trộn chunk và hành vi chờ được chia sẻ bởi các backend bất đồng bộ.

Chế độ chờ yêu cầu robot được hỗ trợ. RTC cục bộ thông thường vẫn khả dụng mà không cần khả năng này, nhưng các khoảng dừng do thay đổi văn bản/lệnh được lên kế hoạch và tình trạng thiếu dữ liệu có thể phục hồi thì cần đến nó. Các follower điều khiển vị trí SO, OMX, Koch, HopeJr và Rebot hỗ trợ tính năng này; OpenArm, Reachy2 và các wrapper hai tay có các ràng buộc cấu hình được liệt kê trong bảng hỗ trợ robot. Khi được hỗ trợ, bộ đệm trống có thể giữ lại mục tiêu cuối cùng đã áp dụng trong action_starvation_grace_s (mặc định là 1 giây), bao gồm cả thời gian cần thiết để xử lý hết suy luận cũ và dự đoán từ một lần chụp mới. Sau khi chuyển động đã bắt đầu, nếu grace bằng không hoặc robot không được hỗ trợ, hệ thống sẽ gặp lỗi ngay lập tức khi cạn kiệt; quá trình khởi động có hạn chót riêng của nó. Khác với đường dẫn RTC cục bộ trước đây, tình trạng cạn kiệt không còn là một tick bị bỏ qua vô thời hạn. Grace không bao giờ kéo dài các giới hạn yêu cầu hoặc độ tươi đã hết hạn.

Local RTC cung cấp các ngân sách bổ sung này thông qua --inference.:

Đây là các giá trị khởi đầu, không phải các đảm bảo phần cứng đã được đo lường. RTC phải giữ đủ phát lại sau khi tinh chỉnh cho một lần suy luận tiếp theo và biên độ thời gian. Việc tăng queue_threshold sẽ không có tác dụng nếu suy luận thường xuyên tiêu thụ toàn bộ chân trời dự đoán khả dụng; hãy giảm độ trễ hoặc xác thực một chân trời dài hơn/tần suất hành động khác.

Lỗi terminal không bao giờ tự động tiếp tục chuyển động của chính sách. Với việc thu thập quan sát khả dụng và điều khiển bộ chấp hành, quá trình tắt máy sẽ tuân theo --return_to_initial_position (mặc định là true) và ngắt kết nối. Việc quay về sẽ đọc một quan sát đầy đủ, do đó sự cố camera kéo dài có thể ngăn chặn điều này. Việc áp dụng lệnh thất bại sẽ ngăn chặn các chuyển động tắt máy tiếp theo cho tất cả các backend, bao gồm cả sync. Điều này không thay đổi dự đoán đồng bộ hay giới thiệu cơ chế phục hồi cụ thể cho camera.

Phiên tương tác

Thêm --interactive=true để điều khiển quá trình rollout từ terminal thay vì bắt đầu ngay lập tức. Phần cứng được kết nối và policy được nạp như bình thường, nhưng robot sẽ đứng yên cho đến khi bạn nhập /start — hữu ích khi bạn muốn bố trí cảnh trước, hướng dẫn lại policy giữa các lần thử, hoặc chạy nhiều lần mà không phải trả lại thời gian nạp.

lerobot-rollout \
    --strategy.type=base \
    --policy.path=${HF_USER}/my_smolvla_policy \
    --robot.type=so100_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
    --task="pick up the cube" \
    --interactive=true

> /start
Rollout running — task 'pick up the cube'. /subtask <text> to change it, ...
> /subtask put the cube in the box
Task: 'pick up the cube' → 'put the cube in the box' (applies from the next policy inference)
> /vqa is the cube inside the box?
Asked: 'is the cube inside the box?' — answering from the next observation...
Q: is the cube inside the box?
A: No — the cube is on the table to the left of the box.
> /reset
Task restored to 'pick up the cube'
Resetting — returning the robot to its initial position...
Robot reset — holding at initial position. /start to run.
> /stop

Các dòng bắt đầu bằng > là những gì bạn nhập; phiên không hiển thị bất kỳ prompt nào của riêng nó.

Ctrl-C vẫn tắt như bình thường, và việc đóng stdin (Ctrl-D, hoặc cuối của một script được pipe) sẽ kết thúc phiên — do đó, một script được pipe phải giữ stdin mở trong khoảng thời gian dự kiến:

(printf '/start\n'; sleep 60; printf '/stop\n') | lerobot-rollout ... --interactive=true

/subtask cập nhật tác vụ cho các bước suy luận tiếp theo. Với --inference.type=sync, các hành động chunk đã tính toán trước sẽ bị loại bỏ. Với RTC cục bộ hoặc suy luận từ xa, một thay đổi trong quá trình yêu cầu hành động sẽ hủy kết quả đã lỗi thời. Trên robot hỗ trợ giữ cục bộ (local hold), engine sẽ vô hiệu hóa chuyển động đang xếp hàng/được nội suy, chờ vòng lặp điều khiển xác nhận việc giữ, sau đó yêu cầu chuyển động mới dưới tác vụ mới. Hãy kỳ vọng robot sẽ dừng lại trong quá trình chuyển tiếp này; đây không phải là một pha trộn liên tục được đảm bảo. Một thay đổi giữa các yêu cầu có thể giữ lại các hành động đã được chấp nhận trước đó để đảm bảo tính liên tục. RTC cục bộ trên robot không hỗ trợ giữ vẫn sẽ hủy kết quả đã lỗi thời, nhưng có thể dùng hết các hành động còn lại và kết thúc. Hãy thay đổi hướng dẫn giữa các lần chạy nếu robot đó không thể giữ đúng cách.

Với --use_torch_compile=true cục bộ, một chỉ lệnh làm thay đổi hình dạng tensor đã xử lý có thể kích hoạt biên dịch lại. Padding có thể giữ một số thay đổi tác vụ ở cùng hình dạng, nhưng không đảm bảo rằng lần biên dịch sau sẽ phù hợp với phần phát lại còn lại hoặc hạn chót thay đổi chỉ lệnh: điều này có thể gây ra lỗi nghiêm trọng. Hãy tắt biên dịch khi khám phá các chỉ lệnh trừ khi các chuyển tiếp đó đã được xác thực. Các thay đổi trong quá trình làm nóng biên dịch ban đầu không yêu cầu giữ chuyển động, vì chuyển động của chính sách chưa bắt đầu.

/vqa và /autosteer yêu cầu một policy khai báo hỗ trợ sinh văn bản và triển khai PreTrainedPolicy.generate_text(), chẳng hạn như một checkpoint EO1 được huấn luyện phù hợp, hoặc một external planner. Khả năng này được kiểm tra trước khi chấp nhận một truy vấn; hành vi cụ thể của từng checkpoint vẫn cần được xác thực.

/vqa trả lời từ quan sát tiếp theo và in ra khi sẵn sàng, để bạn có thể tiếp tục nhập liệu trong lúc chờ; chỉ có một câu hỏi đang được xử lý tại một thời điểm (các truy vấn của chính autosteer chia sẻ cùng khe đó). Khi có bộ lập kế hoạch bên ngoài, câu hỏi được trả lời trên một luồng worker trong khi robot tiếp tục hành động, và các nội dung bên dưới không áp dụng. Các backend bất đồng bộ trước tiên đi vào trạng thái giữ cục bộ đã được xác nhận và vô hiệu hóa chuyển động đã xếp hàng/được nội suy, sau đó gửi một quan sát mới đến đường dẫn văn bản. Một phiên chạy hoạt động khỏe mạnh sẽ tiếp tục từ một khối hành động mới sau khi có câu trả lời; các phiên chạy tạm dừng hoặc đã dừng sẽ ở trạng thái không hoạt động. Việc tạo văn bản đồng bộ chạy trực tiếp trên luồng điều khiển và loại bỏ các hành động đã tính toán trước của chính sách, do đó tick tiếp theo sẽ tiếp tục từ suy luận mới. Thời gian truy vấn được tính vào --duration. Các câu hỏi chỉ được chấp nhận khi một phiên chạy đang diễn ra — một engine nhàn rỗi không có góc nhìn hiện tại. Nếu chỉ thị hoặc ngữ cảnh thực thi vô hiệu hóa một câu trả lời bất đồng bộ, câu hỏi sẽ nhận được một thông báo hủy thay vì câu trả lời đã lỗi thời. Kết thúc phân đoạn cũng báo cáo các câu hỏi chưa được trả lời, bao gồm cả việc tạo văn bản vẫn đang diễn ra; việc báo cáo hủy không làm gián đoạn một cuộc gọi mô hình đang chạy hoặc giải phóng sớm khe truy vấn của nó.

/autosteer giao cho policy một mục tiêu và yêu cầu nó đưa ra subtask tiếp theo mỗi --autosteer_interval_s giây (mặc định là 10), áp dụng từng subtask thông qua cùng một đường dẫn như /subtask và thông báo trong chat. Mỗi truy vấn là một lần sinh văn bản hoàn chỉnh, do đó khoảng cách này là một núm chỉnh chi phí: giá trị thấp hơn sẽ lập kế hoạch lại sớm hơn nhưng tiêu tốn nhiều hơn phần vòng lặp để sinh văn bản thay vì hành động. Tiến độ của kế hoạch nằm trong policy chứ không nằm trong rollout, nên kế hoạch sẽ kết thúc cùng với segment; sequencer cũng sẽ dừng lại khi gặp /reset, /subtask, /autosteer off, và lần thất bại lập kế hoạch đầu tiên.

Các log dưới mức ERROR sẽ bị tắt trong khi phiên đang chạy để tránh việc đầu ra thường xuyên xen lẫn với những gì bạn đang nhập; các lỗi và sự cố suy luận nghiêm trọng vẫn sẽ hiển thị, và việc ghi log bình thường sẽ được khôi phục khi phiên kết thúc. Các tóm tắt nhịp độ sẽ được in trong khung chat, và chạy mà không có --interactive sẽ cho bạn xem lại log trực tiếp.

Sessions hoạt động qua SSH và trên các máy không có giao diện đồ họa — không cần máy chủ hiển thị.

Ghi hình trong khi tương tác. --strategy.type=sentry cũng chấp nhận --interactive=true và ghi liên tục trong khi bạn điều khiển: mỗi đoạn /start…/reset lưu các episode hoàn chỉnh cùng một episode cuối không đầy đủ, và bộ dữ liệu vẫn mở cho đến khi tắt. Các khung hình mang nguồn gốc tác vụ của hành động thực sự được gửi, nên các hành động đã được xếp hàng hoặc nội suy dưới tác vụ cũ vẫn giữ nhãn cũ.

Việc lưu episode ở giữa lượt chạy sẽ tạm dừng suy luận bất đồng bộ, vô hiệu hóa các hành động đã xếp hàng/được nội suy và yêu cầu một lệnh giữ cục bộ được hỗ trợ. Chúng chỉ tiếp tục từ một lần bắt mới nếu lượt chạy vẫn đang hoạt động và ổn định. Cùng một cơ chế bảo vệ này áp dụng cho việc lưu DAgger và việc xả/lưu bộ đệm vòng Highlight. Việc tạm dừng ghi hình và tình trạng thiếu thông thường chia sẻ hành vi chờ vật lý, nhưng hạn chót và lý do để tiếp tục của chúng vẫn tách biệt.

lerobot-rollout \
    --strategy.type=sentry \
    --policy.path=${HF_USER}/my_smolvla_policy \
    --robot.type=so100_follower \
    --robot.port=/dev/ttyACM0 \
    --dataset.repo_id=${HF_USER}/rollout_cube_sessions \
    --task="pick up the cube" \
    --interactive=true

Các chiến lược ghi hình khác (episodic, DAgger, highlight) không được hỗ trợ: chúng tự ràng buộc các điều khiển bàn phím riêng và hoàn tất bộ dữ liệu khi run() thoát, do đó không thể khởi động lại theo từng phân đoạn.

Trình lập kế hoạch bên ngoài

--planner.model_id=<name> định tuyến /vqa và /autosteer qua client VLM của pipeline chú thích (extra annotations) thay vì đầu ra văn bản của policy. Các lệnh gọi được thực thi trên một worker thread trong khi robot tiếp tục hành động, và không yêu cầu giữ ngôn ngữ cho chúng, với một ngoại lệ có chủ đích: khi /autosteer bắt đầu, backend suy luận sẽ tạm dừng cho đến khi có phản hồi đầu tiên từ planner, vì mục tiêu là ngữ cảnh cho planner chứ không phải chỉ thị cho policy. Các backend bất đồng bộ (rtc, remote) sẽ hủy bỏ các hành động đã được xếp hàng hoặc đang được tính toán cho chỉ thị trước đó; backend đồng bộ sẽ giữ robot. Sau khi subtask đầu tiên được áp dụng, backend sẽ tiếp tục từ một quan sát mới. /subtask vẫn áp dụng chỉ thị của bạn trực tiếp và hủy bỏ lập kế hoạch tự động; các phản hồi muộn từ planner không thể ghi đè lên nó.

Planner hoạt động với mọi backend suy luận. Với suy luận cục bộ, nó tái sử dụng công thức con tác vụ của bộ xử lý đã nạp nếu có, và nếu không thì yêu cầu một chỉ dẫn ngắn; điều này không đảm bảo rằng checkpoint có thể tuân theo nó. --planner.instructions='["pick up the cup","open the drawer"]' giới hạn đầu ra của planner: VLM được yêu cầu chọn một trong các chuỗi này, và một phản hồi con tác vụ tiếp theo nằm ngoài danh sách sẽ là lỗi. Chữ hoa/thường, khoảng trắng thừa và dấu chấm cuối câu bị bỏ qua, và cách diễn đạt của chính danh sách được gửi đến policy. Nếu không có cờ này, danh sách được đọc từ nhãn tác vụ của tập dữ liệu huấn luyện của checkpoint (thông qua train_config.json). Mọi nhãn đều được đưa vào prompt, vì vậy hãy truyền cờ với một danh sách ngắn hơn cho các tập dữ liệu có nhiều tác vụ. Nếu không thể đọc tập dữ liệu, một cảnh báo sẽ được ghi log và đầu ra của planner vẫn ở dạng tự do. Suy luận từ xa sở hữu policy, nên cả công thức lẫn từ vựng huấn luyện đều không khả dụng cục bộ: hãy truyền --planner.instructions một cách tường minh, nếu không câu trả lời sẽ ở dạng tự do. Planner đã được thử nghiệm trên phần cứng chỉ với suy luận cục bộ.

Planner bên ngoài nhận --planner.history cặp quan sát/lệnh gần nhất (mặc định là 4), tiếp theo là các hình ảnh hiện tại. Mỗi cặp chứa quan sát được dùng để yêu cầu một chỉ thị và chỉ thị sau đó được engine chấp nhận; việc chấp nhận không đồng nghĩa với việc thực thi thành công. Các chỉ thị lặp lại vẫn được giữ trong lịch sử để VLM có thể đánh giá việc thiếu tiến triển. Lịch sử sẽ được xóa khi có sự tiếp quản thủ công, reset, dừng, kết thúc phân đoạn, hoặc một mục tiêu autosteer mới. Đặt --planner.history=0 để tắt tính năng này. /vqa có thể kiểm tra lịch sử này nhưng không thêm các mục mới. Đối với một yêu cầu subtask tiếp theo, VLM trước tiên phải mô tả cảnh và nêu rõ lệnh trước đó đã hoàn thành, đang thực hiện hay thất bại, và chỉ sau đó mới nêu tên chỉ thị tiếp theo. Một phản hồi done có nghĩa là mục tiêu đã hoàn tất: autosteer dừng lại, phiên chạy kết thúc, và robot giữ nguyên tư thế cho đến khi có /reset hoặc /start. Một done muộn từ trước một /subtask, /reset hoặc mục tiêu mới sẽ bị bỏ qua. Mỗi subtask được áp dụng sẽ được in ra kèm theo đánh giá cảnh của model và độ trễ của yêu cầu.

Bắt đầu một máy chủ VLM tương thích OpenAI riêng biệt, sau đó kết nối:

transformers serve Qwen/Qwen3-VL-8B-Instruct --port 8000
# Alternatively: vllm serve Qwen/Qwen3-VL-8B-Instruct --port 8000
lerobot-rollout ... --task="pick up the cup" --interactive=true \
    --planner.model_id=Qwen/Qwen3-VL-8B-Instruct \
    --planner.api_base=http://localhost:8000/v1
> /start
> /vqa What is the next short instruction to clear the table?
> /subtask put the cup in the sink
> /autosteer clear the table

Một model được host hoạt động theo cách tương tự. Ví dụ này sử dụng Hugging Face Inference Providers, với một token có quyền “Make calls to Inference Providers”:

export HF_TOKEN=hf_...
lerobot-rollout ... --task="put all colored cubes in the green bin" --interactive=true \
    --planner.model_id=Qwen/Qwen3.8-27B:novita \
    --planner.api_base=/static-proxy?url=https%3A%2F%2Frouter.huggingface.co%2Fv1 \
    --planner.api_key_env=HF_TOKEN

/vqa chỉ báo cáo một câu trả lời; /autosteer áp dụng các chỉ thị. Cấu hình endpoint bằng --planner.api_base, và cấu hình key bằng --planner.api_key_env=<variable> (được ưu tiên, key không xuất hiện trong các lệnh và log) hoặc --planner.api_key. --planner.request_timeout_s (mặc định 600) và --planner.request_max_retries (mặc định 2) giới hạn mỗi request; --planner.camera_key chọn một camera; --planner.log_path thêm mỗi lượt trao đổi dưới dạng một dòng JSON. Các phụ thuộc cho việc phục vụ model thuộc về môi trường server. --autosteer_interval_s đo thời gian chuyển động của robot sau khi một phản hồi được áp dụng, ngoài độ trễ của request. Điều hướng đa cấp và kiểm kê cảnh tự động nằm ngoài phạm vi của adapter này.

Kiểm soát bằng lập trình

RolloutController cung cấp các thao tác giống như API của thư viện — start() / reset() / stop() / set_task() an toàn cho luồng, cùng với callback RolloutEvent, không kèm theo stdin, in ra hoặc tắt log:

from threading import Event, Thread

from lerobot.rollout import (
    LinkedEvent,
    RolloutController,
    RolloutEvent,
    build_rollout_context,
    create_strategy,
)

parent = Event()  # your application's shutdown signal
ctx = build_rollout_context(cfg, LinkedEvent(parent))  # loads policy, connects robot
strategy = create_strategy(cfg.strategy)
strategy.setup(ctx)

controller = RolloutController(strategy, ctx, on_event=print)  # or your own observer
serve_thread = Thread(target=controller.serve)  # serve() blocks; run it where you like
serve_thread.start()

controller.start()                        # robot starts executing the policy
controller.set_task("grab the red cube")  # re-instruct mid-run
controller.reset()                        # stop movement, return home, stay warm
controller.stop()                         # end serve()

serve_thread.join()
strategy.teardown(ctx)  # teardown stays with the caller

RolloutController yêu cầu sự kiện đóng của ngữ cảnh phải là một LinkedEvent, được xây dựng như ở trên: bộ điều khiển kết thúc các đoạn chạy thông qua cờ cục bộ của nó, trong khi sự kiện parent của bạn vẫn buộc phải thực hiện đóng hoàn toàn. Đặt play_sounds=False trừ khi bạn muốn có các thông báo bằng giọng nói.

Các cờ phổ biến

Báo cáo Chu kỳ

Non-interactive rollout ghi log trạng thái của nó mỗi năm giây. Thay đổi khoảng thời gian bằng --status_interval_s=10, hoặc tắt nó bằng --status_interval_s=0.

Rollout: loop 29.7/30 Hz · over budget 2/149 · starved 0 · infer 18.7 ms (worst 40.1) · process 2.41 GiB · GPU 5.12/79.6 GiB

Latency là giá trị trung vị/xấu nhất trong khoảng thời gian (turnaround cho RTC/remote). Các trường không khả dụng sẽ bị bỏ qua; bộ nhớ GPU là của toàn thiết bị, còn bộ nhớ remote là cục bộ. Việc báo cáo sẽ tạm dừng khi vòng lặp bị chặn.

Mọi chiến lược đều báo cáo những gì vòng lặp điều khiển của nó thực sự đạt được, tương tự như lerobot-record, lerobot-teleoperate và lerobot-replay — tất cả đều chạy theo cùng một bộ đếm thời gian. Mỗi tập được lưu sẽ có một dòng tóm tắt, và khi vòng lặp kết thúc — kể cả khi nhấn Ctrl-C — một khối thông tin bao phủ toàn bộ phiên chạy sẽ được hiển thị:

Cadence (episode 1): 29.84 Hz policy vs 30 Hz target · 1200 ticks, 20.1 s measured · 6/598 cycles over the 33.3 ms budget (work mean 18.7 ms, worst 48.1 ms)
Cadence (episode 2): 29.84 Hz policy vs 30 Hz target · 1200 ticks, 20.1 s measured · 6/599 cycles over the 33.3 ms budget (work mean 18.7 ms, worst 48.1 ms)
Cadence summary — whole run, 2 episodes · target 30 Hz × 2 (16.7 ms tick slot, 33.3 ms cycle budget): 2400 ticks, 1197 cycles judged
  effective cadence: 29.84 Hz policy / 59.67 Hz commands over 40.2 s measured
  cycles over the 33.3 ms work budget: 12/1197 (1.0%) — work mean 18.7 ms, worst 48.1 ms
  ticks over their 16.7 ms slot: 40/2400 (costs interpolation smoothness only)
  loop-body steps (share of measured work):
    observe      mean   3.13 ms · worst   9.00 ms ·  31.7% of work · 2400 calls
    process_obs  mean   0.50 ms · worst   1.00 ms ·   5.1% of work · 2400 calls
    infer        mean   5.18 ms · worst  40.00 ms ·  52.4% of work · 2400 calls
    send         mean   0.40 ms · worst   0.40 ms ·   4.1% of work · 2400 calls
    record       mean   0.67 ms · worst 620.00 ms ·   6.8% of work · 2402 calls
  pacing headroom: 7.4 ms slept per tick on average (max 13.0 ms) — near zero means the loop is saturated

Đọc từ trên xuống: tần suất hiệu dụng là giá trị bạn đạt được so với --fps, số chu kỳ vượt ngân sách cho biết tần suất vòng lặp không thể duy trì mức đó, phân rã bước cho thấy thời gian đã đi đâu, và dự phòng nhịp độ gần bằng không nghĩa là không còn gì để hấp thụ một nhịp chậm. Tỉ trọng infer cao chỉ ra chính sách hoặc thiết bị; tỉ trọng observe cao chỉ ra các camera. Giá trị worst của một bước cao hơn nhiều so với mean của nó là một trường hợp đơn lẻ — ở trên, record là 0,67 ms mỗi khung hình và ngoại lệ 620 ms là save_episode chặn đã đóng một tập.

Một chu kỳ ở đây tương ứng với một hành động chính sách, gồm --interpolation_multiplier tick. Chỉ các chu kỳ nguyên vẹn vượt quá ngân sách 1/fps mới khiến bạn mất frame; một tick đơn lẻ vượt quá khe thời gian của nó chỉ làm cho chuyển động nội suy kém mượt mà hơn, đó là lý do hai loại này được tính riêng biệt. Nếu không có nội suy, một chu kỳ chỉ là một tick, nên báo cáo bỏ qua sự phân biệt này và tính tick xuyên suốt.

Trong phiên tương tác, mỗi phân đoạn /start có bộ đếm thời gian riêng, nên báo cáo sẽ được gửi vào chat một lần cho mỗi phân đoạn (/reset, /stop, hoặc --duration) thay vì một lần cho mỗi tiến trình.

Sử dụng theo chương trình

Đối với các phần mở rộng, lerobot.inference là gói công khai dành cho cấu hình backend, các engine cục bộ và các hợp đồng lập lịch dùng chung. lerobot.remote_inference chịu trách nhiệm cho engine từ xa, giao thức, triển khai và cài đặt phiên; lerobot.rollout chịu trách nhiệm cho vòng lặp robot, các chiến lược, nội suy và ghi hình. Hãy import các symbol công khai từ gói của chúng thay vì từ các tệp cài đặt. Các phụ thuộc từ xa tùy chọn chỉ cần thiết khi sử dụng backend hoặc server từ xa.

Đối với các triển khai tùy chỉnh (ví dụ: với bộ xử lý động học), hãy sử dụng trực tiếp API của module rollout:

from lerobot.rollout import BaseStrategyConfig, RolloutConfig, build_rollout_context
from lerobot.inference import SyncInferenceConfig
from lerobot.rollout.strategies import BaseStrategy
from lerobot.utils.process import ProcessSignalHandler

cfg = RolloutConfig(
    robot=my_robot_config,
    policy=my_policy_config,
    strategy=BaseStrategyConfig(),
    inference=SyncInferenceConfig(),
    fps=30,
    duration=60,
    task="my task",
)

signal_handler = ProcessSignalHandler(use_threads=True)
ctx = build_rollout_context(
    cfg,
    signal_handler.shutdown_event,
    robot_action_processor=my_custom_action_processor,       # optional
    robot_observation_processor=my_custom_obs_processor,     # optional
)

strategy = BaseStrategy(cfg.strategy)
try:
    strategy.setup(ctx)
    strategy.run(ctx)
finally:
    strategy.teardown(ctx)

Xem examples/so100_to_so100_EE/rollout.py và examples/phone_to_so100/rollout.py để có các ví dụ đầy đủ với bộ xử lý động học.