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

在 Notebook、测试、自定义脚本或直接集成该库时使用此方式。

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 — 基准测试配置（configs/benchmark/pusht.yaml、configs/benchmark/libero.yaml），用于选择 Benchmark 类及其设置。
• --output_dir — 默认为 ./results/benchmark。

在 CLI 中覆盖基准测试设置，例如 --benchmark.num_episodes 10 --benchmark.num_envs 8。

输出

• 将 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
   

   • 完成标准：一个回合端到端运行成功，并打印出摘要。
3. 使用预期的回合数和环境数运行完整基准测试。
   • 完成标准：已写入 results.json 和 results.csv，且成功指标已填充。
4. 通过 BenchmarkResults/TaskResult 字段解读结果；使用相同配置与基线检查点进行比较。
5. 当任务表现退步时，录制视频以供定性评审（record_mode: failures）。

添加或更改基准测试

1. 在 benchmark/gyms/ 中继承 Benchmark（参考 PushTBenchmark / LiberoBenchmark）；gym 本身来自 physicalai.gyms（pusht.py、libero.py 等）。
2. 在 library/configs/benchmark/ 中添加匹配的配置。
3. 在 library/tests/unit/benchmark/ 下添加测试。
   • 完成标准：uv run pytest tests/unit/benchmark 通过，且单回合运行成功。

必要检查

• 如果 .ckpt 和导出目录都是受支持的路径，策略必须能从两者运行。
• 对于面向用户的基准测试变更，Python API 路径（Benchmark(...).evaluate(...)）与 CLI 封装器在支持的输入方面必须一致。
• 成功和回合指标均已填充（不会意外为零或 NaN），且多次运行结果可复现。
• 环境数和回合数符合硬件条件；较大的 num_envs 不会超出内存。
• 大型 gym 依赖（如 libero、robocasa）应通过可选 extras 控制，并采用惰性导入。

相关技能

• physicalai-train-training-a-policy — 用于生成待基准测试的检查点。
• physicalai-train-exporting-and-validating — 在基准测试导出的部署用制品时使用，确保部署结果一致。