Initial pi0 minimal validation

2026-07-11 20:04:18 +08:00
commit 4fe0099f3f
18 changed files with 1611 additions and 0 deletions
@@ -0,0 +1,76 @@
+# π0 Minimal Validation
+
+这是一个 **Physical Intelligence π0 风格的最小、可运行过拟合实验**。它用小型视觉语言前缀和 action expert 学习连续动作 chunk，通过 flow matching 从噪声一次生成未来 `16×2` 轨迹。
+
+项目不是官方代码，也不复制官方规模、数据和机器人能力；目标只是验证核心数学与信息流能否端到端训练。
+
+## 最小架构
+
+```text
+图像 + 语言指令 → 小型 VLM prefix
+                         │ blockwise attention
+连续本体/历史 state ─────┤
+noisy action + timestep ─┘
+                         ▼
+                   action expert
+                 │
+                 ▼
+      flow velocity → action chunk
+```
+
+默认从相邻 Alpamayo 项目读取 1 个 PAI 驾驶样本，生成 4 个确定性轻微增强变体，输入 `64×64` 图像，预测未来 16 个 XY 动作点。
+
+## π0 与 π0.5 的关键差异
+
+| 方面 | 本项目对应的 π0 | π0.5 最小复现中的额外能力 |
+|---|---|---|
+| 控制层级 | 语言/视觉条件直接生成连续 action chunk | 先生成高层 subtask，再以 subtask 为条件生成动作 |
+| 动作表示 | flow action expert 输出连续动作 | 可同时有 FAST 风格离散动作 token 和连续 flow 动作 |
+| VLM 输出 | 主要作为条件语义前缀 | 自回归预测 subtask/离散动作 token |
+| 训练目标 | 本实验仅使用 flow velocity MSE | 还可联合文本/动作 token CE |
+
+与 π0 一致，本项目把连续 state 放在 action suffix，而不是像 π0.5 那样先离散成语言 token。
+
+因此，本项目故意不实现 π0.5 的高层 subtask 生成和 VLM 离散轨迹分支。效果图将对比 flow 生成轨迹与真值，而不是三方动作对比。
+
+## 安装与测试
+
+```bash
+cd pi0-minimal-validation
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e '.[dev]'
+pytest -q
+```
+
+`tests/test_flow.py` 验证直线概率路径 `x_t=(1-t)·noise+t·action`、目标速度 `action-noise`、MSE 损失、随机可复现性和 Euler 积分。
+
+## 过拟合训练与效果图
+
+```bash
+pi0mini-train --config configs/overfit.yaml
+pi0mini-infer --checkpoint outputs/overfit/checkpoint.pt
+```
+
+也可用 `python -m pi0mini.train --config configs/overfit.yaml` 运行。默认训练 600 步，推理使用 10 步 Euler flow integration。训练后应生成 checkpoint、loss 历史、逐样本评估 JSON 和 `outputs/overfit/trajectory_comparison.png`。
+
+默认数据源为：
+
+```text
+../../alpamayo/alpamayo-qwen05b-validation/data/processed/overfit_manifest.jsonl
+```
+
+如本地路径不同，修改 `configs/overfit.yaml` 中的 `data.source_manifest`。
+
+## 限制
+
+- 小型自定义编码器代替预训练 PaliGemma，参数规模与官方模型不可比。
+- 仅对几个增强样本做记忆性训练，loss 下降不代表泛化、鲁棒性或安全性。
+- 二维驾驶轨迹替代多机器人、多相机、高维关节动作和异构数据联合训练。
+- 固定步长 Euler sampler 只用于演示，没有实时控制、碰撞检查、约束或故障降级。
+- 严禁将输出用于真实车辆、机械臂或其他会产生物理影响的设备。
+
+## 成功标准
+
+成功只表示：该缩小实现的视觉/语言条件、blockwise action expert 和 flow matching 能够端到端反向传播，并记住极小训练集。它不证明与官方 π0 数值等价。