Robot_Arm/ml/README.md

机械臂避障策略：从数据到部署的运行手册

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

一键运行：Windows 双击 ml/console.bat（Linux/WSL 运行 bash ml/console.sh），浏览器自动打开训练控制台 http://localhost:8100/，点「开始训练」选好起止阶段即从对拍一路跑到验收，全程进度、曲线、终端输出都在网页上，可随时停止、从停下的那一步继续（见「训练控制台」）。 也可以在终端按阶段执行 bash ml/pipeline.sh <阶段>，或 bash ml/pipeline.sh all 一次跑完；每一阶段完成后看本手册对应小节的「检查」。R2（第 5 步）或 M5（第 7 步）不通过时一键流程会停下，按对应小节处理。

阶段	命令	预计耗时（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 → 浏览器测	10 分钟	浏览器 __POLICY.latency() 输出
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 分钟，正式约 3 小时	ml/runs/base/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 出题约 2 秒/题）	ml/runs/policy_bench.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′ 步（R4，需要在浏览器里看延迟）建议先手动做；一键流程默认从第 2 步开始。

---

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，这一步、数据、模型都要重来（指纹不符时各脚本会拒绝运行）。

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

bash ml/pipeline.sh r4              # 随机初始化 4.92 M 模型导出 fp32 ONNX 到 webapp/models/
python ml/serve.py                  # 浏览器打开 http://localhost:8000/?policy=1 ，来回拖动黄球约 1 分钟

控制台运行 __POLICY.latency()：推理 batch=8 P99 < 15 ms、安全层 P99 < 15 ms 为通过（随机权重的动作是乱的，手臂会乱动或频繁刹停，这一步只看延迟）。 不通过：把 ml/configs/base.json 的 model.d 从 192 改为 128（ff 改 512）后重跑 r4；仍不通过再加 &ep=webgpu 对比。把输出发我。

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 代码计算），30% 样本加 σ = 1° 噪声增广（加噪后间隙 < 3 mm 的不用）。 认证最小间隙 < 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）。 随后自动跑 R2 检查（ml/data/r2.json）：近邻样本前 3 步标签差 label_std_mean < 0.10（10% 步长）为通过；不通过时这一步以返回码 4 结束、一键流程停下，先把 r2.json 发我。小样本时近邻对不足，pass 为 null，不拦。

6. 预训练

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

先跑 2000 步测吞吐（ml/runs/bench_base/log.jsonl 的 samples_per_s，eta_h 是剩余小时数），再正式训练到 60000 步或闭环到达率连续 5 次不升为止。

• 通过线（R10）：samples_per_s ≥ 5000，即 60000 步 ≤ 3.5 小时。参考：3090、batch 1024 实测 6.2 k 样本/s ≈ 2.8 小时。MeanFlow 的 JVP 双前向使训练受算力限制，加大 batch 不会提高样本/s；低于通过线时把 configs/base.json 的 fk_caps 从 96 降到 48，仍不够再把 steps 降到 40000
• 训练中每 2000 步打印一行 EVAL {...}：val 任务闭环（部署节奏、不开安全层）success、collision_rate、time_ok_1p3、start_fail。时限 = 老师时长 × 2（至少 3 s）
• 显存不够把 batch 改成 512。中断后续训（日志追加；新训练会覆盖旧日志）：

python -m ml.train --samples ml/data/samples --out ml/runs/base --resume ml/runs/base/last.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 头。WTA 的产物在独立目录，不会覆盖 MeanFlow：

CFG=ml/configs/wta.json bash ml/pipeline.sh train    # → ml/runs/bench_wta/、ml/runs/wta/
CFG=ml/configs/wta.json bash ml/pipeline.sh m5       # → ml/runs/m5_gate_wta.json；通过则选定 wta

需要强制指定后续阶段的起点模型时用 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 降到 64，或把 seg_plans 从 10 降到 5

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 → webapp/models/（约 20 MB）

默认 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。 Node 里的推理/安全层耗时只作参考，浏览器延迟用第 13 步实测。

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() 查看刹停、换向、精修次数
• 运行时投影护栏 5 mm：候选动作离障碍 < 5 mm 时沿间隙梯度外推（训练数据的过滤线是 3 mm，护栏比数据更保守）
• 工具偏移 ≠ 0 时自动交回原规划器
• 离线环境：把 onnxruntime-web 的 ort.min.js 与 wasm 文件放到 webapp/vendor/ort/，地址加 &ortLocal=1

14. 回传给我

步骤	文件
2	对拍输出（终端 JSON）、R4 的 __POLICY.latency() 输出
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/acceptance.json、浏览器 __POLICY.latency() 输出
任一步出错	ml/runs/pipeline.json、ml/runs/console.log（控制台启动时）或终端输出

训练控制台

Windows：双击 ml/console.bat          Linux / WSL：bash ml/console.sh
（等价于 python -m ml.monitor --open，需要训练用的 Python 环境；Windows 另需 Git for Windows 提供的 Git Bash）

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

开始：点右上角「▶ 开始训练」→ 选起始/结束阶段（默认从第一个还没成功完成的阶段到「验收汇总」）、动作头、共识过滤、任务数、进程数、目标样本数、挖错轮数 → 「开始」。控制台在后台执行 bash ml/pipeline.sh all（FROM/TO 即起止阶段），用的是启动控制台的同一个 Python。 停止：「■ 停止」结束整个进程树，这一步记为「已停止」，已完成的步骤保留；再点「开始」默认从这一步继续。 网页可以随时关，训练不受影响，重新打开即可接着看；关闭控制台窗口会结束训练，要关终端继续跑，Linux 用 nohup bash ml/console.sh &。 终端里直接跑的 bash ml/pipeline.sh … 同样会显示进度（只是不能在网页上停止）；控制台检测到终端里有阶段在跑时不会重复开始。

页面内容，从上到下：

区域	内容	数据来源
流水线	11 个阶段的状态（完成 / 运行中 / 失败 / 已停止 / 未开始）与各步用时	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 = 两遍评估；对拍、老师门禁、导出、部署评测、验收无法计量，显示用时与粗估。全流程百分比与剩余时间按手册表格的粗估耗时加权，只作参考。

同一局域网的手机或其他电脑要看：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。出题与间隙计算已分块（每块 512 个位形）。
• 小样本摸底：几百条任务时 val 可能为空，训练会提示并跳过闭环验证；R2 检查近邻对不足时 pass 为 null，不拦后续步骤。
• all 在第 7 步中止：M5 门禁不通过时有意退出（返回码 3），按第 7 步换 WTA 头。
• 浏览器只有 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                流水线状态文件读写
  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）、acceptance.py（验收汇总）
  toy/toy_bimodal.py       2D 双模态对照实验（动作头选型依据）
  export_onnx.py  serve.py
  configs/                 base.json（MeanFlow）、wta.json（回退）、apg.json
webapp/js/ik-policy.js       运行时：特征、距离下界认证、刹停、投影、精修、Runner（浏览器与 Node 共用）
webapp/js/ik-policy-glue.js  查看器接入（?policy=1）
tests/policy_bench.cjs       部署形态评测（nc / route / r8 / nc1000）