data-gen-bpu/HANDBOOK.md

102 lines
9.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# bench 掌控手册 —— 这套东西到底在做什么、你能控制什么、怎么判断好坏
写给不想读代码的人。读完这一页,你应该能回答三个问题:现在在跑什么、跑出来的东西能不能用、我改哪里能改变结果。
(细节口径在 `CONTRACT.md`,部署在 `README.md`,设计在 `../BPU量化轨迹工厂-设计方案.html`。)
## 一、它在做什么(一段话)
把 338 个视觉模型逐个量化编译到 BPU,每个“模型×芯片×配置”叫一个 **job**。GLM-5.3 Agent 自行准备输入、量化、编译和上板;harness 管理资源并用本次真实产物核验。一次执行的对话、工具调用和观测是一条 **rollout(轨迹)**。
流程:**领取任务 → Agent 执行 → 本次实测判定 → 导出并筛选训练候选**。
`bench run` 可以预热权重、FP32 基线和 ONNX 缓存。完整 Oracle 仅供显式对照,不是任务前置,也不参与成功判定、奖励或 SFT 筛选。FP32 仍是 INT8 精度的比较基线,两者使用同一评测集。
旧 Oracle、旧 repair 和已有结果保留。历史 repair 已获得失败现场,适合分析修复过程,不能当成独立完成任务的示范;尚未开始的旧 repair 保留编号但不再领取。
## 二、你能控制的东西(改这些文件,其他都是派生的)
| 你想改 | 改哪里 | 什么时候生效 |
|---|---|---|
| 跑哪些模型 / 优先级 | `registry/models.csv`(status 列 ready 才会进 run) | 下一个 `bench new-run` |
| 每个模型跑哪些芯片、几种配置、每个 job 采几条轨迹 | `registry/matrix.yaml` | 下一个 new-run |
| 四道门多严(G2 余弦阈值、G3 允许掉几个点) | `registry/gates.yaml` | 下一个 new-run(老 run 用它建 run 时的快照,不会偷偷变) |
| 用几张卡、几个 CPU 槽、agent 并发几个 | `config.yaml → pools` | 下一次 `bench run` / `bench collect` 启动 |
| agent 的轮数 / token 预算、用哪个模型 | `config.yaml → rollouts / endpoints` | 下一条 rollout |
| agent 看到的规则和旋钮表 | `agent/SYSTEM.md`、`agent/prompts/*.md` | 下一条 rollout;**改完必须把 `agent/VERSION` +1** |
| agent 的边界(能读什么、能写什么) | `agent/extensions/guard-core.js`(教学层)+ `scripts/agent_jail.sh`(物理隔离) | 下一条 rollout |
| 看门狗多久算卡死 | `config.yaml → watchdog.stall_s`(05-compile 自动用 long 车道 3600 s) | 下一个阶段 |
**不要手改的**:`runs/`、`state/`、`data/`、`cache/`(全是程序生成,append-only),`registry/models.csv` 在机器上生成、只从机器拉回(`scripts/sync.sh --pull`)。
**改完怎么上机**:只在本地这棵树改,`scripts/sync.sh` 推上去。它会先检查机器上有没有人直接改过,有就拒绝——这是防"两个人改一棵树互相覆盖"的闩。
## 三、日常六条命令
```
bench watch --run <run> 实时看板:每个 job 在哪个阶段、卡了多久、哪些 STALLED
bench status --run <run> [--fail] 一眼汇总 / 失败清单(按 error_class 分组)
bench show <job_id> 一个 job 的全部:oracle 结果、四道门、每条 rollout 的 verdict
python3 scripts/audit_rollouts.py --run <run> 每条 rollout 一行:能不能当数据、为什么不能 ← 判"可行不可行"就看这个
python3 scripts/trace.py <rollout_dir> 一条轨迹逐轮回放:agent 每一步读了什么、跑了什么、拿到什么
bench report --run <run> 静态 HTML 报告(reports/<run>.html)
```
启动/续跑:`scripts/start_run.sh --target s100p|s600 --note "..."`(一个 run 只跑一种板型)、`bench collect --run <run> [--job …] [--limit N]`(采轨迹)。
换代码/改配置要重启调度器时:`bench drain --run <run>`(跑完手里的不再认领新 job)→ 等它退出 → `scripts/start_run.sh --resume --run <run>`。不要 kill 正在编译的进程。
注意常驻进程里的代码是启动那一刻的:改了 harness/ 或 config.yaml,正在跑的 `bench run` / `bench collect` 不会变,新起的才会。
两条自检:`node agent/extensions/guard-core.test.js`(边界判定单测)、`scripts/guard_smoke.sh`(起真 pi 进程试图越界,应全部被拒)。
## 四、怎么判断一条 rollout 好不好
先说结论:**不看 claim(agent 自己说的),看 verdict(harness 核验的);不看它"跑完了没",看它"是不是干净地跑完的"。**
`audit_rollouts.py` 每行给的原因就是判据,含义如下:
| 原因 | 意思 | 能当数据吗 |
|---|---|---|
| `oracle_read×N` | agent 成功读了 `<job>/oracle/…`(标准答案) | **不能**。PASS 也是抄的 |
| `sibling_read×N` | 读了同一 job 别的 rollout | **不能**。GRPO 要求组内独立 |
| `stalled_killed` | 05-compile 被看门狗按 900 s 误杀 | **不能当负样本**——不是 agent 的错(已修:compile 走 3600 s 车道) |
| `old_version(vX<Y)` | 用旧一版的提示词/边界跑的 | 导出默认过滤,留档不删 |
| 历史 `claim_absent` / `claim_mismatch` | 旧审计标签;当前 claim 可选 | 不据此扣分或拒收。候选内容是否有实质虚报由单次审核检查 |
| `harness/toolchain_read×N` | 去读评判代码或工具链源码 | 不算污染,但说明提示词没把它劝住,预算会被这个烧掉 |
| 干净 + `RL ✓` | 初步审计合格 | 仍需核验结果与训练分组,不代表已可直接训练 |
| `SFT ✓` | 独立执行、实测 PASS、对话和工具记录完整且单次内容审核通过 | 成功 SFT 候选 |
想亲手看一条:`trace.py` 回放里盯这几个词——`oracle`、`rollouts/0X`(不是自己的编号)、`harness/`、`site-packages`、`path-guard:`(被拒的那一下)、自然终答(结论是否有依据)、`bench stage run`(真正干活的提交)。常见 e2e 流程是:读 job.json → 按需准备输入 → 写配置 → 编译并检查日志 → 检查 HBM → 上板评测 → 自然终答。具体步骤由 Agent 根据观测决定。
## 五、失败的轨迹要删吗
**不删。** 理由不是舍不得,是这三条:
1. 它们是复盘证据。convnext#2 那条"编译成功但预算没撑到 eval"、resnet18#0 那条"被看门狗误杀",都是靠原始轨迹才定位到 bug 的。删了下次同样的坑还得再踩一次才知道。
2. 训练数据的过滤在**导出时**做:`export/to_agentrl.py --min-agent-version 5` 只收新口径;`audit_rollouts.py --annotate` 把污染结论写进 `annotations` 表。数据集干净与磁盘上留不留无关。
3. 版本号是给你追溯用的:`rollout.json.agent_config_version` 记着这条轨迹是在哪一版规则下跑的。每次改 SYSTEM.md/prompts/extensions 就 +1,旧版本的自然被过滤掉,不需要删。
同理 job/run 也不删:一个 run 的口径(venv、registry、门阈值)变了就开新 run,老 run 留着对照。
## 六、"怎么一直有问题、能不能一次修好"——诚实的回答
前面 4 版 guard 每一版都被绕过,是因为它做的是**解析 agent 写的 shell 字符串**——这类防线永远追不平所有写法(换行 cd、`$IFS`、`$(...)`、软链……)。现在改成两层:
- `scripts/agent_jail.sh`:mount namespace 把 `oracle/`、别的 rollout、编译工作目录里别人的东西**直接从文件系统里摘掉**。进程看不见的东西,再多绕法也没用。这层不解析任何字符串,所以不会再有"新写法绕过"这一类 bug。
- `guard-core.js`:退化成教学层,给 agent 一句人话的拒绝理由,省它的预算。它被绕过也不再泄漏。
**jail 藏不住的一样东西**:LLM key(`~/.pi/agent/models.json`)。pi 进程自己要读它,同一进程里跑的 bash 就一定读得到。这是结构性的,靠 guard 拒 token + 定期轮换 key 兜底,别指望 jail。
能"一次修好"的部分已经修好(隔离、误杀、旋钮表、`--config` 路径);剩下的是 agent 行为层面的调优(它是否无效探索、结论是否有依据),那只能靠跑、audit、改提示词、+1 版本,循环。日常同时看实际启动与合格样本数、主要丢样原因、每条合格数据的总成本和耗时;旧 `RL ✓` 标签不是发布或训练完成证明。
## 七、v4 部署时的历史快照(2026-09-15)
- r20260915-03 里 11 条已完成 rollout **0 条可用**(7 条读了 oracle、3 条被误杀、其余是旧版本),已全部 `--annotate` 标注,不删。
- v4(jail + guard-core v4 + compile long 车道 + 提示词修正)已上机;canary:`cls--resnet18--nash-e--ptq--int8` #02 在 jail 里跑,3 次工具调用就写出 compile.yaml 提交编译,没有任何侦察。
- canary 干净跑完(`audit_rollouts.py` 显示 `RL ✓`)之后再放剩下 113 条:`bench collect --run r20260915-03`。
## 八、v5 修复与验证(2026-09-15)
v5 已把阶段执行移到 jail 外部 worker,state/其他 job 与评判代码被隐藏,任务输入与阶段产物只读;
命令客户端仅写 handles,pi 自身输出写 workspace 后由外部驱动收存。旧常驻 collect 不会热加载新驱动,后续采集需新进程。
导出默认最低版本5并读取污染/误杀 annotations,旧9份数据集已新增 VOID 标记。
`bench heartbeat --run <run>` 正常无输出退出0,异常退出1;`bench watch` 非TTY仅输出一次。
完整实测、审计前后对比和未覆盖项见 [REPORT-codex.md](docs/archive/REPORT-codex.md)。本节取代上面 v4 的“当前”状态描述。