skills/general-debug/SKILL.md
触发：MNN 中出现正确性 bug、单测/golden 对不上、回归；或做完改动（新 op、fusion、图 pass、后端 kernel）后行为异常。
使用方法：先按下方 Bug 分类导航 匹配症状定位到对应章节，每个章节独立可读；如果症状横跨多类，按导航表列出的顺序逐一排查。
边界：不读不改
schema/private/、source/internal/。
| # | 类别 | 典型症状 | 章节 |
|---|---|---|---|
| 1 | 内存别名 / 生命周期 | 数值错乱、乱码 token、NaN；代码逻辑看着正确、指针地址合法；换后端结果不同；关掉某优化就好；单/多线程行为差异 | §1 |
| 2 | 量化误差 / 导出侧权重损坏 | 低 bit（Q4）下输出乱码或退化、Q8/更高 bit 正常；所有推理后端都错（CPU/Metal 一致地错）；torch 侧 --test 正常但 MNN 推理错；只有大模型/大 vocab 触发 | §2 |
| 3 | （待补：并发 / 线程竞争） | 结果不稳定、每次运行不同；单线程稳定但多线程随机错 | 待补 |
| 4 | （待补：图优化回归） | 某个 converter pass 之后模型跑错，disable 该 pass 后正常 | 待补 |
| 5 | （待补：数值精度 / fp16 溢出） | 结果"接近对"但存在系统性偏差，长序列尤其明显 | 待补 |
| 6 | （待补：Shader / Codegen 错） | GPU 后端某 shape 或某 quant 组合下崩溃或乱码；调整 threadgroup / kernel 参数症状变化 | 待补 |
新增章节时同步在这张表里补一行；每个章节命名为
## <编号> <类别名>，保持编号递增。
触发（满足以下之一强烈怀疑本类）：
onResize / buffer 分配相关代码改过后开始回归；printf 或改 buffer size 就"好了"。"地址看着都对但结果错" ≈ 内存别名或生命周期错误。 遇到这种症状优先怀疑内存复用，不要先去怀疑算法本身。这类 bug 的共同特征：
printf 或改 buffer 大小就"好了"（其实只是位置错开了）；方法论一句话：别信"这块 buffer 应该是独立的"，用地址等式去证明。
进入排查前先牢记 MNN 的三条内存复用语义（拿不准就去读 source/core/BufferAllocator.hpp、source/core/Backend.hpp）：
BufferAllocator 是 arena，free 不释放alloc(size)：如果 free pool 里有相同 size 的 chunk，直接复用地址；free(chunk)：只是把这块标记为可复用，物理内存保留；alloc(); free(); alloc(); free() 模式，只要 size 相同，第二次 alloc 必然拿回第一块。onResizeBegin / onResizeEnd / compute() 之间，pipeline 会根据 tensor 生命周期把互不重叠的 tensor 分配到同一块 backend buffer；Tensor* 在不同 op 里的物理 buffer 可能不同；不同 Tensor* 也可能共享同一物理 buffer；id<MTLBuffer>、CUDA void*）同样会发生。MemChunk 的 ptr() 仅在 lifetime marker in-use 期间稳定onResize 里申请的 chunk，onExecute 期间用它的 ptr() 是安全的（op 内时序保证）；在怀疑的 op 的 onExecute 入口打印所有 scratch chunk / tensor 的物理地址：
MNN_PRINT("[MyOp] cos=%p sin=%p qTmp=%p kTmp=%p out=%p\n",
mTmpCos.ptr(), mTmpSin.ptr(), mTmpQC4.ptr(), mTmpKC4.ptr(), output->host<void>());
判据：
onResize 里所有 alloc，包括子调用 MNNNorm / MNNLowpToFp32 之类内部若也走 allocator 需要一起看）。onResize 找根因如果确认了别名，直接看该 op 的 onResize：
反模式：a = alloc(N); free(a); b = alloc(N); free(b); — size 相同 + 交错就一定别名。
正确模式：先把所有 chunk alloc 完（此时前面的 chunk 都还是 in-use），再一起 free：
mA = buf->alloc(N);
mB = buf->alloc(N); // 此时 mA 未 free，allocator 只能给新地址
mC = buf->alloc(M);
...
buf->free(mA);
buf->free(mB);
buf->free(mC);
onExecute 里继续用 ptr() 依然合法 —— free 只是"生命周期声明结束"，物理内存仍在。参考实现：source/backend/cpu/CPULayerNorm.cpp、source/backend/cpu/CPURoPE.cpp::onResize。
当症状出现在多个 op 之间（比如做了 QKV / Gate-Up fusion 之后），要检查 backend 侧的 tensor buffer 是否被 pipeline 分配到了同一物理 buffer：
MetalBackend.mm 里 matchQKVFusions 的做法 —— 在 onResizeEnd 的 compute() 之后再检查 output buffer 是否重叠，重叠就 fallback；compute() 之后才知道实际分配结果，反过来做检查等于空跑；reorderQKVProjections），或直接放弃这次 fusion。如果地址不别名但结果仍错，考虑：
numHead * headDim 写，但 alloc 只按 headDim 或漏了 threadNumber 倍数。快速验证：把 scratch buffer size 翻倍再跑，如果症状消失就是越界。alloc 拿回来的是别的 op 用过的脏数据。fp32 / fp16 里的脏数据可能不是 NaN 而是"看着正常的小数"，症状是"结果略微不对"。chunk.ptr() + tId * stride 里 stride 少乘一个维度，导致相邻线程互踩。单线程能过就是这个。onResize 里把 std::vector / 栈数组的地址存到成员里，然后在 onExecute 里用 —— onResize 返回后那块内存已失效。BufferAllocator 或成员变量的 std::vector（且要 resize 而不是 reserve）。| 症状 | 最可能的原因 |
|---|---|
| 单 op 对，串起来错；从第一步就错 | Scratch buffer 别名（Step 3） |
| 一个后端错另一个后端对 | 有别名的一侧走了 arena reuse（Step 1/3） |
| 关掉 fusion / 优化 pass 就好 | 跨 op tensor buffer 重叠（Step 4） |
| 加 printf / 改 buffer size 就好 | 越界写或别名（Step 5） |
| 单线程对，多线程错 | tId 分片 stride 少算了维度（Step 5） |
| 每次运行结果不一样、有时对有时错 | 未初始化 + arena reuse 的脏数据（Step 5） |
| 结果全 NaN / 全 0 | 生命周期错位（Step 6）或未写就读 |
症状：Qwen3 c4-head 模型，Metal 后端正常，CPU 后端从 prefill 第一步就吐乱码 token。
排查路径：
mTmpCosFloat.ptr() == mTmpSinFloat.ptr()，mTmpCos.ptr() == mTmpSin.ptr()。别名坐实。CPURoPE::onResize：alloc(); free(); alloc(); free(); 交错模式，size 又相同。BufferAllocator.hpp 注释确认语义：free 只标记可复用、alloc 命中相同 size 直接复用地址。为什么 Metal 没事：MetalRope.mm 用 id<MTLBuffer>（ARC），且 cos/sin 在 shader 内当场算，不走 arena reuse，天然没有别名机会。
修复（对齐 CPULayerNorm.cpp 惯用法）：CPURoPE::onResize 里把所有 scratch chunk 一次性 alloc 完，最后统一 free。onExecute 里继续用 ptr() 依然合法。
避坑要点：这个 bug 无法通过 review 逻辑代码发现 —— 代码逻辑完全正确，cosFloat[j] = c 也确实写到了 cosFloat 指向的地址，只是这个地址恰好也是 sinFloat。必须靠"打印地址、找相等对"这一步来揭穿。
| 文件 | 作用 |
|---|---|
source/core/BufferAllocator.hpp | Arena 语义注释，是否复用 freed chunk 的官方描述 |
source/core/Backend.hpp | Backend tensor buffer 生命周期接口 |
source/backend/cpu/CPULayerNorm.cpp | 正确的批量 alloc-then-free-all 模式参考 |
source/backend/cpu/CPURoPE.cpp | 参考案例的修复实现（onResize 注释里写了原因） |
source/backend/metal/MetalBackend.mm | 跨 op tensor buffer 重叠检查（matchQKVFusions） |
触发（满足以下之一强烈怀疑本类）：
llmexport.py --test "<query>"（torch 侧 rebuilt 模型，不走量化打包）输出正常；run_test.out）全过。"所有后端一致地错 + torch 侧对 + 单测过" ≈ 导出产物（权重文件）本身坏了。 此时不要在推理引擎里找 bug，而是：
transformers/llm/export/utils/torch_utils.py::quant（大权重按 _QUANT_MAX_ELEMENTS=256M 元素沿 oc 分块），实际量化在 _quant_on_device（优先 CUDA→MPS→CPU）。utils/mnn_converter.py::build_weight（header + q_weight + alpha [+ bias]）；lm_head/tie_embeddings 的 offset 信息写进 llm_config.json 的 tie_embeddings 字段。[zero, scale]；引擎 dequant 公式 w = q * scale + (zero + offset * scale)，offset = -(1 << (bit-1))（见 transformers/llm/engine/src/diskembedding.cpp）。--quant_bit/--quant_block（body）、--lm_quant_bit/--lm_quant_block（lm_head 单独控制）、--quant_config <json>（任意 op 级覆盖，如 {"/lm/lm_head/Linear": {"bits": 8, "block_size": 0}}）、--hqq、--seperate_embed。三个证据凑齐即可确认：① CPU 和 GPU 后端一致地错；② --test torch 侧输出正常（权重映射没问题）；③ op 单测全过（kernel 没问题）。
每次只动一个变量，导出后跑 CPU greedy 与 HF golden 对比：
| 实验 | 命令要点 | 用于区分 |
|---|---|---|
| 全 Q8 | --quant_bit 8 --quant_block 0 | 是否 4bit 特有 |
| 去 hqq | 去掉 --hqq | 是否 hqq 引入 |
| body Q4 + lm_head Q8 | --hqq --lm_quant_bit 8 --lm_quant_block 0 | 是否 lm_head |
| body Q8 + lm_head Q4 | --quant_bit 8 --lm_quant_bit 4 | 反向确认 lm_head |
| 某类层强制 8bit | --quant_config 指定 op 列表 | 是否特定层类 |
| block 0 vs 64 | --lm_quant_block 0/64 | 是否 block 量化特有 |
本案例结论链：Q8 全对 → body Q4 + lm_head Q8 对 → body Q8 + lm_head Q4 错 → 锁定 lm_head Q4；block 0/64 都错 → 与 block 无关，是 4bit 打包本身。
写脚本读 llm.mnn.weight，按 llm_config.json 的 tie_embeddings（weight_offset/alpha_offset/alpha_size/quant_bit/quant_block/alpha_dtype）反量化若干行，与 HF embed_tokens.weight 算 cosine：
边界 2^27 字节 = 2^28 个 int4 元素，恰好等于分块大小 256M 元素 → 怀疑 _quant_on_device 对满块输入出错。直接用随机张量复现：
qw_mps, _ = _quant_on_device(w.to('mps'), 4, 0, False, False, False) # 131072 x 2048
qw_cpu, _ = _quant_on_device(w, 4, 0, False, False, False)
# mps 输出全 0，cpu 正常 → 框架 bug 坐实
再逐 op 拆：(q.reshape(-1,2) * m).sum(axis=1) —— 乘法结果正常，sum(axis=1) 在 MPS 上对 ≥2^28 uint8 元素静默返回全 0（uint8→int64 归约溢出类 bug，2^27 元素正常）。
packed |= col << shift 按位累加替代 sum），不要指望升级框架版本；torch.equal），再全量重导 + 端到端跑 CPU 和 GPU greedy。| 症状 | 最可能的原因 |
|---|---|
所有后端一致错 + torch --test 对 | 导出产物权重坏（本节） |
| Q4 错 Q8 对 | 4bit 打包路径 bug（Q8 不走打包） |
| 只有大 vocab / 大 hidden 模型触发 | 大张量分块边界 / 框架大张量静默 bug |
| 反量化比对"部分行坏部分行好"，边界是 2 的幂 | 溢出 / 截断 / 框架归约 bug |
| 坏区全 0（非随机垃圾） | 某步整体输出 0（归约/拷贝失败），非量化误差 |
| 反量化比对全部行都乱 | 先怀疑自己的反量化约定（nibble 序、zero/scale 布局），用 Q8 导出验证脚本 |
症状：Qwen3.5-2B Q4+hqq 导出，Metal 和 CPU greedy 都输出乱码；Q8 导出完全正常；--test torch 侧正常；op 单测全过。最初被当作"Metal 乱码问题"排查。
排查路径：
_QUANT_MAX_ELEMENTS // ic = 第一个量化分块 → 随机张量复现：MPS 上 2^28 元素 Q4 打包输出全 0，CPU 正常；sum(axis=1) 是罪魁：MPS 对 ≥2^28 个 uint8 元素的归约静默返回全 0（alpha 正常，所以只有权重坏）。根因：lm_head 248320×2048 ≈ 508M 元素 > 256M 分块上限，第一块恰好 2^28 元素；torch_utils.py Q4 打包用 (q_weight * multipliers).sum(axis=1)，该 sum 在 MPS 上触发框架 bug → 前 131072 行 lm_head 权重全零 → logits 大面积错乱 → 乱码。小模型（如 qwen3-0.6b）vocab 小、不触发分块满 2^28，因此从未暴露。
修复（transformers/llm/export/utils/torch_utils.py）：
# 旧：q_weight = (q_weight * multipliers).sum(axis=1).to(torch.uint8) # MPS 大张量静默全 0
# 新：uint8 逐列按位累加，全程不发生 dtype 提升，绕开归约
packed = torch.zeros(q_weight.shape[0], dtype=torch.uint8, device=q_weight.device)
for i in range(group_size):
shift = quant_bit * (group_size - 1 - i)
packed |= q_weight[:, i] << shift
q_weight = packed
验证：torch.equal(mps结果, cpu结果) == True；重导 Q4+hqq 后 CPU（58 tok/s）与 Metal（90 tok/s）greedy 输出均正确。
避坑要点：
| 文件 | 作用 |
|---|---|
transformers/llm/export/utils/torch_utils.py | 量化 + 低 bit 打包（本案例修复处，含 256M 分块逻辑） |
transformers/llm/export/utils/mnn_converter.py | build_weight 写权重文件、write_header、tie_embeddings 信息 |
transformers/llm/export/utils/hqq_quantizer.py | hqq 量化实现 |
transformers/llm/engine/src/diskembedding.cpp | 引擎侧 Q4/Q8 dequant 参考（nibble 序、alpha 布局、offset 公式） |
transformers/llm/engine/src/llmconfig.hpp | tie_embeddings 字段解析 |