physicalai-train-training-a-policy

ポリシーのトレーニング（ライブラリ）

トレーニングには、Policy と DataModule を使う physicalai.train.Trainer（library/src/physicalai/train/trainer.py にある lightning.Trainer のサブクラス）を使用します。このライブラリでは、同等のエントリーポイントを意図的に 2 つサポートしています。

• CLI — physicalai fit（および validate、test、predict）：library/configs/ にある jsonargparse YAML を使用し、コマンドラインで上書きします。デフォルトではチェックポイントは experiments/{name}/version_N/ に保存されます。library/docs/how-to/training/cli.md を参照してください。
• Python API — Policy、LeRobotDataModule（または別のデータモジュール）、Trainer を構築し、trainer.fit(model=policy, datamodule=datamodule) を呼び出します（必要に応じてチェックポイントを指定し、validate／test／predict も実行できます）。library/docs/getting-started/quickstart.md と library/docs/explanation/trainer/README.md を参照してください。

CLI のサブコマンドと Python API は同じオブジェクトを共有します。YAML の class_path／init_args は、コードで組み立てる場合と一致させてください。

4 つの CLI サブコマンドは、共通の --model／--data／--trainer.* 形式を使用します（cli/_dispatch.py を参照）。validate／test／predict では、さらに --ckpt_path を指定します。タスクがシェルの使い方ではなくライブラリの動作に関するものである場合は、まず Python API の手順を優先し、ユーザー向けの変更であればその後 CLI との同等性を確認してください。

設定ファイルの構成

設定ファイルでは、class_path／init_args を使って次の 3 つを接続します。

• model — Policy のサブクラス（例：physicalai.policies.ACT）。
• data — DataModule。通常は repo_id（例：lerobot/pusht）を指定した physicalai.data.lerobot.LeRobotDataModule です。
• trainer — Lightning の引数（max_epochs、accelerator、devices、コールバックなど）。

ファーストパーティの設定ファイルは library/configs/physicalai/<policy>/<embodiment>/ に、LeRobot 用の設定ファイルは library/configs/lerobot/ にあります。__base__ を使って組み合わせ、CLI で任意のフィールドを上書きできます（--trainer.max_epochs 200 --data.train_batch_size 64）。

Python API のワークフロー

コード、ノートブック、テスト、ライブラリとの直接統合、または Trainer、Policy、データモジュールの変更を求められた場合は、この手順を使用してください。

from physicalai.data import LeRobotDataModule
from physicalai.policies import ACT
from physicalai.train import Trainer

datamodule = LeRobotDataModule(repo_id="lerobot/pusht", train_batch_size=2)
policy = ACT()
trainer = Trainer(fast_dev_run=True)
trainer.fit(model=policy, datamodule=datamodule)

1. CLI がインスタンス化するものと同じオブジェクトを構築します：Policy、DataModule、Trainer。
   • 完了条件：jsonargparse YAML に依存せずに構築できること。
2. Trainer(fast_dev_run=True) で API の接続をスモークテストします。
   • 完了条件：形状や特徴量のエラーなく、トレーニングバッチ 1 つと検証バッチ 1 つが完了すること。
3. Python から検証／テスト／予測を実行します。対応する Trainer メソッドを使い、必要に応じて ckpt_path を指定します。
   • 完了条件：API 呼び出しと同等の CLI コマンドで、チェックポイントと設定ファイルの動作が一致すること。

CLI のワークフロー

ターミナルコマンド、library/docs/how-to/ 以下のドキュメント、YAML 設定ファイル、再現可能な実験、またはエントリーポイントの動作について求められた場合は、この手順を使用してください。

1. ポリシーファミリーに合った既存の設定ファイルを起点にします。ゼロから作成せず、コピーしてください。
   • 完了条件：エラーなく、physicalai fit --config <your.yaml> --print_config で解決済みの設定全体が表示されること。
2. 実際の実行の前に、接続をスモークテストします。

   physicalai fit --config configs/physicalai/<policy>/<embodiment>/<config>.yaml --trainer.fast_dev_run=true
   

   • 完了条件：形状や設定のエラーなく、トレーニングバッチ 1 つと検証バッチ 1 つが完了すること。
3. 必要に応じて CLI で上書きしながら、トレーニングを実行します。

   physicalai fit --config configs/physicalai/<policy>/<embodiment>/<config>.yaml --trainer.max_epochs 200
   

   • 完了条件：experiments/{name}/version_N/ にチェックポイントが作成されること。
4. チェックポイントから検証／テスト／予測を実行します。

   physicalai validate --config configs/physicalai/<policy>/<embodiment>/<config>.yaml --ckpt_path experiments/<name>/version_0/checkpoints/last.ckpt
   

5. 損失だけでなく、メトリクスを見ながら反復します。タスクに関連する検証メトリクスが改善していることを確認し、その結果を得た設定ファイルとチェックポイントを記録してください。

実行のデバッグ

• API：短いスクリプトやテストで Policy、DataModule、Trainer を直接構築し、オブジェクトの構築、データの読み込み、CLI の解析のどこで失敗しているかを切り分けます。
• --trainer.fast_dev_run=true — 各ステージで 1 バッチを実行します。失敗したときは、まずこれを試してください。
• --print_config — jsonargparse が構築した、解決済みの設定 JSON を確認します。
• 形状や特徴量の不一致は、通常、データモジュールの Feature 名またはアクション次元がポリシーと一致していないことを意味します。physicalai-train-adding-a-policy スキルを参照して照合してください。
• データセットのダウンロードが停止する場合：実行時に LeRobot の repo_id が取得されています。physicalai-train-working-with-datasets スキルを参照してください。

必須チェック

• 長時間の実行を始める前に、設定が解決され（--print_config）、fast_dev_run が成功すること。
• ライブラリ向けの変更では、同等の Python API 構築パスが成功すること。
• accelerator／devices が、インストール済みのバックエンド追加機能（xpu／cuda／cpu）に合っていること。
• 新規または名前を変更した設定フィールドが、ポリシーの Config クラスと一貫していること。
• トレーニングコマンドを示すドキュメントのコードブロックが、引き続き tests/test_docs.py に合格すること。

検証

# from library/
physicalai fit --config configs/physicalai/<policy>/<embodiment>/<config>.yaml --trainer.fast_dev_run=true
uv run --no-sync pytest tests/unit/train

API に関わる変更では、Policy、DataModule、Trainer を直接構築して trainer.fit(...) を呼び出す、同等の Python スモークテスト（シェルのヒアドキュメントではありません）を追加するか、実行してください。

関連スキル

• physicalai-train-adding-a-policy — モデル自体に変更が必要な場合。
• physicalai-train-working-with-datasets — 設定の data 部分について。
• physicalai-train-benchmarking-a-policy — トレーニング済みチェックポイントをジムで評価する場合。