physicalai-runtime-loading-exported-policies

加载已导出的策略

Runtime 通过 src/physicalai/inference/model.py 中的 InferenceModel 加载 Studio 导出目录（或与其结构一致的 Hub 快照）。清单解析位于 src/physicalai/inference/manifest.py；后端在 src/physicalai/inference/adapters/registry.py 中注册（onnx → .onnx，openvino → .xml）。Hub 下载使用 src/physicalai/inference/utils/_hub.py。

工作流

1. 确定产物：本地导出目录或 Hub repo_id、预期后端，以及用户需要的是 select_action 还是 predict_action_chunk。

   • 完成标准：编辑代码前已选定加载路径和 API 入口。

2. 优先尝试自动检测加载（本地）：

   from physicalai.inference import InferenceModel
   model = InferenceModel("./exports/act_policy")
   

   • 完成标准：产物符合已注册的扩展名时，无需显式指定 backend= 即可构造 model。

3. 加载 Hub（适用于已发布的软件包）：

   model = InferenceModel.from_pretrained("OpenVINO/act-fp16-ov", revision="<commit-sha>")
   

   • 完成标准：涉及安全或 CI 时，固定 revision 以确保可复现。

4. 仅在自动检测结果不明确时显式指定后端：

   model = InferenceModel("./exports/act_policy", backend="openvino", device="CPU")
   

5. 根据 references/export-load-contract.md 和后端说明（references/onnx.md、references/openvino.md）验证结构。

   • 完成标准：清单、模型文件和处理器产物均可在导出目录中解析。

6. 不负责机器人计时，执行冒烟推理：

   model.reset()
   action = model.select_action(observation)
   

   • 完成标准：针对有代表性的观测键/形状，单次前向传递成功。对于硬件循环，请交接给 physicalai-runtime-running-policy-on-robot。

验证流程

uv run pytest tests/unit/inference/test_model.py tests/unit/inference/test_manifest.py -q

对于适配器变更，请添加或运行 tests/unit/inference/ 下的针对性测试。

必要检查

• 导出目录包含后端模型文件，并且 manifest.json 符合 docs/reference/manifest-schema.md。
• 元数据中的输入/输出/特征名称与清单中的预处理器一致。
• 可选后端未安装时，应提供清晰的安装指引（onnxruntime、OpenVINO）。
• 除非适配器已在 src/physicalai/inference/adapters/ 中注册，否则不要记录该后端。
• Hub 加载不得记录令牌；生产文档优先使用固定的 revision=。

参考资料

• references/export-load-contract.md — 消费端契约（请与 Studio 导出技能协调）。
• references/onnx.md、references/openvino.md — 适配器约束。