bugfix

# MNN Bugfix 排查 Skill（入口） > **触发**：MNN 中出现正确性 bug、单测/golden 对不上、回归；或做完改动（新 op、fusion、图 pass、 > 后端 kernel、量化导出）后行为异常。 > > **边界**：不读不改 `schema/private/`、`source/internal/`。 本文件**只做分流，不承载技术内容**：先用下面两张表决定该读哪一份分册（或该转去哪个 skill）， 再整份读那一份。分册之间互不依赖，可独立阅读。 修复验证与是否提交单测，按 [test-ci 的 Bugfix 单测提交原则](../test-ci/test-suite.md#bugfix-单测提交原则) 执行。 ## 第一步：这个 bug 是不是本 skill 的 | 情况 | 去哪 | |---|---| | **QNN / NPU（高通 HTP）**：结果不对/精度差、报 `1002/6000/1003/6004`、`graphFinalize/graphExecute` 失败、`validateOpConfig failed`、某算子 QNN 不支持、LLM 在 NPU 上乱码 | [`qnn-debug`](../qnn-debug/SKILL.md)（QNN 两条执行路径、中间张量 dump、误差模式与算子约束速查），不要在这里从头排查 | | **CPU 性能改动之后稳定地错在某一档**：只有 t4+ 错、只有超过某长度错、只有某条 precision/ISA 错，或不崩不报错只是模型输出质量变差 | [`cpu/optimize/bugfix.md`](../cpu/optimize/bugfix.md)（CPU 五层交界处的六类不一致 + 「改动面 → 必查条目」索引） | | **崩溃**（SIGSEGV / abort / 真机 crash 日志） | [`crash-debug`](../crash-debug/SKILL.md) | | 其余：跨后端通用的**正确性**方法论 | 本 skill，继续看第二步 | **与 CPU 分册的判别口径**：那本收「稳定地错在某一档」，本 skill 收「同一输入每次跑都不一样」 （[`nondeterminism.md`](nondeterminism.md)）与「与层无关的框架级根因」。同一组合下结果不可复现，留在本 skill。 ## 第二步：症状 → 分册 | 分册 | 典型症状（强判别信号加粗） | 旧编号 | |---|---|---| | [`memory-aliasing.md`](memory-aliasing.md) | 数值错乱、乱码 token、NaN，但指针地址都合法、单 op 单跑对；**一个后端错另一个后端对**；关掉某个新加的优化/融合就好；加 printf 或改 buffer size 就"好了"；**反复创建/销毁后物理内存按固定步长线性增长**；**iOS 长循环单测被 jetsam（signal 9）而 C++ 侧生命周期全部配平**（§1.10 Metal autorelease pool 累积） | §1 | | [`export-and-quant.md`](export-and-quant.md) | 低 bit（Q4）乱码而 Q8 正常；**所有推理后端一致地错**；torch 侧 `--test` 正常；只有大 vocab / 大模型触发 | §2 | | [`concurrency.md`](concurrency.md) | 崩在**析构链**上（`~XxxMemObj` / `~Tensor`）但同一段代码单线程跑一万次都对；**后台线程 / GCD 队列上异步销毁**对象；线上偶现、本地必不复现；崩溃地址不合法或像被复用过的堆内存 | §3 | | [`fp16-range.md`](fp16-range.md) | 长 prompt 输出重复/漂移，短 prompt 正常；**fp32（`precision: high`）对、fp16 错**且所有 fp16 后端一致地错；**出错阈值恰是 2 的幂**（2048/4096） | §5 | | [`gpu-oob.md`](gpu-oob.md) | `[METAL] command buffer error` 后**速度假快数百倍**；只在某 shape 阈值之上触发；关某条 kernel 路径 env 后消失；同一越界在别的模型上表现为静默数值损坏 | §6 | | [`kernel-assumptions.md`](kernel-assumptions.md) | 某**类**模型（SWA / prefix LM / bidirectional）静默乱码，标准 causal LLM 正常；调一个"看起来无关"的性能开关就好 | §7 | | [`stale-cache.md`](stale-cache.md) | 开 `use_mmap` 才乱码（单字符刷屏）；**App 内错、`llm_demo` 对**；清缓存目录或换 `tmp_path` 就好；换模型不换目录后乱码 | §8 | | [`nondeterminism.md`](nondeterminism.md) | **同一输入每次跑结果都不一样**：§9 输出在正常/乱码间漂移、加无关代码就"好了"、只在某线程数触发、大片 ±65504 或 `!!!`、bisect 结论不稳定；§10 内容连贯但逐 run 不同（贪心解码仍分叉） | §9、§10 | | [`gpu-inflight-overwrite.md`](gpu-inflight-overwrite.md) | **单跑 N 次全过、放进测试家族里偶发失败**，且 **`MallocScribble` 下仍全过**（← 与 §9 的硬分野）；错误值合理但偏 10~30%、出错位置对应"最早写入的那批数据"；**两次 forward 之间插一次 GPU drain 就稳定通过**；增删无关前置用例失败率就变；GPU 跑分逐 run 抖动像"某条快路径时有时无"；改了 uniform 传递方式后 decode 从第 2 个 token 起全错 | §11 | | [`nan-masking.md`](nan-masking.md) | **只有带激活（relu/relu6/clamp）的用例才错**，无激活版"恰好"通过；输出恒 0 或恒 clamp 边界；原始输出打印是 `nan`；只有退化输入（全零权重块/零 scale）触发；比较器对 nan 静默放行 | §12 | > **旧编号一列是给历史引用用的**：其他 skill 与复盘记录里写的「general-debug §9 / §10」等指的就是 > 这里对应的分册。分册内部的小节号（§1.3、§5.6、§9.4 …）保持不变，可以继续直接引用。 > §3 只收 **host 侧共享所有权 / 引用计数**的竞争；相邻的三类竞争在别处： > [`memory-aliasing.md`](memory-aliasing.md) §1.6（GPU 单 dispatch 内 threadgroup 竞争，含逐 op commit 二分法）、 > [`nondeterminism.md`](nondeterminism.md) §10（CPU 动态分发 × 异构 kernel） > 与 [`gpu-inflight-overwrite.md`](gpu-inflight-overwrite.md) §11（**跨 command buffer** 的 host↔device 时序）。 > > 尚未入库：**图优化回归**（某个 converter pass 之后跑错、disable 该 pass 就正常），即历史编号 §4。 > 首次复现时按下面的维护约定新开一份分册，编号从 **§13** 起——§4 是历史空号，不再复用。 **症状横跨多类时**的推荐顺序：先做「所有后端是否一致地错」的分流（一致 → `export-and-quant`， 不一致 → `memory-aliasing`），再做「fp32 是否也错」（fp32 对 → `fp16-range`）， 最后才怀疑 kernel 假设与缓存。**「每次跑都不一样」优先于一切**——非确定性会让前面所有对拍结论作废， 先去 `nondeterminism.md` 把它压成确定性问题；**若 `MallocScribble` 下不复现、且单跑该用例永远通过 只有和别的用例一起跑才偶发**，那不是 §9，直接转 `gpu-inflight-overwrite.md`（§11）。 ## 通用排查原则（所有分册共用） 1. **先复现最小化**：定住能稳定复现的最小 case（最短 prompt、最小 shape、单线程），然后逐步添加变量。 2. **两向 A/B**：换后端、换开关、换编译选项、换线程数 —— 任一维度上"这边错那边对"都是强线索。 3. **别信"这块应该是独立的"，用直接观察去证明**：地址、值、时序都要用打印/断点去看，不要靠推理。 4. **修改先做假设，验证后再改代码**。改一版跑一版，避免"多改一起观察但不知道哪个生效"。 5. **改完记录**：如果本次 bug 有可复用的教训，追加到对应分册的"参考案例"；如果发现新的 bug 类别， 新开一份分册并更新本文的分流表。 6. **导出/序列化崩溃先查 I/O 边界**：用回溯定位第一个文件写入点；converter 入口先创建并验证父目录， `fopen` 失败必须立即返回，禁止把空 `FILE*` 传给 `fwrite`。不要把这种晚发的 SIGSEGV 误判成模型或后端问题。 7. **区分建图与执行阶段的资源绑定**：对外部 backend API，先确认 graph tensor 创建时允许哪些字段， client buffer、memory handle 等运行时资源只在 API 要求的阶段绑定；在至少两个 SDK/SoC 组合上检查 建图日志，不能以某个版本的宽容行为代替契约。 **对拍纪律**（每个分册都会踩）：hash 输出前剔除 `cost time` 等计时行；对拍前预热一次（首次运行 会重建 pipeline cache）；`llm_demo` 强制共享 `tmp/` 缓存目录，对拍前 `rm -rf tmp`； 确定性测试必须显式钉死 sampler（`"sampler_type":"greedy"`），默认 `mixed` 本身就是非确定采样。 ## 目录结构 ``` skills/general-debug/ ├── SKILL.md ← 本文件，症状分流 + 通用原则 ├── memory-aliasing.md §1 内存别名 / 生命周期（arena reuse、融合别名竞争、fp32 当 oracle） ├── export-and-quant.md §2 量化误差 / 导出侧权重损坏（量化 bisect、离线反量化比对） ├── concurrency.md §3 并发 / 线程竞争（host 侧引用计数、TSAN A/B、编译期哨兵） ├── fp16-range.md §5 fp16 表示能力不足（值域改写、查表化重构的三类陷阱） ├── gpu-oob.md §6 GPU shader 越界 / command buffer 故障 ├── kernel-assumptions.md §7 后端 kernel 隐式假设违反（causal mask、layout 约定） ├── stale-cache.md §8 持久化缓存误信（weight-mmap sync 自我污染、跨模型污染） ├── nondeterminism.md §9 未初始化内存 / 堆垃圾依赖 + §10 多线程数值非确定 ├── gpu-inflight-overwrite.md §11 host↔device 时序竞争（在飞 uniform 被 encode 期覆写 / 未上传的输入被读取） └── nan-masking.md §12 非有限值（inf/NaN）注入与掩盖（relu-only 失败 = 上游 NaN 定影） ``` ## 维护约定 - 每份分册按同一骨架写：`触发` → `核心心法` → `相关背景`（可选）→ `排查流程`（Step 化）→ `常见对照表：症状 → 优先怀疑` → `参考案例` → `相关文件索引`。 - 新增类别 = **新开一份分册**（不要往已有分册里塞进第二类根因），文件名用症状而非编号， 并在本文的分流表与目录结构里各补一行；分册内部小节号沿用新分册的编号段。 - 参考案例写"排查路径 + 根因 + 修复 + 避坑要点"，其中**排除项与它们为什么误导**必须写， 否则下一个人会重跑同样的死路。 - 结论上提到分册正文，过程与数字留在案例段；性能相关的过程数据不进本仓， 归到对应后端 skill 的结论文档或外部台账，不要挤进本 skill。 - 复盘走 [`retrospective`](../retrospective/SKILL.md)。