physicalai-train-exporting-and-validating

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Exporting and Validating Studio Policies

导出并验证Studio策略

Export lives in

library/src/physicalai/export/

backends.py

(the

ExportBackend

enum —

onnx

openvino

torch

executorch

— plus per-backend parameter classes) and

mixin_policy.py

(

ExportablePolicyMixin

, which gives policies

export(output_dir, backend=...)

). The Python API is primary library behavior; the CLI entry

library/src/physicalai/cli/export.py

must preserve the same artifact contract. Studio owns export; Runtime owns loading.

导出功能位于

library/src/physicalai/export/

目录下：包含

backends.py

（定义了

ExportBackend

枚举——

onnx

、

openvino

、

torch

、

executorch

——以及各后端对应的参数类）和

mixin_policy.py

（

ExportablePolicyMixin

，为策略提供

export(output_dir, backend=...)

方法）。Python API是核心库的主要功能；CLI入口

library/src/physicalai/cli/export.py

必须遵循相同的产物协议。Studio负责导出，Runtime负责加载。

Workflow

工作流程

Identify the inputs: source policy class (e.g.
```
physicalai.policies.ACT
```
),
```
.ckpt
```
path, target backend, and the Runtime loader behavior expected for that backend.
- Done when: all four are pinned before touching code.

Pick the route and keep both consistent — they must produce the same artifact:

Python:

policy.export(output_dir, backend=ExportBackend.ONNX)

CLI:

physicalai export --policy physicalai.policies.ACT --ckpt_path model.ckpt --backend onnx --output_dir ./export

Read backend constraints before editing generic code. See the backend reference for the target (
```
references/<backend>.md
```
). Do not generalize a fix across backends without checking each.
Export, then validate numerical parity against the Torch policy path on representative inputs. Parity proves correctness.
- Done when: max abs/rel diff on sample inputs is within the family's tolerance, or the divergence is understood and documented.
Validate artifact structure and metadata against
```
references/export-contract.md
```
.
- Done when: the expected model file and metadata files exist, and input/output/feature names match Runtime preprocessing.
Confirm the Runtime path. For deployment-bound artifacts, verify Runtime can auto-detect (by extension) or explicitly load the backend via
```
InferenceModel(...)
```
.

确定输入项：源策略类（例如
```
physicalai.policies.ACT
```
）、
```
.ckpt
```
路径、目标后端，以及该后端对应的Runtime加载器预期行为。
- 完成标志：在修改代码前，上述四项均已明确。

选择执行方式并保持两种方式一致——它们必须生成相同的产物：

Python方式：

policy.export(output_dir, backend=ExportBackend.ONNX)

。

CLI方式：

physicalai export --policy physicalai.policies.ACT --ckpt_path model.ckpt --backend onnx --output_dir ./export

。

在编辑通用代码前，先阅读后端约束。查看目标后端的参考文档（
```
references/<backend>.md
```
）。未经逐一检查，不要跨后端推广修复方案。
导出后，针对代表性输入验证与Torch策略路径的数值一致性。一致性可证明正确性。
- 完成标志：样本输入的最大绝对/相对差异在允许范围内，或差异已被理解并记录在案。
根据
references/export-contract.md
验证产物结构和元数据。
- 完成标志：存在预期的模型文件和元数据文件，且输入/输出/特征名称与Runtime预处理匹配。
确认Runtime加载路径。对于用于部署的产物，验证Runtime是否可以通过扩展名自动检测，或通过
```
InferenceModel(...)
```
显式加载该后端。

Validation loop

验证循环

Run export → validate → fix → repeat until both parity and structure pass:

bash

undefined

执行导出→验证→修复→重复，直到一致性和结构检查均通过：

bash

undefined

from library/

physicalai export --policy <ClassPath> --ckpt_path <model.ckpt> --backend <backend> --output_dir ./export uv run pytest tests/unit/export -k <backend>


For API-facing changes, add or run an equivalent Python script/test that loads the checkpoint, calls `policy.export("./export-api", backend=ExportBackend.<BACKEND>)`, and compares artifact metadata with the CLI output.

Treat **parity** (correctness) and **latency/warmup** (deployment viability) as separate checks; passing one does not imply the other.

physicalai export --policy <ClassPath> --ckpt_path <model.ckpt> --backend <backend> --output_dir ./export uv run pytest tests/unit/export -k <backend>


对于面向API的变更，添加或运行等效的Python脚本/测试：加载检查点，调用`policy.export("./export-api", backend=ExportBackend.<BACKEND>)`，并将产物元数据与CLI输出进行比较。

将**一致性**（正确性）和**延迟/预热**（部署可行性）视为独立检查；通过其中一项并不意味着另一项也通过。

Backend notes

后端说明

onnx / openvino — deployment-oriented; Runtime core ships adapters, so artifacts load when deps are installed.
torch — development/debugging; only claim deployment support when a matching Runtime adapter is installed and documented.
executorch — optional, dependency-sensitive, edge/mobile; Runtime core ships no adapter in this package. Treat as available only with a documented companion distribution.

onnx / openvino — 面向部署；Runtime核心包含适配器，因此在安装依赖后即可加载产物。
torch — 用于开发/调试；仅当匹配的Runtime适配器已安装并记录在案时，才声称支持部署。
executorch — 可选，依赖敏感，面向边缘/移动设备；本包中的Runtime核心不包含适配器。仅在有文档记录的配套发行版中才视为可用。

Required checks

必查项

Export directory contains the expected backend model file and metadata files.
Metadata names inputs/outputs/features consistently with Runtime preprocessing and action-chunk semantics.
Python API export and CLI export produce equivalent artifact structure and metadata.
Backend-specific dependencies are imported lazily or guarded with clear install guidance.
Do not add a backend to user-facing docs unless Runtime can load it in-package or via a documented companion.
CLI docs (
```
library/docs/how-to/export/
```
) and Python API examples stay consistent.

导出目录包含预期的后端模型文件以及元数据文件。
元数据中的输入/输出/特征名称与Runtime预处理和动作块语义保持一致。
Python API导出和CLI导出生成的产物结构和元数据完全等效。
后端特定依赖采用延迟导入方式，或附带清晰的安装指引。
除非Runtime可以在包内或通过文档记录的配套组件加载该后端，否则不要在面向用户的文档中添加该后端。
CLI文档（
```
library/docs/how-to/export/
```
）和Python API示例保持一致。

References

参考文档

```
references/export-contract.md
```
— artifact requirements shared with Runtime (keep synchronized; CI should fail on divergence).

references/onnx.md

references/openvino.md

references/torch.md

references/executorch.md

— per-backend constraints.

```
references/export-contract.md
```
— 与Runtime共享的产物要求（需保持同步；CI应在出现差异时失败）。

references/onnx.md

、

references/openvino.md

、

references/torch.md

、

references/executorch.md

— 各后端的约束条件。