physicalai-train-training-a-policy

训练策略（库）

训练使用 physicalai.train.Trainer（library/src/physicalai/train/trainer.py，lightning.Trainer 的子类），并搭配一个 Policy 和一个 DataModule。该库刻意支持两种同等的入口：

• 命令行界面 — 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。

命令行子命令和 Python API 共用相同的对象；YAML 中的 class_path / init_args 应与代码中的配置一致。

四个命令行子命令共用相同的 --model / --data / --trainer.* 参数结构（参见 cli/_dispatch.py）；validate / test / predict 还需指定 --ckpt_path。如果任务关注的是库的行为，而非命令行用法，请优先采用 Python API 路径，然后在面向用户的改动中验证命令行行为是否一致。

配置剖析

配置通过 class_path / init_args 连接以下三个部分：

• 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__ 组合配置，并可在命令行中覆盖任意字段（--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. 构建与命令行将实例化的相同对象：Policy、DataModule 和 Trainer。
   • 完成标准：无需依赖 jsonargparse YAML 即可完成构建。
2. 对 API 连线进行冒烟测试，使用 Trainer(fast_dev_run=True)。
   • 完成标准：一个训练批次和一个验证批次均能完成，且没有形状或特征错误。
3. 从 Python 执行验证 / 测试 / 预测，使用对应的 Trainer 方法，并在需要时传入 ckpt_path。
   • 完成标准：API 调用与等效的命令行命令在检查点和配置行为上保持一致。

命令行工作流

当用户需要终端命令、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
   

   • 完成标准：一个训练批次和一个验证批次均能完成，且没有形状或配置错误。
3. 运行训练，并根据需要在命令行中覆盖参数：

   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 — 每个阶段运行一个批次；遇到任何故障时，首先尝试此项。
• --print_config — 查看 jsonargparse 构建的确切解析后配置。
• 形状或特征不匹配通常意味着数据模块的 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 的更改，添加或运行一个等效的 Python 冒烟测试（而非 shell heredoc），直接构造 Policy、DataModule 和 Trainer，并调用 trainer.fit(...)。

相关技能

• physicalai-train-adding-a-policy — 模型本身需要更改时使用。
• physicalai-train-working-with-datasets — 用于配置中的 data 部分。
• physicalai-train-benchmarking-a-policy — 在 gym 中评估训练好的检查点。