mcpField
P
physicalai-train-exporting-and-validating

physicalai-train-exporting-and-validating

github.com/open-edge-platform开发14680 次安装今天更新
代码仓库

关于 physicalai-train-exporting-and-validating

physicalai-train-exporting-and-validating 是面向 physicalai 策略开发者的模型导出与验证技能，涵盖 Python API 和 CLI 工作流。它强调检查导出产物结构、数值一致性及 Runtime 加载兼容性。

主要功能

  1. 01导出为 ONNX、OpenVINO、Torch 或 ExecuTorch
  2. 02提供 Python API 与 CLI 工作流
  3. 03检查导出产物结构和元数据
  4. 04将结果与 Torch 路径进行数值比对
  5. 05验证 Runtime 加载方式

适用场景

  1. 01为部署导出策略模型
  2. 02确认 API 和 CLI 产物一致
  3. 03排查推理结果与 Torch 的差异
  4. 04检查运行时加载及后端依赖

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/open-edge-platform/physical-ai-studio --skill physicalai-train-exporting-and-validating

安装后在 Claude Code 中输入/physicalai-train-exporting-and-validating确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
executorch.md
export-contract.md
onnx.md
openvino.md
torch.md

详细介绍

导出和验证 Studio 策略

导出功能位于 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 负责加载。

工作流

  1. 确定输入：源策略类（例如 physicalai.policies.ACT）、.ckpt 路径、目标后端，以及该后端预期的 Runtime 加载行为。
    • 完成标准：开始修改代码前，以上四项均已确定。
  2. 选择路径，并确保两种路径保持一致——它们必须生成相同的制品：
    • Python：policy.export(output_dir, backend=ExportBackend.ONNX)。
    • CLI：physicalai export --policy physicalai.policies.ACT --ckpt_path model.ckpt --backend onnx --output_dir ./export。
  3. 修改通用代码前，先阅读后端约束。 查看目标后端的参考文档（references/<backend>.md）。未经逐一检查各后端，不要将修复泛化到所有后端。
  4. 先导出，再与 Torch 策略路径进行数值一致性验证，使用有代表性的输入。数值一致性可以证明正确性。
    • 完成标准：样本输入的最大绝对/相对差异处于该系列的容差范围内，或已了解并记录差异原因。
  5. 根据 references/export-contract.md 验证制品结构和元数据。
    • 完成标准：预期的模型文件和元数据文件均存在，且输入、输出和特征名称与 Runtime 预处理相匹配。
  6. 确认 Runtime 路径。 对于用于部署的制品，验证 Runtime 能否通过扩展名自动检测，或通过 InferenceModel(...) 显式加载该后端。

验证循环

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

# from library/
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 输出进行比较。

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

后端说明

  • onnx / openvino — 面向部署；Runtime 核心随附适配器，因此安装依赖后即可加载制品。
  • torch — 用于开发/调试；只有在安装并记录了匹配的 Runtime 适配器后，才能声明支持部署。
  • executorch — 可选、依赖敏感，面向边缘设备/移动设备；此软件包中的 Runtime 核心不随附适配器。只有存在文档说明的配套发行版时，才将其视为可用。

必需检查

  • 导出目录包含预期的后端模型文件和元数据文件。
  • 元数据中的输入/输出/特征名称与 Runtime 预处理及动作块语义保持一致。
  • Python API 导出和 CLI 导出生成等效的制品结构和元数据。
  • 后端专属依赖采用延迟导入，或通过清晰的安装说明加以保护。
  • Runtime 无法在软件包内加载某个后端，且没有文档说明的配套版本时，不要将该后端添加到面向用户的文档中。
  • CLI 文档（library/docs/how-to/export/）和 Python API 示例保持一致。

参考资料

  • references/export-contract.md — 与 Runtime 共享的制品要求（保持同步；CI 应在两者不一致时失败）。
  • references/onnx.md、references/openvino.md、references/torch.md、references/executorch.md — 各后端的约束。

评论

支持 Markdown