# SO-101 CLI 参考（LeRobot 0.6.1）

> 按 v0.6.1 官方文档核对；尚未在目标 GPU/真机上执行。安装报告包含 CLI 帮助，实际差异必须回填。
> 遥操、采集和 rollout 在 3080；训练在 3090。电机设置/校准会写硬件或校准数据，先按装配文档确认接线。

## 0. 环境与变量

```bash
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}}'
```

将账号、端口和相机索引替换为实测值；训练机同样设置数据路径和 ID。优先稳定设备路径，备份实际校准目录。所有阶段使用同一个 robot/teleop ID、相机字段和任务文本。上面的单相机配置只是起点。

## 1. 探测、设置电机与校准

```bash
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
```

校准位置以实际输出及 `--robot.calibration_dir` / `--teleop.calibration_dir` 配置为准，不假设存于当前目录。更换电机、校准或机构后记录新版本，先遥操验证。

## 2. 遥操

```bash
lerobot-teleoperate \
  --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
```

先清空工作区，低速验证限位与停止手段，再采数。数据采集中的控制键以当前 CLI 提示为准，不沿用旧版“空格开始、回车保存”的说法。

## 3. 采集（3080）

```bash
lerobot-record \
  --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 验证保存、解码和时序，再完整采集。正式采集使用新数据目录，续录前核对当前版本的 resume 流程，勿覆盖旧实验。停止录制后将整个数据目录经 rsync 同步至 3090；保留 meta、视频和数据文件的相对结构。Hub 上传是可选独立步骤，不自动走镜像上传。

## 4. 训练（3090）

以下 batch/步数是起步配置，不承诺最终成功率或训练耗时。输出目录每个实验独立，不复用已存在的目录。

```bash
# 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
```

先做短训练与保存/重载验证，再跑正式训练。显存不足调顶层 `--batch_size`；更改步数时一并检查学习率调度。记录实际冻结模块、图像数量/尺寸、精度、峰值显存和步耗时。默认微调不应写作“全参数解冻”。ACT 的视觉骨干也可能需要首次下载权重。

`lerobot/smolvla_base` 首次会访问 Hub；正式复现实验应记录 revision 并保存完整本地快照，后续将 `--policy.path` 指向该快照。不要只保存模型权重而遗漏处理器、统计量或配置。

## 5. 真机执行（3080）

将训练输出中完整的 `pretrained_model` 目录（含配置和处理器）复制到本机；以实际输出目录为准。

```bash
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
```

使用训练时的相机/动作契约和当前机器人校准。先单次低风险试运行，再按 [评测协议](evaluation.md) 测 20 次。`lerobot-eval` 不作为这里的真机命令替代；同步 rollout 达标后再评估 Async/RTC。

## 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)。