physicalai-runtime-configuring-inference-pipeline

配置推理流水线

流水线顺序：观测 → 预处理器 → runner → 后处理器 → 动作输出。请参阅 docs/how-to/inference/configure-pre-post-processing.md。

核心代码：

• src/physicalai/inference/component_factory.py — ComponentRegistry、instantiate_component、_MAX_COMPONENT_DEPTH。
• src/physicalai/inference/model.py — 根据清单规范构建处理器链。
• 内置组件位于 preprocessors/ 和 postprocessors/ 下；runner 位于 runners/ 下。

工作流

1. 阅读清单中的相关部分，了解 preprocessors、postprocessors 和 model.runner。

   • 完成标准：你知道规范使用的是 type（注册表中的短名称）还是 class_path。

2. 内置组件优先使用 type，这些组件已在 component_factory 中注册（例如文档中的 normalize/denormalize 模式）。

3. 对于显式类，使用 class_path + init_args：

   preprocessors:
     - class_path: physicalai.inference.preprocessors.StatsNormalizer
       init_args:
         artifact: stats.safetensors
   

   • 完成标准：init_args 中的路径通过 resolve_artifact 相对于导出目录解析。

4. 添加新的内置处理器：

   • 在相应的包中实现 Preprocessor / Postprocessor 子类。
   • 如果需要适用于清单的别名，请在 component_factory 中注册一个简短的 type 名称。
   • 在 tests/unit/inference/preprocessors/ 或 postprocessors/ 下添加单元测试。
   • 完成标准：使用 type 或 class_path 的清单能在精简的 InferenceModel 测试中实例化。

5. 嵌套组件的 init_args 必须保持在 _MAX_COMPONENT_DEPTH 限制内；避免循环规范。

验证流程

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

必要检查

• 处理器顺序与训练/导出语义一致（在 runner 之前执行归一化，在之后执行反归一化）。
• 清单中的资源文件名不得遍历路径（..、绝对路径）。
• 当新公开的处理器对用户可见时，需将其补充到 docs/reference/inference-api.md 或操作指南文档中。
• runner 选择（SinglePass、分块 runner）应与 predict_action_chunk 和 select_action 文档保持一致。

参考资料

• docs/reference/manifest-schema.md
• docs/how-to/inference/use-manifest.md