メインコンテンツまでスキップ

ACT の学習

ACT（Action Chunking Transformer）は ALOHA 系の手法で、参照実装は tonyzhaozh/act、論文は Learning Fine-Grained Bimanual Manipulation with Low-Cost Hardware です。公式コードの学習入力は HDF5 エピソード です。

IO-AI は公式 ACT を基に ioaitech/train_act:cuda を公開しています。CUDA 学習環境・ACT 依存関係・LeRobot → HDF5 変換層・標準の ACT 学習エントリが入っており、LeRobot データセットをそのままマウントして学習できます。

使い分け​

タスク境界が明確で動作パターンが比較的安定した模倣学習向け。大規模言語モデルに依存しないため Pi0 系より単純ですが、タスク間一般化は VLA 基盤より弱くなりがちです。

次に当てはまる場合 ACT を優先：

  • 同一ロボット・同一または近いタスクのデータ
  • 単タスク方策を早くデプロイしたい
  • 言語は主な変動因子ではない
  • 複数チェックポイントを実機で評価できる

公式 README でも、損失が平坦化した後も実世界性能は伸び得るため、学習延長と複数 CKPT 比較が推奨されています。

データ要件​

イメージは LeRobot データセットを /data/input にマウントすることを想定します。

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

変換層の読み取り：

  • observation.state → HDF5 observations/qpos（16 次元未満はゼロパディング、超過は切り詰め）
  • action → HDF5 action（同様に 16 次元）
  • observation.images.* → 自動推定、または --camera_keys で明示

16 次元でない状態のゼロ詰め／切り詰めが下流制御と整合するか必ず確認してください。

イメージで学習​

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

スモーク（先頭 2 エピソード）​

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

本番テンプレート​

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基準バッチ。多 GPU では --batch_mode で解釈が変わる。
--batch_modefixed_globalグローバルバッチを単 GPU基準に近づける。
--num_epochs12000メインの学習エポック。
--steps0num_epochs <= 0 のときのエポック別名。
--learning_rate5e-5学習率。
--save_interval6000manifest 系。CKPT は ACT 内部ロジックに従う。
--kl_weight / --chunk_size / --hidden_dim / --dim_feedforward公式に近い既定ACT の主要ハイパラ。
--camera_keys / --camera_names自動数と順序を一致させる。
--max_episodes0先頭 N 件だけ変換。0 は全件。

公式 ACT での再現​

公式は HDF5 前提です。

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 への変換が必要で、ioaitech/train_act:cuda が変換＋学習の推奨経路です。完全に公式リポのみで行う場合は同等の変換を自前で実装してください。

トラブルシューティング​

カメラキーが見つからない​

meta/info.json の features を確認し、--camera_keys と --camera_names を明示。

多 GPU で NCCL タイムアウト​

まず単 GPU・少数エピソードで検証。--num_workers 0 を維持し、--convert_workers を下げる。

損失は良いが実機が悪い​

公式経験どおり学習継続と複数 CKPT の実機比較を。policy_last だけに依存しない。

既に公式 HDF5 がある​

LeRobot 変換は不要。imitate_episodes.py を直接利用（プラットフォーム既定ラッパの外）。

参考リンク​