Files

T

Hark 8bfe9bc083 ml: 全流程代码与运行手册（数据打包/可微运动学与对拍/MeanFlow+WTA 模型/训练/闭环仿真/APG/挖错循环/ONNX 导出）；webapp 策略运行时 ik-policy.js + ?policy=1 接入；tests/policy_bench.cjs；ik-solver 增 pairList/clusterExport/criticalPairs/pairGap/leverTable

2026-10-17 15:48:19 +00:00

9.0 KiB

Raw Blame History

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

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

最省事的跑法是按阶段执行 bash ml/pipeline.sh <阶段>，每一阶段完成后看一眼本手册对应小节的「检查」再进下一步。

阶段	命令	预计耗时（16 核 CPU + RTX 3090）	产出
1 环境	`bash ml/pipeline.sh setup`	10 分钟	依赖
2 对拍	`bash ml/pipeline.sh kin`	2 分钟	`ml/assets/kin.json`、对拍 PASS
3 老师门禁	`bash ml/pipeline.sh gate1`	25–30 分钟（单核）	`ml/data/consistency.json`
4 生成数据	`bash ml/pipeline.sh gen`	1–2 小时；加共识过滤 5–9 小时	`ml/data/shard_*.jsonl`、`stats.json`
5 打包样本	`bash ml/pipeline.sh prep`	15–30 分钟	`ml/data/samples/`
6 预训练	`bash ml/pipeline.sh train`	先 2000 步测速，正式约 1.5–6 小时	`ml/runs/base/best.pt`
7 M5 门禁	`bash ml/pipeline.sh m5`	10 分钟	`ml/runs/m5_gate.json`
8 APG 微调	`bash ml/pipeline.sh apg`	以前 100 步测速为准（预计 2–4 小时）	`ml/runs/apg/best.pt`
9 挖错循环	`bash ml/pipeline.sh mine`	每轮约 1–2 小时，3–6 轮	`ml/runs/current.pt`
10 导出	`bash ml/pipeline.sh export`	1 分钟	`webapp/models/traj_policy.onnx`
11 评测	`bash ml/pipeline.sh bench`	约 1 小时（Node CPU，1070 个任务）	`ml/runs/policy_bench.json`
12 使用	`python ml/serve.py` → 浏览器 `?policy=1`	—	—

耗时除第 4 步外均为估算，以每步首次输出的速度为准。

1. 环境

Linux 或 WSL2；NVIDIA 驱动 + CUDA（nvidia-smi 能看到 3090）
Node ≥ 18，Python 3.10–3.12
先按 CUDA 版本装 PyTorch（https://pytorch.org ，例：pip install torch --index-url https://download.pytorch.org/whl/cu124），再：

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

3. 老师一致性门禁

bash ml/pipeline.sh gate1

看 consistentByGateRule：≥ 0.90 直接生成；< 0.90 时第 4 步会自动加 --consensus 4（过滤与邻居绕法不一致的样本，生成成本约 5 倍）。也可手动用 CONSENSUS=0/1 覆盖。

4. 生成老师数据

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

每条约 2 秒/核（不共识）。检查 ml/data/stats.json：keepRate 应在 0.95 左右，byCatMode 里 C 类（贴立柱）有足够样本，projectedSamplesFor50k 约 180 万。

5. 打包训练样本

bash ml/pipeline.sh prep

每条轨迹按 50 Hz 时间律重放，每 3 步取一个样本（特征与部署同一份 JS 代码计算）。检查 ml/data/samples/index.json：train_samples 约 170 万、val_samples 约 9 万。

6. 预训练

bash ml/pipeline.sh train

先跑 2000 步测吞吐（ml/runs/bench/log.jsonl 的 samples_per_s），再正式训练到 configs/base.json 的 60000 步或闭环到达率连续 5 次不升为止。训练中每 2000 步打印一行 EVAL {...}：闭环（部署节奏）success 到达率、collision_rate、time_ok_1p3。显存不够就把 configs/base.json 的 batch 改成 512。中断后加 --resume ml/runs/base/last.pt 续训：

python -m ml.train --samples ml/data/samples --out ml/runs/base --resume ml/runs/base/last.pt

7. M5 门禁：MeanFlow 头是否可用

bash ml/pipeline.sh m5

在 1000 个贴立柱任务上关安全层闭环运行。穿柱率 ≤ 2% 通过；不通过（或训练日志出现「训练发散」）则换预定回退的 WTA K=8 头重训：

CFG=ml/configs/wta.json bash ml/pipeline.sh train && bash ml/pipeline.sh m5

8. APG 可微微调

bash ml/pipeline.sh apg

按部署节奏可微展开策略，直接优化到达、碰撞余量（5 mm）、平滑与行程，并保留 BC 锚定。每 500 步闭环验证，按到达率存 best.pt，完成后复制为 ml/runs/current.pt。显存不够把 configs/apg.json 的 batch 降到 64。

9. 挖错循环

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

每轮：5 万道新题关安全层作答 → 错题分类 E1–E5 → 错题与邻居进 APG 采样池 → E2（局部极小）请老师补少量路径 → APG 微调 → 门禁集比较，不达标自动回滚。连续 2 轮提升 < 0.5 个百分点自动停止。每轮报告在 ml/runs/mine/r*/report.md 与 gate.json。

10. 导出

bash ml/pipeline.sh export          # fp16 ONNX + meta.json → webapp/models/

fp16 转换报错时去掉 --fp16 手动导出 fp32（约 20 MB，同样可用）：

python -m ml.export_onnx --ckpt ml/runs/current.pt --out webapp/models/traj_policy.onnx

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

bash ml/pipeline.sh bench

跑与浏览器同一份运行时（webapp/js/ik-policy.js）：贴立柱 30 例（pos、pose 各一遍）、直线被挡 40 例、一次性贴立柱扩展集 1000 例。验收看 ml/runs/policy_bench.json：各集合 collisionFrames 必须为 0；near_column_* 的 ok 30/30；near_column_1000 0 失败为目标。 Node 里的推理/安全层耗时只作参考，浏览器延迟用第 12 步实测。

12. 在查看器里使用

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() 查看刹停、换向、精修次数
工具偏移 ≠ 0 时自动交回原规划器
离线环境：把 onnxruntime-web 的 ort.min.js 与 wasm 文件放到 webapp/vendor/ort/，地址加 &ortLocal=1

13. 回传给我

每完成一步把对应文件发我即可，我据此判断下一步或改代码：

步骤	文件
2	对拍输出（终端 JSON）
3–5	`ml/data/consistency.json`、`ml/data/stats.json`、`ml/data/samples/index.json`
6	`ml/runs/bench/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–12	`ml/runs/policy_bench.json`、浏览器 `__POLICY.latency()` 输出

常见问题

指纹不符：collide.json 变了。依次重跑第 2、4、5 步并重训。
训练发散（loss 出现 nan/inf，自动停在 diverged.pt）：先把 lr 降到 5e-4 重试一次，仍发散就走 WTA 回退（第 7 步）。
显存不足：降 batch；APG 还可把 seg_plans 从 10 降到 5。
浏览器只有 1 线程：没走 ml/serve.py（缺 COOP/COEP 头）。
查看器徽标「策略模式不可用」：看控制台报错，多为模型文件缺失、指纹或 TCP 不符。

文件地图

ml/
  pipeline.sh              一条龙阶段脚本
  gen/                     老师数据：sampler / teacher（确定性 PRM A*）/ timelaw / gen_dataset / consistency / stats / run_parallel.sh
  prep/                    export_kin.cjs（→ assets/kin.json）、build_dataset.cjs（→ samples/*.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、loop.sh
  eval/                    dump_parity.cjs + check_parity.py（JS↔PyTorch 对拍）
  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       部署形态评测

9.0 KiB Raw Blame History Unescape Escape