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

> 原文链接：https://robotics.hellobike.com/tutorials/lerobot-train-act-diffusion-policy
> 频道：tutorials | 更新日期：2026-10-22 | 标签：LeRobot, Imitation Learning, ACT, Hugging Face Hub, Robot Dataset, Replay
> 核心摘要：本文按 LeRobot 官方流程整理：先完成机器人与遥操作设备校准，再登录 Hugging Face、录制并上传数据集，随后回放 episode 检查动作可重复性，最后用自采数据训练 ACT policy，并说明断点续训与跑通确认方式。

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

> 本文依据以下官方文档整理：[huggingface.co/docs/lerobot/il_robots](https://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 条目

- [LeRobot](/sdks/lerobot)

## 原始参考来源 (Sources)

- [huggingface.co/docs/lerobot/il_robots](https://huggingface.co/docs/lerobot/il_robots)