Align pi0.7 minimal structure with paper

README.md

@@ -1,246 +1,125 @@
 # π0.7 Minimal Validation
 
-这是一个面向**结构验证和小样本过拟合**的 π0.7-style 教学项目。它在前面的
-π0.6/RECAP 最小实验之上，重点验证一条可解释的 steerable policy 链路：利用
-短时历史形成 memory，在高层预测视觉 subgoal，通过可独立缺省的 policy
-metadata 控制动作风格，并在存在控制延迟时用 RTC 对齐动作 chunk。
+这是一个面向**结构验证和极小样本过拟合**的 π0.7 最小实现。目标不是复现参数量、预训练权重或论文指标，而是保留官方论文中的关键模块、模态顺序、注意力信息流和训练/推理闭环。
 
-本项目不是 Physical Intelligence 官方实现，也不能用于真实车辆或机器人控制。
+实现依据：
 
-## 公开资料边界
+- **π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 结构。
 
-截至本项目实现时，作者没有在 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 ───────────────┐
+history images --MEM video encoder--┐
+history/current states -------------> observation block
                                      │
-current image + task ────────────────┼→ TinyGoalGenerator → predicted subgoal
+task + predicted subtask + metadata -> causal text prompt
                                      │
-optional speed/quality/mistake/control metadata
-                                     ↓
-                              HighLevelPolicy
-                                     ↓
-noisy action + flow time + RTC prefix → Pi07Mini action expert
-                                     ↓
-                          continuous action chunk
+generated future observation -------> image-goal block
+                                     │
+FAST action tokens -----------------> causal discrete action branch
+                                     │
+clean RTC prefix + noisy postfix ---> flow action expert
 ```
 
-## 重点结构
-
-### 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 的开头：
+官方 Figure 19 对应的 prefix 顺序被明确实现为：
 
 ```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
+memory observations -> causal text -> bidirectional image goals -> causal FAST
 ```
 
-默认随机采样 `d=0..12`，返回已执行 prefix，并对 padding tail 屏蔽损失。RTC 在
-这里表示训练/评估时的离线对齐机制，不包含实际控制器、异步推理线程或硬实时保证。
+- 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。
 
-### 5. CFG
+## High-level 到 low-level 的闭环
 
-推理时在相同 observation、goal、memory 和初始噪声下计算 metadata conditional
-与 metadata-omitted 预测：
+高层策略输入当前 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
-v_cfg = v_uncond + beta * (v_cond - v_uncond)
+prefix positions: ground-truth clean action, flow time = 1, no loss
+postfix positions: noisy action, sampled flow time, flow-matching loss
 ```
 
-默认 `beta=2.0`。必须同时报告 `beta=0,1,2`，因为高 guidance 可能放大过拟合、
-产生分布外动作，不能只展示最好看的曲线。
+推理时已经 committed 的 action prefix 在每个 denoising step 被重新写回，且对应 token 的 flow time 固定为 1。RTC 不再通过简单左移 target 来近似。
 
-## 数据与防泄漏约束
+## 官方 prompt dropout
 
-- history proxy 和 ambiguous pair 只依赖当前图像与过去状态；
-- subgoal condition 只使用 endpoint target，不能编码完整 action chunk；
-- flow expert 训练时不能读取 teacher-forced 真值动作 token；
-- 所有模型对比使用同一 initial noise、归一化统计和 RTC delay；
-- 数据增强的随机数由 sample index 和 seed 决定，保证复现实验；
-- 仓库不包含或重新分发原始 PAI 数据。
+- 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)
+```
+
+## 运行
 
 ```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
-```
+1. high-quality segments 上的 visual goal flow；
+2. next-subtask high-level policy；
+3. 带 prompt dropout、FAST、flow、KI 和 training-time RTC 的低层 policy。
 
-最终展示不能只有 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 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。
 
-还必须提供：
+## 当前最小训练结果
 
-- 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 上的差异指标。
+默认配置在 Apple MPS 上完成 `800 / 200 / 900` 步训练：
 
-小样本过拟合中，某个消融偶然更好并不证明模块无效；应展示全部固定设置结果，
-不调换 noise seed 或只挑选最佳样本。
+- 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；它们说明链路可训练，但不支持真实世界效果主张。
 
-- 严禁连接车辆、机械臂、移动机器人或任何会造成物理影响的执行器。
-- 合成 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
-编号或官方结果表。
+- 本项目只允许离线训练和可视化，严禁连接真实车辆或机器人执行器。
+- future observation 是单帧数据上的代理构造，不是真实多视角未来视频。
+- 小样本过拟合、loss 下降或轨迹重合不代表泛化、闭环稳定性或安全性。
+- 成功只说明论文中的模块接口和信息流能在缩小模型上形成可训练闭环。