physicalai-train-benchmarking-a-policy

Studio ポリシーのベンチマーク

ベンチマークでは、学習済みポリシーをジムで実行し、成功率をスコア化して評価します。ベンチマーククラスは library/src/physicalai/benchmark/gyms/benchmark.py（Benchmark、PushTBenchmark、LiberoBenchmark）にあります。結果の型は benchmark/gyms/results.py（BenchmarkResults、TaskResult）に、ロールアウトのロジックは library/src/physicalai/eval/rollout.py（evaluate_policy）にあります。このライブラリは、Python APIからの直接利用と、physicalai benchmark CLIラッパー（library/src/physicalai/cli/benchmark.py）の両方をサポートしています。

Python API の呼び出し

ノートブック、テスト、カスタムスクリプト、またはライブラリの直接統合には、この方法を使用します。

from physicalai.benchmark.gyms import PushTBenchmark
from physicalai.policies import ACT

policy = ACT.load_from_checkpoint("experiments/act/version_0/checkpoints/last.ckpt")
benchmark = PushTBenchmark(num_episodes=1)
results = benchmark.evaluate(policy)
print(results.summary())
results.to_json("results/benchmark/results.json")
results.to_csv("results/benchmark/results.csv")

エクスポート済みのアーティファクトの場合は、まず Runtime 向けのモデルを読み込みます。

from physicalai.benchmark.gyms import PushTBenchmark
from physicalai.inference import InferenceModel

model = InferenceModel("./exports/act_policy")
results = PushTBenchmark(num_episodes=1).evaluate(model)

CLI の呼び出し

physicalai benchmark \
  --config configs/benchmark/pusht.yaml \
  --policy physicalai.policies.ACT \
  --ckpt_path experiments/act/version_0/checkpoints/last.ckpt \
  --output_dir ./results/benchmark

• --policy — ポリシークラスのパスです。
• --ckpt_path — .ckpt または エクスポートディレクトリを指定します。
• --config — Benchmark クラスとその設定を選択するベンチマーク設定（configs/benchmark/pusht.yaml、configs/benchmark/libero.yaml）です。
• --output_dir — デフォルトは ./results/benchmark です。

たとえば、--benchmark.num_episodes 10 --benchmark.num_envs 8 のように、CLI でベンチマーク設定を上書きできます。

出力

• results.summary() を標準出力に表示します。
• results.json と results.csv を --output_dir に書き込みます。
• 設定の video_dir と record_mode（all | failures | successes | none）を指定すると、動画を出力できます。

ワークフロー

1. API または CLI を意図的に選択します。 コードレベルのタスクには Python API を、設定／ドキュメント／エントリーポイントに関するタスクには CLI を使用します。
   • 完了条件：選択した方法が、ユーザーの求める利用範囲に合っていること。
2. フルスイープを実行する前に、チェックポイント／エクスポートからポリシーを読み込めることを確認します。

   physicalai benchmark --config configs/benchmark/<suite>.yaml --policy <ClassPath> --ckpt_path <path> --benchmark.num_episodes 1
   

   • 完了条件：1 エピソードがエンドツーエンドで実行され、サマリーが表示されること。
3. 意図したエピソード数／環境数でフルベンチマークを実行します。
   • 完了条件：results.json と results.csv が書き込まれ、成功指標が設定されていること。
4. BenchmarkResults／TaskResult のフィールドを使って結果を解釈し、同じ設定でベースラインのチェックポイントと比較します。
5. タスクの性能が低下した場合は、定性的なレビュー用に動画を記録します（record_mode: failures）。

ベンチマークの追加または変更

1. benchmark/gyms/ に Benchmark のサブクラスを作成します（PushTBenchmark／LiberoBenchmark を参考にしてください）。ジム本体は physicalai.gyms（pusht.py、libero.py、…）にあります。
2. 対応する設定を library/configs/benchmark/ に追加します。
3. library/tests/unit/benchmark/ にテストを追加します。
   • 完了条件：uv run pytest tests/unit/benchmark が成功し、1 エピソードの実行も成功すること。

必須チェック

• 両方がサポート対象のパスである場合、.ckpt とエクスポートディレクトリの両方からポリシーを実行できること。
• ユーザー向けのベンチマーク変更では、Python API の経路（Benchmark(...).evaluate(...)）と CLI ラッパーで、サポートされる入力が一致していること。
• 成功指標／エピソード指標が設定されていること（誤ってゼロ／NaN になっていないこと）、また実行ごとに再現可能であること。
• 環境数／エピソード数がハードウェアに適合していること。大きな num_envs の場合もメモリに収まること。
• 重いジムの依存関係（例：libero、robocasa）がオプションの追加機能の背後に置かれ、遅延インポートされていること。

関連スキル

• physicalai-train-training-a-policy — ベンチマーク対象のチェックポイントを作成する場合に使用します。
• physicalai-train-exporting-and-validating — デプロイ時との同等性を確認するため、エクスポート済みアーティファクトをベンチマークする場合に使用します。