四、异常码分类体系：按错误来源与严重级别构建层级化结构
端侧推理引擎的异常码设计，本质上是对“失败模式”的工程化编码。与云端服务不同，端侧环境（手机、IoT、车载、边缘盒子）的硬件异构性、系统碎片化、用户行为不可控性，使得异常来源极其分散。如果仅用扁平数字编号，排障时往往需要逐条翻阅文档，效率极低。本章将系统讲解如何从“错误来源”和“严重级别”两个正交维度，设计一套可扩展、可检索、可自动处理的层级化异常码结构。
上图展示了层级化异常码的完整结构。第一层用两位字母标识错误来源，第二层用一位数字标识严重级别，第三层用三位数字标识具体错误场景。这种设计使得异常码本身携带了足够多的上下文信息，例如 MD-1-001 直接表明是“模型来源、致命级别、加载失败”，无需额外查表即可快速定位问题方向。
4.1 核心原理：为什么需要多维分类
端侧推理的异常处理与云端有本质区别。云端可以通过日志聚合、分布式追踪快速定位问题，而端侧设备往往处于离线或弱网状态，异常信息只能通过本地日志、崩溃转储或用户上报回传。如果异常码设计不合理，排障人员面对一堆无规律的编号，几乎无法判断问题优先级和影响范围。
多维分类的核心价值体现在三个层面：
- 可过滤性：按来源分类后，可以快速筛选出“所有硬件相关异常”或“所有模型相关异常”，便于专项排查。例如，某次版本更新后大量设备上报
HW-*异常，可以立即怀疑是驱动兼容性问题。 - 可排序性：按严重级别分级后，可以优先处理致命异常。端侧设备资源有限，不可能对所有异常都做同等深度的处理，分级机制让系统在资源紧张时能够“丢卒保车”。
- 可扩展性：层级化结构允许在每一层独立扩展。新增一个错误来源时，只需分配新的字母码；新增一个具体错误时，只需在对应来源和级别下追加序号，不会破坏已有编码。
此外，层级化异常码还天然支持“通配符匹配”策略。例如，监控系统可以配置规则：所有 *-1-* 异常（致命级别）触发立即告警，所有 HW-*-* 异常（硬件来源）触发硬件健康检查。这种模式在云端监控平台中非常实用。
4.2 错误来源分类：五大来源与判定方法
根据端侧推理的实际场景，我们将错误来源划分为五大类，外加一个“其他”兜底类别。每一类都有明确的判定边界，避免模糊地带。
| 来源码 | 来源名称 | 典型场景 | 判定依据 |
|---|---|---|---|
| MD | 模型 | 模型文件损坏、算子不支持、权重维度不匹配、量化参数错误 | 异常发生在模型加载、解析、编译或执行阶段，且与模型文件内容直接相关 |
| DT | 数据 | 输入张量形状错误、数据类型不支持、数据越界、预处理失败 | 异常发生在数据输入或预处理阶段，且与输入数据内容或格式相关 |
| HW | 硬件 | NPU/GPU 内存不足、DSP 超时、总线错误、驱动无响应 | 异常由硬件设备返回，或与硬件资源分配、访问相关 |
| OS | 系统 | 文件系统权限不足、线程创建失败、内存映射失败、系统调用异常 | 异常由操作系统 API 返回，或与系统资源管理相关 |
| UI | 用户输入 | 参数配置非法、模型路径不存在、推理超时设置错误 | 异常由用户提供的配置或参数触发，且可通过输入校验避免 |
| OT | 其他 | 未知内部错误、第三方库异常、未分类错误 | 无法归入以上五类时的兜底分类 |
判定方法上，建议在异常捕获层设置“来源探测器”。例如，当捕获到 std::bad_alloc 时，检查分配内存的上下文：如果是在加载模型权重时分配，则归为 MD；如果是在输入预处理时分配，则归为 DT；如果是在推理执行时分配，则归为 HW。这种上下文感知的判定方式比单纯看异常类型更准确。
4.3 严重级别分级：四级体系与响应策略
严重级别决定了系统对异常的处理优先级和用户可见度。我们采用四级体系：致命、严重、警告、提示。
- 致命（1级）：系统无法继续运行，推理进程必须终止。例如，模型文件损坏导致无法加载，NPU 硬件故障导致计算单元不可用。此类异常必须立即记录完整上下文，并尝试保存崩溃转储。
- 严重（2级）：当前推理任务失败，但系统进程可以存活。例如，单次推理内存不足，可以释放缓存后重试。此类异常需要上报，但不需要终止进程。
- 警告（3级）：推理结果可能不准确，但流程未中断。例如，输入数据部分越界被截断，或量化精度损失超过阈值。此类异常应记录日志，但用户可能无感知。
- 提示（4级）：正常但值得记录的信息。例如，模型加载耗时超过预期，或使用了回退路径。此类异常仅用于性能分析和行为追踪。
分级策略与业务场景强相关。对于自动驾驶等安全攸关场景，警告级别可能就需要触发安全降级；而对于图像分类等非关键场景，警告级别仅记录即可。因此，异常码中的级别字段是“建议值”，实际响应策略由上层业务决定。
4.4 案例拆解：从异常码到排障闭环
下面通过一个真实案例，展示层级化异常码如何加速排障流程。
背景与约束：某 AIoT 设备厂商在量产阶段收到用户反馈，部分设备在夜间运行 3-4 小时后出现推理失败。设备端侧部署了人脸检测模型，使用 NPU 加速。由于设备数量庞大且分布在不同网络环境，无法实时远程调试，只能依赖日志回传。
初始现象：设备日志中出现大量 HW-2-014 异常码，同时伴随 OS-3-002 警告码。初步判断为硬件内存不足，但为何只在夜间出现？
分析过程：
- 通过异常码过滤，发现
HW-2-014全部集中在夜间 22:00-02:00 时段。 - 进一步查看
OS-3-002（内存碎片化警告）的时间分布，发现与前者高度重合。 - 结合设备运行规律，推测夜间可能有其他后台任务（如系统更新、数据备份）占用内存，导致 NPU 可用内存不足。
实际操作：在设备端增加内存监控模块，记录 HW-2-014 发生时的系统内存快照。确认是系统后台任务导致的内存碎片化，NPU 无法申请到连续大块内存。
结果对比：修复方案为在推理前主动进行内存整理，或调整 NPU 内存分配策略为“允许非连续分配”。修复后，HW-2-014 发生率下降 97%，夜间推理失败问题解决。
复盘经验：如果异常码没有来源和级别维度，排障人员需要从数千条日志中逐条分析，至少需要 2-3 天才能定位到内存碎片化问题。而层级化异常码让问题在 2 小时内就聚焦到了“硬件内存 + 严重级别”的范围内。
4.5 常见误区与设计建议
在设计异常码体系时，以下误区需要特别注意：
误区一：级别与来源混淆。有些团队将“模型错误”直接等同于“致命错误”，忽略了模型推理时也可能出现可恢复的警告（如精度下降）。正确做法是：来源和级别是两个独立维度，任何来源都可能出现任何级别。
误区二：编码过于密集。为了节省存储空间，使用极短的编码（如 4 位数字），导致无法表达层级关系。实际上，异常码通常以字符串形式存储，多几个字符对存储影响微乎其微，但可读性提升巨大。
误区三：忽略“未知”类别。没有设计兜底分类，导致无法归类的异常被强制塞入某个不合适的类别，污染统计数据。务必保留 OT 或其他兜底类别。
设计建议：在异常码末尾预留 1 位“版本位”，用于标识异常码体系的版本。当异常码定义更新时，旧版本设备上报的异常码仍可被正确解析。例如 MD-1-001-1 中的 -1 表示版本 1。
最后，异常码体系不是一次性设计完成的。随着产品迭代，新的错误场景会不断出现。建议建立异常码注册中心，所有新增异常码必须经过评审，确保分类合理、级别恰当。同时，定期分析异常码分布，识别高频异常并推动根因修复，形成“设计-使用-反馈-优化”的闭环。