全部文档
当前文档

暂无内容

如果没有找到您期望的内容,请尝试其他搜索词

文档中心

LeRobot 机器人开发与模仿学习实践

最近更新时间:2026-11-12 16:49:27

背景信息

本文介绍如何在星泓训推平台创建 LeRobot 开发任务,读取机器人示范数据,训练 ACT 策略,并在 ALOHA 仿真任务中评估策略。

项目

本文配置

LeRobot

v0.4.4

策略

ACT

数据集

lerobot/aloha_sim_transfer_cube_human,v3.0

评估任务

AlohaTransferCube-v0

准备工作

计算资源与运行要求

  1. 登录星泓训推平台,准备可用的资源组和队列。

  2. 确保账号具有开发任务及对应资源和存储的使用权限。

  3. 训练使用单 GPU。环境需支持 CUDA、TorchCodec 视频解码及 ALOHA 的 EGL 渲染;首次下载数据和视觉骨干权重时需要外网。

本文命令在 Linux 开发环境的 Bash 终端执行。

配置持久化存储

  1. 在“公共资产管理 → 存储配置”中,新建或选择可读写的存储配置。

  2. 核对存储根目录、访问权限和挂载路径。本文使用 /mnt/data,任务创建时需在“挂载配置”中选择该存储。

  3. 本文文件放在 /mnt/data/lerobot。如果修改挂载路径,后续命令中的路径也需同步修改。

使用文件存储 KPFS 时,选择对应目录作为存储根目录。使用 KS3 上传本地数据或模型时:

  1. 在本地准备文件并解压数据集,保留原目录结构。

  2. 登录对象存储控制台,选择“存储空间”,打开目标空间。

  3. 选择“内容管理 → 上传文件”,上传数据或模型。

  4. 回到平台的“存储配置”,选择该 KS3 实例及对应的 KS 路径。

挂载后的文件路径由存储根目录决定。例如,需要 /mnt/data/lerobot/datasets 时,所选根目录内应包含 lerobot/datasets,避免重复嵌套目录。直接在容器内创建 /mnt/data 不会自动形成持久化挂载。

操作步骤

步骤一:创建并连接开发任务

  1. 进入“快速上手 → 一键启动”,点击“LeRobot机器人开发”卡片的“立即前往”。

  2. 填写任务名称;镜像类型选择“官方镜像”,使用模板预选的 LeRobot 开发镜像(v0.4.4)。

  3. 选择准备好的资源组、队列和资源规格,在“挂载配置”中选择可读写存储,确认挂载路径为 /mnt/data,点击“确定”。

  4. 等待开发任务状态变为“运行中”,在列表操作列点击“连接”。

  5. 在连接窗口选择 WebIDE,本文使用 Jupyter Notebook;进入 JupyterLab 后,选择 Other → Terminal,打开终端。

图中名称和资源配置为入口示意,按本文的资源要求选择实际配置。

步骤二:检查存储与运行环境

先核对任务详情中的挂载配置,再检查目录和可用容量:

ls -ld /mnt/data
df -h /mnt/data

缓存和检查点需要读写、重命名、符号链接及文件锁支持。执行以下命令检查工作目录,检查文件会在结束时自动清理:

python - <<'PY'
from pathlib import Path
import fcntl
import tempfile

with tempfile.TemporaryDirectory(prefix=".storage-check-", dir="/mnt/data") as folder:
    root = Path(folder)
    original = root / "original.txt"
    original.write_text("storage-ok", encoding="utf-8")
    renamed = original.rename(root / "renamed.txt")
    link = root / "linked.txt"
    link.symlink_to(renamed.name)
    assert link.read_text(encoding="utf-8") == "storage-ok"
    with (root / "check.lock").open("w") as lock:
        fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
        fcntl.flock(lock, fcntl.LOCK_UN)
print("存储操作检查通过")
PY

如果操作失败,先检查挂载权限及存储类型;不支持上述操作时,使用文件存储 KPFS 作为工作目录。

检查框架、视频解码和仿真依赖:

python - <<'PY'
from importlib.metadata import version
import torch
import torchcodec
import gym_aloha
print("LeRobot:", version("lerobot"))
print("PyTorch:", torch.__version__)
print("TorchCodec:", version("torchcodec"))
print("CUDA:", torch.cuda.is_available())
assert version("lerobot") == "0.4.4", "镜像中的 LeRobot 版本与本例不符"
assert torch.cuda.is_available(), "本例训练需要 CUDA GPU"
PY
lerobot-train --help
lerobot-eval --help
ffmpeg -version

LeRobot 应为 0.4.4,CUDA 应返回 True。若版本不同或依赖导入失败,先核对镜像与本教程是否对应,不在任务中自行升级整套框架。

步骤三:读取机器人示范数据

本例使用公开数据集 lerobot/aloha_sim_transfer_cube_human 的 v3.0 版本。首次运行需要下载数据及模型依赖;没有容器外网时,可提前准备完整缓存并通过存储挂载使用。

设置缓存和结果目录:

export HF_HOME=/mnt/data/lerobot/cache/huggingface
export HF_LEROBOT_HOME=/mnt/data/lerobot/datasets
export TORCH_HOME=/mnt/data/lerobot/cache/torch
export MUJOCO_GL=egl
mkdir -p "$HF_HOME" "$HF_LEROBOT_HOME" "$TORCH_HOME" /mnt/data/lerobot/runs

读取第一帧,检查状态、动作和图像:

python - <<'PY'
from lerobot.datasets.lerobot_dataset import LeRobotDataset

dataset = LeRobotDataset(
    "lerobot/aloha_sim_transfer_cube_human", revision="v3.0"
)
print("frames:", len(dataset))
print("episodes:", dataset.meta.total_episodes)
for key in ("observation.state", "action", "observation.images.top"):
    print(key, tuple(dataset[0][key].shape))
PY

自有数据需包含完整的 LeRobot 元信息、轨迹及视频。替换数据前,核对采样频率、相机字段、状态和动作维度、时间对齐。MCAP、HDF5 数据需要按源字段转换,不能仅改文件名。

步骤四:训练 ACT 策略

本文在开发终端前台执行算法,运行期间保持终端会话连接。开发任务显示“运行中”表示开发环境已经启动,算法进度以终端输出和日志文件为准。

export LEROBOT_RUN=/mnt/data/lerobot/runs/act_$(date +%Y%m%d_%H%M%S)
set -o pipefail
lerobot-train \
  --dataset.repo_id=lerobot/aloha_sim_transfer_cube_human \
  --dataset.revision=v3.0 \
  --policy.type=act \
  --policy.device=cuda \
  --policy.push_to_hub=false \
  --output_dir="$LEROBOT_RUN" \
  --job_name=act_transfer_cube \
  --batch_size=8 \
  --steps=1000 \
  --save_freq=500 \
  --num_workers=2 \
  --wandb.enable=false \
  2>&1 | tee "$LEROBOT_RUN.train.log"

本例训练 1,000 步,关闭模型上传和 WandB。终端应持续输出训练步数和 loss,完整输出同时保存在 $LEROBOT_RUN.train.log。首次训练还可能下载 ACT 视觉骨干的预训练权重,缓存由 TORCH_HOME 保留。可根据任务需要增加训练步数,显存不足时调小 batch size。不要提前创建 LEROBOT_RUN 对应目录,该版本会拒绝在已有目录中启动新的训练。

训练结束后检查:

ls "$LEROBOT_RUN/checkpoints"
ls "$LEROBOT_RUN/checkpoints/last/pretrained_model"

last 是指向最近一次检查点的符号链接,工作目录需支持该文件操作。pretrained_model 中的权重、策略配置和处理器文件需完整保留,不能只复制模型权重。记录本次 LEROBOT_RUN 路径,新终端中按实际路径重新设置变量。

步骤五:仿真评估

使用与训练数据对应的 ALOHA 方块转移任务:

lerobot-eval \
  --policy.path="$LEROBOT_RUN/checkpoints/last/pretrained_model" \
  --policy.device=cuda \
  --env.type=aloha \
  --env.task=AlohaTransferCube-v0 \
  --eval.batch_size=1 \
  --eval.n_episodes=5 \
  --output_dir="$LEROBOT_RUN/eval" \
  2>&1 | tee "$LEROBOT_RUN/eval.log"

终端输出 Overall Aggregated Metrics,评估统计写入 $LEROBOT_RUN/eval/eval_info.json,视频在 eval/videos 内。检查脚本正常结束、统计文件和视频均已生成。可增加 eval.n_episodes,获得更多回合的评估统计。

步骤六:保存结果与复用环境

数据、模型、日志和结果保存在 /mnt/data/lerobot,由挂载存储保留。

  1. 重新使用结果时,创建或启动使用相同镜像的开发任务,并挂载同一存储。

  2. 在新终端中恢复 HF_HOME、HF_LEROBOT_HOME、TORCH_HOME、MUJOCO_GL 和 LEROBOT_RUN,使用原实验目录读取结果。

  3. 如修改了镜像内的代码或依赖,在开发任务列表选择“更多 → 保存镜像”保存环境。挂载目录中的文件由存储保留,不随镜像一起备份。

  4. 确认脚本结束、结果文件保存完成后,在任务列表停止不再使用的开发或训练任务,释放资源。

文档导读
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈