data-gen-bpu/CONTRACT.md

18 KiB
Raw Permalink Blame History

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 的预算。