ACT モデル訓練ガイド
本稿では、IO-AI.TECH が公開する Docker イメージ ioaitech/train_act:cuda を用いて ACT モデルを訓練する手順を説明します。マウントパス、引数名、デフォルト値はイメージ内スクリプトと一致します。
イメージは Docker Hub の ioaitech 組織下に公開されています（例：ioaitech/train_act:cuda）。
適用場面
ACT は、タスク境界が明確でアクションパターンが比較的安定した模倣学習向けです。まず単一タスクの訓練パイプラインを確実に通し、その後ハイパーパラメータを調整する、という進め方に向いています。
本ガイドは、EmbodiFlow プラットフォームでアノテーション済みデータを LeRobot 形式でエクスポート済みであることを前提とします。
ワンコマンドで訓練
前提条件
- Linux ホスト
- NVIDIA ドライバが正常
- Docker が利用可能
docker run --gpus allで GPU が見える
簡易確認：
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi
最小実行
ローカルの LeRobot データセットを /data/input、出力を /data/output にマウントします。
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_demo \
--task_name demo_task \
--num_epochs 1 \
--batch_size 8
マウント、形式認識、訓練フローをまず検証する用途です。問題なければエポック数など本番向けに増やします。
推奨テンプレート
実運用に 近い設定例です。
docker run --rm --gpus all \
-v /path/to/lerobot_dataset:/data/input \
-v /path/to/output:/data/output \
ioaitech/train_act:cuda \
--run_name lemon_act_v1 \
--task_name pick_lemon \
--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 \
--gpus all
特定 GPU のみ使う場合は最後の行を --gpus 0 や --gpus 0,1 に変更します。
データ要件
起動時に /data/input/meta/info.json の存在を確認します。欠けると即終了します。データセットルートは少なくとも次の構造である必要があります。
your_dataset/
├── meta/
│ └── info.json
├── data/
└── videos/
訓練エントリポイントは LeRobot v2 と v3 に対応し、バージョンを検出して必要に応じて互換処理・中間変換を行います。
カメラフィールド
画像フィールド名が一般的な規約に沿っていれば、meta/info.json からカメラキーを推論します。特殊な場合は明示的に渡します。
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_cam_exp \
--task_name tron2_task \
--camera_keys observation.images.cam_high,observation.images.cam_right_wrist,observation.images.cam_left_wrist \
--camera_names cam_high,cam_right_wrist,cam_left_wrist
--camera_keys：LeRobot 側の画像フィーチャキー--camera_names：ACT 側のカメラ名
両者の順序は厳密に対応させます。
主な引数
以下はイメージ内 train_lerobot_to_act.py の定義と一致します。
訓練コア
| 引数 | デフォルト | 説明 |
|---|---|---|
--batch_size | 64 | バッチサイズ |
--num_epochs | 12000 | エポック数 |
--steps | 0 | num_epochs の別名。num_epochs=0 のときのみ使用 |
--learning_rate | 5e-5 | 学習率 |
--save_interval | 6000 | チェックポイント保存間隔（エポック） |
--gpus | all | 全 GPU、または 0,1 など |
--batch_mode | fixed_global | マルチ GPU 時のグローバルバッチの扱い |
--num_workers | 0 | コンテナでは /dev/shm 負荷軽減のため 0 推奨 |
ACT モデル
| 引数 | デフォルト | 説明 |
|---|---|---|
--task_name | auto | データセットから主タスクを推論 |
--run_name | 自動 | チェックポイントサブディレクトリ名 |
--policy_class | ACT | 通常はデフォルトのまま |
--kl_weight | 10 | KL 損失の重み |
--chunk_size | 100 | アクションチャンク長 |
--hidden_dim | 512 | Transformer 隠れ層次元 |
--dim_feedforward | 3200 | FFN 次元 |
--seed | 42 | 乱数シード |
データブリッジ
| 引数 | デフォルト | 説明 |
|---|---|---|
--camera_keys | 推論 | LeRobot 画像キー指定 |
--camera_names | 自動生成 | ACT カメラ名 |
--episode_len | 0 | 強制エピソード長。0 は自動 |
--idle_threshold | 1e-4 | 静止フレームしきい値 |
--max_episodes | 0 | 先頭 N エピソードのみ（スモークテスト） |
--convert_workers | 0 | 変換の並列ワーカー数 |
--keep_converted_hdf5 | オフ | 中間 HDF5 を残す（デバッグ用） |
出力
マウント した /data/output に書き出されます。
/path/to/output/
├── checkpoints/
│ └── <run_name>/
│ ├── policy_best.ckpt
│ ├── policy_last.ckpt
│ └── dataset_stats.pkl
└── manifest.json
policy_best.ckpt：訓練中に良かったチェックポイントpolicy_last.ckpt：最後に保存したチェックポイントdataset_stats.pkl：訓練で使った統計manifest.json：実行メタデータ
マルチ GPU の注意
マルチ GPU 起動はコンテナ内で処理されるため、通常は手動で torchrun を組む必要はありません。
- 単 GPU 結果との整合を取りやすい
--batch_mode fixed_globalを優先 - コンテナでは
--num_workers 0を維持 - 初回は
--max_episodes 10などで短い検証
スループット優先なら --batch_mode fixed_per_gpu を検討します。
よくある質問
1. データセットが見つからない
/data/inputへのマウントパス/data/input/meta/info.jsonの存在
を確認してください。info.json が無い場合は訓練コード以前の問題です。
2. DataLoader 異常や NCCL タイムアウト
--num_workers 0を維持--convert_workersを2や4に下げる--max_episodesで短い実行に切り詰める
3. task_name の指定
タスクメタデータが揃っていれば --task_name auto で足りることが多いです。複雑な場合は明示指定を推奨します。
4. 初回が遅い
ResNet18 重みはイメージに含まれていますが、変換と初回データロードには時間がかかります。ログが進んでいれば通常は問題ありません。
実践的な提案
- 本番前に 1 エポックまたは少数エピソードでパイプライン確認
- ベースラインを固定し、一度に変える変数は少なく
- 最終チェックポイントだけでなく中間も比較