data-gen-bpu/docs/archive/SPEC-two-phase-compile.md

16 KiB
Raw Blame History

已归档(2026-09-17):未实现,暂不做。 注意不是"被 long 车道替代"——long 只是 STALLED 后把看门狗阈值抬到 3600s 的重试车道 (stagerun.py 对 05-compile 无条件设 ctx.lane="long"),与两阶段编译无关。 本文的动机测量(量化 107s / BPU 编译 4680s)至今仍然成立,问题也仍未解决。

SPEC · 05-compile 拆成两阶段(交接文档)

给下一个负责改这块的 agent。所有数字都是 2026-09-15 在 120.48.151.164 实测的, 不要重新调研,直接按这个改。与 CONTRACT.md 冲突时先改 CONTRACT。


0. 一句话

把「量化」和「BPU 编译」拆开。agent 在量化后用极少量样本跑 .bc 推理拿到精度信号, 快速迭代;确认可行后才做那一次昂贵的 BPU 编译,产出 .hbm 上板出权威数字。

现在 agent 每次实验要等 35–118 分钟,其中 97% 花在对迭代毫无价值的 BPU 编译上。


1. 为什么(证据)

1.1 时间构成

resnet50 / nash-e 单次 hb_compile 的日志时间戳:

13:10:37  启动
13:12:25  quantized_model.bc 已存盘         ← 量化结束:107 秒
13:12:43  逐节点余弦表打印完毕
13:12:44  "Start to compile model."          ← BPU 编译开始
14:30:42  .hbm 产出                          ← 78 分钟

量化 107 秒 : BPU 编译 4680 秒 = 1 : 44。

其他实测(单次编译总耗时):convnext.small 118 分钟 · efficientnet.b4 74 分钟 · resnet50 61 分钟。

1.2 工具链原生支持,不是 hack

horizon_tc_ui/compile/hbm_builder.py:

def build(self):
    if self.skip == "export": return
    self.export_model()        # 导出 float onnx
    if self.skip == "convert": return
    self.convert_model()       # 校准 + 量化 → 存 _quantized_model.bc
                               # ★ 算子不支持在这里崩(hbdk.convert)
    self.node_info()           # 逐节点表:Node / NodeType / ON / Threshold /
                               #   Calibrated Cosine / Quantized Cosine / Output Data Type
    self.remove_node()
    if self.skip == "compile": return          # ← --skip compile 停在这
    self.compile_model()       # BPU 编译 → .hbm      ← 78 分钟在这
    self.hbm_perf()
    self.print_model_info()

--skip 的合法值:Literal["export", "convert", "compile"](源码 hbm_builder.py:29)。

1.3 两阶段实测(resnet18 / nash-e)

阶段一  hb_compile -c c.yaml --skip compile          23 秒
        产出 _quantized_model.bc (12.2 MB) + _quant_info.json + 逐节点余弦表 ✅

阶段二  hbdk4.compiler.load(".bc")                   0.03 秒   ← 不重做校准
        hbdk4.compiler.compile(m, ".hbm", march=..)  73 秒
        产出 phase2.hbm   12,205,656 字节

对照   oracle 走完整 hb_compile(8 路并发时)        881 秒
        产出 .hbm          12,205,656 字节

产物字节数完全一致。两阶段路径和一次性路径等价,无正确性风险。

(881 vs 96 的差距里有并发竞争成分,不能全算成拆分收益。可靠的比例是 §1.1 的 1:44。)

1.4 .bc 推理速度(实测,244 核机器)

.bc 单进程 1 线程     40.5 ms/张
.bc 单进程 8 线程     38.9 ms/张     ← 线程无效,内部基本单线程
.bc 8 进程 × 2 线程   12.6 ms/张     ← 多进程可线性摊薄
板端 BPU (resnet18)    0.889 ms/张   ← 比 .bc 快 45 倍

板端单张推理确实比 .bc 快 45 倍(这一点最初被我说反了,已更正)。 但要跑板端就得先付 BPU 编译的钱,所以真正的对比是:

A:量化 + .bc 评测 B:完整编译 + 板端评测
量化 23 s / 107 s 同左
BPU 编译 不做 73 s(resnet18)/ 4680 s(resnet50)
2000 张推理 25 s(8 进程) 1.8 s
合计 48 s / 132 s ~150 s / ~4790 s

交叉点:A 更快 ⟺ N < T_bpu_compile / 0.0117(N = 张数)

模型 BPU 编译 交叉点 T1 = 2000 张
resnet18 73 s 6,200 张 A 赢约 3 倍
resnet50 4,680 s 400,000 张 A 赢 36 倍
convnext.small ~7,000 s 600,000 张 A 赢

模型越大优势越大——而 agent 卡住的全是大模型。

反转情况(必须写进实现):

  • T2 交付(5 万张):resnet18 走 .bc 要 630 秒,走板端只要 117 秒 → T2 必须走板端
  • .hbm 已存在时:无条件用板端,没理由回头用 .bc

1.5 「量化成功但编译失败」的 gap 有多大 —— 实测 0 次

全部 273 次 05-compile 尝试:

OK                   113
STALLED               93   ← 看门狗误杀(我们的 bug,见 §5)
FAIL unknown          53   ← yaml 键错,校验阶段,量化之前
RUNNING                7
ABORTED                4
FAIL unsupported_op    3   ← yolov8n

那 3 个 unsupported_op 查了日志:

是否走到 "Start to compile model": 0      ← 根本没到 BPU 编译
是否产出 .bc: 0
报错: *** ERROR-OCCUR-DURING hbdk.convert ***, _convert function crashed!

算子支持性检查在 hbdk.convert(量化阶段)完成,--skip compile 照样会跑到、照样会崩。

失败原因 次数 阶段 --skip compile 能否提前发现
yaml 键错 53 校验 ✅
unsupported_op 3 量化(convert) ✅
看门狗误杀 93 BPU 编译 ❌ 但这是 bug

「量化成功但 BPU 编译因模型/配置原因真失败」= 0 次 / 273 次。

但这是观察不是保证,边界:样本全是 cls+det 卷积网络;配置以 oracle 默认为主; 资源类失败(compile() 有 max_time_per_fc 参数)没出现过;93 次误杀掩盖了部分真相。 所以 §3 的「强制一次正式编译」不能省。

1.6 优化级别的编译耗时(resnet18,用于 --check)

opt=0    7.8 秒      ← O2 的 1/9
opt=1   30.0 秒
opt=2   70.9 秒      ← 正式产物用这个

2. 早退逻辑(两级,不要合并成一级)

这是最容易被误解的地方:「能不能生成 HBM」和「精度够不够」是两个问题,由两个步骤回答。

① hb_compile --skip compile
   ├─ 崩了 → 算子不支持 / yaml 错。连 .bc 都没有,无从推理。
   │         换配置重来。【不浪费 BPU 编译】
   └─ 成功 → 拿到 .bc + 逐节点余弦表 + quant_info.json
            ↓
② .bc 少量样本推理
   ├─ 精度明显不行 → 换配置重来。【不浪费 BPU 编译】
   └─ 精度可以
            ↓
③ BPU 编译(这一次必须做,见 §3)
   ├─ 失败 → agent 看得到,还有预算修
   └─ 成功 → .hbm
            ↓
④ 上板实测 → G3 权威数字 → verdict

3. 要实现的东西

3.1 新阶段 quantize

bench stage run quantize [--config workspace/x.yaml]     → handle
  • 实现:现有 05-compile 的调用加 --skip compile
  • 产物:_quantized_model.bc · _quant_info.json · 逐节点余弦表
  • AGENT_RUNNABLE 里加上它
  • bench stage wait 结束时必须直接打印(不要让 agent 去 cat 日志):
    • 模型输出的 Calibrated / Quantized Cosine
    • 逐节点表里余弦最低的 10 个节点:Node · NodeType · ON · Quantized Cosine · Output Data Type
    • ON 列的 BPU / CPU 计数(给 §6 的 BPU 占比约束用)

依据:agent 现在要花 5–10 轮才摸到这张表。b0#03 烧了 201k token,大头在读日志。

3.2 eval 支持小样本 + 指定后端

bench stage run eval --on bc --n 32      → 只算 G2(余弦)
bench stage run eval --on bc --n 500     → G2 + top1 粗估
bench stage run eval --on hbm            → 板端权威(默认,收尾用)

样本数怎么选(照抄,不要自己发明):

N 耗时(单进程 40.5 ms/张) 拿到什么 用途
32 1.3 秒 真正的 G2 数字 registry/gates.yaml 的 G2.n_samples 就是 32。快循环里算出来的不是估计值,就是 G2 本身
500 20 秒 top1 粗估 ±2 pp 足够区分「崩了」(top1 2%)和「没崩」(top1 76%)
2000(T1 全量) 81 秒 G3 pass-screen 收尾用,且应走板端
  • 默认 --n 32,agent 想要更准再加
  • 并行度限制在 4 进程以内:config.yaml 的 cpu 池只有 10 槽,8 进程会和编译抢
  • 样本必须是校准外样本(和现有 G2 口径一致)

3.3 compile 增加 --check

bench stage run compile --check      # opt=0,只验可编译性,不留产物
bench stage run compile              # opt 按配置(默认 O2),产出正式 .hbm
  • --check 用 hbdk4.compiler.compile(load(bc), tmp, march, opt=0)
  • 必须在输出里写明:O0 通过 ≠ O2 一定通过(O2 优化更激进,可能碰资源约束), 它替代不了 §3.4 的正式编译

3.4 硬规则:claim 前必须有一次成功的正式编译

bench stage run compile(非 --check)成功至少一次,否则 verdict 直接 FAIL, error_class = no_verified_artifact。

理由:§1.5 的 gap 实测是 0,但样本有边界。让 agent 自己编一次、自己看到失败、自己有机会修, 比「harness 事后收尾」强得多——后者让 agent 对失败既看不到也修不了。

代价只有一次编译。b0#03 现在是 7 次(6866 秒),改完是 1 次,仍省 85%。

3.5 阶段二从 .bc 直接编,不重做校准

from hbdk4.compiler import load, compile
m = load(f"{prefix}_quantized_model.bc")          # 0.03 秒
compile(m, hbm_path, march=march, opt=opt, jobs=jobs)

实测产物与一次性 hb_compile 字节一致(§1.3)。


4. 改完之后 agent 的循环长什么样

# 快循环,每次 25–110 秒,可以做 10+ 次
bench stage run quantize --config compile.yaml
bench stage wait <handle>          # 直接打印最差 10 个节点 + BPU/CPU 计数
bench stage run eval --on bc --n 32
bench stage wait <handle>          # G2 余弦,1.3 秒

# ...改 quant_config,重复...

# 定档,1 次
bench stage run compile            # 78 分钟(大模型)
bench stage wait <handle> --poll 60
bench stage run hbm                # G1
claim(terminal=..., ...)

# agent 结束后由 harness 做:上板实测 → G3 → verdict

时间账(以 b0#03 那条真实轨迹为准):

现在 改完
agent 做了几次实验 7 同样 7 次,且还有预算再做 10 次
花在等待上 6866 秒(1.9 小时) 7 × ~110 秒 + 1 次编译
预算消耗 62 轮 / 201k token(耗尽) 约 1/5
BPU 编译 7 次(6 次白等) 1 次
最终上板 没走到 走到了

b0#03 当时已经定位到解法(74 个尾部节点走 CPU),就差一次实验的预算。


5. 前置条件:必须先修看门狗

93 次 05-compile 被看门狗误杀(error_class = stalled)。 判据是 「日志 900 秒不增长 且 进程树 CPU < 5%」,但 BPU 编译期间 hbdk-lld(链接器) 正满负荷跑——进程树 CPU 采样没覆盖到这层孙子进程。

实测:resnet101 和 regnet.y.3.2gf 已经是 attempt=1 / lane=long(stall_s 3600), duration_s = 4078 仍被杀。加时长解决不了,要改采样口径。

为什么这是前置条件:如果 §3.4 的正式编译被误杀,agent 会以为自己的配置编不出来, 去改一个本来没问题的配置——白烧预算,还学到错误经验。 b0#03 的 claim 里已经写着「O2 时曾因 CPU 争用被 watchdog 杀掉,改用 O1」—— 它已经学到了这个由我们 bug 造成的错误经验,修好后要在 SYSTEM.md 里纠正。


6. 顺带要一起做的两条(和本方案强耦合)

6.1 G1 加 BPU 占比硬约束

逐节点表的 ON 列标 BPU / CPU。要求 bpu_node_ratio ≥ 95%,否则 G1 FAIL。

为什么现在必须加:b0#03 的 claim 里已经计划「把 features.6/7/8 尾部 74 个节点 加入 run_on_cpu 走 float32」。一旦允许,agent 的最优策略就是把敏感算子全挪下 BPU—— 精度当然达标,但等于没量化,也违反「必须用 BPU 推理」。

6.2 位宽构成进 reward

记 si8 / si16 / float 的节点占比,reward 对 int16 占比扣分:r -= 0.5 × si16_ratio。

为什么:b0#03 的解法实测是——

oracle:190 节点  100% BPU  188 个 si8
agent :123 节点  100% BPU  122 个 si16    ← 全网络 int16

它没偷跑 CPU,但整网提到了 int16(BPU 上约为 int8 一半吞吐)。 延时不设硬门禁的话,all_node_type: int16 就是一行代码的通用解, agent 学会这一行就通关,任务失去难度,轨迹失去训练价值。

门禁宽松(G3 相对劣化 ≤5%,鼓励通过)+ 奖励精细(int16 占比扣分,鼓励优化),两者不矛盾。


7. 验收标准

# 验收项 判定
1 bench stage run quantize 在 resnet18 上 ≤ 30 秒产出 .bc 实测 23 秒
2 bench stage wait 输出里能直接看到最差 10 个节点 + BPU/CPU 计数 人工看一眼
3 eval --on bc --n 32 ≤ 3 秒,且余弦数字与正式 G2 一致 对比同一配置的 G2
4 从 .bc 编出的 .hbm 与一次性 hb_compile 的产物字节一致 sha256sum 比对
5 compile --check(O0)耗时约为 O2 的 1/9 实测 7.8 vs 70.9 秒
6 没有成功正式编译就 claim → verdict FAIL,error_class=no_verified_artifact 造一条测试轨迹
7 一条 convnext.small 的 rollout 在 60 轮内完成 ≥ 8 次实验 现在是 0–4 次
8 看门狗修好后,convnext.small(118 分钟编译)不被误杀 跑一次

8. 陷阱清单(别踩)

  1. 不要让 harness 在 agent 之后「收尾编译」。 agent 必须自己编一次、自己看到失败。
  2. 不要用 .bc 出交付数字。 .bc ≡ .hbm 的 run_sim(x86 模拟器)已验证逐位一致, 但 run_sim ≟ 板端真实执行只抽查过 2 张图。.bc 只能做相对比较,绝对数字以板端为准。
  3. 不要用 O0 代替正式编译。 必要不充分。
  4. 不要为了省 2 秒开 8 进程。 cpu 池只有 10 槽,会和编译抢。4 进程封顶。
  5. 不要在 T2 上用 .bc。 5 万张时板端快 5 倍(resnet18:117 秒 vs 630 秒)。
  6. 改了阶段划分必须升 agent/VERSION(当前 5)并更新 SYSTEM.md 的命令清单, 否则新旧口径的轨迹会混进同一个数据集。
  7. registry/gates.yaml 的 G2.n_samples: 32 是 --n 默认值的依据, 两边要保持一致;改了其中一个必须改另一个。

9. 参考:本文所有数字的出处

数字 出处
量化 107 秒 / BPU 编译 4680 秒 runs/r20260915-03/cls--resnet50--nash-e--ptq--int8/oracle/stages/05-compile/a00/hb_compile.log 时间戳
--skip compile 23 秒 在 /tmp/skiptest 实跑 resnet18
load()+compile() 73 秒 · 产物字节一致 同上,work/phase2.hbm vs oracle/artifacts/*.hbm
.bc 40.5 / 38.9 / 12.6 ms/张 /tmp/bcspeed2.py,40 样本
板端 0.889 ms/张 runs/.../cls--resnet18--nash-m--ptq--int8/oracle/stages/07-board/a01/meta.json
O0/O1/O2 = 7.8 / 30.0 / 70.9 秒 /tmp/skiptest/optlevel.py
273 次编译的失败归类 state/jobs.sqlite 的 stages 表 + 日志 grep
unsupported_op 发生在 convert runs/r20260915-0{2,3}/det--yolov8n--*/oracle/stages/05-compile/a00/hb_compile.log
b0#03 的 190/123 节点、si8/si16 构成 解析两边 hb_compile.log 的逐节点表 ON 列与 Output Data Type 列
--skip 合法值 horizon_tc_ui/compile/hbm_builder.py:29