# π0.7 Minimal Validation

这是一个面向**结构验证和小样本过拟合**的 π0.7-style 教学项目。它在前面的
π0.6/RECAP 最小实验之上，重点验证一条可解释的 steerable policy 链路：利用
短时历史形成 memory，在高层预测视觉 subgoal，通过可独立缺省的 policy
metadata 控制动作风格，并在存在控制延迟时用 RTC 对齐动作 chunk。

本项目不是 Physical Intelligence 官方实现，也不能用于真实车辆或机器人控制。

## 公开资料边界

截至本项目实现时，作者没有在 Physical Intelligence 官方网站、公开论文索引或
`openpi` 仓库中找到可核验的 π0.7 原始论文、官方训练源码、checkpoint 或完整
model card。因此这里不能声称“逐层复现论文”，也不会虚构官方模块尺寸、损失、
数据配方或实验数字。

本仓库所说的 **paper-faithful toy** 有严格边界：若 π0.7 的公开描述强调 memory、
goal generation、high-level control、steerable metadata、CFG 和 real-time
chunking，本项目保留这些模块的输入输出关系与必要消融；所有未公开细节都使用
最小、明确标注且有测试的本地替代。`TinyMEMEncoder`、`TinyGoalGenerator`、
`HighLevelPolicy` 和 `Pi07Mini` 都是本仓库命名，不代表官方内部类名。

若后续公开原始论文或源码，应重新审计本项目，而不是把当前实现当成事实来源。

## 模型阶段与输入输出

| 阶段 | 输入 | 模块 | 输出 | 训练或验证目标 |
|---|---|---|---|---|
| 1. 历史构造 | 当前图像、过去 XY；不接受 future | deterministic history proxy | `6` 帧 oldest-to-newest 图像、历史状态、共享当前状态的 ambiguous history pair | 检查无未来轨迹泄漏 |
| 2. Temporal memory | 历史图像与历史状态 | `TinyMEMEncoder` | memory tokens / pooled memory embedding | 区分当前状态相同、过去路径不同的样本 |
| 3. Goal generation | 当前 observation、memory、任务文本 | `TinyGoalGenerator` | endpoint heatmap / subgoal XY | 只监督 future endpoint，不把完整真值轨迹输入 policy |
| 4. High-level policy | observation、memory、任务与可见 metadata | `HighLevelPolicy` | high-level context、goal/metadata logits | goal loss 与 high-level classification loss |
| 5. Steerable flow policy | high-level context、预测 goal、metadata、noisy action、flow time | `Pi07Mini` low-level action expert | 连续 action vector field `[16,2]` | flow-matching loss |
| 6. RTC alignment | action chunk、随机 delay `d∈[0,12]`、已执行 action prefix | real-time chunking target alignment | 从 `action[d]` 开始的 target 与有效位置 mask | 仅在有效位置计算 masked flow loss |
| 7. CFG inference | 同一 observation 的 conditional 与 metadata-omitted 两次前向 | classifier-free guidance | guided action chunk | 与普通 conditional、unconditional 和真值同图比较 |
| 8. 轨迹恢复 | normalized action deltas、历史终点、训练统计 | denormalize + cumulative sum | 未来 XY 轨迹 | 轨迹 MSE 与可视化，不等同安全指标 |

核心信息流：

```text
history frames + history states
              ↓
       TinyMEMEncoder ───────────────┐
                                     │
current image + task ────────────────┼→ TinyGoalGenerator → predicted subgoal
                                     │
optional speed/quality/mistake/control metadata
                                     ↓
                              HighLevelPolicy
                                     ↓
noisy action + flow time + RTC prefix → Pi07Mini action expert
                                     ↓
                          continuous action chunk
```

## 重点结构

### 1. MEM：短时历史而非单帧

PAI 的极小 manifest 只有一张相机图像，本项目依据已观测的过去 XY 对该图像做
确定性的微小平移和曝光变化，构造短时视觉 history proxy。它不是实际多帧视频，
只能验证 temporal memory 的接口。

`ambiguous_history_pair` 刻意构造两个“当前状态相同、历史路径不同”的序列。
完整模型应比 `no_history` 消融更能区分它们。这里的 MEM 仅表示本仓库的 temporal
memory encoder；在官方资料缺失时，不推断该缩写的官方全称。

### 2. Goal generator：只用 endpoint 监督

训练目标是 future trajectory 的最后一个 XY endpoint，经高斯渲染得到 heatmap。
API 只接受 endpoint，不接受整条 future trajectory，从而避免把低层动作答案作为
视觉 subgoal 条件泄漏给 action expert。推理和最终评估必须使用**模型预测的 goal**；
真值 heatmap 只可用于训练监督和 oracle 诊断。

### 3. High-level 与 steerable metadata

最小数据由一条 expert demonstration 确定性构造五种 policy mode：

| Mode | speed | quality | mistake | control |
|---|---|---|---|---|
| expert | normal | expert | none | human |
| fast | fast | good | none | autonomous |
| slow | slow | good | none | autonomous |
| understeer | normal | poor | understeer | autonomous |
| stop | slow | poor | stop | autonomous |

训练时 `speed`、`quality`、`mistake`、`control` 独立做 metadata dropout，任务文本
始终保留。这既检验属性是否能单独控制行为，也提供 CFG 所需的 omitted condition。
这些合成标签不是人类偏好数据，也不能证明真实世界可控性。

### 4. RTC：控制延迟下的 action chunk 对齐

若推理耗时等价于已经执行 `d` 个 action，模型不应再次预测旧 chunk 的开头：

```text
original target: a0 a1 ... a15
delay d=4:       a4 a5 ... a15 PAD PAD PAD PAD
valid mask:       1  1 ...   1   0   0   0   0
```

默认随机采样 `d=0..12`，返回已执行 prefix，并对 padding tail 屏蔽损失。RTC 在
这里表示训练/评估时的离线对齐机制，不包含实际控制器、异步推理线程或硬实时保证。

### 5. CFG

推理时在相同 observation、goal、memory 和初始噪声下计算 metadata conditional
与 metadata-omitted 预测：

```text
v_cfg = v_uncond + beta * (v_cond - v_uncond)
```

默认 `beta=2.0`。必须同时报告 `beta=0,1,2`，因为高 guidance 可能放大过拟合、
产生分布外动作，不能只展示最好看的曲线。

## 数据与防泄漏约束

- history proxy 和 ambiguous pair 只依赖当前图像与过去状态；
- subgoal condition 只使用 endpoint target，不能编码完整 action chunk；
- flow expert 训练时不能读取 teacher-forced 真值动作 token；
- 所有模型对比使用同一 initial noise、归一化统计和 RTC delay；
- 数据增强的随机数由 sample index 和 seed 决定，保证复现实验；
- 仓库不包含或重新分发原始 PAI 数据。

## 安装

```bash
cd pi07-minimal-validation
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e '.[dev]'
```

默认数据路径：

```text
../../alpamayo/alpamayo-qwen05b-validation/data/processed/overfit_manifest.jsonl
```

若路径不同，请修改 `configs/overfit.yaml` 的 `data.source_manifest`。

## 测试

```bash
pytest -q
```

测试至少应覆盖：history/goal 无 future 泄漏、ambiguous history、metadata 独立
dropout、五类策略构造、action normalization、flow matching、RTC shift/mask、
MEM/goal/high-level/policy 前向形状、CFG 公式和 checkpoint reload。

## 三阶段过拟合训练

```bash
pi07mini-train --config configs/overfit.yaml
```

或：

```bash
python -m pi07mini.train --config configs/overfit.yaml
```

| 阶段 | 默认步数 | 更新内容 | 目的 |
|---|---:|---|---|
| goal | 300 | MEM + goal generator | 先证明 history-conditioned endpoint heatmap 可被记忆 |
| high-level | 200 | MEM + high-level policy | 记住五类 metadata/goal 高层条件 |
| policy | 900 | 完整 `Pi07Mini` | 联合训练 metadata dropout、flow action 与 RTC masked target |

默认预算面向极小样本过拟合，不代表官方训练 schedule。训练完成后应保存实际
训练会生成 loss history、checkpoint、evaluation JSON 和消融效果图。

## 当前最小实验结果

固定相同 flow 初始噪声时，高层策略预测 `steer_left`。轨迹 MSE 如下：

| 条件 | MSE |
|---|---:|
| Full context + oracle endpoint goal | 0.470 |
| Full context + generated goal | 0.491 |
| No metadata | 2.458 |
| No goal | 4.043 |
| No history | 2.159 |
| Metadata CFG beta=2 | 10.576 |

完整上下文明显优于移除 metadata、goal 或 history 的消融。TinyGoalGenerator 的像素级结果仍较粗糙；生成 goal 在当前 policy 上可提供有效条件，但不能视为真实未来图像生成能力。较强 CFG 在此极小数据实验中造成退化。

## 推理、画图与必要消融

```bash
pi07mini-infer --checkpoint outputs/overfit/checkpoint.pt
```

或：

```bash
python -m pi07mini.infer --checkpoint outputs/overfit/checkpoint.pt
```

最终展示不能只有 full model。相同样本、noise seed 和 RTC delay 下至少比较：

| 实验 | 移除内容 | 要回答的问题 |
|---|---|---|
| `full` | 无 | 完整链路能否过拟合并重建对应 mode 的轨迹？ |
| `no_metadata` | speed/quality/mistake/control | policy mode 差异是否真的来自 steerable condition？ |
| `no_goal` | predicted goal | endpoint condition 是否改善几何方向和终点？ |
| `no_history` | MEM history，只保留当前 observation | temporal history 是否解决相同当前状态的歧义？ |

还必须提供：

- predicted goal heatmap 与 ground-truth endpoint heatmap；
- expert/fast/slow/understeer/stop 的真值与预测轨迹；
- CFG `beta=0,1,2`；
- RTC delay `0,4,8,12` 的 masked trajectory error；
- 每个 ablation 的轨迹 MSE，以及 goal endpoint error；
- full/no-history 在 ambiguous history pair 上的差异指标。

小样本过拟合中，某个消融偶然更好并不证明模块无效；应展示全部固定设置结果，
不调换 noise seed 或只挑选最佳样本。

## 安全限制

- 严禁连接车辆、机械臂、移动机器人或任何会造成物理影响的执行器。
- 合成 fast/understeer/stop 轨迹只用于离线可控性探针，不是安全驾驶示范。
- endpoint 命中、轨迹 MSE 下降、loss 收敛和 CFG 改善都不代表闭环稳定性。
- history proxy 不是视频；RTC target shift 也不是硬实时系统验证。
- metadata 可控性可能放大危险属性，尤其是 `fast`、`poor` 或高 CFG beta。
- 真实部署至少需要真实时序传感器、闭环 rollout、OOD 与延迟压力测试、动力学
  约束、碰撞检查、冗余控制器、故障降级、急停和人工监督。
- PyTorch checkpoint 使用 pickle 机制，只加载可信来源的文件。

## 能得出的结论

成功实验最多能说明：本仓库定义的 memory、endpoint goal、high-level metadata、
conditional flow、CFG 与 RTC 对齐可以在几个合成 PAI trajectory mode 上形成一条
可训练、可消融的最小链路。它不能证明与未公开 π0.7 的结构或数值等价，不能
证明 emergent capability，也不能支持任何真实世界安全或泛化主张。

## 可核验背景资料

- [Physical Intelligence](https://www.pi.website/)
- [Physical-Intelligence/openpi](https://github.com/Physical-Intelligence/openpi)

在原始 π0.7 论文或官方源码可核验前，本 README 不提供推测性的论文链接、arXiv
编号或官方结果表。