mcpField
P
physicalai-train-adding-a-policy

physicalai-train-adding-a-policy

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

关于 physicalai-train-adding-a-policy

用于指导在 PhysicalAI 中新增策略系列的开发技能，涵盖实现、注册、测试和文档更新。

主要功能

  1. 01三文件策略结构
  2. 02训练与推理接口
  3. 03策略 API 和 CLI 注册
  4. 04配置与形状验证
  5. 05测试和文档检查清单

适用场景

  1. 01实现新的 PhysicalAI 策略系列
  2. 02检查动作与观测张量形状
  3. 03通过 CLI 提供策略

安装

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

$npx skills add https://github.com/open-edge-platform/physical-ai-studio --skill physicalai-train-adding-a-policy

安装后在 Claude Code 中输入/physicalai-train-adding-a-policy确认已加载。

附带文件references/base-classes.md

详细介绍

添加 Studio Policy

Policy 存放在 library/src/physicalai/policies/<name>/ 中。每个系列都是一个面向 Lightning 的 Policy，封装一个 torch.nn.Module Model，并拆分为三个文件。基类位于 policies/base/（policy.py 中的 Policy、model.py 中的 Model）；共享的 Config / FromConfig 类型来自 Runtime（physicalai.config）——请参阅 Runtime 文档 use-from-config 和 configuration。

工作流

  1. 先阅读相邻系列。 研究 policies/pi05/（当前参考实现）：config.py（Pi05Config(Config)）、model.py（Pi05Model(Model)）、policy.py（Pi05(ExportablePolicyMixin, Policy)）、preprocessor.py，以及架构所需的其他模块（例如 pi_gemma.py）。对于有意保持精简的系列，policies/act/ 是一个更小的三文件布局，不包含 VLM 栈。

    • 完成标准：能够说出每个新文件对应仿照哪个现有文件。

  2. 在 policies/<name>/ 中创建三个文件：

    • config.py — <Name>Config(Config)，所有超参数均为带类型的字段。
    • model.py — <Name>Model(Model)，仅包含纯 torch.nn.Module 逻辑。
    • policy.py — <Name>(Policy)（仅在实现导出时添加 ExportablePolicyMixin）。
    • 完成标准：from physicalai.policies.<name> import <Name>, <Name>Config, <Name>Model 可以正常导入。

  3. 实现训练和推理共用的策略接口，通过基类 Policy 提供：

    • forward(...) — 训练路径；返回值须与 training_step 兼容。
    • predict_action_chunk(...) — 推理路径；返回具有已配置动作时域的张量。
    • select_action(...) — 除非有充分理由采用专用流程，否则使用基类的动作队列行为。
    • 完成标准：合成批次的形状符合以下检查。

  4. 注册该系列，以便 API 和 CLI 用户都能找到它：

    • 在 policies/__init__.py 中添加导出（__all__ 和导入，例如 <Name>、<Name>Config、<Name>Model）。
    • 在 policies/__init__.py 的 get_physicalai_policy_class(...) / get_policy(...) 分发逻辑中添加小写名称。
    • 完成标准：from physicalai.policies import <Name>, get_policy 可正常使用，get_policy("<name>") 返回一个实例，且 --model physicalai.policies.<Name> 可以解析。

  5. 添加 CLI 配置前，先验证直接 API 构造：

    from physicalai.policies import get_policy

policy = get_policy("<name>")
    • 完成标准：直接构造、配置往返，以及合成 forward(...) / predict_action_chunk(...) 形状检查均通过。

  6. 当该策略面向 CLI 用户时，在 library/configs/physicalai/<name>.yaml 中添加训练配置。 配置 model.class_path、data.class_path（通常为 physicalai.data.lerobot.LeRobotDataModule）以及 trainer.*。参照 configs/physicalai/pi05.yaml。

    • 完成标准：physicalai fit --config configs/physicalai/<name>.yaml --trainer.fast_dev_run=true 可完成一个步骤。

  7. 仅在准备就绪时接入导出。 添加 ExportablePolicyMixin 和有效的样例输入，然后遵循 physicalai-train-exporting-and-validating 技能。如果有意不支持导出，请在策略文档字符串中明确说明。

  8. 添加测试，放在 library/tests/unit/policies/ 下现有策略测试旁边：至少包含一个构造/配置路径测试，以及一个形状验证测试。

    • 完成标准：uv run pytest tests/unit/policies -k <name> 通过。

  9. 更新文档（如果该策略面向用户）：更新 library/docs/explanation/policy/ 以及相关配置/API 示例。

必须通过的检查

逐项检查以下内容（不能只看一眼觉得“没问题”）：

  • Action 形状语义 — batch、时域/分块长度和 action 维度正确，且与该系列的惯例保持一致。
  • Observation 特征 — 特征名称与数据集/配置约定一致（data/observation.py：Feature、FeatureType）。
  • API 构建路径 — 导入、get_policy(...)、直接使用构造函数，以及合成形状检查均能通过，且不涉及 CLI。
  • 配置路径 — 当策略可通过 CLI 使用时，能通过 physicalai fit 使用的 jsonargparse CLI 路径（class_path/init_args）完成构建。
  • 重量级依赖 — 在 library/pyproject.toml 中将大型系列置于可选 extra 后，并采用延迟导入，与 pi05/pi0/groot/smolvla 的方式一致。
  • 不允许静默更改契约 — 未经协调导出/Runtime，不得更改 action 维度、特征名称或预处理方式。

验证

在 library/ 中运行：

uv run pytest tests/unit/policies -k <name>
physicalai fit --config configs/physicalai/<name>.yaml --trainer.fast_dev_run=true
prek run --all-files library/

参考资料

  • references/base-classes.md — Policy/Model 契约及文件拆分要求。

评论

支持 Markdown