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

目标：在你的机器上从零跑出 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`），再：

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

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

```bash
bash ml/pipeline.sh kin
```

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

## 3. 老师一致性门禁

```bash
bash ml/pipeline.sh gate1
```

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

## 4. 生成老师数据

```bash
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
bash ml/pipeline.sh prep
```

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

## 6. 预训练

```bash
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` 续训：

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

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

```bash
bash ml/pipeline.sh m5
```

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

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

## 8. APG 可微微调

```bash
bash ml/pipeline.sh apg
```

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

## 9. 挖错循环

```bash
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
bash ml/pipeline.sh export          # fp16 ONNX + meta.json → webapp/models/
```

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

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

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

```bash
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. 在查看器里使用

```bash
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       部署形态评测
```