Mô phỏng: cục bộ hoặc được phục vụ

Một môi trường mô phỏng có thể được điều khiển theo hai cách:

• dưới dạng môi trường batched (--env.*): nhiều môi trường cho một tác vụ, được thực hiện đồng thời bởi mỗi lần gọi step(). lerobot-eval và đánh giá trong quá trình huấn luyện sử dụng nó.
• dưới dạng sim robot (--robot.type=sim): một môi trường phía sau giao diện Robot, có thể thay thế bằng phần cứng thực. lerobot-rollout, lerobot-record, lerobot-teleoperate và lerobot-replay sử dụng nó.

Chạy trên máy cục bộ, thông qua API môi trường, hoặc được phục vụ bởi lerobot-env-server, thường trong một ảnh Docker riêng, để các phụ thuộc của trình mô phỏng không bao giờ gặp các phụ thuộc của chính sách. Việc đặt endpoint sẽ chọn chế độ thực thi được phục vụ; cả hai đường dẫn đều phơi bày cùng các quan sát chuẩn (ảnh HWC uint8, trạng thái float32 phẳng), kết thúc tập và các quy ước điều khiển.

Mã giữ ba lớp tách biệt:

• Một env (lerobot.envs, --env.type) là thứ mà một lệnh LeRobot thực thi, được cấu hình bởi một EnvConfig. Không phải env nào cũng là mô phỏng: gym_manipulator điều khiển một robot thực.
• Một sim (lerobot.sim) là trình mô phỏng phía sau một môi trường mô phỏng: một SimConfig chỉ định tích hợp của nó, được bước bởi LocalVectorEnv, không có torch.
• env server (lerobot.env_server) phục vụ một mô phỏng; RemoteVectorEnv điều khiển nó với cùng API như LocalVectorEnv.

Đánh giá một checkpoint

Trên máy cục bộ, với trình mô phỏng được cài đặt bên cạnh LeRobot (xem LIBERO):

lerobot-eval \
  --policy.path=lerobot/smolvla_libero \
  --policy.pretrained_revision=a24f1f380461b665158d52acd140152c79e8b36d \
  --policy.device=cuda \
  --env.type=libero --env.task=libero_spatial --env.task_ids='[0]' \
  --rename_map='{"observation.images.image": "observation.images.camera1", "observation.images.image2": "observation.images.camera2"}' \
  --eval.n_episodes=1 --eval.batch_size=1 \
  --output_dir=outputs/eval_libero

Đã phục vụ: khởi động máy chủ với cùng môi trường (xem Phục vụ một môi trường), và thêm điểm cuối của nó:

lerobot-env-server --config_path=docker/sim/configs/libero.yaml --docker=true
lerobot-eval ... --env.server.endpoint=tcp/127.0.0.1:7448

Mọi tùy chọn cho server đều nằm dưới --env.server.*, và không có tùy chọn nào áp dụng cho việc chạy cục bộ. Client yêu cầu triển khai có tên theo --env.type, như cách cấu hình server đặt tên; truyền --env.server.deployment nếu muốn dùng triển khai khác. Endpoint hoặc triển khai sai sẽ thất bại trong vòng --env.server.handshake_timeout_s (10 giây) và nêu rõ endpoint đang phục vụ gì. Đối với server được bảo mật bằng TLS, truyền file Zenoh JSON5 của nó bằng --env.server.zenoh_config_path, tương tự như với suy luận từ xa. Server phải chạy môi trường mà lệnh mô tả: cùng loại, tác vụ, quy ước điều khiển và cơ thể mô phỏng (robot_type), nếu không đánh giá sẽ từ chối khởi động và liệt kê các khác biệt. Các tùy chọn khác có sự khác biệt (độ phân giải, độ dài episode) sẽ được ghi log dưới dạng cảnh báo.

Tên quan sát được lấy từ môi trường (observation.images.<camera>, observation.state). Khi một checkpoint được huấn luyện với các tên camera khác, hãy ánh xạ chúng bằng --rename_map, như với bất kỳ robot nào, và giữ nguyên danh tính của từng camera ngay cả khi nhiều camera có cùng hình dạng. Các camera giả lập (empty_cameras) là một cài đặt của policy được lưu cùng checkpoint; chỉ ghi đè bằng --policy.empty_cameras khi cần thiết.

Trước bước đầu tiên, mọi checkpoint đầu vào phải tồn tại trong môi trường sau khi đổi tên, với số chiều của trạng thái và hành động cùng số kênh RGB khớp nhau. Chiều cao và chiều rộng của ảnh có thể khác nhau: tiền xử lý chính sách chịu trách nhiệm thay đổi kích thước. Các quy ước của bộ điều khiển (hành động delta so với hành động tuyệt đối, định dạng xoay) không được kiểm tra; hãy sử dụng checkpoint được huấn luyện theo quy ước của môi trường.

Mỗi lần gọi step() sẽ tiến triển mỗi môi trường chưa hoàn thành trong lô một bước. Một môi trường đã kết thúc sẽ giữ nguyên quan sát cuối cùng cho đến lần reset tiếp theo; việc tiến triển các môi trường khác sẽ không bao giờ khởi động lại nó. Với --eval.use_async_envs=true (mặc định), mỗi môi trường chạy trong một tiến trình worker riêng, cục bộ hoặc trên máy chủ, và lô được tiến triển song song. Máy chủ chấp nhận tối đa max_envs môi trường mỗi lô (mặc định là 32). --env.server.encoding=jpeg (hoặc --robot.env.server.encoding=jpeg, kèm --env.server.jpeg_quality, mặc định là 90) gửi các khung hình camera được phục vụ dưới dạng JPEG: phản hồi nhỏ hơn cho máy chủ từ xa và lô lớn hơn, với cái giá là thời gian mã hóa và khung hình có tổn hao. Trên localhost, khung hình thô sẽ nhanh hơn. Một phản hồi mang theo khung hình của mọi môi trường trong lô và phải nằm trong giới hạn max_payload_bytes (mặc định là 32 MiB) ở cả hai đầu, nếu không máy chủ sẽ từ chối lô khi mở. Đối với các lô lớn hoặc camera độ phân giải cao, hãy tăng giá trị này trên máy chủ (max_payload_bytes trong phần zenoh của tệp YAML, cạnh listen_endpoints) và trên client (--env.server.max_payload_bytes, hoặc --robot.env.server.max_payload_bytes).

Chạy robot mô phỏng

Cùng một môi trường như một môi trường dạng lô (batched env) và như một robot mô phỏng:

lerobot-eval    --env.type=libero --env.task=libero_spatial --env.task_ids='[0]' ...
lerobot-rollout --robot.type=sim --robot.env.type=libero --robot.env.task=libero_spatial --robot.task_id=0 ...

Ví dụ:

lerobot-rollout \
  --robot.type=sim --robot.env.type=libero --robot.env.task=libero_spatial --robot.task_id=0 \
  --task="pick up the black bowl between the plate and the ramekin and place it on the plate" \
  --policy.path=lerobot/smolvla_libero \
  --policy.pretrained_revision=a24f1f380461b665158d52acd140152c79e8b36d \
  --rename_map='{"observation.images.image": "observation.images.camera1", "observation.images.image2": "observation.images.camera2"}' \
  --device=cuda --fps=20 --inference.type=sync \
  --display_data=true --display_mode=rerun \
  --return_to_initial_position=false --play_sounds=false

• --robot.env.* nhận các tùy chọn giống như --env.* trong đánh giá. --robot.task_id chọn một tác vụ duy nhất để robot thực thi, trong khi đánh giá chạy mọi tác vụ của bộ bài tập hoặc những tác vụ trong --env.task_ids. Môi trường EnvHub là --robot.env.type=envhub --robot.env.hub_path=<user/repo> --robot.env.trust_remote_code=true.
• Một số policy cần bộ xử lý của môi trường (XVLA và Cosmos3 trên LIBERO, Isaac Lab Arena). lerobot-eval sẽ áp dụng chúng, và robot mô phỏng với --inference.type=sync cũng vậy. Suy luận từ xa thì không, do đó nó sẽ từ chối checkpoint như vậy khi khởi động.
• --robot.env.server.endpoint=tcp/... điều khiển môi trường trên một máy chủ env thay vì chạy cục bộ, tương tự cách --env.server.endpoint thực hiện cho một môi trường dạng batch. Robot sẽ kiểm tra xem máy chủ có đang chạy môi trường đó hay không.
• Mỗi send_action() tiến hành môi trường chính xác một lần. Việc đọc quan sát, suy luận chính sách và chờ đợi không làm tiến mô phỏng; vòng lặp điều khiển hiện có chịu trách nhiệm điều phối nhịp độ theo thời gian thực.
• --fps phải bằng tần suất điều khiển của môi trường, chia cho --interpolation_multiplier khi nội suy, vì mỗi lệnh sẽ tiến môi trường một bước. Khi ghi hình, --dataset.fps phải bằng --fps. Rollout sẽ từ chối khởi động nếu không thỏa mãn điều này.

Một robot mô phỏng là một robot: thay --robot.type=sim --robot.env.* bằng --robot.* của robot theo dõi thực, và mọi thứ khác giữ nguyên. Người vận hành từ xa điều khiển nó giống như cách nó điều khiển robot theo dõi thực (--teleop.type=so101_leader cho một cặp SO-101), khi môi trường khai báo tên và đơn vị của hành động robot theo dõi; sự không khớp sẽ được báo cáo ở hành động đầu tiên. lerobot-record lưu trữ thân robot mà môi trường khai báo làm robot_type của bộ dữ liệu (panda cho LIBERO), hoặc sim_robot khi nó không khai báo gì.

Các tập được ghi lại tuân theo môi trường. lerobot-record và chiến lược rollout theo tập khởi động lại môi trường mô phỏng ở đầu mỗi tập, và kết thúc nó khi tập của môi trường kết thúc (thành công, chấm dứt hoặc đạt giới hạn bước) hoặc khi thời lượng hết, tùy điều kiện nào đến trước. Do đó, mỗi tập được ghi lại là một tập mô phỏng, bắt đầu từ trạng thái ban đầu của nó. Không cần đặt lại thủ công, vì vậy hãy bỏ qua giai đoạn đặt lại giữa các tập bằng --dataset.reset_time_s=0, và với chiến lược rollout theo tập, hãy truyền thêm --strategy.reset_to_initial_position=false. Khi một tập kết thúc, robot dừng lại: nó bỏ qua các hành động và giữ nguyên trạng thái cuối, và latest giữ lại phần thưởng, sự chấm dứt và sự thành công cuối cùng. Thao tác từ xa và chiến lược rollout cơ bản sau đó bắt đầu một tập mới (chiến lược cũng đặt lại chính sách), và replay dừng lại. Các chiến lược sentry, highlight và DAgger hiện chưa hỗ trợ robot mô phỏng, vì chúng ghi lại theo thời gian hoặc theo yêu cầu thay vì theo tập; hãy dùng chiến lược theo tập để ghi lại. Robot thực không bị ảnh hưởng: các tập của chúng được tính theo thời gian, và cảnh của chúng được đặt lại thủ công. Để đánh giá tỷ lệ thành công, hãy dùng lerobot-eval và một môi trường dạng batch.

Các tính năng camera của robot sử dụng cùng tên observation.images.<camera> như khi ghi hình trên phần cứng thực. Một camera không có tên sẽ là observation.images.image. Đánh giá theo lô giữ nguyên các khóa của môi trường, chẳng hạn như observation.image cho một camera; khi triển khai checkpoint có tên đó thông qua SimRobot, hãy sử dụng --rename_map='{"observation.images.image": "observation.image"}'.

Đối với suy luận từ xa, giữ nguyên các tùy chọn --robot.* và thay thế các tùy chọn chính sách và suy luận cục bộ bằng:

--inference.type=remote \
--inference.endpoint=tcp/127.0.0.1:7447 \
--inference.deployment=libero \
--inference.semantics=libero-delta-v1

Khởi động máy chủ policy riêng biệt bằng cách sử dụng cấu hình suy luận từ xa. Schema của nó phải khớp với các quan sát của robot sau --rename_map. Bỏ qua --policy.path khỏi lệnh rollout vì máy chủ policy sẽ tải checkpoint. Đối với RTC cục bộ, hãy sử dụng --inference.type=rtc cùng với các cài đặt RTC của policy.

Khi policy bị trễ, việc giữ một robot mô phỏng sẽ không làm tiến triển vật lý. Các lỗi của trình mô phỏng sẽ lan truyền đến việc tắt rollout.

Cung cấp một môi trường

Từ bản checkout mã nguồn LeRobot (ảnh được xây dựng từ đó), chạy từ thư mục gốc của kho:

lerobot-env-server --config_path=docker/sim/configs/libero.yaml --docker=true

--docker=true sử dụng docker/sim/compose.server.yaml, chọn image từ sim.type, gắn (mount) YAML hiệu lực và chạy container trên mạng host, do đó server sẽ lắng nghe trên localhost:7448 trừ khi --zenoh.listen_endpoints chỉ định khác. Thay đổi YAML để chọn một simulator khác. Tốc độ điều khiển, quy ước hành động, tên các thành phần và loại robot của mỗi simulator được lấy từ conventions() của tích hợp tương ứng, vì vậy YAML chỉ cần nêu tên tác vụ và các tùy chọn của simulator.

Đối với lerobot-policy-server, mọi trường YAML đều chấp nhận ghi đè bằng lệnh dòng lệnh ở cấp con, và tệp không bị thay đổi. Một giá trị từ điển như sim.kwargs sẽ được gộp vào của YAML:

lerobot-env-server --config_path=docker/sim/configs/libero.yaml --docker=true \
  --sim.task=libero_goal \
  --sim.kwargs='{gym_kwargs: {observation_height: 256, observation_width: 256}}'

Cấu hình hiệu lực được lưu tại $HF_LEROBOT_HOME/sim, nên container khởi động lại sẽ tìm thấy nó. Việc chuyển đổi cấu hình sẽ tạo lại server và kết thúc các phiên đang hoạt động. Ảnh sẽ được xây dựng khi thiếu; thêm --build=true để xây dựng lại sau khi thay đổi trình mô phỏng hoặc mã nguồn LeRobot, hoặc --stop=true để tắt server. Container yêu cầu quyền truy cập GPU của Docker cho việc render EGL. Các kho EnvHub được phục vụ với --envhub=<user/repo>; xem EnvHub và server trình mô phỏng.

Nếu trình mô phỏng render bằng Vulkan (Isaac Sim, hoặc ManiSkill/SAPIEN như trong RoboMME, mà image của nó có kèm sẵn file Vulkan) bị lỗi trong container với vkCreateInstance failed hoặc ERROR_INCOMPATIBLE_DRIVER trong khi chạy bình thường ngoài Docker, thì container có thư viện của driver NVIDIA nhưng thiếu các file loader trỏ đến chúng (/usr/share/vulkan/icd.d/nvidia_icd.json, /usr/share/glvnd/egl_vendor.d/10_nvidia.json). Chế độ mặc định của NVIDIA Container Toolkit, được dùng bởi gpus: all, có thể không mount các file này; chế độ CDI thì có. Hãy yêu cầu GPU thông qua CDI (--device nvidia.com/gpu=all cho docker run, devices: [nvidia.com/gpu=all] thay cho gpus: all trong docker/sim/compose.server.yaml), hoặc thêm hai file đó vào image.

Nếu không có --docker=true, cùng một lệnh sẽ chạy server trong môi trường hiện tại: cài đặt các phụ thuộc native của trình mô phỏng trong một môi trường cô lập, cài đặt LeRobot với --no-deps, và cài đặt docker/sim/requirements.txt. Trong mọi trường hợp, nó sẽ lắng nghe trên localhost; để chấp nhận các máy khác, hãy truyền địa chỉ của giao diện mạng mà chúng có thể truy cập, như trong --zenoh.listen_endpoints='[tcp/192.168.1.20:7448]', và thêm TLS cùng kiểm soát truy cập bằng một zenoh.config_file trong YAML.

Ảnh runtime của LIBERO sử dụng các tệp trạng thái ban đầu NumPy đã được chuyển đổi. Quy trình xây dựng ảnh sẽ chuyển đổi các tài sản upstream đáng tin cậy bằng scripts/ci/convert_libero_init_states.py; máy chủ sẽ từ chối nếu thiếu các tệp đã chuyển đổi. RoboTwin và RoboMME lần lượt yêu cầu torch riêng của chúng cho lập kế hoạch native và ManiSkill; việc cài đặt torch của chúng được cách ly khỏi môi trường policy.

Các yêu cầu từ máy chủ không bao giờ được thử lại. Sau một thời gian chờ không rõ ràng, client sẽ thất bại; hãy đóng nó và mở một phiên mới.

Thêm một bài kiểm tra hiệu năng

Xem Thêm một benchmark để biết về các module mô phỏng, quy ước, hình ảnh và tích hợp CI.