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），进程显存硬帽 VRAM_FRAC=0.78
离线 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。

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

段	命令	耗时	回传
数据	FROM=kin TO=prep bash ml/pipeline.sh all	数小时	ml/data/stats.json、ml/data/r2.json、ml/runs/r4.json
训练	FROM=train TO=m5 bash ml/pipeline.sh all	约 3–6 小时	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。