跳到主要内容

ACT 模型训练

ACT（Action Chunking Transformer）来自 ALOHA 工作，官方实现位于 tonyzhaozh/act，论文为 Learning Fine-Grained Bimanual Manipulation with Low-Cost Hardware。官方代码以 HDF5 episode 为训练输入。

艾欧智能已经基于官方 ACT 实现构建并发布 ioaitech/train_act:cuda Docker 镜像。该镜像包含 CUDA 训练环境、ACT 训练依赖、LeRobot 到 HDF5 episode 的转换层，以及标准 ACT 训练入口。因此读者可以直接挂载 LeRobot 数据集训练，不需要先手动整理官方 HDF5 数据。

国内镜像

镜像默认发布在 Docker Hub：ioaitech/train_act:cuda。中国大陆环境可改为 swr.cn-east-3.myhuaweicloud.com/ioaitech/train_act:cuda。

何时使用​

ACT 适合任务边界清晰、动作模式相对稳定的模仿学习任务。它不依赖大规模语言模型，训练链路比 Pi0/Pi0.5 更直接；代价是跨任务泛化能力通常不如 VLA 基座模型。

优先考虑 ACT 的情况：

  • 数据来自同一机器人、同一任务或少量相近任务。
  • 希望快速得到一个可部署的单任务策略。
  • 语言指令不是主要变量，任务名主要用于实验管理。
  • 你愿意通过多 checkpoint 实机评估，而不是只看最终 loss。

官方 ACT README 明确建议：真实世界任务在 loss 平台后仍可能继续改善，必要时应延长训练并比较多个 checkpoint。

数据要求​

镜像输入为 LeRobot 数据集，容器内路径固定为 /data/input。至少需要：

your_dataset/
├── meta/
│   └── info.json
├── data/
└── videos/

转换层会读取：

  • observation.state：写入 ACT HDF5 的 observations/qpos，不足 16 维会补零，超过 16 维会截断。
  • action：写入 HDF5 的 action，同样按 16 维处理。
  • observation.images.*：自动推断相机字段，也可以用 --camera_keys 显式指定。

如果你的机器人状态不是 16 维，务必确认补零或截断是否符合下游控制接口。文档示例以跑通训练为目标，不代表任何机器人都可以直接部署。

使用镜像训练​

先做 GPU 自检：

docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

最小验证​

docker run --rm --gpus all \
  -v /path/to/lerobot_dataset:/data/input \
  -v /path/to/output:/data/output \
  ioaitech/train_act:cuda \
  --run_name act_smoke \
  --task_name smoke_task \
  --num_epochs 1 \
  --batch_size 8 \
  --max_episodes 2

这条命令会转换前 2 个 episode，适合检查相机字段、state/action 维度和 HDF5 转换流程。

正式训练模板​

docker run --rm --gpus all \
  -v /path/to/lerobot_dataset:/data/input \
  -v /path/to/output:/data/output \
  ioaitech/train_act:cuda \
  --run_name pick_block_act_v1 \
  --task_name pick_block \
  --num_epochs 12000 \
  --batch_size 64 \
  --learning_rate 5e-5 \
  --chunk_size 100 \
  --kl_weight 10 \
  --hidden_dim 512 \
  --dim_feedforward 3200 \
  --batch_mode fixed_global

多相机字段建议显式写清楚：

docker run --rm --gpus all \
  -v /path/to/lerobot_dataset:/data/input \
  -v /path/to/output:/data/output \
  ioaitech/train_act:cuda \
  --run_name multi_camera_act \
  --task_name pick_block \
  --camera_keys observation.images.front,observation.images.left_wrist,observation.images.right_wrist \
  --camera_names front,left_wrist,right_wrist \
  --num_epochs 12000 \
  --batch_size 64

输出目录：

/path/to/output/
├── checkpoints/
│   └── <run_name>/
│       ├── policy_best.ckpt
│       ├── policy_last.ckpt
│       └── dataset_stats.pkl
└── manifest.json

若需要保留中间 HDF5 以便排查，增加 --keep_converted_hdf5。默认训练结束后会清理 /data/output/converted_hdf5。

常用参数​

参数默认值说明
--batch_size64基准 batch。多卡时由 --batch_mode 决定语义。
--batch_modefixed_global保持全局 batch 接近单卡参考值；追求吞吐时可用 fixed_per_gpu。
--num_epochs12000ACT 主训练轮数。
--steps0num_epochs 的兼容别名，仅在 num_epochs <= 0 时使用。
--learning_rate5e-5主学习率。
--save_interval6000当前主要写入 manifest；训练脚本仍按内部逻辑保存 checkpoint。
--policy_classACT通常保持默认。
--kl_weight10官方常用值。
--chunk_size100动作 chunk 长度，也是 ACT 查询数。
--hidden_dim512Transformer 隐层维度。
--dim_feedforward3200FFN 隐层维度。
--camera_keys自动推断LeRobot 视觉字段，逗号分隔。
--camera_names自动生成ACT 内部相机名，顺序必须与 camera_keys 对齐。
--max_episodes0仅转换前 N 个 episode；0 表示全量。
--convert_workers0转换并发 worker；内存紧张时显式降到 4 或 8。
--num_workers0训练 DataLoader worker。容器里建议保持默认。

从官方源码复现​

官方 ACT 仓库使用 HDF5 数据集，不直接消费 LeRobot 数据。最小复现路径如下：

git clone https://github.com/tonyzhaozh/act.git
cd act

conda create -n aloha python=3.8.10
conda activate aloha
pip install torchvision torch pyquaternion pyyaml rospkg pexpect
pip install mujoco==2.3.7 dm_control==1.0.14 opencv-python matplotlib einops packaging h5py ipython
cd detr && pip install -e .

官方训练示例：

python3 imitate_episodes.py \
  --task_name sim_transfer_cube_scripted \
  --ckpt_dir /path/to/ckpt \
  --policy_class ACT \
  --kl_weight 10 \
  --chunk_size 100 \
  --hidden_dim 512 \
  --batch_size 8 \
  --dim_feedforward 3200 \
  --num_epochs 2000 \
  --lr 1e-5 \
  --seed 0

若要用平台导出的 LeRobot 数据复现官方 ACT，需要先转换为官方 HDF5 episode。推荐使用 ioaitech/train_act:cuda 完成该转换与训练；若完全回到官方仓库，则需要自行实现等价的数据转换。

排错​

找不到相机字段​

检查 meta/info.json 中的 features。若自动推断不符合预期，显式传入 --camera_keys 和 --camera_names。两者数量与顺序必须一致。

多卡训练卡住或 NCCL 超时​

先用单卡和少量 episode 验证。多卡时保持 --num_workers 0，并降低 --convert_workers。如果仍不稳定，先排除数据转换阶段的磁盘与内存压力。

训练 loss 已平台但实机动作仍不稳定​

ACT 官方经验是继续训练仍可能改善真实执行效果。保留多个中间 checkpoint，用固定实机评估集比较，不要只看 policy_last.ckpt。

需要使用原始 ACT 数据格式​

如果你已经有官方 HDF5 数据，不需要走 LeRobot 转换。可以直接使用官方仓库或在镜像中调用 imitate_episodes.py，但此路径不属于平台默认封装。

参考链接​