跳转至

LeRobot 与 ACT

先体验现成任务，再学习采集示范和训练自己的策略。 LeRobot 提供设备接入、遥操作、数据采集与策略训练框架，ACT 是其中一种模仿学习策略。Web 工作台提供可视化操作入口，命令行流程适合需要控制配置和扩展开发的用户。

预训练体验 · Web 可视化操作 · LeRobot 环境与接入 · 遥操作与数据采集

开始前应已完成连接与零位检查和一种小幅控制。先选下面一条路线；预训练体验、Web 训练和命令行开发可以分别开始，六节内容不要求依次全部执行。

你的目标 建议路径
先体验已有动作 第 1 节：按模型包选择原生或浏览器推理，无需先采集数据
用网页训练自己的任务 工作台准备 → 任务与采集 → Web 训练 → 评估，可跳过第 3 节的 CLI 安装
使用 LeRobot 命令行 环境与校准 → 任务与采集 → CLI 训练 → 评估，无需安装 Web 服务
开发双臂或自定义集成 对应单臂流程通过后进入第 6 节

1. 预训练 ACT 体验

目前 GitHub 已公开 ACT 积木放置发布包：让 FL 将积木放到预先布置的工作区中心，无需重新训练。先确认手里的模型格式：

模型来源与格式 应走哪条路径
GitHub act-pick-v1.0.0 的 TAR.GZ 发布包 按下方积木放置步骤，使用配套原生推理环境
已获得含 web-act.json 与 model.onnx 的适配包 跳到浏览器推理，按该包自己的相机与校准要求操作

只有 FL 时可以先完成手动控制；体验该积木模型还需要两路相机和下表中的计算环境。主臂不是自主推理的必需设备。

项目 该发布模型的要求
机械臂 Star Arm 102-FL，7 个位置通道
相机 俯视 up、正面 front，均为 640 × 480、30 FPS
场景 按发布教程复现积木、目标区、相机位置和视角
模型包 stararm102_pick_act_torch271.tar.gz
发布版本 act-pick-v1.0.0，训练 100,000 步的检查点
原始推理路径 Ubuntu 22.04、兼容 CUDA 的 NVIDIA GPU、发布版 LeRobot 插件

ACT 工作区与相机布置参考

  1. 在发布页下载模型，按配套校验文件确认完整性，保留配置与处理器文件。
  2. 对照场景与相机布置摆放设备，核对 up / front 对应的真实画面。
  3. 按配套推理指南准备发布版环境、校准和设备配置。不要用新插件的类型名直接替换旧配置。
  4. 先检查相机和关节反馈，确认起始场景后运行一次，记录成功或失败的原因，再重复试验。

完成标准： 能在明确的设备、模型、校准与场景条件下复现任务。发布版尚未给出测得的成功率；环境变化后应重新评估。

Web 工作台的模型管理支持完整 ACT ZIP 及旧版 TAR.GZ 导入；导入后仍需检查特征、相机和校准是否匹配。该 TAR.GZ 发布包不能直接当成浏览器 ONNX 模型包使用。其他随设备交付的预训练动作，按各自的模型说明确认任务条件。

浏览器推理

仅在已获得浏览器适配包时走此路径。 此路径不要求 Python、PyTorch 或本地推理服务。没有适配包时，返回上方 GitHub 发布模型的原生流程；不要把 TAR.GZ 改扩展名后导入。

  1. 打开 ACT 浏览器推理，导入含 web-act.json 和 model.onnx 的包。
  2. 查看模型声明的关节、相机和归一化要求，按需加载本机校准 JSON。
  3. 连接 FL，按模型所需视图选择相机，检查预览和关节反馈。
  4. 先运行校验／预热，确认真实图像和状态可被模型读取；这一步不发送运动。
  5. 检查工作区和起始姿态，再确认执行。保持页面在前台，按界面提供的停止操作结束任务。

完成标准： 模型校验通过，输入匹配，单次任务完成且可以停止。页面目标频率不是所有电脑都能达到的性能保证。当前公开 ACT 发布包与此模型格式不同，浏览器适配包应从其配套发布或交付资料获取。

2. Web 可视化采集与训练

打开 ACT 工作台

工作台把设备连接、示范采集、训练任务、模型管理和实机推理串联起来。按任务选择对应工作区：

工作区 你要完成的操作 需要准备
数据采集 配置主从臂与相机，录制并检查回合 本地设备服务；无需先手动搭建完整训练环境
训练任务 选择数据集、检查配置、提交训练并查看日志 按工作台提示准备 Ubuntu 22.04 / 24.04 本地组件与训练环境
模型管理 保存或导入模型，检查配套配置 完整模型包与匹配的关节、相机和校准信息
实机推理 连接设备并运行单次评估 FL、相机和已检查的模型
  1. 准备 LD / HD 主臂、FL 从臂及两路相机；只体验现成模型的用户返回第 1 节。
  2. 停止控制台中的动作，点击 全部断开并释放相机，再切换到 ACT 工作台。
  3. 按页面提示安装并启动采集所需本地设备服务，确认工作台显示服务可用。
  4. 继续定义任务与采集。训练组件在提交训练前按工作台提示准备，无需在本节提前运行 CLI 安装命令。

完成标准： 工作台设备服务可用，串口与相机已释放给工作台。下一步在工作台内连接设备，不需要再回实时控制页面建立第二个连接。

3. LeRobot 环境、设备接入与校准

本节用于命令行路径。Web 用户按工作台管理环境；导入外部模型时，同样需要核对下表中的特征与校准要求。

选择匹配的环境

路径 特征与边界
已发布 ACT 模型 Motor_0…Motor_5、gripper，配套 0.0.1 插件；使用发布说明中的环境
新的单臂 HD / FL 任务 stararm102_hd / stararm102_fl，命名关节；按当前单臂插件说明安装
Web 工作台 使用本地服务及工作台配置；导入模型时核对特征、相机与校准

不同代际的插件分别安装，不混用校准。已发布策略的关节名称、单位和相机配置不能直接套到新插件。

安装并检查设备

  1. 按 LeRobot 环境安装创建独立环境，安装所选插件和依赖。
  2. 检查 pip check、插件导入与 CLI 帮助是否正常，记录代码及依赖版本。
  3. 确认主从型号、实际串口、关节 ID 和按钮配置，关闭占用设备的其他程序。
  4. 按主从校准步骤分别保存校准，后续使用相同的 teleop.id 与 robot.id。
  5. 读取关节反馈，检查方向、范围与物理姿态，再进行遥操作。

硬件零点在 Web 控制台按参考姿态设置；LeRobot 校准用于所选插件的范围与映射，多圈计数重置也不能替代这两项操作。

完成标准： 环境检查通过，主从设备与校准标识明确，重新连接后反馈与实际姿态一致。

4. 遥操作与数据采集

先定义自己的任务

先选择一个能重复布置的小任务，例如把固定区域内的物体放进指定容器。写清楚：

  • 开始状态：机械臂、物体、容器的位置，以及相机视角。
  • 成功标准：物体最终在哪里、是否松开、何时算完成。
  • 变化范围：需要覆盖哪些起始位置、方向或光照变化。
  • 失败类型：未抓住、放置偏差、动作中断等。

示范应覆盖你希望模型处理的变化，同时保持任务描述和相机配置一致。

检查遥操作与相机

  1. Web 用户在 ACT 工作台内连接主从臂，检查小幅跟随，不同时打开实时控制连接；命令行用户按 LeRobot 无相机遥操作检查方向、夹爪与按钮行为。
  2. 确认小范围动作正常后，再添加相机。CLI 用户按相机配置识别设备与图像。
  3. 固定相机视角、输入名称、分辨率和帧率，检查画面连续、没有持续遮挡，再开始录制。

通过 Web 工作台采集

打开 ACT 工作台，进入 数据采集。

  1. 确认已完成工作台准备，本地服务状态正常。
  2. 选择 LD / HD 主臂和 FL 从臂，连接设备，检查姿态和遥操作。
  3. 配置两路相机，预览画面。工作台提供 wrist / world 视图配置；它们不能仅改名就当作已发布模型的 up / front 视角。
  4. 设置任务名称和数据集标识，创建并锁定配置。第一轮建议先使用 640 × 480、30 FPS，核对真实采集状态。
  5. 录制一次完整示范，结束后检查相机画面、动作／状态波形和回合结果。
  6. 检查首个回合正确后再继续采集，及时导出备份；工作台支持数据集 ZIP 导入和导出。

完成标准： 一个回合可以查看，图像与动作连续，任务完成过程清晰，配置可复用。删除或排除失败回合前，先保留原始记录，便于追查问题。

通过 LeRobot 命令行采集

命令行用户按 GitHub LeRobot 教程中的对应设备录制流程操作，保持第 3 节选定的环境与校准标识。

  1. 指定实际主从端口、相机配置、任务描述与新的数据集标识。
  2. 先录制少量回合，检查图像、动作／状态、任务标签与保存数量。
  3. 确认首个回合完整后再扩展采集量，保留原始数据和配置。
  4. 如需动作回放，先检查轨迹、初始姿态与工作区；回放会驱动真实机械臂。

完成标准： 至少能回看一个完整示范，并说明数据使用了哪套设备、相机、关节特征与校准。

5. ACT 训练与评估

先确认已保存至少一个可检查的完整数据集；测试录制成功不代表数据量与场景覆盖已足够训练。下面按实际采集路径选择一项。

Web 工作台训练

  1. 抽查回合的开头、抓取过程与结尾，确认画面对应动作，没有明显中断或错误映射。
  2. 进入 训练任务。按工作台提示准备 Ubuntu 22.04 / 24.04 的本地组件与训练环境；训练端负责准备 PyTorch / LeRobot 依赖。
  3. 选择本次数据集，核对策略、输入视图、关节特征与输出目录，再提交任务。
  4. 查看任务状态和日志。完成后进入 模型管理，保留模型、训练配置和数据版本。

完成标准： 训练任务完成，模型文件与配置完整，能追溯到使用的数据。训练完成或 loss 降低不等于实机任务已经通过。

LeRobot 命令行训练

沿用采集时的独立环境，按 GitHub LeRobot 教程的 ACT 训练命令执行：

  1. 核对实际数据集标识、图像输入名、动作特征和任务描述。
  2. 设置新的训练输出目录与策略配置，确认所需计算设备可用，再启动训练。
  3. 查看日志与检查点，保留权重、预处理配置、数据版本和依赖版本。
  4. 使用配套评估命令前，先检查下方的模型、校准与场景条件。

实机评估

Web 用户执行下面的工作台步骤；CLI 用户在原环境中按 GitHub 配套评估流程配置模型路径、设备和新评估目录，无需转到 Web 导入模型。两条路径都先做单次试验并保存结果。

  1. 在模型管理选择或导入完整模型包，检查动作维度、关节特征、相机视图和校准要求。
  2. 进入 实机推理，连接 FL 与相机，确认数据来自当前设备。
  3. 若模型使用归一化关节范围，按要求加载自己设备的范围校准 JSON；工作台采集的原生角度数据与外部归一化数据不能混用。
  4. 复位到预定初始场景，先执行单次任务，记录结果；之后再逐步增加场景变化。
每次评估记录 示例内容
版本 模型、训练数据、设备与校准版本
场景 相机位置、物体起点、光照变化
结果 总尝试数、成功数、失败类型
下一步 补哪些示范，还是修正相机、校准或执行配置

6. 双臂与进阶开发

单臂通信、校准、采集与评估通过后，再扩展到双臂。双臂使用左右两套主从设备与 14 个动作／状态字段，不能只把单臂配置中的串口数量加倍。

  1. 标记左右主从设备，分别确认四个端口、按钮配置与参考姿态。
  2. 按双臂适配器说明检查左右字段、相机视图和动作映射。
  3. 先检查单侧，再检查双侧协同；重新建立对应的数据集与评估配置。
  4. 扩展设备或插件时，保留关节名称、单位、范围与校准约定，先验证数据接口，再进入训练与实机执行。

完成标准： 左右设备及数据字段可明确区分，能追溯一次采集和评估使用的配置。

LeRobot CLI 参考 · 单臂源码 · 双臂源码 · Python 双臂控制

GitHub 保存可执行命令、插件版本和模型文件；Wiki 按任务组织操作顺序与完成标准。遇到异常请查看故障排查。