physicalai-train-training-a-policy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Training a policy (library)

训练策略（库端）

Training uses

physicalai.train.Trainer

(

library/src/physicalai/train/trainer.py

, a

lightning.Trainer

subclass) with a

Policy

and a

DataModule

. The library deliberately supports two equal entry points:

CLI —

physicalai fit

(and

validate

test

predict

): jsonargparse YAML under

library/configs/

, overrides on the command line; checkpoints under

experiments/{name}/version_N/

by default. See

library/docs/how-to/training/cli.md

Python API — construct

Policy

LeRobotDataModule

(or another datamodule), and

Trainer

, then

trainer.fit(model=policy, datamodule=datamodule)

(and

validate

test

predict

with a checkpoint as needed). See

library/docs/getting-started/quickstart.md

and

library/docs/explanation/trainer/README.md

The CLI subcommands and the Python API share the same objects; YAML

class_path

init_args

should match what you would wire in code.

The four CLI subcommands share the same

--model

--data

--trainer.*

shape (see

cli/_dispatch.py

);

validate

test

predict

additionally take

--ckpt_path

. When a task is about library behavior rather than shell usage, prefer the Python API path first and then verify CLI parity if the change is user-facing.

训练使用

physicalai.train.Trainer

（

library/src/physicalai/train/trainer.py

，

lightning.Trainer

的子类），搭配

Policy

和

DataModule

。该库特意支持两种同等的入口方式：

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

应与代码中的组装逻辑一致。

四个CLI子命令共用相同的

--model

--data

--trainer.*

参数结构（详见

cli/_dispatch.py

）；

validate

test

predict

还额外支持

--ckpt_path

参数。当任务涉及库行为而非Shell使用时，优先采用Python API路径，若变更面向用户，则需验证CLI与API的一致性。

Anatomy of a config

配置文件结构

A config wires three pieces via

class_path

init_args

```
model
```
— a
```
Policy
```
subclass (e.g.
```
physicalai.policies.ACT
```
).

data

— a

DataModule

, usually

physicalai.data.lerobot.LeRobotDataModule

with a

repo_id

(e.g.

lerobot/pusht

```
trainer
```
— Lightning args (
```
max_epochs
```
,
```
accelerator
```
,
```
devices
```
, callbacks…).

Configs live in

library/configs/physicalai/

(first-party:

act.yaml

pi0.yaml

pi05.yaml

groot.yaml

smolvla.yaml

) and

library/configs/lerobot/

(LeRobot-wrapped). Compose with

__base__

and override any field on the CLI (

--trainer.max_epochs 200 --data.train_batch_size 64

配置文件通过

class_path

init_args

组装三部分内容：

```
model
```
—
```
Policy
```
的子类（例如
```
physicalai.policies.ACT
```
）。

data

— 数据模块，通常是带有

repo_id

的

physicalai.data.lerobot.LeRobotDataModule

（例如

lerobot/pusht

）。

```
trainer
```
— Lightning参数（
```
max_epochs
```
、
```
accelerator
```
、
```
devices
```
、回调函数等）。

配置文件存储在

library/configs/physicalai/

（官方配置：

act.yaml

、

pi0.yaml

、

pi05.yaml

、

groot.yaml

、

smolvla.yaml

）和

library/configs/lerobot/

（LeRobot封装配置）中。可通过

__base__

组合配置，并在CLI中覆盖任意字段（例如

--trainer.max_epochs 200 --data.train_batch_size 64

）。

Python API workflow

Python API工作流

Use this path when the user asks for code, notebooks, tests, direct library integration, or changes to

Trainer

Policy

, or datamodules.

python

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)

Construct the same objects the CLI would instantiate: a
```
Policy
```
, a
```
DataModule
```
, and
```
Trainer
```
.
- Done when: construction works without relying on jsonargparse YAML.
Smoke-test the API wiring with
```
Trainer(fast_dev_run=True)
```
.
- Done when: one train + one val batch complete without shape or feature errors.
Validate / test / predict from Python with the corresponding
```
Trainer
```
method and
```
ckpt_path
```
when needed.
- Done when: the API call and the equivalent CLI command agree on checkpoint/config behavior.

当用户需要代码、Notebook、测试、直接库集成，或对

Trainer

、

Policy

、数据模块进行修改时，采用此路径。

python

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)

构造与CLI实例化相同的对象：
```
Policy
```
、
```
DataModule
```
和
```
Trainer
```
。
- 完成标志：无需依赖jsonargparse YAML即可成功构造对象。
通过
Trainer(fast_dev_run=True)
进行API组装冒烟测试。
- 完成标志：成功完成一个训练批次和一个验证批次，无形状或特征错误。
从Python调用验证/测试/预测：使用对应的
```
Trainer
```
方法，必要时传入
```
ckpt_path
```
。
- 完成标志：API调用与等效CLI命令在检查点/配置行为上保持一致。

CLI workflow

CLI工作流

Use this path when the user asks for terminal commands, docs under

library/docs/how-to/

, YAML configs, reproducible experiments, or entry-point behavior.

Start from an existing config matching your policy family; copy it rather than writing from scratch.
- Done when:
```
physicalai fit --config <your.yaml> --print_config
```
  renders the fully-resolved config with no errors.
Smoke-test the wiring before a real run:
bash
```
physicalai fit --config configs/physicalai/<name>.yaml --trainer.fast_dev_run=true
```
- Done when: one train + one val batch complete without shape or config errors.

Run training, overriding on the CLI as needed:

bash

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

Done when: checkpoints appear under
```
experiments/{name}/version_N/
```
.

Validate / test / predict from a checkpoint:

bash

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

Iterate on metrics, not just loss — confirm the val metric relevant to the task moves, and record the config + checkpoint that produced it.

当用户需要终端命令、

library/docs/how-to/

下的文档、YAML配置、可复现实验或入口点行为时，采用此路径。

从匹配策略类型的现有配置开始：复制现有配置而非从头编写。
- 完成标志：
```
physicalai fit --config <your.yaml> --print_config
```
  可渲染出完全解析的配置且无错误。
正式运行前进行组装冒烟测试：
bash
```
physicalai fit --config configs/physicalai/<name>.yaml --trainer.fast_dev_run=true
```
- 完成标志：成功完成一个训练批次和一个验证批次，无形状或配置错误。

运行训练，必要时在CLI中覆盖配置：

bash

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

完成标志：检查点出现在
```
experiments/{name}/version_N/
```
目录下。

从检查点进行验证/测试/预测：

bash

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

针对指标而非仅损失进行迭代：确认与任务相关的验证指标有所变化，并记录生成该指标的配置和检查点。

Debugging a run

训练运行调试

API: construct
```
Policy
```
,
```
DataModule
```
, and
```
Trainer
```
directly in a short script or test to isolate whether failure is in object construction, dataloading, or CLI parsing.
```
--trainer.fast_dev_run=true
```
— one batch each stage; the first thing to try on any failure.
```
--print_config
```
— see the exact resolved config jsonargparse built.
Shape/feature mismatches usually mean the datamodule's
```
Feature
```
names or action dim disagree with the policy — cross-check against the
```
physicalai-train-adding-a-policy
```
skill.
Dataset download stalls: the run is pulling a LeRobot
```
repo_id
```
; see the
```
physicalai-train-working-with-datasets
```
skill.

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
```
技能。

Required checks

必要检查项

Config resolves (
```
--print_config
```
) and
```
fast_dev_run
```
passes before any long run.
The equivalent Python API construction path passes for library-facing changes.
```
accelerator
```
/
```
devices
```
match the installed backend extra (
```
xpu
```
/
```
cuda
```
/
```
cpu
```
).
New or renamed config fields stay consistent with the policy's
```
Config
```
class.
Doc code blocks that show training commands still pass
```
tests/test_docs.py
```
.

正式长时运行前，需确保配置可解析（
```
--print_config
```
）且
```
fast_dev_run
```
测试通过。
针对库端变更，需确保等效Python API构造路径可通过测试。
```
accelerator
```
/
```
devices
```
需与已安装的后端扩展（
```
xpu
```
/
```
cuda
```
/
```
cpu
```
）匹配。
新增或重命名的配置字段需与策略的
```
Config
```
类保持一致。
文档中展示训练命令的代码块需通过
```
tests/test_docs.py
```
测试。

Verify

验证步骤

bash

undefined

bash

undefined

from library/

进入library/目录

physicalai fit --config configs/physicalai/<name>.yaml --trainer.fast_dev_run=true uv run pytest tests/unit/train


For API-facing changes, add or run an equivalent Python smoke test (not a shell heredoc) that constructs `Policy`, `DataModule`, and `Trainer` directly and calls `trainer.fit(...)`.

physicalai fit --config configs/physicalai/<name>.yaml --trainer.fast_dev_run=true uv run pytest tests/unit/train


针对API层面的变更，需添加或运行等效的Python冒烟测试（而非Shell heredoc），直接构造`Policy`、`DataModule`和`Trainer`并调用`trainer.fit(...)`。

physicalai-train-training-a-policy

Original

Translation

Training a policy (library)

训练策略（库端）

Anatomy of a config

配置文件结构

Python API workflow

Python API工作流

CLI workflow

CLI工作流

Debugging a run

训练运行调试

Required checks

必要检查项

Verify

验证步骤

from library/

进入library/目录

Related skills

相关技能