# π0.7 Minimal Validation

这是一个面向**结构验证和极小样本过拟合**的 π0.7 最小实现。目标不是复现参数量、预训练权重或论文指标，而是保留官方论文中的关键模块、模态顺序、注意力信息流和训练/推理闭环。

实现依据：

- **π0.7: a Steerable Generalist Robotic Foundation Model with Emergent Capabilities**；
- **MEM: Multi-Scale Embodied Memory for Vision Language Action Models**；
- **Training-Time Action Conditioning for Efficient Real-Time Chunking**；
- π0.5/π0.6 的 FAST、flow action expert 与 Knowledge Insulation 结构。

## 最小结构

```text
history images --MEM video encoder--┐
history/current states -------------> observation block
                                     │
task + predicted subtask + metadata -> causal text prompt
                                     │
generated future observation -------> image-goal block
                                     │
FAST action tokens -----------------> causal discrete action branch
                                     │
clean RTC prefix + noisy postfix ---> flow action expert
```

官方 Figure 19 对应的 prefix 顺序被明确实现为：

```text
memory observations -> causal text -> bidirectional image goals -> causal FAST
```

- observation 只能读取 observation；
- text 读取 observation，并在 text 内因果注意；
- image goals 读取 observation、完整 text 和 goal block；
- FAST 读取此前全部上下文，并在 FAST 内因果注意；
- flow actions 读取 observation、text、image goals 和彼此，但不能读取 teacher-forced FAST；
- flow loss 通过 Knowledge Insulation 不更新 VLM/MEM stream。

## High-level 到 low-level 的闭环

高层策略输入当前 observation、MEM history、总体任务、metadata，以及过去的 subtask history，输出下一条 subtask。推理时该**预测 subtask**同时用于：

1. 条件化 visual subgoal generator；
2. 条件化低层 flow/FAST policy。

评估不再使用 ground-truth subtask 替代高层预测。

## Visual subgoal

论文使用 segment 末端的多视角未来观测作为 world-model target。当前极小数据只有一张当前图像，因此本项目生成一个确定性的 `future_observation_proxy`：根据 segment 末端状态对当前相机图像进行小幅图像空间变换，得到与未来相机帧相同的 RGB 接口。

这比旧版 endpoint heatmap 更接近论文结构：low-level policy 接收的是生成的 RGB future observation，而不是直接编码的二维终点坐标。它仍只是缺少真实未来视频时的最小替代，不能证明真实图像 world modeling 能力。

## Training-time RTC

训练严格采用 action-prefix conditioning：

```text
prefix positions: ground-truth clean action, flow time = 1, no loss
postfix positions: noisy action, sampled flow time, flow-matching loss
```

推理时已经 committed 的 action prefix 在每个 denoising step 被重新写回，且对应 token 的 flow time 固定为 1。RTC 不再通过简单左移 target 来近似。

## 官方 prompt dropout

- visual subgoal 出现在 25% policy examples；
- 有 visual subgoal 时，subtask 以 30% 概率移除；
- episode metadata 整体以 15% 概率移除；
- speed、quality、mistake 分别再以 5% 概率移除；
- control mode 始终保留；
- visual history 整体以 30% 概率移除。

metadata CFG 使用论文公式：

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

## 运行

可从环境安装、数据导入/合成 fallback、训练到评估一路执行的中文 Notebook：

- [`notebooks/pi07_minimal_reproduction.ipynb`](notebooks/pi07_minimal_reproduction.ipynb)

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e '.[dev]'
pytest -q
pi07mini-train --config configs/overfit.yaml
pi07mini-infer --checkpoint outputs/overfit/checkpoint.pt
```

训练分为三个最小阶段：

1. high-quality segments 上的 visual goal flow；
2. next-subtask high-level policy；
3. 带 prompt dropout、FAST、flow、KI 和 training-time RTC 的低层 policy。

评估输出：

- predicted subtask；
- generated visual subgoal；
- full/no-metadata/no-goal/no-history/CFG 消融；
- delay `0/4/8/12` 的 RTC postfix action error；
- trajectory 和 normalized action MSE。

## 当前最小训练结果

默认配置在 Apple MPS 上完成 `800 / 200 / 900` 步训练：

- high-level subtask：`steer_left`，与目标一致；
- generated future-observation MSE：`0.0246`；
- full generated-goal normalized action MSE：`0.2848`；
- no-goal normalized action MSE：`0.2938`；
- no-metadata normalized action MSE：`0.3739`；
- RTC delay `8/12` 的 postfix action MSE：`0.1210 / 0.0874`。

在这个极小数据实验中，metadata CFG 的 trajectory MSE 仍然退化，且 generated goal 的视觉细节较粗糙。结果被完整保留，不挑选更有利的 noise seed；它们说明链路可训练，但不支持真实世界效果主张。

## 安全与结论边界

- 本项目只允许离线训练和可视化，严禁连接真实车辆或机器人执行器。
- future observation 是单帧数据上的代理构造，不是真实多视角未来视频。
- 小样本过拟合、loss 下降或轨迹重合不代表泛化、闭环稳定性或安全性。
- 成功只说明论文中的模块接口和信息流能在缩小模型上形成可训练闭环。