1. 课程导入

在边缘计算与智能驾驶场景中，地平线旭日（Sunrise）系列芯片凭借高能效的BPU架构被广泛采用。然而，当算法工程师把在GPU上训练好的模型迁移到旭日平台时，常常会遇到算子不支持、精度下降、编译报错、推理结果异常等问题。这类问题的根源，往往不是模型本身有错，而是算子与BPU硬件、工具链、量化策略之间的兼容性没有对齐。本课程围绕"旭日算子兼容性排查"这一主题，帮助你把零散的报错经验，整理成一套可复用的排查方法论。

一、学习目标：从"能跑通"到"能定位"

本课程不满足于让你记住几个报错代码，而是希望建立三层能力：

• 认知层：理解旭日工具链中算子从框架模型到BPU可执行指令的完整转换链路，知道每一层可能引入兼容性约束。
• 方法层：掌握"看日志—查算子清单—比对约束—定位根因—替换或改写"的标准排查流程。
• 实战层：能够独立处理典型算子不支持、量化溢出、动态shape、自定义算子等高频问题，并给出可落地的替代方案。

二、核心价值：为什么算子兼容性值得单独学

很多工程师把算子兼容性当成"踩坑"，遇到就查论坛、换版本，问题解决了却不清楚为什么。实际上，算子兼容性排查能力直接决定三件事：

1. 项目周期：模型转换失败若不能快速定位，往往导致数天甚至数周的返工。
2. 部署精度：某些算子虽被支持，但在量化后精度骤降，需要判断是算子问题还是量化策略问题。
3. 性能上限：算子是否落在BPU高效执行区间，直接影响帧率与功耗，兼容性排查也是性能优化的前置工作。

换句话说，掌握这套方法，你就能把"模型能不能上板"从玄学变成工程判断。

三、整体知识框架

旭日算子兼容性排查的知识体系可以拆成四个相互关联的层面，下图展示了从模型输入到问题定位的整体结构关系：

图中上半部分是"模型—工具链—算子库"的转换链路，中间是排查核心，下半部分是四类高频问题分支，底部是验证闭环。学习路径也据此展开：先建立链路认知，再掌握排查动作，最后通过案例固化经验。

四、方法流程：一次完整的排查应该怎么走

面对一个转换失败或推理异常的模型，建议按以下顺序推进，避免盲目试错：

1. 收集信息：保留完整的转换日志、模型结构文件、量化配置和工具链版本号。
2. 定位阶段：判断问题发生在模型解析、算子映射、量化校准还是编译生成阶段。
3. 比对算子：用工具导出模型中全部算子，与BPU支持清单逐项比对，标记不支持或带约束的算子。
4. 分析约束：对"支持但有约束"的算子，检查输入维度、数据类型、属性参数是否越界。
5. 制定方案：根据根因选择替换算子、拆分结构、调整量化策略或使用CPU回退。
6. 验证闭环：重新转换并做精度比对，确认问题真正解决。

其中第3步通常借助工具链自带的检查命令完成，例如：

hb_mapper checker --model-type onnx \
  --march bayes \
  --model model.onnx \
  --input-shape input 1x3x224x224 \
  --output-file check_result.txt

检查结果会列出每个算子的支持状态与约束提示，这是后续判断的关键依据。

五、典型场景与常见误区

以一个图像分类模型迁移为例：模型在GPU上推理正常，转换到旭日后报"算子不支持"。初学者容易直接删除该算子或换用近似结构，结果精度大幅下降。正确做法是先确认该算子是否有等价实现，再评估替换对精度的影响。