data-gen-bpu/HANDBOOK.md

9.5 KiB
Raw Blame History

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。本节取代上面 v4 的“当前”状态描述。