10 KiB
bench/ 契约(CONTRACT v0.4 落地版)
本文件是《BPU 量化轨迹工厂 设计方案 v0.4》的可执行摘要。代码与本文件冲突时,以本文件为准并修代码;本文件与设计方案冲突时,先改设计方案再改这里。
0. 三条原则
- harness 是 oracle。 每个 job 先由确定性流水线跑出 ground truth(
oracle/result.json)。agent 的表现永远相对 oracle 衡量。 - agent 只有一个可写区。
rollouts/<kk>/workspace/。job.json、harness/eval/、data/、cache/全部只读。agent 说什么不算数,verdict 才算数。 - Append-only。
run_id冻结;换工具链、改配置、修 bug 都开新 run。manifest.json记两套 venv 的pip freezesha256,job 启动前比对,不一致拒跑。状态只在state/jobs.sqlite,文件系统只存内容。
1. 目录
bench/
├── CONTRACT.md README.md config.yaml requirements.txt
├── bin/bench # CLI 入口
├── registry/ # 输入 · 不可变 · git 管理
│ ├── models.csv matrix.yaml gates.yaml budgets.yaml datasets.yaml boards.yaml
├── data/ # 只读 · agent 永不下载
│ ├── pool/<dataset>/<version>/ # 全量 + manifest.json
│ ├── t1/<dataset>/<seed>.tar # smoke 子集,单包
│ └── calib/<task>/<input_spec>/ # npy,与 val 零交集
├── cache/{weights,onnx}/<sha256>/ cache/baseline/<model>--<dataset>/
├── harness/ # L1 + L3
│ ├── pipeline.py scheduler.py watchdog.py registry.py db.py errors.py gates.py
│ ├── stages/ backends/{ptq,qat}.py eval/
├── agent/ # L2 pi 配置
│ ├── SYSTEM.md settings.json.tmpl models.json.tmpl prompts/ extensions/
├── export/{to_agentrl,redact,reward}.py
├── scripts/ # 一次性:入池、Excel 转换、环境修补、板卡探测
├── state/jobs.sqlite reports/ datasets/<dataset_id>/
└── runs/<run_id>/
├── manifest.json
└── <job_id>/
├── job.json # 只读 · 输入契约
├── oracle/stages/<NN>-<name>/{stdout.log,stderr.log,exit_code,meta.json}
├── oracle/artifacts/<job_id>.{onnx,bc,hbm}
├── oracle/result.json
└── rollouts/<kk>/{workspace/, agent/{session.jsonl,events.jsonl}, claim.json, verdict.json}
2. 命名
| 标识 | 格式 | 示例 |
|---|---|---|
| run_id | r<YYYYMMDD>-<seq> |
r20260914-01 |
| job_id | <task>--<model>--<march>--<backend>--<qcfg> |
det--yolov8n--nash-e--ptq--int8 |
| task | 10 类固定 | cls det seg iseg pose mde stereo flow feat occ |
| march | nash-e / nash-m / nash-p |
s100→e · s100p→m · s600→p |
| qcfg | 段内 a-z0-9. |
int8 · fp16int8 |
| rollout | <job_id>/rollouts/<kk> |
…/rollouts/03 |
| stage | <NN>-<name> |
01-fetch 02-baseline 03-export 04-calibrate 05-compile 06-hbm 07-board 08-eval |
| dataset_id | ds<YYYYMMDD>-<seq> |
ds20260914-01 |
段内字符集 [a-z0-9.],段间 --。job_id 既是目录名也是 join key。
3. 状态机
job(由 oracle 决定):PENDING → ORACLE_RUNNING → PASS | FAIL | UNVERIFIED
rollout(由 verdict 决定):QUEUED → RUNNING → VERIFYING → PASS | FAIL | BLOCKED | TIMEOUT
- PASS = 必选门全部 pass。
- 门无法判定(数据缺、板未接)→ 该门
unverified,jobUNVERIFIED。 na(本轮设计上不评)≠unverified(本该评没评成)。na 不阻塞 PASS。- BLOCKED 判定:oracle 同阶段同类 error_class 失败 → 正确;oracle 通过 → 误判。
4. 四道门
| 门 | 必选 | 判定 |
|---|---|---|
| G1 compile | 是 | .hbm 存在;hb_model_info 的 march / 输入 dtype / layout 与 job.json 一致;hb_verifier 通过;日志无 ERROR |
| G2 numeric | 是 | 校准外样本逐输出余弦 ≥ 阈值(默认 0.99;occ 0.97;feat 逐输出);只报 min |
| G3 task | 是 | 量化实测 − FP32 基线在容差内;kind 必须显式 abs_pp 或 rel_pct;T1 上记 pass-screen,T2 上才 pass |
| G4 perf | 否 | 仅 job.json 有 latency_budget_ms 才判;mean 与 p95 分开存 |
5. 数据三档
| 档 | 用途 | 规模 |
|---|---|---|
| T0 calib | PTQ 校准 | 128–512,train 抽,与 val 零交集 |
| T1 smoke | 默认门 | cls 2000 · det/iseg/pose 1000 · seg 500 · 其余全量 |
| T2 full | 交付数 | 完整 val,开新 run |
复制入池,不软链;chmod -R a-w;manifest.json 记 sha256/数量/来源/日期。T1 打成单 tar 避开 JuiceFS 小文件。
6. 调度与看门狗
- 池:
gpu 4 · cpu 8 · board 1 · agent 3。板卡严格串行带锁。 - 没有固定超时。 STALLED = 日志
stall_s(900 s)不增长 且 进程树 CPU < 5%。硬上限 24 h 只是保险。 - 重阶段(compile / board / eval)由 harness 执行。agent 走
bench stage run/bench stage wait,不在 bash 里跑 hb_compile。 - rollout 预算 = turns + tokens;墙钟 12 h 仅防挂死。
7. 重试与轨迹边界
| 层 | 谁 | 触发 | 轨迹 |
|---|---|---|---|
| oracle 阶段 | harness | 瞬态 error_class | 不是轨迹 |
| rollout 内 | agent | 自己改配置重提 | 同一条轨迹 |
| 新 rollout | harness | matrix k | 全新轨迹,永不串联 |
| repair | harness | oracle FAIL | 全新轨迹,输入是 oracle 现场 |
agent 的读写边界(path-guard,2026-09-15 起为读白名单):agent 的 cwd 是 <job>/rollouts/<kk>/workspace/,只能写这里(与 /tmp)。
可读:workspace、本 rollout 根(agent/ stages/ handles/ rollout.json)、<job>/job.json、<job>/data、bench/data、bench/cache、bench/bin、.horizon/、AGENTS.md、本 rollout 在 work_root 下的编译工作目录;repair 额外可读 <job>/oracle/。
项目树内其余一律拒——别的 rollout(GRPO 组内独立性)、e2e 的 oracle/、harness/、state/、export/、别的 job;项目树外拒 ~/.pi、~/toolchains、bench/.env.local、state/ 与 work_root 的真实路径。
bash 里 cd/pushd/popd 一律拒(唯一例外 cd <自己的 workspace>,换行后的 cd 也算——^ 要带 m);命令替换 $(…)/反引号、$IFS、路径里的 $VAR/ 一律拒(都是把路径藏起来躲过 token 扫描的手段);剩下像路径的 token 逐个判(glob 取前缀、相对路径按 cwd 解析)。每个 token 判两次:原路径与 realpath,两次都过才放行——否则 workspace 里 ln -s ../../../oracle o 再 cat o/result.json 就绕过去了(read 工具也一样)。$HOME 下默认全拒(~/.pi、~/toolchains、bench-state、bench-work 都在那儿),只放行 ALLOW_EXTRA 与白名单目录的真实路径。
但 guard 只是教学层,不是防线。 解析 shell 字符串的白名单每一轮都还能找到新绕法(v3 就被换行 cd、$IFS、$VAR/ 拼接、workspace 内软链四种手法穿透)。真正的隔离是 scripts/agent_jail.sh:unshare -rm 起 mount namespace,把 <job>/oracle(e2e)、所有兄弟 rollout、~/.pi、.env.local 用空目录//dev/null bind 掉,进程根本看不见。非 root 可用,不影响 bench stage run detach 出去的子进程读写 work_root/state。rollout.py 起 pi 时包这一层。
判定核心 agent/extensions/guard-core.js 有单测(node agent/extensions/guard-core.test.js),真机自检 scripts/guard_smoke.sh。每次拒绝记 agent/guard.log。
改了 SYSTEM.md / prompts / extensions 就 agent/VERSION +1(当前 4),rollout.json 记 agent_config_version,导出按版本筛。
8. error_class
unsupported_op shape_infer export_fail calib_nan verifier_mismatch(确定性,不重试)
oom board_offline stalled(瞬态,重试 ≤ 2 / ≤ 2 / 1)
unknown(进人工分类队列)
9. reward(v0,离线算,配方版本化)
r = 1.0[G1] + 1.0[G2] + 2.0[G3]
r += 1.0·clip((Δ_agent − Δ_oracle)/|tol|, −1, 1)
r += 0.5·clip((lat_oracle − lat_agent)/lat_oracle, −1, 1)
r −= 0.5·turns/max_turns + 0.5·tokens/max_tokens
r −= 2.0[claim ≠ verdict]
BLOCKED: +1.0 若 oracle 同类失败 else −2.0 ;TIMEOUT: −1.0
G3 = na 时其 2.0 权重按比例分给 G1/G2,精度相对项取 0
10. 两套 venv
| backend | venv | 关键版本 |
|---|---|---|
| ptq | ~/toolchains/oe-3.7.0/venv |
hbdk4 4.7.5 · horizon_tc_ui 3.5.3 · hmct 2.6.5 |
| qat | ~/toolchains/oellm2/venv |
hbdk4 4.12.3a2 · horizon_plugin_pytorch 3.3.5 |
harness 按 backend 选解释器。禁止把 backend 判断交给 agent。
11. 下游边界
~/data_collect 零耦合。只搬清洗规则 R1–R8 与 redact,落在 export/,不 import。
12. 协作规则(2026-09-15 起,两个会话同时改一棵树踩过一次)
- 只有一个写者能改一层。 分层:
harness/(oracle 流水线、阶段、门、调度)·agent/(pi 配置、扩展、提示词)·export/(清洗、脱敏、reward)·registry/(清单与阈值,改了就是新 run)·scripts/。谁在改哪层写进下面的表;别的会话对那层只读。 - 改动只发生在本地副本,机器上不直接改代码。 流程:改 →
git commit(scripts/sync.sh会自动提交)→scripts/sync.sh推送。sync 带守卫:远端自上次推送后被动过就拒绝,先合并再推。 registry/models.csv是在机器上由excel_to_models.py生成的,方向反过来:scripts/sync.sh --pull。- 机器上的
runs/ state/ data/ cache/ datasets/是数据,不同步、不手改;改判走bench rejudge,补测走bench board-backfill。 - 正在跑的调度进程(
bench run/bench collect)加载的是启动时的代码;改了 harness 只对新进程生效,子进程工具(harness.tools.*、harness.eval.run)立刻生效——改评测口径必须同时升EVALUATOR_VERSION。
| 层 | 当前写者 |
|---|---|
| harness/ agent/ export/ scripts/ registry/ | 本会话(Cowork · bench 主线) |
| 其他会话 | 只读;发现问题写成 issue 贴过来,不直接改 |