data-gen-bpu/CONTRACT.md

201 lines
18 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 v0.4 落地版)
本文件是《BPU 量化轨迹工厂 设计方案 v0.4》的可执行摘要。代码与本文件冲突时,以本文件为准并修代码;本文件与设计方案冲突时,先改设计方案再改这里。
2026-09-16 按当前目标收敛:默认运行 CSV 中 ready 模型的 S100P(`nash-m`)量化、编译、上板与精度评测,并为这些模型采集真实 Agent 轨迹。新 run 必须固定一个 target:S100P=`nash-m`,S600=`nash-p`;target 只收窄本 run 的 matrix 展开,不修改旧 run 或全局默认。`collect --coverage all` 为本 run 的 oracle 模型补齐 e2e 计划:只去掉 matrix 的 priority 限制,保留任务类型、run target、backend、policy 和 k。已结束的流程和 Agent 轨迹都必须导出为数据,成功、精度未达标、预算耗尽分别标注,导出不能阻塞上板。
2026-09-16 全 338 项覆盖补充:保持原 CSV 标签和历史 run。新批次可用 `expand --model` 显式选择模型,
前置检查依据实际权重入口、构建/导出代码、评测器、校准、数据与附加门;新增 Ultralytics 任务还必须有真实
checkpoint/ONNX/指标对照证据,缺项即拒绝入队。具名批次只放宽 priority/task/status 选择,保留原 march、
backend、policy、k 和精度门。任务快照记录 admission 来源,不能把 admission 或 probe 等同于编译/上板通过。
`collect --first-pass` 每个 job 只领取首条,重复采样仍保持 QUEUED,不改 kk、不补造轨迹。
`coverage --all-runs` 总表包含全部 CSV 行,独立列出前置阻塞、实际阶段、原始响应中的 teacher 身份和训练导出;
传统算法仍保留条目并说明 PTQ 不适用。FastSAM 的类别语义未补齐前不能入队。
Pose 须有真实导出的关键点对应证据;板端同时判定 OKS AP 与平均原图坐标偏移 ≤2px。
对应由同图人框 IoU≥0.5 一对一匹配确定,统计全部17点,保留未匹配记录;无匹配或缺证据为 UNVERIFIED。
## 0. 三条原则
1. **Agent 独立完成任务。** GLM-5.3 可直接领取 e2e,自行调用输入准备、量化、编译和上板工具;`bench run` 可选地预热 01–03 缓存。harness 分配资源、核验本次 HBM 的实测精度并保存轨迹。完整 Oracle 仅用显式 `bench run --oracle` 作历史对照或排查,不参与 Agent 执行、成功判定、奖励或 SFT 筛选。
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 输入准备**:`PENDING → ORACLE_RUNNING → PREPARED | FAIL | UNVERIFIED`(沿用现有运行态名称)。
`PREPARED` 只表示 01–03 成功,写 `oracle/preparation.json`,不产生 Oracle verdict,也不代表适配或精度通过。显式 `--oracle` 可从 PENDING/PREPARED 跑完整 01–08,写 `oracle/result.json`,终态仍为 PASS/FAIL/UNVERIFIED。默认准备命令不覆盖已结束任务。
**rollout(由实际核验结果决定)**:`QUEUED → RUNNING → VERIFYING → PASS | FAIL | BLOCKED | UNVERIFIED`
Agent 执行是否结束/超预算独立记录在 `verdict.execution_terminal`、`timeout_reason`,不再用 `TIMEOUT` 覆盖已经核验的结果。`completion` 分别记录编译、HBM、真实上板、精度评测是否完成及精度是否达标。预算用尽但必选门已通过仍为 PASS;没做到的阶段为未完成,不凭预算耗尽推断模型失败。旧 TIMEOUT 可用 `bench verify` 按原 job 门槛重核,无需重编。
- PASS = 必选门全部 pass。
- 门无法判定(数据缺、板未接)→ 该门 `unverified`,job `UNVERIFIED`。
- `na`(本轮设计上不评)≠ `unverified`(本该评没评成)。na 不阻塞 PASS。
- BLOCKED 记录 Agent 的阻塞报告和本次实测。失败日志不能证明任务不可解,`blocked_correct` 不作推断;不进入成功 SFT 或奖励学习候选。
## 4. 四道门
| 门 | 必选 | 判定 |
|---|---|---|
| G1 compile | 是 | .hbm 存在;`hb_model_info` 的 march / 输入 dtype / layout 与 job.json 一致;`hb_verifier` 通过;日志无 ERROR |
| G2 numeric | 否 | 校准外样本逐输出余弦用于诊断,记录 min;编译一致性由 G1 单独核验 |
| G3 task | 是 | 同一 T1、同一预处理和评测器,板卡 HBM 真实输出相对 FP32 的任务指标劣化 ≤ 5%,改善通过;`rel_pct`,不放宽阈值;T1 上记 `pass-screen`,T2 上才 `pass` |
| G4 perf | 否 | 仅 job.json 有 `latency_budget_ms` 才判;mean 与 p95 分开存 |
07-board 记录性能,08-eval 用板卡输出计算任务精度;两者按 job 的 march 领取兼容的空闲板,每块物理板共用一个跨进程锁,凭证只进入这两个受信任阶段的子进程。两个阶段可分别领取同 march 的不同板,实际板名和槽位写入阶段证据。没有兼容板卡时 G3 为 unverified,不回退模拟器冒充上板。
旧 job 的板卡字段为空时按 march 查询当前注册板卡;非空但 march 不匹配则报错。`board-backfill` 复用已有 HBM,补缺失的性能和板端精度,不重编。
新 job 使用新门槛,历史 job 仍按冻结的门槛重判。评测器 0.5 保持 0.4 的 FP32 预处理与指标公式,允许复用其基线;实测文件另记执行版本、输出来源和 HBM SHA256。
## 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 24 · agent 12`;board 容量来自 `registry/boards.yaml` 中启用的实际板卡数量。不同板可并行,同一板严格串行带锁。
- 板卡登记使用固定且唯一的 `slot`,对应 `board-<slot>.lock`;现有板保留 slot 0 以兼容在途旧进程。新增板使用新槽位,删除/禁用板卡后不复用槽位;重复接入同一地址不能增加容量。只把实际独立、运行库兼容的物理板加入池。新增/禁用板卡是调度资源变更,不重写冻结的 job 或已生成 HBM。新调度进程等待时重读板卡登记;旧进程仍需自然收尾后更换。
- 新 run 的任务指纹不包含板卡设备列表,但仍包含 march 映射与其他 registry 内容。旧 run 扩板前把原始 `boards.yaml` 保存为 `board_registry.initial.yaml`;续跑时用该快照验证旧整体指纹,证明除板卡设备列表外的输入未变,不能跳过模型、数据、门槛、工具链校验。
- **没有固定超时。** STALLED = 日志 `stall_s`(900 s)不增长 且 进程树 CPU < 5%。硬上限 24 h 只是保险。
- 板端 RPC 的原有单次 3600 秒上限由独立 `board_guard` 在板上执行;SSH stdin 租约每 5 秒刷新,断连或 30 秒失联回收本次进程组。守护进程不加载模型,避免原生运行库阻塞清理。板端互斥锁由守护进程和推理子进程共同持有,未清空不能交给新推理。租约存活日志与样本/迭代进度分开记录,不能把心跳当作推理进展。主机阶段锁只代表调度占用,不能代替板端进程核验。
- 重阶段(compile / board / eval)由 harness 执行。agent 走 `bench stage run` / `bench stage wait`,不在 bash 里跑 hb_compile。
- rollout 预算 = turns + tokens;墙钟 12 h 仅防挂死。
- Agent 动态领取任务:先覆盖尚无完整轨迹的不同模型,同等覆盖下优先预计耗时较短的模型,再做重复采样;同一 job 同时最多一条 Agent 轨迹。每次有空位都重新读取队列,`collect --watch` 等待输入准备和在途任务,避免新完成的模型一直排在旧批次后面。
- 同一 run 只运行一个新 collector;任务领取原子化。SIGTERM 或 `state/drain-collect-<run>` 停止领取,已开始的任务自然收尾。导出在独立线程刷新,不占 Agent 名额。
## 7. 重试与轨迹边界
| 层 | 谁 | 触发 | 轨迹 |
|---|---|---|---|
| oracle 阶段 | harness | 瞬态 error_class | 不是轨迹 |
| rollout 内 | agent | 自己改配置重提 | 同一条轨迹 |
| 新 rollout | harness | matrix k | 全新轨迹,永不串联 |
| 历史 repair | 不再生成或领取 | 保留既有编号和结果 | 有 Oracle 现场的修复案例,仅保留分析用途 |
显式扩大已有 run 的 Agent 覆盖时,仅追加缺少的计划和范围说明 annotation;编号接在该 job 的最大 kk 之后,重复执行不重复添加。冻结的 job、已执行轨迹、oracle 结果及评测门槛不变。确定性 oracle 的 PASS 不代表该模型已有 Agent 训练轨迹。
**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(当前 6),rollout.json 记 `agent_config_version`,导出按版本筛。
## 8. error_class
`unsupported_op shape_infer export_fail calib_nan verifier_mismatch`(确定性,不重试)
`oom board_offline board_busy stalled`(瞬态,前三者重试 ≤ 2,stalled 重试 ≤ 1)
`unknown`(进人工分类队列)
## 9. reward(v0.6,离线算,配方版本化)
```
r = 1.0[G1] + 1.0[G2] + 2.0[G3]
r −= 0.5·turns/max_turns + 0.5·tokens/max_tokens
r −= 2.0[claim ≠ verdict]
TIMEOUT: −1.0;BLOCKED 无特殊奖惩,仍保存本次真实阶段得分
G3 = na 时其 2.0 权重按比例分给 G1/G2
板卡不可用(G3 unverified 且最后一次 07-board/08-eval 为 board_offline):G2/G3 权重取 0,G1 保持 1.0 不加分,
免 TIMEOUT 罚分,reward 输出带 unverifiable="board_offline"(v0.4,2026-09-16)
```
板卡不可用的轨迹在导出器里仍按 UNVERIFIED 排除在 RL/SFT 候选之外;回收它们的办法是 `bench board-backfill --run R --rollout JOB:KK`
用其现成 HBM 补跑 07/08 再 verify,而不是改分。
不再计算相对 Oracle 的精度或延时奖励。G3 仍比较同一评测集上的 FP32 与本次 INT8,沿用任务冻结的门槛。
TIMEOUT 扣分根据执行终止原因独立相加,已完成的 G1/G2/G3 成果照常得分,不再整条清零。
## 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。
数据默认按 `purpose=all` 保留已结束的成功、失败及部分轨迹;SFT 是其中的用途筛选,不能代表全部数据量。Agent 的 `teacher.jsonl` / `student.jsonl` 只含真实对话、工具调用和观测,缺失内容不得编造。`pipeline.jsonl` 保留确定性流程的实际输入、阶段动作与测量,明确标记其来源,不能计成模型生成的 Agent 轨迹。每个 run 使用同一导出目录,显式刷新,按稳定 ID 去重;导出失败报错并可补导,不回滚已完成任务。
`bench.verdict/3` 不读取 Oracle;旧判定在导出时只读重核,源 verdict、数据库、消息和产物不改。SFT 候选要求本次实测 PASS、声明一致、完整对话和工具定义,并保留污染注释与版本过滤。Oracle FAIL 不再触发待复核;历史 repair 保留原模式,仅供分析。导出是候选数据,仍需训练端分组、去重和独立评测。
## 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`。**换代必须 `bench drain` 等它跑完再起新进程,只 sync 文件不算换代**(踩过:一个调度进程跑了 13 小时的旧代码)。
| 层 | 当前写者 |
|---|---|
| harness/ agent/ export/ scripts/ registry/ | 本会话(Cowork · bench 主线) |
| 其他会话 | 只读;发现问题写成 issue 贴过来,不直接改 |
## v5 隔离修订(优先于上文旧实现描述)
工具层仍只允许 workspace 写入;底层 jail 额外允许 handles 票据与私有 /tmp。
阶段执行移到 namespace 外,只信任外部生成的 stages/artifacts/verdict;客户端不 import harness。
本 job 输入、本 rollout(除 workspace/handles)、data/cache/bin/.horizon 与本 rollout work_root 均只读。
state(包括真实路径)、harness/export/registry/config/.env.local、其他 job/run/rollout 与其他 work_root 全部隐藏。
repair 仅额外保留本 job oracle 只读。使用 PID namespace 和 capability drop,避免 /proc/宿主进程及 remount 绕过。
~/.pi 仍可读凭证;这是已有结构性限制。jail 不可用时拒绝启动,不能静默退回 guard。
预算采用 max_turns 硬上限,无 grace turns;成本依据本条 rollout.json 的预算。