ylhan/lerobot_learn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refine robot milestones and make GPU setup reproducible

Browse Source
This commit is contained in:
ylhan
2026-09-08 15:03:32 +08:00
parent 0e1b7eaf4d
commit d71fcc7650
9 changed files with 406 additions and 537 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli_reference.md
+82 -50
View File
@@ -1,74 +1,106 @@
# LeRobot CLI 命令参考（SO-101 · 默认在 3080 主家跑；训练命令在 3090）
# SO-101 CLI 参考（LeRobot 0.6.1）
> ⚠️ LeRobot 从 v0.3/0.4 的 `python -m lerobot.xxx` 改成了独立 **`lerobot-*` 控制台命令**（v0.5/0.6）。
> 下列命令基于调研，**确切 flag 以装好后 `<命令> --help` 实测为准**——跑完 setup 后先 `lerobot-record --help` 等核对一遍，把差异记回来。
> 前置：`source ~/robot/.venv/bin/activate && cd ~/robot/lerobot && export HF_ENDPOINT=https://hf-mirror.com`
> 按 v0.6.1 官方文档核对；尚未在目标 GPU/真机上执行。安装报告包含 CLI 帮助，实际差异必须回填。
> 遥操、采集和 rollout 在 3080；训练在 3090。电机设置/校准会写硬件或校准数据，先按装配文档确认接线。
## 0. 环境与变量
## 0. 常用准备
```bash
pip install pynput # 采数时用键盘 空格/回车 开始/停止 episode
huggingface-cli login # HF token（推/拉 数据集、模型）
source ~/robot/.venv-lerobot-0.6.1/bin/activate
# 使用 Hub 时先登录；本地 rsync 路线不要求登录。
# hf auth login
export ROBOT_DATA="$HOME/robot/data/so101_pickplace_v1"
export DATASET_ID="YOUR_HF_USER/so101_pickplace_v1"
export PORT_F="/dev/serial/by-id/REPLACE_FOLLOWER"
export PORT_L="/dev/serial/by-id/REPLACE_LEADER"
export TASK="put the red brick in a bowl"
export CAMERAS='{front:{type:opencv,index_or_path:0,width:640,height:480,fps:30}}'
```
## 1. 探测硬件
```bash
lerobot-find-port # 列出 USB 串口，认出手臂(和底盘轮)的 /dev/tty*
lerobot-find-cameras # 列出 USB 相机及其 index
```
> 记住每个设备对应的端口/索引，下面命令要用。多设备时**电机 ID 按顺序烧录**，别串。
将账号、端口和相机索引替换为实测值；训练机同样设置数据路径和 ID。优先稳定设备路径，备份实际校准目录。所有阶段使用同一个 robot/teleop ID、相机字段和任务文本。上面的单相机配置只是起点。
## 2. 校准（每条臂都要）
## 1. 探测、设置电机与校准
```bash
# follower（执行从手）
lerobot-calibrate --robot.type=so101_follower --robot.port=<PORT_F> --robot.id=my_follower
# leader（遥操主手）
lerobot-calibrate --robot.type=so101_leader --robot.port=<PORT_L> --robot.id=my_leader
lerobot-find-port
lerobot-find-cameras
# 新电机逐个连接，根据交互提示设置 ID/波特率；不要一次接满总线。
lerobot-setup-motors --robot.type=so101_follower --robot.port="$PORT_F"
lerobot-setup-motors --teleop.type=so101_leader --teleop.port="$PORT_L"
lerobot-calibrate --robot.type=so101_follower --robot.port="$PORT_F" --robot.id=my_follower
lerobot-calibrate --teleop.type=so101_leader --teleop.port="$PORT_L" --teleop.id=my_leader
```
> 校准会引导你把每个关节到极限位置、记 min/max/mid。产物存到 `--calibration_dir`（默认 `calibrations/`），**别丢**。
校准位置以实际输出及 `--robot.calibration_dir` / `--teleop.calibration_dir` 配置为准，不假设存于当前目录。更换电机、校准或机构后记录新版本，先遥操验证。
## 2. 遥操
## 3. 遥操作（验证跟手）
```bash
lerobot-teleoperate \
--robot.type=so101_follower --robot.port=<PORT_F> --robot.id=my_follower \
--teleop.type=so101_leader --teleop.port=<PORT_L> --teleop.id=my_leader
--robot.type=so101_follower --robot.port="$PORT_F" --robot.id=my_follower \
--robot.cameras="$CAMERAS" \
--teleop.type=so101_leader --teleop.port="$PORT_L" --teleop.id=my_leader
```
> 拿 leader 摆位 → follower 应同步跟上。**跟手不顺先查 ID/齿轮/校准**，别急着采数。
## 4. 采数（P1 核心）
先清空工作区，低速验证限位与停止手段，再采数。数据采集中的控制键以当前 CLI 提示为准，不沿用旧版“空格开始、回车保存”的说法。
## 3. 采集（3080）
```bash
lerobot-record \
--robot.type=so101_follower --robot.port=<PORT_F> --robot.id=my_follower \
--teleop.type=so101_leader --teleop.port=<PORT_L> --teleop.id=my_leader \
--dataset.repo_id=$HF_USER/so101_<task> \
--dataset.num_episodes=30 \
--dataset.single_task="put the red brick in a bowl" \
--robot.cameras="{front:{type:opencv,index_or_path:0,width:640,height:480,fps:30}}"
--robot.type=so101_follower --robot.port="$PORT_F" --robot.id=my_follower \
--robot.cameras="$CAMERAS" \
--teleop.type=so101_leader --teleop.port="$PORT_L" --teleop.id=my_leader \
--dataset.repo_id="$DATASET_ID" --dataset.root="$ROBOT_DATA" \
--dataset.single_task="$TASK" --dataset.num_episodes=50 \
--dataset.push_to_hub=false
```
- 键盘：**空格=开始 episode，回车=保存**。
- 多相机（P2 双臂）：`--robot.cameras="{front:{...},left_wrist:{...},right_wrist:{...}}"`（index 以 `find-cameras` 为准）。
- 采完自动 push 到 HF Hub（`$HF_USER/...`），3090 上即可训练。
## 5. 训练（在 3090 训练机上跑，数据集从 Hub 拉）
先用少量 episode 验证保存、解码和时序，再完整采集。正式采集使用新数据目录，续录前核对当前版本的 resume 流程，勿覆盖旧实验。停止录制后将整个数据目录经 rsync 同步至 3090；保留 meta、视频和数据文件的相对结构。Hub 上传是可选独立步骤，不自动走镜像上传。
## 4. 训练（3090）
以下 batch/步数是起步配置，不承诺最终成功率或训练耗时。输出目录每个实验独立，不复用已存在的目录。
```bash
# ACT（P1 快速验证）
lerobot-train --policy.type=act --dataset.repo_id=$HF_USER/so101_<task>
# SmolVLA（主力，24GB 单卡全量微调）
lerobot-train --policy.type=smolvla --dataset.repo_id=$HF_USER/so101_<task>
# ACT：固定任务基线。
lerobot-train \
--policy.type=act --policy.device=cuda --policy.push_to_hub=false \
--dataset.repo_id="$DATASET_ID" --dataset.root="$ROBOT_DATA" \
--batch_size=8 --steps=20000 --seed=42 \
--output_dir="$HOME/robot/outputs/act_pickplace_v1" \
--job_name=act_pickplace_v1 --wandb.enable=false
# SmolVLA：显式加载预训练基座，然后微调。
lerobot-train \
--policy.path=lerobot/smolvla_base --policy.device=cuda --policy.push_to_hub=false \
--dataset.repo_id="$DATASET_ID" --dataset.root="$ROBOT_DATA" \
--batch_size=4 --steps=20000 --seed=42 \
--output_dir="$HOME/robot/outputs/smolvla_pickplace_v1" \
--job_name=smolvla_pickplace_v1 --wandb.enable=false
```
> 3090 24GB：SmolVLA 全量、π0-FAST 用 LoRA。GPU 不足时降 batch / 用 `--policy.batch_size`。
先做短训练与保存/重载验证，再跑正式训练。显存不足调顶层 `--batch_size`；更改步数时一并检查学习率调度。记录实际冻结模块、图像数量/尺寸、精度、峰值显存和步耗时。默认微调不应写作“全参数解冻”。ACT 的视觉骨干也可能需要首次下载权重。
`lerobot/smolvla_base` 首次会访问 Hub；正式复现实验应记录 revision 并保存完整本地快照，后续将 `--policy.path` 指向该快照。不要只保存模型权重而遗漏处理器、统计量或配置。
## 5. 真机执行（3080）
将训练输出中完整的 `pretrained_model` 目录（含配置和处理器）复制到本机；以实际输出目录为准。
## 6. 评测 / 部署到真机（在 3080 主家跑，臂插它）
```bash
# 两种名字都见过（随版本），用 --help 确认当前是哪个
lerobot-eval --policy.path=<trained_model_dir> --robot.type=so101_follower --robot.port=<PORT_F> --robot.id=my_follower
# 或
lerobot-rollout --policy.path=<trained_model_dir> --robot.type=so101_follower --robot.port=<PORT_F> --robot.id=my_follower
export MODEL_DIR="$HOME/robot/models/act_pickplace_v1/pretrained_model"
lerobot-rollout \
--strategy.type=base \
--robot.type=so101_follower --robot.port="$PORT_F" --robot.id=my_follower \
--robot.cameras="$CAMERAS" \
--task="$TASK" --policy.path="$MODEL_DIR" --policy.device=cuda
```
> 3090 单机直连 follower，让**没被遥操的 follower** 独立完成任务 = P1 验收。
---
使用训练时的相机/动作契约和当前机器人校准。先单次低风险试运行，再按 [评测协议](evaluation.md) 测 20 次。`lerobot-eval` 不作为这里的真机命令替代；同步 rollout 达标后再评估 Async/RTC。
## P4 分布式（薄边厚芯）命令形态
- **3080 主家（推理芯）**：policy server —— 不是官方 `lerobot-*`，而是我们自写（`server/`），内部调 LeRobot 的 policy 推理，输入 obs 输出 action chunk；**训练仍归 3090**。
- **RPi5（机器人）**：thin client（`client/`）—— 采 3 相机 + 本体状态 → 推 3080 → 收 chunk → 实时插值下发舵机/底盘 + 断链 fail-safe。
- 复用：3080 上仍用 `lerobot-record`（遥操采集）；训练丢给 3090 的 `lerobot-train`。
## 6. 双臂与移动
P2 先检查 v0.6.1 的 `BiSOFollower` 配置，不从零移植双臂驱动。P3 复用 LeKiwi host/client，P4 核对官方 PolicyServer/RobotClient 与组合 robot 兼容性，再添加适配、状态机和本机故障处理。此处暂不编写未验证的整机 CLI。
参考：[v0.6.1 模仿学习流程](https://github.com/huggingface/lerobot/blob/v0.6.1/docs/source/il_robots.mdx)、[v0.6.1 SmolVLA 与 rollout](https://github.com/huggingface/lerobot/blob/v0.6.1/docs/source/smolvla.mdx)、[SO-101 电机设置](https://huggingface.co/docs/lerobot/so101)。
docs/evaluation.md
+43
View File
@@ -0,0 +1,43 @@
# 实验与评测协议
当前无实测结果。本文件为模板，每轮复制至独立实验记录后填写；不得将占位或演示数据填为真实结果。
## 实验身份
记录日期、操作者、任务、机器人/机构版本、校准 ID 与备份校验值、相机安装照片和参数、数据版本/校验值、LeRobot 版本、依赖锁 SHA256、GPU/驱动、模型来源 revision、checkpoint、处理器、训练步数/batch/种子/精度/冻结模块。
另记录训练步耗时、训练峰值显存、推理峰值显存与延迟 P50/P95/P99。评测不通过时先分类失败原因，再决定补数据、修机构或调模型。
## P1/P2/P4 任务评测
1. 开始前写明任务成功条件、初始位置范围、物体、目标区域、最大执行时长、允许的接触、碰撞定义与停止条件。抓放成功应包括物体最终稳定留在目标区域，而非仅短暂抓起。
2. 预先列出 20 次初始条件和测试顺序。可用 5 个规定位置各 4 次；这只能说明该范围内能力。未见位置、物体、光照或语言指令泛化应另测，不能混为同一结论。
3. 固定 checkpoint；测试期间不调参、不挑选成功视频替代全量记录。每次运行前允许人工复位；运行开始后任何人工接管均算本次失败。
4. 超时、掉落或需人工救援算失败；保存失败视频与原因。更换模型/数据或调参后重新开始完整一轮，不删除失败试次。
5. 阶段门槛：20 次至少成功 16 次、碰撞 0 次；全部干预和失败完整记录。任一碰撞均使该轮不通过。该样本量只是项目门槛，不代表精确的长期可靠性估计。
| 试次（1–20，每次一行） | 初始条件 | 成功/失败 | 耗时 | 干预次数 | 碰撞次数 | 失败阶段/原因 | 视频/日志 |
|---|---|---|---|---|---|---|---|
| 待填 | | | | | | | |
汇总：成功 __/20，超时 __，干预 __，碰撞 __，是否通过 __。P4 同时报告移动、到位、抓取、运输、放置的分阶段结果，但整机成功必须全程通过。
## P3 到位与制动
根据 P1 抓取容差和底盘试验，**在验收前**填入：位置误差上限 __；角度误差上限 __；停稳速度/持续时间 __；停车时间上限 __；停车距离上限 __；测试负载 __；地面 __；最大速度 __。
重复 20 次移动到位，逐次记录位置/角度误差、停稳时间及是否达标，报告误差分布。全部符合预先规定阈值才能连接操作策略。未定义阈值时只能称为探索测试，不能验收。
## P4 故障注入
在受控工作区从低速、轻负载开始。使用独立停止手段，按实际负载明确手臂保持/受控停止行为；不默认回中位。
| 故障 | 测试内容 | 触发到停车时间/距离 | 手臂行为 | 旧动作是否失效 | 重连是否需重新使能 | 是否通过 |
|---|---|---|---|---|---|---|
| 断网 | 双向断开与单向通信失败 | 待测 | | | | |
| 推理进程退出 | 服务意外退出 | 待测 | | | | |
| 相机卡死 | 无新帧与反复返回旧帧 | 待测 | | | | |
| 乱序/过期动作 | 延迟包、重复包、旧 session 包 | 待测 | | | | |
| 队列耗尽 | 推理耗时超过动作缓冲 | 待测 | | | | |
所有故障均符合 P3 预定停止上限、旧动作不可再执行、恢复需显式使能后，故障验收才通过。阈值或停止行为改变后须复测。