具身开发者社区

外观

教程huggingface.co6 天前

LeRobot 用自采数据训练 ACT 并真机回放验证（文档示例） ​

本文按 LeRobot 官方流程整理：先完成机器人与遥操作设备校准，再登录 Hugging Face、录制并上传数据集，随后回放 episode 检查动作可重复性，最后用自采数据训练 ACT policy，并说明断点续训与跑通确认方式。

AI 整理
  • 数据与采集
  • 具身模型

> 本文依据以下官方文档整理：huggingface.co/docs/lerobot/il_robots。命令与版本以文档当前版本为准。

前置条件 ​

  • 已按机器人专属教程完成 robot 和 teleop device 的 set up and calibrated
  • 一台 LeRobot 支持的平台机器人，以及 teloperation device，例如 leader arm or keyboard
  • 如需图像输入，已为 setup 添加 cameras
  • Hugging Face write-access token，并可通过 CLI 登录
  • 训练时可使用 Nvidia GPU，并设置 --policy.device=cuda；也可用 Apple silicon，并设置 policy.device=mps
  • 如启用 --wandb.enable=true，需要先运行 wandb login

1. 1. 遥操作机器人并确认设备 id ​

先用同一套 robot 和 teleop device 做 teleoperation。文档强调：robot 的 id 会用于存储 calibration file；同一 setup 在 teleoperating、recording、evaluating 时要使用相同 id。

bash
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

2. 2. 带相机可视化遥操作 ​

如果 setup 中包含 cameras，可以在 teleoperate 时同时 visualizing the camera feeds and joint positions。下面示例使用 --display_data=true，并在 --robot.cameras 中配置 opencv camera。

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

3. 3. 登录 Hugging Face 并记录用户名 ​

录制数据集会用到 Hugging Face hub features。先用 write-access token 登录 CLI，然后把 Hugging Face repository name 存入变量，后续 repo_id 会用到 ${HF_USER}。

bash
hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential
bash
HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')
echo $HF_USER

4. 4. 录制自采数据集并上传 ​

熟悉 teleoperation 后开始录制 dataset。下面命令录制 5 episodes，并将 dataset 上传到 hub。数据会以 LeRobotDataset format 存储；默认录制结束后 push 到 Hugging Face page。

bash
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}}" \
    --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.rgb_encoder.vcodec=auto \
    --dataset.encoder_threads=2

5. 5. 查看、上传或回放数据集 ​

本地 dataset 存在 ~/.cache/huggingface/lerobot/{repo-id}。录制后可查看数据集页面，也可手动上传本地 dataset。为了检查动作可重复性，可 replay 已录制的 episode。

bash
echo https://huggingface.co/datasets/${HF_USER}/so101_test
bash
hf upload ${HF_USER}/record-test ~/.cache/huggingface/lerobot/{repo-id} --repo-type dataset
bash
lerobot-replay \
    --robot.type=so101_follower \
    --robot.port=/dev/tty.usbmodem58760431541 \
    --robot.id=my_awesome_follower_arm \
    --dataset.repo_id=${HF_USER}/record-test \
    --dataset.episode=0 # choose the episode you want to replay

6. 6. 用自采数据训练 ACT policy ​

使用 lerobot-train 训练 policy。文档示例中 --policy.type=act 会加载 configuration_act.py，并会自动适配 dataset 中保存的 motor states、motor actions 和 cameras。

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

7. 7. 从 checkpoint 继续训练 ​

Training should take several hours，checkpoints 会出现在 outputs/train/act_so101_test/checkpoints。可从本地 last checkpoint 恢复，也可在已 push checkpoint 到 Hub 时从 repo 恢复。

bash
lerobot-train \
  --config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
  --resume=true
bash
lerobot-train --config_path=${HF_USER}/my_policy --resume=true

验证是否跑通 ​

确认流程跑通可看这些结果：teleoperate 命令会连接 robot 和 teleop device 并开始 teleoperation；record 结束后 dataset 会上传到 Hugging Face page，本地也会出现在 ~/.cache/huggingface/lerobot/{repo-id}；replay 时 robot should replicate movements similar to those you recorded；train 后可在 outputs/train/act_so101_test/checkpoints 找到 checkpoints。

文档里点名的注意事项 ​

  • robot 的 id 用于存储 calibration file；同一 setup 在 teleoperating、recording、evaluating 时要使用相同 id。
  • 如果不想录制后上传 dataset，可使用 --dataset.push_to_hub=False。
  • 恢复录制时重新运行同一命令并加 --resume=true；--dataset.num_episodes 必须是 additional episodes，不是目标总 episode 数；还要设置 --dataset.root="local_path"。
  • 录制控制快捷键：Right Arrow 或 n 进入下一个；Left Arrow 或 r 取消并重录；Escape 或 q 停止 session、encode videos 并上传 dataset。
  • 录制控制流快捷键在 X11、Wayland、headless/SSH sessions 可用；如果 keys have no effect，确保在 interactive terminal 且终端聚焦。Keyboard teleoperation 仍需要 global key backend，不支持 Wayland 或 headless machines。
  • 数据采集建议先从 grasping an object at different locations and placing it in a bin 开始；至少 50 episodes，每个 location 10 episodes；保持 cameras fixed，并让被操作物体在 camera 中可见。

相关 SDK 条目 ​

来源

本页事实对应的公开页面，以原文为准。

  1. huggingface.co/docs/lerobot/il_robots访问 2026-10-22