cbb/Robot_Arm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ml: 按运行手册审查修订——头分目录不互相覆盖（ml/runs/<CFG>、selected_ckpt/CKPT）；统一 $PYTHON（Windows Git Bash 可跑）；gen 按实测样本/任务自动补量；R10 改终态判据（≥5k 样本/s≈60k 步≤3.5h）；m5 纯策略/仿真安全层双口径；无老师题定长 6 s 口径；APG 展开随批时长、端点+中点铰链、余量 3 mm（投影同步）；挖错池只用本轮；门禁加 R7；bench 加 R8 对抗集与刹停率、--nc-n/--route-n/--r8-n；新增 check_r2 与 acceptance；export 默认 fp32；出题分块防 OOM；val 为空保护

Browse Source
This commit is contained in:
Hark
2026-10-18 06:40:24 +08:00
committed by cbb
parent 8800a68cad
commit f8cdabb781
18 changed files with 493 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ml/README.md
+94 -50
View File
@@ -3,32 +3,34 @@
目标：在你的机器上从零跑出 Transformer 避障策略，并在查看器里直接用上。
方案依据见 `docs/Transformer轨迹拟合训练方案.md`。所有命令在**仓库根目录**执行。
最省事的跑法是按阶段执行 `bash ml/pipeline.sh <阶段>`，每一阶段完成后看一眼本手册对应小节的「检查」再进下一步。
按阶段执行 `bash ml/pipeline.sh <阶段>`，每一阶段完成后看本手册对应小节的「检查」再进下一步。
| 阶段 | 命令 | 预计耗时（16 核 CPU + RTX 3090） | 产出 |
| 阶段 | 命令 | 预计耗时（28 核 CPU + RTX 3090） | 产出 |
|---|---|---|---|
| 1 环境 | `bash ml/pipeline.sh setup` | 10 分钟 | 依赖 |
| 2 对拍 | `bash ml/pipeline.sh kin` | 2 分钟 | `ml/assets/kin.json`、对拍 PASS |
| 2 对拍 | `bash ml/pipeline.sh kin` | 1 分钟（实测 7.6 s 对拍） | `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` |
| 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` | 以前 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` | — | — |
| 10 导出 | `bash ml/pipeline.sh export` | 1 分钟 | `webapp/models/traj_policy.onnx`（fp32） |
| 11 部署评测 | `bash ml/pipeline.sh bench` | 约 1 小时（Node CPU，1120 个任务） | `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 步外均为估算，以每步首次输出的速度为准。
第 2/4/5/6 步耗时为 RTX 3090 + 28 核实测换算，其余为估算，以每步首次输出的速度为准。
---
## 1. 环境
- Linux 或 WSL2；NVIDIA 驱动 + CUDA（`nvidia-smi` 能看到 3090）
- Linux / WSL2，或 **Windows 原生 + Git Bash**（实测第 2/4/5/6 步与闭环仿真可跑）；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`），再：
- 脚本统一用 `$PYTHON`（默认 `python`）。Linux 上没有 `python` 命令时：`export PYTHON=python3`。Windows 不要用 `python3`（那是 WindowsApps 假壳）
- 先按 CUDA 版本装 PyTorch（https://pytorch.org ），再：
```bash
git pull
@@ -50,59 +52,88 @@ bash ml/pipeline.sh kin
bash ml/pipeline.sh gate1
```
看 `consistentByGateRule`：≥ 0.90 直接生成；< 0.90 时第 4 步会自动加 `--consensus 4`（过滤与邻居绕法不一致的样本，生成成本约 5 倍）。也可手动用 `CONSENSUS=0/1` 覆盖。
看 `consistentByGateRule`：≥ 0.90 直接生成；< 0.90 时第 4 步自动加 `--consensus 4`（每条任务另跑 4 个 ±5 mm 邻居，与多数绕法不一致的样本丢弃，生成成本约 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
# 自定义：N_TASKS=50000 NPROC=28 CONSENSUS=1 TARGET_SAMPLES=1700000 bash ml/pipeline.sh gen
```
每条约 2 秒/核（不共识）。检查 `ml/data/stats.json`：`keepRate` 应在 0.95 左右，`byCatMode` 里 C 类（贴立柱）有足够样本，`projectedSamplesFor50k` 约 180 万。
不共识约 1.6 秒/条/核；共识约 8 秒/条/核。生成完自动统计；**样本数不足 `TARGET_SAMPLES`（默认 170 万）时按实测「样本/任务」自动补生成**（最多补 2 次），不用手动加 `N_TASKS`。
## 5. 打包训练样本
检查 `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（p10 预计约 3） | 同 | p10 < 2.5 mm：发我（APG 与投影的 3 mm 余量要随之下调） |
| `byCatMode` | C 类（贴立柱）各模式都有数千条 | 同 | — |
## 5. 打包训练样本 + R2 检查
```bash
bash ml/pipeline.sh prep
```
每条轨迹按 50 Hz 时间律重放，每 3 步取一个样本（特征与部署同一份 JS 代码计算）。检查 `ml/data/samples/index.json`：`train_samples` 约 170 万、`val_samples` 约 9 万。
每条轨迹按 50 Hz 时间律重放，每 3 步取一个样本（特征与部署同一份 JS 代码计算），30% 样本加 σ = 1° 噪声增广。
检查 `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% 步长）为通过；不通过先发我，不要直接训练。
## 6. 预训练
```bash
bash ml/pipeline.sh train
bash ml/pipeline.sh train # MeanFlow 头 → ml/runs/bench_base/、ml/runs/base/
```
先跑 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` 续训：
先跑 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。中断后续训（日志追加；新训练会覆盖旧日志）：
```bash
python -m ml.train --samples ml/data/samples --out ml/runs/base --resume ml/runs/base/last.pt
```
## 7. M5 门禁：MeanFlow 头是否可用
## 7. M5 门禁：选定动作头
```bash
bash ml/pipeline.sh m5
```
在 1000 个贴立柱任务上关安全层闭环运行。穿柱率 ≤ 2% 通过；不通过（或训练日志出现「训练发散」）则换预定回退的 WTA K=8 头重训：
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：
```bash
CFG=ml/configs/wta.json bash ml/pipeline.sh train && bash ml/pipeline.sh m5
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
bash ml/pipeline.sh apg
```
按部署节奏可微展开策略，直接优化到达、碰撞余量（5 mm）、平滑与行程，并保留 BC 锚定。每 500 步闭环验证，按到达率存 `best.pt`，完成后复制为 `ml/runs/current.pt`。
显存不够把 `configs/apg.json` 的 `batch` 降到 64。
按部署节奏（每次推理提交 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 − 间隙)`。3 mm ≈ 老师轨迹最小间隙的 p10（p50 4.4 mm），避免碰撞项与 BC 标签对抗；运行时投影余量同为 3 mm
- 显存不够把 `configs/apg.json` 的 `batch` 降到 64，或把 `seg_plans` 从 10 降到 5
## 9. 挖错循环
@@ -110,18 +141,21 @@ bash ml/pipeline.sh apg
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`。
每轮：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
bash ml/pipeline.sh export # fp16 ONNX + meta.json → webapp/models/
bash ml/pipeline.sh export # fp32 ONNX + meta.json → webapp/models/（约 20 MB）
```
fp16 转换报错时去掉 `--fp16` 手动导出 fp32（约 20 MB，同样可用）：
默认 fp32：部署走 wasm 与 Node CPU，fp16 在 CPU 后端上不保证更快。只有第 13 步用 `&ep=webgpu` 实测 `__POLICY.latency()` 明显受益时，才另导出 fp16 做对比：
```bash
python -m ml.export_onnx --ckpt ml/runs/current.pt --out webapp/models/traj_policy.onnx
pip install onnxconverter-common
python -m ml.export_onnx --ckpt ml/runs/current.pt --out webapp/models/traj_policy_fp16.onnx --fp16
```
## 11. 部署形态评测（策略 + 安全层）
@@ -130,11 +164,20 @@ python -m ml.export_onnx --ckpt ml/runs/current.pt --out webapp/models/traj_poli
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 步实测。
跑与浏览器同一份运行时（`webapp/js/ik-policy.js`）：贴立柱 30 例（pos、pose 各一遍）、直线被挡 40 例、R8 对抗 50 例（J1 起终差 ≥ 140°、终点贴立柱、两侧都要绕远）、一次性贴立柱扩展集 1000 例。各集合数量可用 `--nc-n` / `--route-n` / `--r8-n` 单独调。
## 12. 在查看器里使用
看 `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
bash ml/pipeline.sh accept
```
自己补跑 val 全部任务的闭环（开仿真安全层）：可达任务到达率 ≥ 98%、D 类停靠距离 ≤ 老师 + 5 mm、起步失败 = 0；再读第 5–11 步产物核对 R2、R7、R8、R10、M5 与部署形态各项。逐项打印「通过 / 未过」，结果在 `ml/runs/acceptance.json`。
## 13. 在查看器里使用
```bash
python -m arm.viewer.build_viewer # 若 webapp/generated/00_data.js 还没生成（查看器原有构建步骤）
@@ -147,24 +190,23 @@ python ml/serve.py # 带跨源隔离头的本地服务，wasm
- 工具偏移 ≠ 0 时自动交回原规划器
- 离线环境：把 onnxruntime-web 的 `ort.min.js` 与 wasm 文件放到 `webapp/vendor/ort/`，地址加 `&ortLocal=1`
## 13. 回传给我
每完成一步把对应文件发我即可，我据此判断下一步或改代码：
## 14. 回传给我
| 步骤 | 文件 |
|---|---|
| 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` |
| 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–12 | `ml/runs/policy_bench.json`、浏览器 `__POLICY.latency()` 输出 |
| 11–13 | `ml/runs/policy_bench.json`、`ml/runs/acceptance.json`、浏览器 `__POLICY.latency()` 输出 |
## 常见问题
- **指纹不符**：`collide.json` 变了。依次重跑第 2、4、5 步并重训。
- **训练发散**（loss 出现 nan/inf，自动停在 `diverged.pt`）：先把 `lr` 降到 5e-4 重试一次，仍发散就走 WTA 回退（第 7 步）。
- **显存不足**：降 `batch`；APG 还可把 `seg_plans` 从 10 降到 5。
- **显存/内存不足**：降 `batch`；APG 还可把 `seg_plans` 降到 5。出题与间隙计算已分块（每块 512 个位形）。
- **小样本摸底**：几百条任务时 val 可能为空，训练会提示并跳过闭环验证。
- **浏览器只有 1 线程**：没走 `ml/serve.py`（缺 COOP/COEP 头）。
- **查看器徽标「策略模式不可用」**：看控制台报错，多为模型文件缺失、指纹或 TCP 不符。
@@ -172,19 +214,21 @@ python ml/serve.py # 带跨源隔离头的本地服务，wasm
```
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
pipeline.sh 一条龙阶段脚本（环境变量见文件头）
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、loop.sh
eval/ dump_parity.cjs + check_parity.py（JS↔PyTorch 对拍）
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 部署形态评测
tests/policy_bench.cjs 部署形态评测（nc / route / r8 / nc1000）
```