Files

T

Hark 406f180cab diag: H 段（老师 oracle 走 rollout / 前缀消融 / 子目标越过顶点规则 / 分轴与分类别指标）；训练：EMA、选模不落在 p_neq 预热、闭环分数选模、24000 步余弦、p_neq 0.5 + p_edge 0.1、子目标头切断抄输入、前缀/dq 增广；仿真：last 记真正提交的候选、碰撞与到达按每题时限、回放门禁读 pass+指纹并走 rollout；数据：动作标签按 1.25·STEP 归一化（act_scale 随 meta/ckpt/ONNX 传递，旧模型 1.0）、收回亏空结转、DAgger 带 qPrev 与起步速度、打包签名变更自动重打；ik-policy.js 同步（actScale、子目标规则、DLS 时清 lastPlan）；本机执行清单与 README 更新

2026-10-19 10:43:05 +00:00

33 KiB

Raw Blame History

Transformer 多峰策略端到端训练与浏览器部署

机械臂避障策略运行手册。目标：在你的机器上从零跑出 Transformer 避障策略，并在查看器里直接用上。方案依据见 docs/Transformer轨迹拟合训练方案.md。所有命令在仓库根目录执行。

一键运行（无人值守）：先激活训练用的 Python 环境，Windows 双击 ml/console.bat（Linux/WSL 运行 bash ml/console.sh），浏览器自动打开训练控制台 http://localhost:8100/，点「开始训练」即从对拍一路跑到验收。等价的终端命令是 bash ml/pipeline.sh all。

断了再点一次就是续跑（断电、蓝屏、误关、手动停止都一样），损失不超过几分钟：
- 已成功的阶段自动跳过；
- 生成：每条任务的随机数只由（种子, 序号）决定，没写完的 shard_XXXX.jsonl.part 保留完整的行、从下一条接着写；
- 打包：已打包完的 shard 跳过；
- 预训练 / WTA / APG：每 10 分钟原子存一次 last.pt（含优化器、步数、最好成绩、早停计数；配置项 ckpt_min），续跑时自动 --resume；
- M5：已评完的那一半（比检查点新的结果文件）跳过；挖错：已过门禁的轮次跳过，断在某轮的 APG 用该轮 last.pt 续。
- 不续的只有几分钟级的短步骤（对拍、一致性门禁、R4、导出、bench、验收），它们整步重跑。
同一时间只能跑一条：网页、终端、all 共用一把锁 ml/runs/pipeline.lock，第二个入口会被直接拒绝。
关窗口不影响训练：网页和控制台窗口都可以关，重新打开即可接着看、可停止。
门槛在流程内自动处理：R4 推理延迟自动测（不过就在训练前停下）；R2 只警告；M5 不过自动改训 WTA 头，两种头都不过才停；每个阶段有超时上限（估时 ×3），卡死会判失败并放锁。也可以按阶段单独执行 bash ml/pipeline.sh <阶段>；每一阶段完成后看本手册对应小节的「检查」。

阶段	命令	预计耗时（28 核 CPU + RTX 3090）	产出
1 环境	`bash ml/pipeline.sh setup`	10 分钟	依赖
2 对拍	`bash ml/pipeline.sh kin`	约 1 分钟（估算：300 条对拍实测 7.6 s，流程跑 2000 条）	`ml/assets/kin.json`、对拍 PASS
2′ R4 延迟	`bash ml/pipeline.sh r4`（无头 Edge/Chrome 自动测）	约 5 分钟	`ml/runs/r4.json`
3 老师门禁	`bash ml/pipeline.sh gate1`	25–30 分钟（单核）	`ml/data/consistency.json`
4 生成数据	`bash ml/pipeline.sh gen`	不共识约 1 小时；共识约 4–5 小时	`ml/data/shard_*.jsonl`、`stats.json`
5 打包样本	`bash ml/pipeline.sh prep`	15–30 分钟	`ml/data/samples/`、`ml/data/r2.json`
6 预训练	`bash ml/pipeline.sh train`	测速 2000 步约 6 分钟，正式 24000 步约 1.5–2.5 小时（未实测：fp32 MF 分支后的吞吐以测速为准）	`ml/runs/base/best.pt`
6′ DAgger 纠偏	`bash ml/pipeline.sh dagger`	未实测，估 3–4 小时：2 轮 ×（采起点 5 分钟 + 老师重规划约 30 分钟 + 打包 + 微调 15000 步）	`ml/runs/base_dagger.ckpt`、`ml/runs/base_dag2/best.pt`
7 M5 门禁	`bash ml/pipeline.sh m5`	估算 10–20 分钟	`ml/runs/m5_gate_base.json`
8 APG 微调	`bash ml/pipeline.sh apg`	未实测：展开长度 60–150 次推理随批变化，以监控页前 50 步换算的 ETA 为准	`ml/runs/apg/best.pt`
9 挖错循环	`bash ml/pipeline.sh mine`	未实测：每轮 = 5 万题作答 + APG，以第 1 轮实际耗时 × 轮数为准	`ml/runs/current.pt`
10 导出	`bash ml/pipeline.sh export`	1 分钟	`webapp/models/traj_policy.onnx`（fp32）
11 部署评测	`bash ml/pipeline.sh bench`	估算约 1 小时（Node CPU，1120 个任务；R8 出题耗时未实测）+ 查看器 R9 约 5 分钟	`ml/runs/policy_bench.json`、`ml/runs/r9_browser.json`
12 验收汇总	`bash ml/pipeline.sh accept`	10–20 分钟	`ml/runs/acceptance.json`
13 使用	`python ml/serve.py` → 浏览器 `?policy=1`	—	—

第 4/5/6 步耗时为 RTX 3090 + 28 核实测换算；标「估算」「未实测」的不要当预算，以每步首次输出的速度为准。第 1 步（安装依赖）建议先手动做；一键流程默认从第 2 步开始，含 2′。

分歧规则：审查方与实现方意见讨论后仍不一致时，以实现方（Hark）的意见为准先落地；下一轮用实测数据说话（见 docs/ML运行手册审查.md 第二节）。

1. 环境

Linux / WSL2，或 Windows 原生 + Git Bash（实测第 2/4/5/6 步与闭环仿真可跑）；NVIDIA 驱动 + CUDA（nvidia-smi 能看到 3090）
Node ≥ 18，Python 3.10–3.12
脚本统一用 $PYTHON（默认 python）。Linux 上没有 python 命令时：export PYTHON=python3。Windows 不要用 python3（那是 WindowsApps 假壳）
先按 CUDA 版本装 PyTorch（https://pytorch.org ），再：

git pull
bash ml/pipeline.sh setup          # pip install -r ml/requirements.txt；cd ml && npm install（onnxruntime-node）

2. 碰撞模型导出与对拍（必须 PASS）

bash ml/pipeline.sh kin

检查：最后打印的 JSON 里 "PASS": true（fk、姿态、组对间隙、83 维特征、间隙梯度与 JS 一致）。 docs/collide.json 以后只要重新拟合或重生成 pair2d/roadmap，这一步、数据、模型都要重来（指纹不符时各脚本会拒绝运行）。

真跑之前（第七轮新增，5–10 分钟）：bash ml/pipeline.sh selftest（进程生命周期与断点续跑自检 → ml/runs/selftest.json，不碰本仓库数据）。通过后正式流程按「数据 → 训练 → 后训练与评测」三段跑，中途出错从该阶段 FROM= 续跑。bash ml/pipeline.sh smoke（副本里极小模型全流程冒烟，40–70 分钟）备用，不必跑。已定判据与待回答问题见 docs/ML运行手册审查.md。

R4 延迟（训练前做，自动）：推理延迟只取决于模型结构，与权重无关，所以用随机初始化模型先测，不过就在训练前改结构，不必等训完。

bash ml/pipeline.sh r4      # 随机初始化模型导出到 ml/runs/r4/traj_policy_r4.onnx（不碰 webapp/models/），无头浏览器自动测 → ml/runs/r4.json

部署形态：模型每次只编码 1 行观测、解码 K=8 条候选（meta.enc_once）；wasm 线程默认 min(16, ⌊0.6×逻辑核⌋)，推理放在 onnxruntime 的代理 Worker 里不占主线程。探针测 4 种配置：默认线程 + Worker（部署口径）、4 线程（对照旧默认）、默认线程不开 Worker（看 tickGapMax：推理是否卡住 20 ms 节拍）、WebGPU。 通过线：部署口径 batch=8 P99 < 15 ms；wasm 不过而 WebGPU 过也算通过，r4.json 记 deploy_ep: webgpu，查看器用 &ep=webgpu。不通过时流程停在这里（返回码 5）：改用 CFG=ml/configs/small.json（d=128、ff=512，约 1.8 M 参数）重跑。确认要继续设 R4_STRICT=0。找不到浏览器时 pass 为 null、流程继续、验收标红；可用 R4_BROWSER=浏览器路径 指定。 onnxruntime-web 默认用本地副本 webapp/vendor/ort/（setup 与 r4 会自动执行 bash ml/prep/vendor_ort.sh 放好，约 33 MB、不入库），不依赖 CDN；ORT_LOCAL=0 强制走 CDN。 WebGPU 配置和查看器参考测试会弹出一个有界面的浏览器窗口（无头模式拿不到真 GPU），跑完自动关闭，期间别动它。 r4.json 还带一项 viewer_ref：随机模型在真查看器里跑 30 道贴柱题的整次规划耗时，只作参考（随机策略几乎每次都要认证多条候选，安全层路径不代表真模型），R9 以第 11 步为准。手动看：python ml/serve.py 后打开 http://localhost:8000/?policy=../ml/runs/r4/traj_policy_r4.onnx&probe=1（随机模型默认会被查看器拒绝，&probe=1 才放行，徽标标红「随机探针模型」）。

3. 老师一致性门禁

bash ml/pipeline.sh gate1

看 consistentByGateRule：≥ 0.90 直接生成；< 0.90 时第 4 步自动加 --consensus 4（每条任务另跑 4 个 ±5 mm 邻居，与多数绕法不一致的样本丢弃，生成成本约 5 倍）。可用 CONSENSUS=0/1 手动覆盖。

4. 生成老师数据

bash ml/pipeline.sh gen                     # 默认 5 万条、进程数 = CPU 核数
# 自定义：N_TASKS=50000 NPROC=28 CONSENSUS=1 TARGET_SAMPLES=1700000 bash ml/pipeline.sh gen

不共识约 1.6 秒/条/核；共识约 8 秒/条/核。生成完自动统计；样本数不足 TARGET_SAMPLES（默认 170 万）时按实测「样本/任务」自动补生成（最多补 2 次），不用手动加 N_TASKS。

检查 ml/data/stats.json：

字段	不共识（实测）	共识（估算）	不正常时
`keepRate`	≈ 0.97	0.80–0.88	共识 < 0.75：把 `stats.json` 发我（老师左右跳变比预期多）
`samplesPerTask`	≈ 36.5	≈ 36.5	—
`samplesEvery3`	≥ 170 万（自动补量后）	≥ 170 万	补量后仍不足：发我
`consensusDrop`	0	约任务数的 10–20%	—
`vertexMinGapMm`	p50 ≈ 4.4、p90 ≈ 5.9 mm	同	—
`gapDrop`	认证最小间隙 < 3 mm 被剔除的轨迹数（未实测，预计约 10%）	同	> 25%：发我（自动补量会按剔除后的样本数补，但老师整体太贴柱）
`byCatMode`	C 类（贴立柱）各模式都有数千条	同	—

5. 打包训练样本 + R2 检查

bash ml/pipeline.sh prep

每条轨迹按 50 Hz 时间律重放，每 3 步取一个样本（特征与部署同一份 JS 代码计算）。40% 样本对 q 加 σ = 3° 噪声增广，标签改为 12 步内线性收回老师轨迹（加噪后间隙 < 3 mm 或收回途中有碰撞的不用）。

动作标签：Y = 每步增量 / (act_scale · STEP)，夹在 ±1，act_scale = 1.25（ACT_SCALE）。老师巡航时主导轴每步正好 1 个 STEP，标签最大 0.8，执行端的 ±1 只防越界；被 ±1 截掉的收回量在下一步补上。运行时增量 = clamp(act, ±1) · act_scale · STEP，act_scale 写在 checkpoint 和 ONNX meta 里，仿真、APG、浏览器运行时都按它反归一化；没有这个字段的旧模型按 1.0 处理。
每个 shard 打包产物带 <shard>.meta.json（数据版本 data_ver=2、act_scale、增广参数、签名 sig）。ACT_SCALE、AUG_P、AUG_SIGMA、AUG_BACK、MIN_GAP_MM 任一变化，签名就变，run_prep.sh 只重打签名不符的 shard；没有 meta 的旧打包一律重打。训练读 meta 取 act_scale，同一次训练的各目录（主数据 + DAgger）必须一致，否则报错。认证最小间隙 < 3 mm 的老师轨迹不进训练集（MIN_GAP_MM=3，与 stats.json 的 gapDrop 同一口径）：模型只学离障碍 ≥ 3 mm 的走法，运行时投影护栏仍保持 5 mm。检查 ml/data/samples/index.json：train_samples 约 170 万、val_samples 约 9 万（5% 任务划为 val）。 MIN_GAP_MM 必须与生成阶段相同（stats.json 的 minGapFilterMm），不一致时这一步直接报错（返回码 8）。随后自动跑 R2 检查（ml/data/r2.json）：判据是 label_std_norm < 0.10（近邻距离 → 0 的回归截距，与搜索池大小无关）；label_std_mean 是旧口径（取最近 5% 近邻，随池大小变），只作参考。不通过时默认只警告、继续训练（阈值尚未经实测校准），验收汇总列为参考项；R2_STRICT=1 才在这里停（返回码 4）。小样本时近邻对不足，pass 为 null。

6. 预训练

bash ml/pipeline.sh train                           # MeanFlow 头 → ml/runs/bench_base/、ml/runs/base/

开训前先跑老师轨迹回放自检（ml/runs/replay_teacher.json，约 1–3 分钟），两部分都过才开训：

运动学口径：老师 50 Hz 轨迹直接放进 PyTorch 运动学 / 碰撞 / 到达判据，到达 ≥ 95%、碰撞 ≤ 1%；
滚动口径：老师当策略（TeacherOracle）走完整的闭环仿真 rollout()（队列、前缀、提交 3 步、标签 clamp、DLS、时限都与策略同一条路径），时限内到达 ≥ 95%、碰撞 ≤ 1%、DLS 接管前与老师轨迹的最大关节偏差 p99 ≤ 0.1°。流程读 json 的 pass 字段，并核对 fp（当前 kin.json）与 data_fp（数据 shard 记录的碰撞模型指纹）；任一不符就重跑一次回放，仍不过 rc 5 停。

闭环指标长期 0% 而开环正常时，跑 PYTHONUTF8=1 python -m ml.eval.diag_cl --ckpt ml/runs/base/last.pt --n 256（约 35–50 分钟）→ ml/runs/diag_cl.json：A 起点特征 Python 与 JS 逐组差、B 两份特征下动作差、C 旧部署口径的失败形态、H 老师 oracle / 前缀消融 / 子目标规则 / 分轴与分类别指标（各键含义见 ml/eval/diag_cl.py 文件头与 docs/本机执行清单.md）。

先跑 2000 步测吞吐（ml/runs/bench_base/log.jsonl 的 samples_per_s，eta_h 是剩余小时数），再正式训练 24000 步（configs/base.json 的 steps，余弦学习率按这个预算走完）。

通过线（R10）：samples_per_s ≥ 5000（24000 步 × batch 1024 ≈ 1.4 小时）。MeanFlow 的 JVP 双前向使训练受算力限制，加大 batch 不会提高样本/s；低于通过线时把 configs/base.json 的 fk_caps 从 96 降到 48
EMA：训练同时维护权重的指数滑动平均（ema 0.999），checkpoint 里存 model（原始权重）与 ema。评估、DAgger、APG 起点、M5、挖错、验收、导出一律用 EMA 权重（没有 ema 的旧 checkpoint 用 model）
训练中每 2000 步用 EMA 权重打印一行 EVAL {...}：val 任务闭环（部署节奏、不开安全层）success、collision_rate、goal_ratio_2s（2 s 时目标误差 / 起点误差的中位数）、time_ok_1p3、start_fail，时限 = 老师时长 × 2（至少 3 s），碰撞与到达只计时限内；开环三项（val 样本、老师状态上）：ol_fk_mm 候选 0 的 16 步末端误差、ol_best_mm 8 个候选里最好的一条、ol_div 候选多样性。
选模：score = success + 0.05·(1 − collision_rate) + 0.05·(1 − min(1, goal_ratio_2s)) − 1e-4·min(ol_best_mm, 500)，到达率全 0 时闭环指标仍能排序。p_neq 预热期内和预热后第一次评估之前不存 best.pt（一步映射还没训过）；早停只在 max(预热 + 2 次评估, 总步数一半) 之后计数，连续 5 次不升即停
损失：FK / 平滑只加在 MF 分支 r = t 且 t ≤ 0.3 的配对去噪估计 x̂ = z − t·u 上；时间嵌入最高角频率 50；MF 分支与 JVP 走 fp32（TF32 矩阵乘）；前 5000 步 p_neq = 0，之后 p_neq = 0.5，另有 10% 样本固定在部署用的 (r = 0, t = 1)（p_edge）
子目标头只用把 sub 特征置零的输入训练（sub 存在时子目标标签与输入是同一个量，原样抄就能答对）；运行时子目标头只在冷启动、sub 为空时使用，口径一致。价值头用完整输入
条件输入增广（训练时现做，aug_pre_drop 0.15 / aug_pre_sigma 0.1 / aug_dq_sigma 0.3）：前缀随机清空（变成 r = 0 样本，标签不变）；前缀加噪声，标签前 r 步同步加、第 r 步扣回；速度特征 dq 加噪声。目的是让模型不能靠照抄上一块和上一帧速度出动作

6′. DAgger 纠偏

bash ml/pipeline.sh dagger

起点模型：预训练 best.pt 的闭环 success > 0 时用它，否则用 last.pt（python -m ml.common.ckpt pick ml/runs/<头>），都取 EMA 权重；之后每轮按同一规则取上一轮的结果。微调时只有起点已走过自己的 p_neq 预热才不再预热。用起点模型在 train 任务上闭环跑（关安全层），每题取「首次碰撞前 0.2 s」和一个随机时刻的状态做起点（须无碰、间隙 > MIN_GAP_MM、离目标 > 5 mm），同时记下该时刻的上一帧。老师从这些起点重新规划（gen_dataset.cjs --tasks，与主数据同认证），时间律从当前速度在首段方向上的分量起步（v0），t = 0 样本的速度特征用真实上一帧；打包后与主数据一起微调。微调的 val 只取主数据，DAgger 样本全部算 train。默认 2 轮（DAG_ROUNDS），每轮 8000 题（DAG_N）、微调 15000 步（DAG_STEPS，lr 3e-4）。老师只用于训练标注，部署仍无老师。M5 门禁读 ml/runs/<头>_dagger.ckpt 指向的模型；APG / 挖错的 BC 项也用 DAgger 样本。可断点续跑（采集、老师 shard、打包、微调各有完成标记）。

显存预算浮动：整卡留 1 GB 给系统（VRAM_RESERVE_GIB，默认 1），训练与 APG 进程启动时按"整卡 − nvidia-smi 已用 − 余量"和"CUDA 空闲 − 余量"两者取小自设本进程上限（ml/common/vram.py）。占显存的应用多，上限就自动变小，不用改配置；想按定值对拍给 VRAM_FRAC（旧口径 0.78）。日志 vram 字段记峰值；预训练 batch=1024 实测峰值 2.76 GiB、APG batch=48 13.08 GiB。显存不够把 batch 改成 512。中断后再跑 bash ml/pipeline.sh train（或 all）会自动从 ml/runs/<头>/last.pt 续训（每 10 分钟存一次），测速那 2000 步做过就跳过。训练发散时不会用发散的权重覆盖 last.pt / best.pt。

7. M5 门禁：选定动作头

bash ml/pipeline.sh m5

1000 个贴立柱任务（无老师题，定长 6 s 时限）跑两遍，结果在 ml/runs/m5_gate_base.json：

policy_only：关安全层的纯策略指标。门禁只看这一项：穿柱率 ≤ 2% 通过，通过后把该模型记为选定模型（ml/runs/selected_ckpt），后续阶段自动从它开始
with_sim_safety：仿真里的近似安全层（候选逐步干涉就换下一条）。只作参考

三种口径的关系：M5 是纯策略能力；仿真安全层是近似；部署能不能过只看第 11 步（与浏览器同一份运行时，含投影、距离认证、刹停、预算、换向锁）。三者互不替代。

不通过时流程内自动改训 WTA K=8 头（约 3 小时，产物在 ml/runs/bench_wta/、ml/runs/wta/，不覆盖 MeanFlow），再判一次 → ml/runs/m5_gate_wta.json；两种头都不过才停（返回码 3）。AUTO_WTA=0 关闭自动分支。单独跑 WTA：CFG=ml/configs/wta.json bash ml/pipeline.sh train 再 CFG=ml/configs/wta.json bash ml/pipeline.sh m5。

需要强制指定后续阶段的起点模型时用 CKPT=路径 bash ml/pipeline.sh apg。

8. APG 可微微调

bash ml/pipeline.sh apg

按部署节奏（每次推理提交 3 步、50 Hz）可微展开策略，优化到达、碰撞余量、平滑与行程，并保留 BC 锚定。每 500 步闭环验证，按到达率存 best.pt，完成后复制为 ml/runs/current.pt。

展开长度：每批覆盖该批老师时长 p90 × 1.2（无老师题按 6 s），在 60–150 次推理（3.6–9 s）之间；日志 plans 字段是本批实际次数
到达项：每 10 次推理段末的 TCP 距离与姿态误差，没有「到达即停」。这是有意的：段末项在整条展开上持续给出接近目标的梯度
碰撞项：每步端点与中点的逐胶囊对铰链 ReLU(3 mm − 间隙)，两处取均值（与只查端点同量纲，w_col 不变）。3 mm 与训练数据的过滤线一致，碰撞项不与 BC 标签对抗；运行时投影护栏是独立的 5 mm
configs/apg.json 定为 batch=48、steps=8000（本机实测 batch=48/plans=150 峰值 13.08 GiB；batch=128 必 OOM；总任务量与原 128×3000 相同）。仍超预算时把 seg_plans 从 10 降到 5，不降 plans_max（会截掉长任务的绕出段）

9. 挖错循环

bash ml/pipeline.sh mine            # 默认 6 轮；ROUNDS=3 APG_STEPS=1000 MINE_N=50000 可调

每轮：5 万道新题关安全层作答 → 错题分类 E1–E5 → 本轮错题与邻居进 APG 采样池（不累积历史轮，旧错题由门禁的「上轮修好仍对 ≥ 95%」把关）→ E2（局部极小）请老师补少量路径 → APG 微调 → 门禁集比较，不达标自动回滚。连续 2 轮提升 < 0.5 个百分点自动停止。

门禁（ml/runs/mine/r*/gate.json）：到达率不降、A 类降幅 ≤ 0.5 个百分点、上轮修好的题 ≥ 95% 仍对、R7：B/C 类左右绕行比例变化 ≤ 5 个百分点、行程中位数比 ≤ 1.05。挖错题与门禁集都是无老师题，到达按定长 6 s 判，time_ok_1p3 与行程比只在有老师参考的题上统计（门禁集上为 null）。

10. 导出

bash ml/pipeline.sh export          # fp32 ONNX + meta.json（含 act_scale）→ webapp/models/（约 20 MB），导出 EMA 权重

默认 fp32：部署走 wasm 与 Node CPU，fp16 在 CPU 后端上不保证更快。只有第 13 步用 &ep=webgpu 实测 __POLICY.latency() 明显受益时，才另导出 fp16 做对比：

pip install onnxconverter-common
python -m ml.export_onnx --ckpt ml/runs/current.pt --out webapp/models/traj_policy_fp16.onnx --fp16

11. 部署形态评测（策略 + 安全层）

bash ml/pipeline.sh bench

跑与浏览器同一份运行时（webapp/js/ik-policy.js）：贴立柱 30 例（pos、pose 各一遍）、直线被挡 40 例、R8 对抗 50 例（J1 起终差 ≥ 140°、终点贴立柱、两侧都要绕远）、一次性贴立柱扩展集 1000 例。各集合数量可用 --nc-n / --route-n / --r8-n 单独调。

看 ml/runs/policy_bench.json：各集合 collisionFrames 为 0；near_column_* 与 route40 全部 ok；near_column_1000 0 失败；brakeRate < 0.02；r8_adversarial 的 recoveryRate ≥ 0.95、livelock = 0。同一步还会在查看器里跑同一批 30 道贴柱题（与 Node 同种子），写 ml/runs/r9_browser.json（会弹出浏览器窗口几分钟）：

R9 通过线：稳态规划 planWarmP99 < 45 ms、运动中饥饿节拍 starve_rate < 1%、认证超时占比 cert_time_rate < 5%（整次规划 = 推理 + 前瞻 + 安全层，60 ms 周期留 15 ms 给渲染与执行时钟；稳态 = 剔除每题静止起步那次冷启动规划，冷启动只是起步延迟，planColdP99 只报；饥饿 = 运动中执行时钟到点队列空了，即实际丢步；认证超时一闸防止靠拒绝候选、刹停换来耗时达标）。brake_rate、tickGapMax 只报不判。
两边对照：policy_bench.json 的 near_column_pos.safetyMsP99 与浏览器 safetyP99 差 > 3× 时验收标红，用 certQueriesP99（每次规划新增距离查询）、certMemoHitRate、certFailWhy（cert / budget / time / box）定位。

12. 验收汇总

bash ml/pipeline.sh accept

自己补跑 val 全部任务的闭环（开仿真安全层）：可达任务到达率 ≥ 98%、D 类停靠距离 ≤ 老师 + 5 mm、起步失败率 ≤ 0.2%；再读第 5–11 步产物核对 R2、R7、R8、R10、M5 与部署形态各项。逐项打印「通过 / 未过」，结果在 ml/runs/acceptance.json。

13. 在查看器里使用

python -m arm.viewer.build_viewer   # 若 webapp/generated/00_data.js 还没生成（查看器原有构建步骤）
python ml/serve.py                  # 带跨源隔离头的本地服务，wasm 可用多线程

浏览器打开 http://localhost:8000/?policy=1：右上角徽标显示「策略模式就绪」后，拖动黄球或松手，手臂由策略闭环执行（不调用任何规划器）。

&ep=webgpu 改用 WebGPU 后端对比延迟
控制台 __POLICY.latency() 查看推理、前瞻、安全层、整次规划的 P50/P99 与节拍；__POLICY.stats() 查看刹停、换向、精修次数
&autotest=30 自动跑与 bench 同一批贴柱题，结果在 __POLICY.autotest
运行时投影护栏 5 mm：候选动作离障碍 < 5 mm 时沿间隙梯度外推（训练数据的过滤线是 3 mm，护栏比数据更保守）
动作尺度读模型 meta 的 act_scale；子目标按「越过顶点」切换（与训练标签同口径：沿拐角平分面越过当前途经点即换下一个，没有超时），与仿真 closed_loop.sub_advance 同一规则
工具偏移 ≠ 0 时自动交回原规划器
离线环境：bash ml/prep/vendor_ort.sh 把 onnxruntime-web 放到 webapp/vendor/ort/，地址加 &ortLocal=1（WebGPU 同样可用）

14. 回传给我

步骤	文件
2	对拍输出（终端 JSON）、`ml/runs/r4.json`
3–5	`ml/data/consistency.json`、`ml/data/stats.json`、`ml/data/samples/index.json`、`ml/data/r2.json`
6	`ml/runs/bench_base/log.jsonl`（测速）、`ml/runs/base/log.jsonl`
7	`ml/runs/m5_gate_*.json`
8–9	`ml/runs/apg/log.jsonl`、`ml/runs/mine/r*/report.json` 与 `gate.json`
11–13	`ml/runs/policy_bench.json`、`ml/runs/r9_browser.json`、`ml/runs/acceptance.json`
任一步出错	`ml/runs/pipeline.json`、`ml/runs/console.log`（控制台启动时）或终端输出

训练控制台

Windows：双击 ml/console.bat          Linux / WSL：bash ml/console.sh
（等价于 python -m ml.monitor --open。先激活训练用的 Python 环境；或设环境变量 PYTHON=训练环境 python 的完整路径。
 启动器以「能 import torch」判断 Python 可用；Windows 另需 Git for Windows 提供的 Git Bash）

不要直接双击 ml/monitor.html：那样只能看到示例数据（页面顶部有黄色提示）。

浏览器自动打开 http://localhost:8100/，零第三方依赖、不连外网，每 5 秒刷新。

自检：控制台启动时检查训练用 Python 能否 import torch、GPU、node、bash，结果显示在「全流程」卡片底部；不过则「开始训练」不可点。开始：点「▶ 开始训练」→ 运行方式（续跑 / 从头重跑）、动作头、共识过滤、任务数、进程数、目标样本数、挖错轮数、MIN_GAP_MM → 「开始」。控制台在后台执行 bash ml/pipeline.sh all。

续跑：跳过已成功的阶段。改了参数时只作废受影响的阶段（改生成参数 → 从生成起重跑；改动作头 → R4 与训练起重跑；改挖错参数 → 从挖错起重跑），旧产物移到 ml/archive/<时间>/，不删除。
从头重跑（FRESH=1）：全部旧产物移到 ml/archive/<时间>/。停止：「■ 停止」时，训练类阶段（预训练 / M5 / APG / 挖错）先收到停止请求（ml/runs/STOP），存好 last.pt 自行退出（最多等 90 秒），然后结束整个进程树；这一步记为「已停止」并放锁，再点「开始训练」即从断点续跑。终端里按 Ctrl+C 或 kill 也会先存档再退出。终端或上一个控制台窗口起的流水线也能在这里停（按锁里记录的进程号）。 网页和控制台窗口都可以关，训练不受影响（Windows 子进程有自己的隐藏控制台，Linux 在独立会话里），重新双击 console.bat 即可接着看。互斥：已有一条在跑时（网页、终端或 all 起的都算），第二个入口会被拒绝并给出持锁进程号；进程被强杀没来得及放锁时，心跳 5 分钟不刷新即视为失效。超时：每个阶段上限 = 估时 ×3（网页「本步粗估 / 上限」；TIMEOUT_SCALE=2 整体放宽），超了判卡死、阶段失败、放锁。生成阶段每分钟往终端输出打一行节拍。安全：开始/停止只接受本控制台页面发起的请求（自定义请求头 + 同源检查），本机其他网页发不进来。

页面内容，从上到下：

区域	内容	数据来源
流水线	12 个阶段的状态（完成 / 运行中 / 失败 / 已停止 / 未开始）与各步用时	`ml/runs/pipeline.json`（每个阶段开始结束时自动写）
全流程	全流程百分比（按各步粗估耗时加权）、当前步骤与它的进度、总用时、本步用时、剩余粗估、开始/停止按钮	同上 + 各阶段产物
GPU	利用率、显存、温度、功耗	`nvidia-smi`
当前运行	正在跑的训练（自动跟随；顶部下拉框可切换 `ml/runs` 下任一次运行）：步数、已用/剩余时间、预计完成时刻、评估标记	`ml/runs/*/log.jsonl`
指标卡与曲线	预训练：总损失、各损失分量、吞吐（R10 线 5000 样本/s）、闭环评估（到达率 / 碰撞率 / ≤老师时长×1.3 / 起步失败）；APG：到达误差、损失分量、展开长度	同上
各阶段结果	数据统计（含 `gapDrop`）、R2、M5 两种口径、挖错各轮与门禁、部署评测、验收逐项	`ml/data/.json`、`ml/runs/.json`
终端输出	控制台启动的流水线的命令行输出，报错标红	`ml/runs/console.log`

当前步骤的进度怎么算：生成数据 = 已写出任务条数 / 目标条数（含自动补量）；打包 = 已打包分片 / 分片数；预训练 = (测速 2000 步 + 正式步数) / (2000 + 总步数)；APG = 步数；挖错 = 已完成轮数 + 本轮 APG 步数（共最多 ROUNDS 轮，提升不足会提前停）；M5 = 两遍评估；对拍、老师门禁、导出、部署评测、验收无法计量，显示用时与粗估。全流程百分比与剩余时间按 ml/pstate.py 里的阶段估时加权（与超时上限同一份表），只作参考。

同一局域网的手机或其他电脑要看：python -m ml.monitor --host 0.0.0.0，用本机 IP 访问；其他机器只能看，开始/停止只接受本机操作（--remote-control 放开）。

常见问题

指纹不符：collide.json 变了。依次重跑第 2、4、5 步并重训。
训练发散（loss 出现 nan/inf，自动停在 diverged.pt）：先把 lr 降到 5e-4 重试一次，仍发散就走 WTA 回退（第 7 步）。
显存/内存不足：降 batch；APG 还可把 seg_plans 降到 5。出题与间隙计算按空闲显存自动分块（用 1/4；空闲量本就扣除了桌面占用）。check_r2 常驻约 1.6 GB（1.7 M 样本）。
小样本摸底：几百条任务时 val 可能为空，训练会提示并跳过闭环验证；R2 检查近邻对不足时 pass 为 null，不拦后续步骤。
返回码：3 = M5 两种头都没过；4 = R2 不过且 R2_STRICT=1；5 = R4 不过；6 = 生成进程崩溃（看 ml/data/log_*.txt，采样器连续失败会写明原因）；8 = MIN_GAP_MM 前后不一致；9 = 已有一条在跑；124 = 阶段超时。
生成阶段报「采样失败：…连续 N 次未命中」：多半是 collide.json 或关节限位变了，某类位形几乎不存在；把该日志发我。
浏览器只有 1 线程：没走 ml/serve.py（缺 COOP/COEP 头）。
查看器徽标「策略模式不可用」：看控制台报错，多为模型文件缺失、指纹或 TCP 不符。

文件地图

ml/
  pipeline.sh              一条龙阶段脚本（环境变量见文件头）；每阶段开始/结束经 pstate.py 写 runs/pipeline.json
  console.bat / console.sh 训练控制台一键启动（Windows / Linux）
  monitor.py  monitor.html 训练控制台：本地 HTTP 服务（开始/停止/进度/日志接口）+ 零依赖网页（地址带 ?demo=1 看示例数据）
  pstate.py                流水线状态 runs/pipeline.json、互斥锁 runs/pipeline.lock、阶段估时/超时表（唯一来源）
  gen/                     老师数据：sampler / teacher（确定性 PRM A*）/ cert.cjs（距离下界认证，实现在 ik-policy.js）/
                           pathdev.cjs（同伦类判定，共识过滤与一致性门禁用）/ timelaw / gen_dataset / consistency / stats / run_parallel.sh
  prep/                    export_kin.cjs（→ assets/kin.json）、build_dataset.cjs（→ samples/*.npy）、npy.cjs（.npy 写出）、run_prep.sh
  common/                  kin_torch.py（可微运动学 + 胶囊间隙）、features.py（83 维特征，与 JS 逐项一致）
  model/                   policy.py（Transformer + MeanFlow / WTA 头）、meanflow.py
  data.py  train.py        样本加载、预训练
  sim/closed_loop.py       部署节奏闭环仿真（验证 / 挖错 / 门禁）
  apg/apg_finetune.py      APG 可微微调
  mining/                  tasks.py（无老师出题）、mine_round.py、gate.py（含 R7）、loop.sh
  eval/                    dump_parity.cjs + check_parity.py（JS↔PyTorch 对拍）、check_r2.py（R2）、r4_probe.py（R4 无头浏览器探针）、acceptance.py（验收汇总）、
                           replay_teacher.py（开训前回放自检，含老师 oracle 走 rollout）、diag_cl.py（闭环失败定位 A/B/C/H）
  toy/toy_bimodal.py       2D 双模态对照实验（动作头选型依据）
  export_onnx.py  serve.py
  configs/                 base.json（MeanFlow）、wta.json（回退）、small.json（R4 不过时的 d=128）、apg.json
webapp/js/ik-policy.js       运行时：特征、距离下界认证、刹停、投影、精修、Runner（浏览器与 Node 共用）
webapp/js/ik-policy-glue.js  查看器接入（?policy=1；&threads= &proxy=0 &ep=webgpu &probe=1）
webapp/r4_probe.html         R4 探针页（r4_probe.py 打开）
tests/policy_bench.cjs       部署形态评测（nc / route / r8 / nc1000）

33 KiB Raw Blame History Unescape Escape