LeHome ACT Baseline 跑通记录：从环境排障到训练、评测与导出视频

摘要

本文记录 LeHome Challenge 官方 ACT（Action Chunking Transformer）Baseline 的完整跑通过程。从 Isaac Lab 环境排障（setuptools 82 兼容性问题）、数据迁移策略、训练配置、评测流程到视频导出，一步步还原真实操作路径。在 top_short 单类任务上，ACT 30k step 取得了 58.33% 的成功率。文末附完整的可执行命令和避坑指南。

正文

1. 背景

考研下岸了，但是生活还是要继续。毕业之前总得做点东西，不然怎么说自己本科是学机器人的呢。最近刷到个比赛，感觉有点意思。之前做 manipulation 都是简单的 pick and place，这次来试试具身方法最擅长的 deformable object manipulation。隔壁传统控制看到都馋哭了。

这篇文章专注一件事：用仿真环境（Isaac Sim）跑通一次 top_short 任务的 ACT baseline 训练 + 评测 + 视频导出。

2. 算力环境

比赛需要跑 Isaac Sim，我本地没有能跑的 GPU。上网找到一个算力平台，正好有 LeHome 官方镜像，配置：

GPU：L40 48G
CPU：14 核
内存：128G
系统盘：30G（停机清空）
数据盘：50G（按量付费）

平台自带的网页远程桌面很卡，疑似普通 VNC，老老实实 SSH。

3. 数据准备

如果和我一样用现成镜像，多半没有数据集。先下载：

nvidia-smi                  # 看看当前配置
cd /root/lehome-challenge   # 镜像预装路径
ls Assets
ls Datasets/example

# 没有就下载
hf download lehome/asset_challenge --repo-type dataset --local-dir Assets
hf download lehome/dataset_challenge_merged --repo-type dataset --local-dir Datasets/example

4. 数据迁移：系统盘 → 数据盘

系统盘很小（30G），每次停机数据清空。merged 数据集有 18G，放在系统盘容易撑爆。数据盘按量付费，合理得多。

数据盘路径：/root/gpufree-data

我的方案：把数据拷到数据盘，原路径用符号链接指过去。

# 创建目标目录
mkdir -p /root/gpufree-data/lehome/Datasets/example

# 复制数据
cp -a /root/lehome-challenge/Datasets/example/. /root/gpufree-data/lehome/Datasets/example/

# 校验大小
du -sh /root/lehome-challenge/Datasets/example
du -sh /root/gpufree-data/lehome/Datasets/example

大小接近就继续：

# 备份 → 软链接 → 验证 → 删备份
mv /root/lehome-challenge/Datasets/example /root/lehome-challenge/Datasets/example.bak
ln -s /root/gpufree-data/lehome/Datasets/example /root/lehome-challenge/Datasets/example
ls -ld /root/lehome-challenge/Datasets/example
readlink -f /root/lehome-challenge/Datasets/example
# 看到 .../example -> /root/gpufree-data/lehome/Datasets/example 就对了

rm -rf /root/lehome-challenge/Datasets/example.bak

5. 验证仿真环境和数据可用性

先放个 replay 看看。replay 能验证这几件事：

数据路径对不对
仿真环境能不能启动
Isaac Lab / Isaac Sim 是否可用
资产是否完整

cd ~/lehome-challenge
python -m scripts.dataset_sim replay \
  --dataset_root Datasets/example/top_short_merged \
  --num_replays 1 \
  --disable_depth \
  --device cpu \
  --enable_cameras

6. 修 Isaac Lab 安装问题

果然先验证是有必要的。报错：

ModuleNotFoundError: No module named 'isaaclab'

看报错像是 Isaac Lab 没装进环境。可能是预装镜像的问题。

6.1 第一次诊断

python -V
ls third_party
test -d third_party/IsaacLab && echo "IsaacLab repo exists" || echo "IsaacLab repo missing"
python -c "import isaaclab; print(isaaclab.__file__)"

还是报 ModuleNotFoundError。

6.2 按官方文档重装

cd /opt/lehome-challenge
source .venv/bin/activate

# 没有 IsaacLab 仓库就补 clone
test -d third_party/IsaacLab || git clone https://github.com/lehome-official/IsaacLab.git third_party/IsaacLab

# 按官方文档安装 IsaacLab 到当前 .venv
./third_party/IsaacLab/isaaclab.sh -i none

# 再把 lehome 包重新装进当前环境
uv pip install -e ./source/lehome

# 验证
python -c "import isaaclab, lehome; print('isaaclab ok:', isaaclab.__file__); print('lehome ok:', lehome.__file__)"

然而还是报错。具体是 flatdict==4.0.1 构建失败：

ModuleNotFoundError: No module named 'pkg_resources'

6.3 找根因

查 GitHub 发现最近上游有人报过几乎同一类错误：安装 IsaacLab 时因为 flatdict 构建阶段找不到 pkg_resources，最终表现成 ModuleNotFoundError: No module named 'isaaclab'。

根因：setuptools 82.0.0 在 2026 年移除了 pkg_resources，而老包 flatdict==4.0.1 在 build isolation 里还依赖它。

6.4 修复方案

思路：

把 setuptools 压回还带 pkg_resources 的版本
用 --no-build-isolation，避免它新开隔离构建环境丢掉 pkg_resources
单独把核心包 isaaclab 补装进去

source .venv/bin/activate

python -m pip install "setuptools<82" wheel
uv pip install "setuptools<82" wheel

uv pip install --no-build-isolation flatdict==4.0.1
uv pip install --no-build-isolation -e ./third_party/IsaacLab/source/isaaclab

python -c "import isaaclab; print('isaaclab ok:', isaaclab.__file__)"
python -c "import lehome; print('lehome ok:', lehome.__file__)"

再次跑 replay：

python -m scripts.dataset_sim replay \
  --dataset_root Datasets/example/top_short_merged \
  --num_replays 1 \
  --disable_depth \
  --device cpu \
  --enable_cameras

成功跑通。可以开始训练了。

7. ACT 训练

先试最简单的 top_short，四类一起上确实遭不住。

7.1 训练配置

cd ~/lehome-challenge
cp configs/train_act.yaml configs/train_act_top_short_ruali.yaml

修改内容：

dataset:
  repo_id: repo_act_top_short_ruali
  root: Datasets/example/top_short_merged

policy:
  type: act
  device: cuda
  push_to_hub: false

  input_features:
    observation.state:
      type: STATE
      shape: [12]
    observation.images.top_rgb:
      type: VISUAL
      shape: [3, 480, 640]
    observation.images.left_rgb:
      type: VISUAL
      shape: [3, 480, 640]
    observation.images.right_rgb:
      type: VISUAL
      shape: [3, 480, 640]

  output_features:
    action:
      type: ACTION
      shape: [12]

output_dir: /root/gpufree-data/lehome-outputs/train/act_top_short
batch_size: 16
steps: 30000
save_freq: 5000
log_freq: 1000

wandb:
  enable: false

主要改了三个地方：

dataset.root → Datasets/example/top_short_merged
output_dir → 数据盘路径
policy.device → cuda

7.2 一个小坑：不要提前创建 output_dir

这是 LeRobot 的一个坑。如果你提前 mkdir -p 了输出目录，训练会报：

FileExistsError: Output directory ... already exists and resume is False

因为默认 resume = false，它不允许输出目录已存在。正确做法：不提前创建训练输出目录，只创建日志目录。

mkdir -p /root/gpufree-data/lehome-outputs/logs

7.3 启动训练

lerobot-train --config_path configs/train_act_top_short_ruali.yaml \
  2>&1 | tee /root/gpufree-data/lehome-outputs/logs/act_top_short_train.log

训练开始后看到：

Creating dataset
Creating policy
Creating optimizer and scheduler
Output dir: /root/gpufree-data/lehome-outputs/train/act_top_short
Start offline training on a fixed dataset

说明数据加载、模型创建、优化器创建、输出目录创建都成功了。

7.4 训练速度

实际日志节奏：

1000 step ≈ 4~5 分钟
30000 step 总耗时 ≈ 2 小时多一点

中间自动保存 checkpoint：5000、10000、15000、20000、25000、30000。

训练结束标志：

Checkpoint policy after step 30000
End of training

7.5 要不要早停

这次我没有早停，直接跑满了 30000 step。经验上，如果 loss 还在明显下降，不建议 15K 就停。先把一趟 baseline 跑完整，再去比较不同 checkpoint 的效果。

8. ACT 评测

8.1 评测命令

cd ~/lehome-challenge
source .venv/bin/activate

mkdir -p /root/gpufree-data/lehome-outputs/eval/act_top_short

python -m scripts.eval \
  --policy_type lerobot \
  --policy_path /root/gpufree-data/lehome-outputs/train/act_top_short/checkpoints/last/pretrained_model \
  --dataset_root Datasets/example/top_short_merged \
  --garment_type top_short \
  --num_episodes 2 \
  --enable_cameras \
  --save_video \
  --video_dir /root/gpufree-data/lehome-outputs/eval/act_top_short \
  --device cpu \
  --headless

参数说明：

--policy_type lerobot：使用 LeRobot policy 路径
--policy_path .../last/pretrained_model：用最终 checkpoint
--dataset_root：评测数据集
--garment_type top_short：只测短袖
--num_episodes 2：每件衣服跑 2 次
--enable_cameras：保存相机图像
--save_video：导出 mp4
--video_dir：视频输出目录
--device cpu：仿真跑在 CPU
--headless：无 GUI 模式

8.2 验证评测输出

find /root/gpufree-data/lehome-outputs/eval/act_top_short -type f

看到类似以下文件就说明评测和视频导出成功：

.../success/episode0_observation_images_top_rgb.mp4
.../success/episode1_observation_images_left_rgb.mp4
.../success/episode0_observation_images_right_rgb.mp4
...

8.3 下载评测视频到本地

服务器上打包：

cd /root/gpufree-data/lehome-outputs/eval
tar -czf act_top_short_eval.tar.gz act_top_short

本地用 scp 下载：

scp -P 端口 root@你的服务器IP:/root/gpufree-data/lehome-outputs/eval/act_top_short_eval.tar.gz .

8.4 有 GUI 的评测

无头模式只能保存相机视角视频。想看 Isaac Sim 画面的话，用平台自带的浏览器面板，跑不带 --headless 的版本：

python -m scripts.eval \
  --policy_type lerobot \
  --policy_path /root/gpufree-data/lehome-outputs/train/act_top_short/checkpoints/last/pretrained_model \
  --dataset_root Datasets/example/top_short_merged \
  --garment_type top_short \
  --num_episodes 1 \
  --max_steps 300 \
  --enable_cameras \
  --device cpu

8.5 评测结果

Total Episodes: 12
Success Rate: 58.33%

每件衣服的细分结果（略）。几点说明：

Top_Short_Seen_0 ~ Top_Short_Seen_9 是 Seen 实例
Top_Short_Unseen_0、Top_Short_Unseen_1 是 Unseen 实例
Seen / Unseen 是实例划分，不是袖长划分
ACT 在 Seen 和 Unseen 上都能成功

9. success / failure 判断机制

查看了官方仓库的评估代码：

LeHome 不是看"视频好不好看"来判成功的。它在检查衣服网格/粒子模型上的若干关键检查点之间的距离关系。

简化理解：

取布料模型上的几个固定点
计算这些点之间的距离
判断是否满足阈值
满足 → success，不满足 → failure

这意味着即便 rollout 看起来"动作挺像那么回事"，如果最终几何关系没达标，评价就是 failure。

10. 总结

这次跑通 LeHome 官方 ACT baseline，最头疼的不是训练，而是一开始的环境排障。setuptools 82 移除 pkg_resources 导致 flatdict 构建失败，这种问题在论文里永远不会写，但实际做项目天天遇到。

对于 LeHome 这种活动，按照经验，都是先跑通一份 baseline 然后再谈其它。ACT 30k 在 top_short 上 58.33% 的成功率不算高，但至少证明了环境和流程是完整的，可以在此基础上尝试其他方法。

摘要

正文