Hugging Face's logo

LeRobot documentation

速查表

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

速查表

所有 LeRobot 命令的汇总。如果您忘记了某个特定命令的用法，或者想了解一个新命令，都可以在这里找到相关信息。

请记住，对于下面列出的所有命令，都要将端口/名称/ID 更改为您自己的值！

查看所有命令并根据您的特定环境进行配置的另一个好方法是使用这个 Jupyter Notebook。

设置与安装

有关安装，请参阅 LeRobot 安装。

实用工具

查找端口

使用此命令来识别您的机器人连接到了哪个串口。请按照终端中的提示操作：系统会要求您拔掉 USB 线缆并按下 Enter 键。随后，脚本将检测并打印出该机器人对应的正确串口。

lerobot-find-port
查找摄像头

快速查找相机索引并验证其输出。此命令会将相机信息打印到终端，并将每个检测到的相机的测试帧保存到 outputs/captured_images

lerobot-find-cameras

校准

在大多数情况下，你只需为每个机器人和遥操作设备执行一次校准。在执行校准之前，请确保所有关节大致处于中间位置。

lerobot-calibrate \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm

请确保在后续的其他脚本中使用与校准时相同的 ID。LeRobot 正是通过这种方式找到校准文件的。

远程操作

使用两台相机进行远程操作，并使用 Rerun 显示数据。

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

记录数据集

数据集会自动上传到 Hugging Face Hub 的 repo_id 下。请确保您已通过 CLI 登录 HF 账户（您可以从 https://huggingface.co/settings/tokens 获取令牌），并将您的用户名存储在 HF_USER 中，以下命令将使用它：

lerobot-record \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_leader_arm \
    --dataset.repo_id=${HF_USER}/so101_dataset_test \
    --dataset.num_episodes=30 \
    --dataset.single_task="put the red brick in a bowl" \
    --dataset.streaming_encoding=true \
    --display_data=true

在收集数据集时，您可以通过键盘控制该过程：

  • 按 右箭头键（→） 或 n：保存当前回合并进入下一个。
  • 按 左箭头键（←） 或 r：删除当前回合并重试。
  • 按 Escape (ESC) 或 q：停止、编码视频并上传。

lerobot-record 会在 --dataset.repo_id 的末尾添加会话的日期和时间，因此 ${HF_USER}/so101_dataset_test 会被保存为 ${HF_USER}/so101_dataset_test_YYYYMMDD_HHMMSS。您可以在 Hugging Face 个人资料页面或通过 ls ~/.cache/huggingface/lerobot/${HF_USER} 找到完整名称，并在下方的训练命令中使用它。添加 --dataset.no_stamp=true 可保留原始名称。

记录深度

Intel RealSense 相机（type: intelrealsense）在设置 use_depth: true 时会记录深度流。深度数据被量化为 12 位编码，并作为独立的视频存储。

lerobot-record \
    ... \
    --robot.cameras="{ head: {type: intelrealsense, serial_number_or_name: \"0123456789\", width: 640, height: 480, fps: 30, use_depth: true} }" \
    --dataset.repo_id=${HF_USER}/so101_depth_test \
    --dataset.single_task="put the red brick in a bowl" \
    --dataset.depth_encoder.depth_min=0.01 \
    --dataset.depth_encoder.depth_max=10.0 \
    --dataset.depth_encoder.shift=0.0 \
    --dataset.depth_encoder.use_log=true

视频编码参数

RGB 和深度流通过 --dataset.rgb_encoder.* 和 --dataset.depth_encoder.* 键独立编码。

lerobot-record \
    ... \
    --dataset.rgb_encoder.vcodec=h264 \
    --dataset.rgb_encoder.pix_fmt=yuv420p \
    --dataset.rgb_encoder.crf=23 \
    --dataset.depth_encoder.vcodec=hevc \
    --dataset.depth_encoder.extra_options='{"x265-params": "lossless=1"}'

训练

根据您的硬件不同，训练策略可能需要几个小时。这就是训练简单的ACT策略的方法：

lerobot-train \
    --dataset.repo_id=${HF_USER}/so101_dataset_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}/policy_test \
    --steps=20000
  • 常见的策略类型：act、diffusion、multi_task_dit、smolvla、pi0、pi05、pi0_fast、groot、xvla。每种策略在侧边栏的 Policies 下都有各自的页面，Compute & Hardware Guide 则展示了哪些策略适合你的 GPU。
  • 设备：cuda（NVIDIA）、mps（Apple Silicon）、cpu

--policy.type 会创建该类型的新策略，并在您的数据集上从头开始训练（某些策略仍会从预训练的视觉或语言骨干网络开始，具体取决于其配置）。若要微调现有模型，请通过 --policy.path 传入本地检查点或 Hub 仓库 ID：策略类型和配置将从中读取，因此无需指定 --policy.type。

lerobot-train \
    --dataset.repo_id=${HF_USER}/so101_dataset_test_YYYYMMDD_HHMMSS \
    --policy.path=username/the_policy_to_finetune \
    --policy.device=cuda \
    --policy.repo_id=${HF_USER}/policy_finetuned_test \
    --output_dir=outputs/train/finetuned_so101_test \
    --steps=20000

没有本地 GPU？在任一命令中添加 --job.target=<flavor>（例如 a10g-small），lerobot-train 就会改为在 Hugging Face Jobs 上运行——它会为你上传仅限本地的数据集，并推送训练好的模型。使用 hf jobs hardware 列出可用的 flavor。若要跟踪任务的指标，请添加 --trackio.enable=true --trackio.space_id=<user>/<space>：Pod 的本地 Trackio 数据库在任务结束后不会保留。

若要恢复训练，请将 --config_path 指向某个检查点，并添加 --resume=true。它接受本地路径或 Hub 仓库 ID（将获取最新的检查点），并通过添加 --job.target=<flavor> 在本地或作业上运行：

lerobot-train --config_path=${HF_USER}/policy_test --resume=true --job.target=a10g-small

推理

推理是指在机器人上运行训练好的策略/模型。为此，我们使用 lerobot-rollout。您需要提供策略的路径，可以是本地路径，也可以是 Hugging Face 仓库 ID，例如上述训练命令中的 ${HF_USER}/policy_test。请使用与收集数据集时相同的端口、--robot.id、相机配置和任务描述。--duration 的单位是秒；如果未指定，策略将一直运行，直到您手动停止。

在 v0.5.x 及更早版本中，lerobot-rollout 尚不存在，您需要改用 lerobot-record。更多信息请参见此处。

lerobot-rollout \
    --strategy.type=base \
    --policy.path=${HF_USER}/policy_test \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
    --task="put the red brick in a bowl" \
    --duration=60
Update on GitHub

←安装 用于机器人的模仿学习→