data-gen-bpu/CONTRACT.md

10 KiB
Raw Blame History

bench/ 契约(CONTRACT v0.4 落地版)

本文件是《BPU 量化轨迹工厂 设计方案 v0.4》的可执行摘要。代码与本文件冲突时,以本文件为准并修代码;本文件与设计方案冲突时,先改设计方案再改这里。

0. 三条原则

  1. harness 是 oracle。 每个 job 先由确定性流水线跑出 ground truth(oracle/result.json)。agent 的表现永远相对 oracle 衡量。
  2. agent 只有一个可写区。 rollouts/<kk>/workspace/。job.json、harness/eval/、data/、cache/ 全部只读。agent 说什么不算数,verdict 才算数。
  3. Append-only。 run_id 冻结;换工具链、改配置、修 bug 都开新 run。manifest.json 记两套 venv 的 pip freeze sha256,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,job UNVERIFIED。
  • 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 贴过来,不直接改