Robot_Arm/docs/ML运行手册审查.md

# ML 运行手册审查（ml/README.md）· 精简版

八轮审查（`0218d7f` → 本次）的已解决条目全部删去，原文在 git 历史里。本文件只留：实测数字 / 已定判据 / 仍待真数据回答的问题 / 正式训练步骤。

环境：本机 CBB-003（RTX 3090，训练可用 19–20 GB；28 核；Python 3.12 + torch 2.10；Edge + onnxruntime-web 1.20.1，已入库 `webapp/vendor/ort/`）。
当前结论：第 1–6 步本机实测可跑；R4 通过；自检 7/8 通过（唯一失败项是 Windows 限制，已接受）；**审查条目已全部处置，下一步直接正式训练。**

---

## 一、实测数字（对照用）

| 项 | 数字 | 口径 |
|---|---|---|
| 对拍 300 条 | PASS（fk 3.4e-13 mm、特征 6e-8、间隙梯度 1.4e-6） | 第 2 步 |
| 生成 | 1.56 s/条 | 第 4 步，80 条 |
| 统计 | keepRate 0.977、samplesPerTask 36.5、cert.minGap p50 4.4 / p90 5.9 mm | 88 条，未加 3 mm 过滤 |
| 预训练 | 4.92 M 参数、6208 样本/s、60k 步 ≈ 2.8 h、显存峰值 2.76 GiB | batch 1024 |
| APG 显存 | batch 48 / plans 150 → 13.08 GiB；batch 128 必 OOM | d=192，1 步 |
| R4 部署口径 | wasm·16 线程·proxy P99 **12.67 ms**（< 15 通过）；WebGPU P99 27.09，不用 | `feat_dyn` 新模型 |
| 自检 | 7/8，3.5 分钟；`train_term=false`（Windows 下 TERM 送不到 python，超时靠 STOP 文件 + 每 10 分钟存档） | `selftest.json` |

## 二、已定的判据与做法

| 事项 | 定为 |
|---|---|
| R9（真查看器、训练好的模型、30 道贴柱题） | 稳态 `planWarmP99` < 45 ms、运动中饥饿 < 1%、认证超时占比 < 5%；冷启动 P99、刹停率、`tickGapMax` 只报 |
| R9 不过 | 几何查询（特征、投影、认证）搬进 Worker，主线程只执行 |
| APG | batch 48、steps 8000（总任务量同原 128×3000），本进程显存上限浮动（整卡 − 已用 − 1 GB 余量，见 `ml/common/vram.py`） |
| 离线 ort | 只用入库本地副本，缺失即报错，不退回 CDN |
| 训练余量 3 mm | `stats.json` 间隙 p10 ≥ 3 mm 保持，否则降到 p10 |
| `R2_STRICT` | `pool_check.independent=true` 且截距 < 0.10 时打开 |
| 共识过滤 | 门 1 < 0.90 自动开 |
| 分歧 | 实现方为准，下一轮数据定 |

## 三、仍待真数据回答（正式训练会自动产出，不单独验证）

1. `gapDrop`：3 mm 过滤的真实剔除比例 → `stats.json`。
2. R2 池无关性 → `r2.json` 的 `pool_check`。
3. R8 出题耗时 → `policy_bench.json` 的 `genS`。
4. APG 收敛与机时（batch 48 下首测）→ APG 日志。
5. 真模型 R9 → `r9_browser.json`。

## 三′、首次正式预训练失败（2026-10-18，21850 步）与修正

现象：闭环到达 0–0.2%、穿柱 77–97%；MF 残差 2 万步停在 7–8、17k–19k 尖峰到 96；梯度 100% 被裁剪。用 last.pt 实测定位：
1. **多峰头塌成单峰（主因）**：同一状态 8 个候选间标准差 0.030、动作幅度 0.151。FK / 平滑损失加在 `one_step(随机噪声)` 上去对齐这一条老师 Y，最优解是条件均值 E[Y|X]，左绕 / 右绕取平均正好穿柱。→ 改加在 r = t、t ≤ 0.3 的配对去噪估计 x̂ = z − t·u 上。
2. **MeanFlow 目标失控**：∂u/∂t 均方根 6–12，而 v 约 1.1，目标被自激的 JVP 项主导。时间嵌入 sin(1000·t) 太陡，JVP 又在 bf16 下算。→ 最高角频率 50；MF 分支 fp32；前 5000 步 p_neq = 0。
3. **闭环分布偏移被低估（推断）**：增广只有 1°。→ 增广 40% / 3° / 12 步收回；新增 DAgger 阶段（策略走到的状态请老师重规划，2 轮）；开训前加老师轨迹回放自检；每次评估加开环误差与候选多样性。

## 四、正式训练（三段，每段跑完回传）

| 段 | 命令 | 耗时 | 回传 |
|---|---|---|---|
| 数据 | `FROM=kin TO=prep bash ml/pipeline.sh all` | 数小时 | `ml/data/stats.json`、`ml/data/r2.json`、`ml/runs/r4.json` |
| 训练（含 DAgger） | `FRESH_FROM=prep FROM=prep TO=m5 bash ml/pipeline.sh all`（增广改了，样本要重打包；gen 不重跑） | 约 9–11 小时（未实测：prep 0.5 + 预训练约 5（fp32 变慢）+ DAgger 约 3.5 + m5 0.3） | `ml/runs/replay_teacher.json`、`ml/runs/base/log.jsonl`、`ml/runs/m5_gate_*.json` |
| 后训练与评测 | `FROM=apg TO=accept bash ml/pipeline.sh all` | 约 10–20 小时 | `ml/runs/acceptance.json`、`policy_bench.json`、`r9_browser.json` |

中途出错：把出错信息发我，修完用 `FROM=<出错阶段>` 接着跑，前面的不重做。

---

## 七、第一次真跑（2026-10-18，网页「开始训练」）暴露的一处阻塞 + 门 1 实测

**阻塞（已修，一行）**：`pipeline.sh` 的 `run() { echo "== $*"; "$@"; }` 把命令回显写进 **stdout**，而 `gate1` 是 `run node ml/gen/consistency.cjs … | tee ml/data/consistency.json.tmp` → 回显被一起存进 `consistency.json`，文件首行变成 `== node ml/gen/consistency.cjs 300 4242`。`gen` 阶段读它判 CONSENSUS 时 `json.load` 当场 `JSONDecodeError: Expecting value: line 1 column 1 (char 0)`，`set -e` 下整条 `all` 停在 gen（阶段 rc：kin 0、r4 0、gate1 0、gen 1）。
- 与平台无关，沙箱 Linux 同样会中，只是没跑到这一步。
- 修法：回显改走 stderr（`echo "== $*" >&2`）。全仓只有 `gate1` 这一处把 `run` 的输出重定向进文件（`check_r2` 等用 `--out` 自写，不受影响）。
- 已写坏的 `ml/data/consistency.json` 就地剥掉首行复用，**没有重跑 25–30 分钟的门禁**。
- 建议实现方顺手加一条自检：任何被 `tee`/`>` 落盘成 JSON 的产物，读之前先确认首字符是 `{`。

**门 1 实测（第一次真数据）**：`tasks 300 / pairs 1133 / consistentRate 0.838 / consistentByGateRule 0.838 / gate FAIL / deterministic 300/300`，分类看 `C 0.824`、`B 0.844`，`devP50 3.6`、`devP90 145.1`。
→ 0.838 < 0.90，**自动走共识分支**（`--consensus 4`），与方案 R1 首测 78% 同一侧；`worstAxisOfInconsistent [43,4,42,40,16,39]` 说明跳变在各轴上分布均匀，不是某一根轴的系统性问题。gen 因此按 4–5 h 那一档估，不是 1 h。