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 校验和一类」—— 猜错了。
逐字节定位后(本机复核):
| 偏移 | 真身 | 实测 |
|---|---|---|
0x120 | COFF 头 TimeDateStamp | 两次相差 正好 10 秒(与两文件 mtime 之差一致) |
760148 | 同一个时间戳的第二份拷贝 | 与 0x120 的 4 字节完全相同 |
793289 | 被嵌入的输出文件名 | ASCII 直接命中(…_T1.dll… vs …_T2.dll…) |
0x170 | 真正的 PE CheckSum | 两份都是 0 |
★ 重做一次干净对照(固定输出名,连编两次,各自拷走再比对):
| 检查 | 结果 |
|---|---|
| 尺寸 | 逐字节相同 |
| 逐字节差异 | 恰好 2 个字节,偏移 0x120 与 760148,且两处是同一个值 |
| 那两处的值 | 只低字节不同(秒级时间戳) |
0x170(真 CheckSum) | 两份都是 0 |
⇒ 三条纪律更新:
Get-FileHash相等不是「代码等价」的判据 —— 同源同名构建每次都会在 COFF 时间戳上不同。归档 SHA 仍可作「这一份产物」的身份标签,但不能靠重建复现它。- 等价性判据改为:尺寸相同 + 差异只落在 COFF
TimeDateStamp的两处拷贝上。 - 不要再用「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 叠成 x2 | ERROR: duplicated UTF-8 BOM … rc=1 |
| 缺失 | 去掉首 BOM | ERROR: missing UTF-8 BOM … (expected exactly one). rc=1 |
★ 一句值得记的话:只挡一半的断言等于没挡。断言最初只写了「防叠加」,直到「缺失」真把构建指向 6000 行以外,才补上另一半。
3.3 唯一一份源:让「证据对着旧内核」不可能发生
做法:新增 src/npu/cuda/q4_gemv_twin.inc,把引擎里四样逐字搬迁过去:
| # | 名字 | 说明 |
|---|---|---|
| 1 | d_f16_to_f32 | f16→f32 的参考语义(热路径不用,留着让人眼核对等价性) |
| 2 | rq_coef | 取一个 q4 系数的数值(int4 补码 + f16 标度) |
| 3 | k_rq_q4_gemv_f32act | 现役单输出 raw-q4 GEMV |
| 4 | k_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 降级为身份标签。 - 真机验证:未独立复现:工具档
--fuse39 形状直测不在本机清单,BOM 断言属构建期;且构建产物 SHA 受 nvcc COFFTimeDateStamp影响不可字节复现。
六、小结
- 「不可复现」不等于「不能用」,但要换判据。SHA 从「等价性判据」降级为「身份标签」,等价性改用「尺寸 + 差异位置」。这一步不做,后面每一轮的 A/B 都会误报回归(因为 SHA 变了)。
- 没有 VCS 时,纪律必须变成「断言或归档」。这三条里没有一条是「注意」能解决的:BOM ⇒ 构建前断言(两处);基线 ⇒ 滚动副本 + 不可变归档 + 硬失败校验;「这一版到底编没编过」⇒ 靠归档 SHA 与 mtime 兜底,但已撞第二次 ⇒ 根治建议是给仓库初始化本地 git(可无 remote)。
- 技术债是静默 bug 的温床。「两份独立拷贝」不会立刻出错,它只会在某一天让证据对着旧内核,然后照样 PASS ⇒ 抽「唯一一份源」的收益不在代码整洁,而在把一类假绿从结构上消灭。
- 体级 bug 与 wrapper 级 bug 要用不同的证据。位级
memcmp能抓 wrapper 错,抓不到「lane 映射写反」这类体级错(如果对手同源)—— 那要靠不同序的参考(容差)与整模型 SHA 兜。判据要跟 bug 的层次匹配。 - 合成测试的输入要「有区分度」。常数 x、全同 KV 行、边界处「本来就该相同」的参数 —— 这些都是自证退化的温床 ⇒ 合成数据的第一个要求不是「像真的」,而是**「错了就会红」**。
相关篇目:第 34 篇(那三条护栏与「尺寸相同」的证据口径);第 35 篇(诊断档的落目录纪律);第 26 篇(同一份代码、注释一改 SHA 就变);第 30 篇(探针自己伪造绿)。 源码与配套资源:本仓库 gitee.com/pei-xiaogua…; CPU 推理源码 gitee.com/pei-xiaogua…