Hugging Face 的 LOGO

LeRobot 文档

真实世界机器人入门

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

真实世界机器人入门

本教程将解释如何训练神经网络以自主控制真实机器人。

你将学到：

  1. 如何记录和可视化您的数据集。
  2. 如何使用您的数据训练策略并准备进行评估。
  3. 如何评估您的策略并可视化结果。

通过遵循这些步骤，您将能够以高成功率复制任务，例如拿起乐高积木并将其放入箱中，如下面的视频所示。

视频：拿起乐高积木任务

本教程不限于特定的机器人：我们将引导您完成可适用于任何受支持平台的命令和 API 片段。

在数据收集过程中，您将使用“远程操作”设备，例如主臂或键盘来远程操作机器人并记录其运动轨迹。

一旦您收集到足够的轨迹，您将训练一个神经网络来模仿这些轨迹，并部署训练好的模型，以便您的机器人能够自主执行任务。

如果您在任何时候遇到任何问题，请加入我们的Discord 社区寻求支持。

设置和校准

如果您尚未设置和校准您的机器人和远程操作设备，请按照机器人特定教程进行操作。

远程操作

在此示例中，我们将演示如何远程操作 SO101 机器人。对于每个命令，我们还提供了相应的 API 示例。

请注意，与机器人关联的 id 用于存储校准文件。在使用相同设置时，在远程操作、记录和评估时使用相同的 id 非常重要。

命令
API 示例
python -m 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

远程操作命令将自动

  1. 识别任何缺失的校准并启动校准程序。
  2. 连接机器人和远程操作设备并开始远程操作。

相机

要将相机添加到您的设置中，请遵循此指南。

通过相机进行远程操作

使用 rerun，您可以再次远程操作，同时可视化相机馈送和关节位置。在此示例中，我们使用 Koch 机械臂。

命令
API 示例
python -m lerobot.teleoperate \
    --robot.type=koch_follower \
    --robot.port=/dev/tty.usbmodem58760431541 \
    --robot.id=my_awesome_follower_arm \
    --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}}" \
    --teleop.type=koch_leader \
    --teleop.port=/dev/tty.usbmodem58760431551 \
    --teleop.id=my_awesome_leader_arm \
    --display_data=true

记录数据集

一旦您熟悉了远程操作，您就可以记录您的第一个数据集。

我们使用 Hugging Face Hub 功能来上传您的数据集。如果您以前没有使用过 Hub，请确保您可以通过 CLI 使用写访问令牌登录，该令牌可以从Hugging Face 设置生成。

通过运行此命令将您的令牌添加到 CLI

huggingface-cli login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential

然后将您的 Hugging Face 存储库名称存储在一个变量中

HF_USER=$(huggingface-cli whoami | head -n 1)
echo $HF_USER

现在您可以记录一个数据集了。要记录 2 个 эпизо드 并将您的数据集上传到 Hub，请执行此针对 SO101 定制的命令。

python -m 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=2 \
    --dataset.single_task="Grab the black cube"

数据集上传

在本地，您的数据集存储在此文件夹中：~/.cache/huggingface/lerobot/{repo-id}。数据记录结束后，您的数据集将上传到您的 Hugging Face 页面（例如https://huggingface.co/datasets/cadene/so101_test），您可以通过运行以下命令获取该页面

echo https://huggingface.co/datasets/${HF_USER}/so101_test

您的数据集将自动标记为 LeRobot，以便社区轻松找到它，您还可以添加自定义标签（例如，在此示例中为 tutorial）。

您可以通过搜索 LeRobot 标签在 Hub 上查找其他 LeRobot 数据集。

记录函数

record 函数提供了一套用于在机器人操作期间捕获和管理数据的工具

1. 数据存储
  • 数据使用 LeRobotDataset 格式存储，并在记录期间存储在磁盘上。
  • 默认情况下，数据集在记录后推送到您的 Hugging Face 页面。
    • 要禁用上传，请使用 --dataset.push_to_hub=False。
2. 检查点和恢复
  • 检查点在录制期间自动创建。
  • 如果发生问题，您可以通过重新运行带有 --control.resume=true 的相同命令来恢复。
  • 要从头开始录制，请手动删除数据集目录。
3. 录制参数

使用命令行参数设置数据录制流程

  • --dataset.episode_time_s=60 每个数据录制 эпизод 的持续时间（默认：60 秒）。
  • --dataset.reset_time_s=60 每个 эпизод 后重置环境的持续时间（默认：60 秒）。
  • --dataset.num_episodes=50 要录制的 эпизод 总数（默认：50）。
4. 录制期间的键盘控制

使用键盘快捷键控制数据录制流程

  • 按右箭头 (→)：提前停止当前 эпизод 或重置时间并进入下一个。
  • 按左箭头 (←)：取消当前 эпизод 并重新录制。
  • 按Escape (ESC)：立即停止会话，编码视频，并上传数据集。

数据收集技巧

一旦您熟悉了数据录制，您就可以创建更大的数据集进行训练。一个很好的入门任务是在不同位置抓取物体并将其放入箱子。我们建议至少录制 50 个 episode，每个位置 10 个 episode。在整个录制过程中保持相机固定并保持一致的抓取行为。还要确保您正在操作的物体在相机中可见。一个好的经验法则是，您应该只通过查看相机图像就能自己完成任务。

在以下部分中，您将训练您的神经网络。在实现可靠的抓取性能后，您可以在数据收集期间开始引入更多变化，例如额外的抓取位置、不同的抓取技术和改变相机位置。

避免过快地添加太多变化，因为它可能会阻碍您的结果。

如果您想深入了解这个重要主题，您可以查看我们撰写的关于什么是一个好的数据集的博客文章。

故障排除：

  • 在 Linux 上，如果左右箭头键和 Esc 键在数据记录期间没有任何效果，请确保您已设置 $DISPLAY 环境变量。请参阅 pynput 限制。

可视化数据集

如果您使用 --control.push_to_hub=true 将数据集上传到 Hub，您可以通过复制粘贴您的 repo ID（通过以下命令获得）在线可视化您的数据集。

echo ${HF_USER}/so101_test

回放 эпизод

一个有用的功能是 replay 函数，它允许您回放您录制的任何 эпизод 或任何数据集中的 эпизод。此功能可帮助您测试机器人动作的可重复性并评估相同型号机器人之间的可转移性。

您可以通过以下命令在机器人上回放第一个 эпизод

python -m 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

您的机器人应该复制与您记录的动作相似的动作。例如，请查看此视频，其中我们使用 replay 在来自Trossen Robotics 的 Aloha 机器人上。

训练策略

要训练控制您的机器人的策略，请使用 python lerobot/scripts/train.py 脚本。需要一些参数。这是一个示例命令

python lerobot/scripts/train.py \
  --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

让我们来解释一下这个命令：

  1. 我们将数据集作为参数提供，使用 --dataset.repo_id=${HF_USER}/so101_test。
  2. 我们提供的策略是 policy.type=act。这会从 configuration_act.py 加载配置。重要的是，此策略将自动适应机器人电机状态、电机动作和相机的数量（例如 laptop 和 phone），这些已保存在您的数据集中。
  3. 我们提供了 policy.device=cuda，因为我们是在 Nvidia GPU 上训练，但你也可以使用 policy.device=mps 在 Apple 芯片上进行训练。
  4. 我们提供了 wandb.enable=true 来使用 Weights and Biases 可视化训练图。这是可选的，但如果您使用它，请确保通过运行 wandb login 登录。

训练应该需要几个小时。您将在 outputs/train/act_so101_test/checkpoints 中找到检查点。

要从检查点恢复训练，下面是一个从 act_so101_test 策略的 last 检查点恢复的示例命令

python lerobot/scripts/train.py \
  --config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
  --resume=true

上传策略检查点

训练完成后，使用以下命令上传最新的检查点：

huggingface-cli upload ${HF_USER}/act_so101_test \
  outputs/train/act_so101_test/checkpoints/last/pretrained_model

你也可以使用以下命令上传中间检查点：

CKPT=010000
huggingface-cli upload ${HF_USER}/act_so101_test${CKPT} \
  outputs/train/act_so101_test/checkpoints/${CKPT}/pretrained_model

评估您的策略

您可以使用 lerobot/record.py 中的 record 脚本，但以策略检查点作为输入。例如，运行此命令以记录 10 个评估 эпизод

python -m lerobot.record  \
  --robot.type=so100_follower \
  --robot.port=/dev/ttyACM1 \
  --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video10, width: 640, height: 480, fps: 30}, side: {type: intelrealsense, serial_number_or_name: 233522074606, width: 640, height: 480, fps: 30}}" \
  --robot.id=my_awesome_follower_arm \
  --display_data=false \
  --dataset.repo_id=$HF_USER/eval_so100 \
  --dataset.single_task="Put lego brick into the transparent box" \
  --policy.path=${HF_USER}/my_policy

如您所见，它与之前用于记录训练数据集的命令几乎相同。有两处更改

  1. 有一个额外的 --control.policy.path 参数，它指示您的策略检查点的路径（例如 outputs/train/eval_act_so101_test/checkpoints/last/pretrained_model）。如果您将模型检查点上传到 Hub，您也可以使用模型存储库（例如 ${HF_USER}/act_so101_test）。
  2. 数据集的名称以 eval 开头，以反映您正在运行推理（例如 ${HF_USER}/eval_act_so101_test）。
< > 在 GitHub 上更新

LeRobot→