7.2 调试与常见问题排查

7.2 调试与常见问题排查

本节摘要：部署故障很少是新问题。本节把高频故障按「转换报错、编译失败、加载异常、性能异常、精度漂移、运行不稳」六类整理成排查索引，每类给出第一动作、常见根因与前文机制的回查点——遇到故障先查表，再动手。

7.1 节的工具回答「跑得好不好」，这一节回答「为什么不好」。排错的能力差距不在见多识广，而在顺序：同样一个故障，按层排查的人半小时收工，凭感觉试的人两天没摸到边。本节的六类故障索引，就是把前六章的机制知识折算成排查顺序。

排错总纲：先定位环节，再找原因

推理系统的故障定位有一个铁律：先确定故障发生在四段链路的哪一段——转换、编译、加载执行、还是长期运行。报错信息通常自带环节线索：转换器报的是解析错，编译报的是算子与形状错，运行期报的是张量与内存错。跨环节乱试（转换报错去重装运行时）是最大的时间黑洞。

图 7-2 六类故障的排查决策图

六类故障的快速索引

转换报错。第一动作是读报错里的算子名与版本号，然后走 2.3 节的三维诊断。高频根因：算子集版本落后（升级工具链即解）、目标前端导出选项不当（重新导出时禁训练态算子）。

编译失败。转换成功但 compile_model 报错，先做对照实验：同一模型换 CPU 编译——CPU 能过则是指定设备的算子或形状限制，NPU 上多见动态轴问题，按 2.1 节锁形状重转。

加载与张量异常。运行期报形状或类型不匹配，把期望值与实际值逐项对照：形状、元素类型、布局、步长。报错信息一般自带两侧数值，冷静读完就省一次瞎猜。

性能异常。症状是「比测试环境慢」。按 7.1 节三件套走：基准复测对齐配置、逐层计时找头部、属性查询查生效配置。高频根因清单：隐式内存拷贝（3.2 节）、性能提示未生效、编译到了兼容指令集路径、笔记本插电状态与功耗策略（4.3 节频率墙）。

精度漂移。量化后掉点直接走 4.4 节的完整路径；非量化场景先怀疑预处理契约——均值缩放做过头、通道顺序反了、归一化区间不一致，这三样占了非量化精度事故的绝大多数，且全部安静不报错。

长期运行不稳。越跑越慢或周期性卡顿，先看三样：内存曲线（涨而不落即泄漏，查会话与请求生命周期）、温度与频率（热降频，4.3 节）、共存服务的资源竞争（5.3 节）。运行不稳的问题九成在资源，不在算法。

异步与并发的三个专属陷阱

多线程场景有几类单机同步代码里遇不到的坑，单独列出。异步回调里的悬垂张量：回调触发时持有别的请求的输出缓冲，若该请求已被复用，读到的是新数据——回调里只取本请求对象，跨线程传递用拷贝。共享请求的串行退化：多个线程排队用同一个请求，「异步」名存实亡，按 3.1 节纪律一请求一线程或按并发数领请求。异常在回调里蒸发：后台线程抛出的异常没人接，表现为「偶发无结果」——回调体内完整捕获并落日志。

⚠️ 排错时最贵的动作是「顺手改了别的东西」。修一个问题的改动如果顺带优化了另一处，那个优化就是未经验证的变量——分开提交、分开验证。

一单跨环节故障的完整追踪

排错索引的用法，用一单「跨了三个环节才定位」的故障来演示。现象：某检测服务灰度期间，运营反馈识别结果「时对时错」，同一批图片重跑结果与首跑不一致——不可复现的精度问题，最容易把人引向玄学。按总纲先定环节：转换与编译自灰度以来没动过，嫌疑集中在执行段；「时对时错」指向并发或状态类问题(7.2 节六类里的第四、六类交叉)。第一步查请求池：发现池大小为一却有三个线程并发取用——3.1 节请求级线程纪律被违反，请求内部的输入张量被互相覆盖。修复为池大小等于并发数，问题立即稳定。

但排查没有停：为什么单测与压测都没抓到？单测单线程自然没事；压测只校验了延迟没校验结果一致性——这是真正的流程漏洞。补上的对策是压测增加结果一致性断言(同一批输入跑两遍输出必须一致)，写进 7.3 节的闸门二。这单的完整价值在第二层：故障修复只算止血，流程补漏才算愈合。每个排查案例都该追问一句「流程哪一环放它进来的」，答案回流到工作流，同一个坑才算真正填上。

报错信息的三段读法

故障索引的入口是报错信息，补一个通用读法。部署报错无论多晦涩，都值得拆三段读：第一段找环节词——「转换」「编译」「加载」「infer」这些词直接把你送到六类索引的对应类目；第二段找对象名——算子名、设备名、张量维度，这些是检索文档与对应章节关键词的钥匙；第三段找期望与实际的对照——成熟的报错会同时给出「期望什么、实际什么」，两侧数字的差值往往就是答案本身(形状差一维、类型差一位宽)。读不懂时把三段分别检索，不要整句粘贴搜索——整句里往往混着本机路径与版本号，噪音盖过信号。最后一条习惯：把每次修复时的原始报错与解法一起存档，团队的知识库里最值钱的就是这些「报错原文加处置」的配对条目。

排错的心理纪律

技术之外的半节，写给深夜值班的人。排错最大的敌人不是复杂度，是焦躁驱动的「乱试」——换版本、改配置、重启机器连成一气，把现场搅得一团糟，原本五分钟能定位的问题被自己亲手抹掉了指纹。三条心理纪律：动手前先拍照——把报错原文、配置快照、最近变更清单记录下来，这是你的现场；每步只动一处——改动后必须复测，复测不变就回滚，让每次实验保持单变量；十五分钟规则——同一条路走了十五分钟没有新信息，停下来换类目，索引里还有五类没查。部署故障几乎都有确定性的根因，它不奖励运气，奖励顺序。

三个高频追问

排错话题收尾，回答三个高频追问。追问一：日志里没有任何报错但结果就是不对，从哪查起？静默故障按「契约」排查——输入数据是否真的符合假设(抽样打印统计值)、配置是否真的生效(属性快照对照)、版本是否真的对齐(模型与运行时的配对记录)；无报错的问题九成是「假设错了但没人验证」，把假设逐个变成断言，问题就现形。追问二：故障只在客户现场出现，开发环境复现不了怎么办？先收现场三件套——环境快照(属性查询输出)、当日报错日志、出问题时段的输入样本；三件套到位后，多数「复现不了」会变成「在复现环境里等条件」——温度、时长、数据分布这些现场变量，开发环境往往缺的正是它们。追问三：怎么减少故障本身？回头看 7.3 节的闸门——每一起线上故障都应该问「哪道闸门能拦住它」，答不出来的故障，就是流程缺口的清单；排错的终点不是修复，是闸门补全。三个追问的共同答案：排错的功夫在排错之外——断言、现场采集与闸门复盘，才是让故障变少的那部分。

排错工具箱的常备清单

给值班现场配一个常备「排错工具箱」，装五样：属性快照脚本(一条命令导出全部运行时配置与设备信息)、最小复现工程(能加载任意 IR 跑一次推理的几十行骨架)、对拍脚本(2.1 节的数值一致性验证)、基准命令模板(7.1 节对齐生产配置的标准命令)、以及本章的六类索引打印件。工具箱的意义在「现场压力下不需要回忆」——凌晨的故障处理，翻清单比翻文档快，比凭记忆更快。每处理完一单故障，把用到的临时脚本沉淀进工具箱，一年后它就是团队最值钱的运维资产。

本节要点回顾

• 先定环节再找原因：转换、编译、执行、长期运行四段，报错信息自带环节线索。
• 六类索引：每类的第一动作与高频根因都已列表，动手前先查表。
• 并发三陷阱：悬垂张量、共享请求退化、回调异常蒸发，多线程排错先查这三样。
• 纪律三则：单变量、留基线、必留档，顺序感比经验值更保命。

单点故障会排了，最后一课是让故障根本少发生：把全书的动作串成一条带反馈闭环的工作流。7.3 节收束全书。