Kestrel_VLLM - 37 · 三条工具链纪律:不可复现的构建、双向 BOM 断言、与「唯一一份源」

43 阅读12分钟

37 · 三条工具链纪律:不可复现的构建、双向 BOM 断言、与「唯一一份源」

一句话:有三件事不改变任何数值,却能让「验证」本身失效 —— 构建产物不可字节复现(那怎么用 SHA 做 A/B 对照?)、编辑器会悄悄吃掉/叠加文件头的 BOM(而报错在 6000 行以外、指错方向)、同一段内核在引擎与工具里各有一份拷贝(于是「证据」可能对着旧内核跑)。本仓没有 git,所以这三条只能写成断言,不能只写成注释。 前置:第 34 篇(那三条护栏与「尺寸相同」的证据口径)、第 35 篇(诊断档的落目录纪律)。 环境:Windows x64 · MinGW-w64 gcc + nvcc(tools/build/build_x64.ps1 / tools/build/build_cuda_tool.ps1)。

一、问题与结论

前面几篇讲的是算得对不对、快不快。这一篇讲别的 —— 那些不改变任何数值、却能让「验证」这件事本身失效的东西:

  • 构建产物不可字节复现(那你怎么用 SHA 做 A/B 对照?);
  • 编辑器会悄悄吃掉/叠加文件头的 BOM(而报错在 6000 行以外,指错方向);
  • 同一段内核在引擎与工具里各有一份拷贝(于是「证据」可能对着旧内核跑)。

这三条的共同点是:它们不产生错误答案,它们腐蚀你判断答案对错的能力。 而本仓没有 git(git 报 not a repository),所以没有 diff 兜底 —— 这三条纪律只能写成断言,不能只写成注释。

结论事实判定
nvcc 产物不可字节复现同源同名构建,每次 SHA 都不同;真身是 COFF 头 TimeDateStamp 的两处拷贝实测
等价性判据改为尺寸相同 + 差异只落在 COFF TimeDateStamp 的两处拷贝上实测
BOM 断言要挡两个方向叠加(EF BB BF EF BB BF)与缺失实测
「唯一一份源」内核抽进 .inc,引擎与工具同一份实测
内核级直测的三种证据位级(vs 同源单输出内核)/ 容差(vs CPU 标量参考)/ 合成数据要逐元素不同实测
只挡一半的断言等于没挡BOM 断言最初只挡「叠加」,直到「缺失」把构建打偏 6000 行才补上另一半实测

二、背景

怎么撞上「不可复现」的:要证明「出厂档不受某个诊断宏影响」时,用 Get-FileHash 对比两次同源构建,得到不同的 SHA —— 一度像是宏外溢。这条线索直接改了后面很多轮的做法。

为什么 BOM 是个坑:这个仓库的 CUDA 源文件必须恰好一个前导 UTF-8 BOM,而这个状态会被编辑器静默改变。缺了它或多了它,报错位置与真因相距极远。

为什么需要「唯一一份源」:内核在引擎里一份、工具里一份 ⇒ 改了引擎忘了改工具,于是工具跑出来的「证据」对着的是旧内核 —— 而它照样 PASS(因为旧内核本来就自洽)。

三、核心机制与做法

3.1 不可字节复现的构建:把 SHA 从「判据」降级为「身份标签」

★ 第一版演示有两处毛病(审计订正):① 那两次构建用了不同的 -o 名,所以差异里混进了被嵌进产物的输出文件名;② 我把剩下的差异猜成「PE 校验和一类」—— 猜错了。

逐字节定位后(本机复核):

偏移真身实测
0x120COFF 头 TimeDateStamp两次相差 正好 10 秒(与两文件 mtime 之差一致)
760148同一个时间戳的第二份拷贝与 0x120 的 4 字节完全相同
793289被嵌入的输出文件名ASCII 直接命中(…_T1.dll… vs …_T2.dll…)
0x170真正的 PE CheckSum两份都是 0

★ 重做一次干净对照(固定输出名,连编两次,各自拷走再比对):

检查结果
尺寸逐字节相同
逐字节差异恰好 2 个字节,偏移 0x120 与 760148,且两处是同一个值
那两处的值只低字节不同(秒级时间戳)
0x170(真 CheckSum)两份都是 0

⇒ 三条纪律更新:

  1. Get-FileHash 相等不是「代码等价」的判据 —— 同源同名构建每次都会在 COFF 时间戳上不同。归档 SHA 仍可作「这一份产物」的身份标签,但不能靠重建复现它。
  2. 等价性判据改为:尺寸相同 + 差异只落在 COFF TimeDateStamp 的两处拷贝上。
  3. 不要再用「3 个已知位置」那一套 —— 那是本次含文件名差异的产物,不是通例。

这条纪律直接改了后面很多轮的做法:第 34 篇里那些「尺寸相同」的证据、以及「差一块就重编一次、SHA 必变」的记录,都建立在这一条上。也解释了一个反复出现的现象:「同一份代码、注释改一下,SHA 就变了」。

3.2 BOM:一个「只在构建时才现形」的编码坑与双向断言

这个仓库的 CUDA 源文件必须恰好一个前导 UTF-8 BOM(EF BB BF)。

3.2.1 叠加(多了一个 BOM)

怎么来的:编辑工具在替换已有 BOM 的文件时,会再加一个。实测:某个 .cu 被叠成 x2;更早的 vllm_cuda_kernels.cu 被叠成 x3 —— 后者居然一路编过了(引擎 DLL 正常)⇒ 这个坑是静默的:直到某个文件恰好编不过才暴露。

报错长什么样:nvcc 报 error: expected a declaration。★ 注意别被下游噪声带偏:它往往先报一串 __half is undefined,让人跑去查 cuda_fp16.h —— 根因是 BOM,不是头文件。

3.2.2 缺失(BOM 被吃掉)

怎么来的:编辑工具有时会吃掉文件首部的 BOM(不是每次都吃 —— 实测 5 个文件里 2 个被吃)。后果比「一个警告」严重得多:cl.exe 改按 cp936 解码 ⇒ 某个中文字符串字面量的尾字节与紧跟的引号配对 ⇒ 在距离真正改动处 6000 行以外报 error: missing closing quote —— 完全指错方向。

3.2.3 落点:写成构建前断言,且两处都要有

不靠人记(本仓无 git,没有 diff 兜底):构建脚本在调 nvcc 之前扫 src/npu/cuda/*.cu 与 *.inc,要求每个文件恰好一个前导 BOM:叠加或缺失都 exit 1。用 ReadAllBytes 看前 6 字节即可:

# 文件名:tools/build/build_x64.ps1 —— 构建前 BOM 双向断言(节选)
foreach ($cu in (Get-ChildItem -Path 'src/npu/cuda' -Include '*.cu','*.inc' -Recurse)) {
    $bb = [System.IO.File]::ReadAllBytes($cu.FullName)
    $hasOne = ($bb.Length -ge 3 -and $bb[0] -eq 0xEF -and $bb[1] -eq 0xBB -and $bb[2] -eq 0xBF)
    if (-not $hasOne) {
        Write-Host "ERROR: missing UTF-8 BOM in $($cu.Name) (expected exactly one)."
        # ... cl.exe 会按 cp936 解码、在离真因很远的地方报 missing closing quote ...
        Pop-Location; exit 1
    }
    if ($bb.Length -ge 6 -and $bb[3] -eq 0xEF -and $bb[4] -eq 0xBB -and $bb[5] -eq 0xBF) {
        Write-Host "ERROR: duplicated UTF-8 BOM in $($cu.Name) (expected exactly one)."
        Pop-Location; exit 1
    }
}

且是两处:src/npu/cuda 那一批走 build_x64.ps1;而 tools/*.cu 不由它编(走 build_cuda_tool.ps1),那里也有同款断言:

# 文件名:tools/build/build_cuda_tool.ps1 —— 同款断言(tools/ 这边也得有)
$bb = [System.IO.File]::ReadAllBytes($Source)
$hasOne = ($bb.Length -ge 3 -and $bb[0] -eq 0xEF -and $bb[1] -eq 0xBB -and $bb[2] -eq 0xBF)
if (-not $hasOne) {
    Write-Host "ERROR: missing UTF-8 BOM in $base.cu (expected exactly one)."
    exit 1
}
if ($bb.Length -ge 6 -and $bb[3] -eq 0xEF -and $bb[4] -eq 0xBB -and $bb[5] -eq 0xBF) {
    Write-Host "ERROR: duplicated UTF-8 BOM in $base.cu (expected exactly one)."
    exit 1
}

负向测试(两个方向都做了,断言不是摆设):

方向做法结果
叠加故意把某个 .inc 叠成 x2ERROR: duplicated UTF-8 BOM … rc=1
缺失去掉首 BOMERROR: missing UTF-8 BOM … (expected exactly one). rc=1

★ 一句值得记的话:只挡一半的断言等于没挡。断言最初只写了「防叠加」,直到「缺失」真把构建指向 6000 行以外,才补上另一半。

3.3 唯一一份源:让「证据对着旧内核」不可能发生

做法:新增 src/npu/cuda/q4_gemv_twin.inc,把引擎里四样逐字搬迁过去:

#名字说明
1d_f16_to_f32f16→f32 的参考语义(热路径不用,留着让人眼核对等价性)
2rq_coef取一个 q4 系数的数值(int4 补码 + f16 标度)
3k_rq_q4_gemv_f32act现役单输出 raw-q4 GEMV
4k_rq_q4_gemv3三输出融合版

引擎与工具都 #include 这一份 ⇒ 「改了引擎忘了改工具」被结构性消除,顺带清掉一笔「两份独立拷贝」的债。VC_RQ_TILE_BYTES(72 B)顺势只留一份 —— 它此前两边各一份,值一旦分叉是静默的。两边的包含点:

/* 文件名:src/npu/cuda/vllm_cuda_kernels.cu —— 引擎侧 */
/* raw-q4 dense GEMV 的唯一一份源抽到 q4_gemv_twin.inc:
 * 本文件与 tools/q35_q4_gpu.cu 都 #include 它。 */
#include "q4_gemv_twin.inc"
/* 文件名:tools/q35_q4_gpu.cu —— 工具侧(同一个文件) */
/* 全部内核 #include 自 src/npu/cuda/q4_gemv_twin.inc(引擎与工具同一文件,
 * 改内核请改 q4_gemv_twin.inc,改完两边一起重建)。 */
#include "../src/npu/cuda/q4_gemv_twin.inc"

3.4 --fuse3:内核级直测与三种证据

三种证据,别混:

证据对手判据强度
①单输出现役内核(逐段发射)memcmp 逐字节位级
②宿主 CPU 标量参考(顺序累加 32 列)maxrel容差(GPU 是 warp 树归约,不同序 ⇒ 不可能是位级)
③权重 / 激活合成(LCG,x 逐元素不同)——

★ 为什么 x 不能用常数:常数 x 会把「两列写反」这类映射错掩盖掉。 ★ 口径边界:① 的对手与融合版同源 ⇒ 它证的是新增的 wrapper 逻辑(分段选择 / 行折行 / 取址)不改逐行结果,不是同义反复;但体级(lane 映射 / 列步长 / 归约树)的 bug,memcmp 抓不到 —— 那由 ② 与整模型三文件 SHA256 兜。不要把旧实现当位级对手:它不同序,只可能给容差。

9 个形状的覆盖面(含 4 个合成死代码形状):

#形状(r0,r1,r2 / cols)覆盖面
1(12288,1024,1024)/5120三输出(attn q/k/v)
2(17408,17408,0)/5120两输出(mlp gate/up)
3(10240,6144,0)/5120两输出(gdn in_qkv+in_z)
4(17408,0,17408)/5120中段为空 r1==0
5(0,1024,1024)/5120首段为空 r0==0(引擎不可达,合成)
6(5120,1024,1024)/5184尾块 cols%256!=0
7(64,32,32)/32纯尾块(主循环一次都不跑)
8(1020,4,0)/5120单输出核早退
9(1020,4,4)/5120融合核早退

⇒ 9/9 位级相同;容差落在 1.3e-07 – 3.0e-06。

★ 一处「名实不符」已订正:上一版把 1020+4+0(%8 == 0)标成「融合核早退」,实际它只触发了单输出核那一发 —— 融合核的早退一次都没跑。现在拆成第 8/9 两行,各钉一个量。⇒ 「我测了这个分支」这句话,必须先确认那个分支真的被走到了。

驱动这些对拍的判据就落在工具的 --fuse3 模式里(融合版 vs 单输出内核 memcmp、再对 CPU 参考取 maxrel):

/* 文件名:tools/q35_q4_gpu.cu —— --fuse3 内核级直测(节选) */
static int fuse3_mode(void) {
    std::printf("[fuse3] k_rq_q4_gemv3 kernel-level direct test (audit SHOULD-5)\n");
    std::printf("[fuse3] fused-vs-single = memcmp (bit-exact); plus a host CPU reference (tolerance).\n");
    std::printf("[fuse3] x is per-element varied (a constant x would hide column-swap bugs).\n");
    int bad = 0;
    for (int i = 0; i < n; i++) bad |= fuse3_case(C[i].tag, C[i].r0, C[i].r1, C[i].r2, C[i].cols);
    std::printf("[fuse3] %s (%d shapes)\n", bad ? "FAIL" : "ALL PASS", n);
    return bad;
}

四、实测数据

口径数值判定
干净对照:两次固定输出名构建的逐字节差异恰好 2 字节(0x120 与 760148,同一个值)实测
那两处偏移的真身COFF 头 TimeDateStamp 的两处拷贝实测
0x170(真 PE CheckSum)两份都是 0实测
BOM 叠加负向测试duplicated UTF-8 BOM … rc=1实测
BOM 缺失负向测试missing UTF-8 BOM … rc=1实测
工具被吃 BOM 的样本5 个文件里 2 个被吃(vllm_cuda_kernels.cu、build_cuda_tool.ps1)实测
--fuse3 位级9/9 形状融合 vs 单输出 memcmp 相同实测
--fuse3 容差1.3e-07 – 3.0e-06(vs CPU 标量参考)实测

五、边界与已知限制

  • 「不可复现」的范围:本次实测的不可复现来源是 COFF TimeDateStamp(及输出名内嵌);归档 SHA 只作身份标签,不作等价性判据。
  • BOM 归因只到「疑似」:编辑工具会吃 BOM,但不是每次都吃(实测 5 个文件里 2 个),现象可复现但不确定;断言本身不依赖这个归因。
  • --fuse3 只证内核级:端到端收益/回归由整模型三文件 SHA256 兜。
  • 「唯一一份源」只覆盖已抽出的 .inc:其它内核仍可能各有拷贝(后续轮次继续收)。

CPU 对照(迁移前基线)

  • CPU 参考:model/vllm_q35_fused.c:q35_fused_gemv —— 同语义 CPU 参考,供容差对拍。
  • 迁移要点:把内核抽进 .inc 成「唯一一份源」(结构性消除「改引擎忘改工具」);位级证据(vs 同源单输出内核)与容差证据(vs CPU 标量)分开;BOM 双向断言 + 把 SHA 降级为身份标签。
  • 真机验证:未独立复现:工具档 --fuse3 9 形状直测不在本机清单,BOM 断言属构建期;且构建产物 SHA 受 nvcc COFF TimeDateStamp 影响不可字节复现。

六、小结

  1. 「不可复现」不等于「不能用」,但要换判据。SHA 从「等价性判据」降级为「身份标签」,等价性改用「尺寸 + 差异位置」。这一步不做,后面每一轮的 A/B 都会误报回归(因为 SHA 变了)。
  2. 没有 VCS 时,纪律必须变成「断言或归档」。这三条里没有一条是「注意」能解决的:BOM ⇒ 构建前断言(两处);基线 ⇒ 滚动副本 + 不可变归档 + 硬失败校验;「这一版到底编没编过」⇒ 靠归档 SHA 与 mtime 兜底,但已撞第二次 ⇒ 根治建议是给仓库初始化本地 git(可无 remote)。
  3. 技术债是静默 bug 的温床。「两份独立拷贝」不会立刻出错,它只会在某一天让证据对着旧内核,然后照样 PASS ⇒ 抽「唯一一份源」的收益不在代码整洁,而在把一类假绿从结构上消灭。
  4. 体级 bug 与 wrapper 级 bug 要用不同的证据。位级 memcmp 能抓 wrapper 错,抓不到「lane 映射写反」这类体级错(如果对手同源)—— 那要靠不同序的参考(容差)与整模型 SHA 兜。判据要跟 bug 的层次匹配。
  5. 合成测试的输入要「有区分度」。常数 x、全同 KV 行、边界处「本来就该相同」的参数 —— 这些都是自证退化的温床 ⇒ 合成数据的第一个要求不是「像真的」,而是**「错了就会红」**。

相关篇目:第 34 篇(那三条护栏与「尺寸相同」的证据口径);第 35 篇(诊断档的落目录纪律);第 26 篇(同一份代码、注释一改 SHA 就变);第 30 篇(探针自己伪造绿)。 源码与配套资源:本仓库 gitee.com/pei-xiaogua…; CPU 推理源码 gitee.com/pei-xiaogua…