简介：AXera第二代AI工具链Pulsar2的官方文档库，面向使用AX650A、AX650N、AX630C、AX620Q等SoC进行AI应用开发的嵌入式工程师与算法开发者。这套资料共28个文件、约279KB，以13个rst格式的Sphinx文档源文件为主体，配合7张png架构示意图、2个md说明文件，另有Python脚本、Makefile与YAML配置辅助文档构建与定制。用户指南划分为quick快速入门、config配置指南、advanced高级进阶三大部分，同时覆盖pulsar2主工具、other_tools辅助工具等模块，对硬件加速、模型部署等关键流程配有直观配图说明。当前已有243人学习浏览，适合刚开始接触Pulsar2、需要系统查阅接口配置与工具链用法的开发者离线检索与对照学习，能有效缩短从了解概念到上手实践的时间。
1. Pulsar2 的文档库：AXera 的 SoC 第二代 AI 工具链，到底解决什么问题
拿到 AXera 的 SoC 评估板，很多算法工程师的第一反应是查算力规格、翻几眼 SoC 天梯图，但真正决定模型能不能跑满 NPU 的，往往是 AI 工具链。Pulsar2 是 AXera 面向自家 SoC 做的第二代 AI 工具链，文档库则把模型转换、量化、编译、板端 runtime 整套链路写成能照着抄的说明。这篇笔记写给第一次接触 AXera SoC 的部署工程师和算法工程师：从工具链构成、最小部署工程到最常见的翻车点，讲清楚怎么靠文档库把 PyTorch/ONNX 模型一步步落进 NPU，参数怎么设、哪些坑是血泪经验换来的。
2. Pulsar2 工具链的构成：从 PyTorch/ONNX 到 NPU 指令要过几道关
2.1 文档库导航里藏了哪些模块
第一次打开 Pulsar2 的文档库，大概率会被左侧导航栏的长度吓一跳。其实把目录拍平，它讲的就是一条流水线：模型进来，指令出去，中间包着转换、量化、编译三层。文档库的导航顺序基本就是工具链的执行顺序，读懂导航等于先读懂工具链。
我一般建议重点看这几个模块：
- 快速入门：环境准备、最小示例工程、固件烧录。先不纠结原理，目标是让板子把自带 demo 跑起来。
- 模型转换：从 ONNX、TorchScript 导出到工具链中间表示的规则，包括支持的框架、opset 版本、导出注意事项。
- 量化与校准：PTQ 量化的标准流程，校准数据集的挑选、量化类型选择、敏感层回退。
- 算子支持清单：逐算子列出支持情况、限制条件、版本差异，这是排查转换失败最常翻的部分。
- 编译与部署：量化模型如何编译成 NPU 可加载的指令文件，产物的构成和存放路径。
- Runtime API：板端加载模型、绑定输入输出、执行推理的接口说明，以 C/C++ 为主。
- 示例工程：常见检测和分类模型的 demo，包含预处理、推理、后处理全套代码。
这些模块之间的输入输出关系像一条装配线：
| 文档模块 | 输入 | 输出 | 对应阶段 |
|---|---|---|---|
| 快速入门 | 评估板 + 固件 + 示例 | 可跑通的 demo | 准备期 |
| 模型转换 | ONNX / TorchScript | 中间 IR | 转换 |
| 量化 / 校准 | 中间 IR + 校准集 | 量化 IR | 量化 |
| 编译 / 部署 | 量化 IR | NPU 指令 / 部署包 | 编译 |
| Runtime API | 部署包 + 输入 | 推理结果 | 运行期 |
| 算子支持清单 | 网络结构 | 兼容性结论 | 转换前检查 |
这种拆分符合 AI 工具链的通用结构。模型转换只负责“翻译”，把上层框架的表达翻译成工具链自己的中间表示；量化负责把 float 权重压缩到 INT8 这类低精度格式，同时尽量保住精度；编译负责把量化后的图映射到 NPU 硬件单元上，生成指令序列。文档库按这个拆，是为了让使用者在不同阶段只看自己需要的那一段。真正常看文档库的人，不是读完整本，而是在转换报错时查算子支持，在量化掉点时查校准方案，在性能不足时查编译参数和性能报告。
2.2 为什么要做“第二个”AI 工具链
标题里的“第二个”不是简单的版本号递增。第一代工具链面向的是第一代 SoC，NPU 调度方式、算力分配、内存管理模型都按老架构设计。到了 AXera 的第二代 SoC，硬件调度粒度更细、算子单元更丰富，老工具链如果继续打补丁，会出现两个典型问题：一是新算子扩不进去，很多 Transformer 结构转不过去；二是量化精度控制停留在黑匣子阶段，模型能转能跑，但精度和帧率都比预期差一截。
Pulsar2 的出现在文档库侧能看到明显变化。一个变化是中间表示重做了，能承载更复杂的图结构，reshape、transpose、attention 这类组合不再动不动就报不支持。另一个变化是量化从“全图 INT8”演进到逐层、逐子图可配置，敏感层可以单独回退到 INT16 或 FP16，不再是一刀切。还有一个变化是编译端的性能报告更完整，开始能区分瓶颈在计算单元还是内存带宽。
实际使用中，量化层面的变化感知最明显。第一代工具链往往整图一刀切 INT8，遇到敏感结构只能全模型回调到 FP16，帧率损失很大。Pulsar2 这类第二代工具链提供逐层精度配置和敏感度分析，用户可以在精度和速度之间找折中。算子覆盖方面，第二代对 Transformer 的支持是标志性差异，这是第一代很难通过小版本升级补上的。所以读 Pulsar2 文档库时，不要全盘复用第一代工具链的旧经验，重点看它新增的章节和 release notes。很多你以为的 bug，是文档库某个版本已经明确修掉的老问题。
2.3 文档库的正确阅读顺序：不是从头读到尾
文档库不是小说，从头读到尾效率很低。我自己的顺序是：先花半天把快速入门跑通，确认工具链、固件、runtime 三板斧能配合；再用算子支持清单预检自己的网络，把不支持的算子提前排查掉；最后在跑真实模型时，按“转换 - 量化 - 编译 - 运行时”的顺序逐段查对应章节，遇到报错再回头翻对应 FAQ。
这个顺序背后的逻辑是：第一层确认环境可用，第二层确认模型可转换，第三层才是调参数。不少人一上来就钻到量化参数里调，调了半天发现模型转换那一步已经有算子不支持，等于白调。文档库目录的排列顺序其实已经暗示了这条路径，跟着走就好。
还有两个阅读建议。一是看文档要带“版本意识”，Pulsar2 的文档库会随工具链迭代更新，算子支持、参数行为都可能变，收藏某个章节链接后要留意版本标注。二是多利用文档里的 FAQ 和示例工程代码。很多报错在 FAQ 里已经描述过，示例工程里的预处理代码也可以直接复用，比自己在网上搜零散经验可靠得多。
3. 照着文档库跑通最小部署工程：步骤、命令与参数
3.1 环境准备：Docker、固件、模型格式
Pulsar2 的工具链常见做法是提供一个 Docker 镜像，把模型转换、量化、编译全部放在 x86 主机容器里做，板子上只放 Runtime 和部署包。好处是 NPU 相关编译依赖不会污染宿主系统，坏处是镜像 tag 和板端固件如果没对上，后面每一步都可能出怪问题。
我的环境准备清单有三项。第一，Docker 镜像按文档库快速入门给出的基础 tag 拉取，不要擅自换新版本；第二，板端固件先升级到文档标注的配套版本，尤其看“固件版本与工具链版本匹配表”，这是后面最容易翻车的地方；第三，模型准备好 ONNX 或 TorchScript 文件，先用 onnx-simplifier 过一遍，把常量折叠、冗余算子清掉，降低后续转换踩算子的概率。
# 以容器方式进入工具链环境，镜像名以文档库实际发布为准 docker run -it --rm \ -v /path/to/models:/models \ -v /path/to/output:/deploy \ pulsar2-toolchain:<版本tag> /bin/bash说明：这条命令把宿主机上两个目录挂进容器，模型目录和输出目录分开，避免中间产物混在一起。进入容器后，后续转换命令都使用容器内的路径，比如 /models 和 /deploy。
3.2 模型转换与 PTQ 量化：校准集和量化参数怎么设
模型转换的常见命令骨架大致如下，具体参数名以实际版本的 CLI Reference 为准：
# 将 ONNX 转成 Pulsar2 中间 IR pulsar2 convert \ --onnx yolov5s.onnx \ --fixed-shape 1,3,640,640 \ --output-dir ./deploy说明：--fixed-shape 是部署推荐的写法，把输入固定为 1,3,640,640。对检测这类模型，固定分辨率能避免后续量化和编译阶段出现动态维度问题。--output-dir 指定中间 IR 输出目录。
转换成功后进入量化，这是精度最敏感的一环。Pulsar2 文档库在量化章节通常会强调三点：校准集规模、数据分布、预处理对齐。我的经验是校准集 100 到 200 张就够，但必须和真实使用场景同分布。
| 量化参数 | 建议值 | 说明 |
|---|---|---|
| 校准集数量 | 100~200 张 | 覆盖不同光照、目标尺度、场景分布 |
| batch-size | 1~8 | 太小波动大，太大校准耗时长 |
| 量化类型 | INT8 为主 | 敏感层可用 INT16/FP16 回退 |
| 预处理 | 与训练一致 | RGB/BGR 顺序、归一化、letterbox 对齐 |
对应的校准命令骨架：
# PTQ 量化：calib_list.txt 每行是预处理后的图片路径 pulsar2 quantize \ --model ./deploy/model.pulsar \ --calibration-list calib_list.txt \ --batch-size 1 \ --quant-level int8说明：校准集数据格式要和部署时一致。模型训练时用的归一化系数是 0.0 到 1.0 还是 0.0 到 255.0，letterbox 用哪种填充方式，都会影响激活值范围统计。很多精度“玄学掉点”最后都查到这一步。
提示：校准集的激活值直方图可以直接反映统计是否偏了。如果直方图明显集中在小值区间，说明预处理或数据分布有问题，先别急着调量化参数。
3.3 编译产物与板端验证：Runtime 怎么加载
量化后的 IR 还需要编译成 NPU 指令文件，这一步通常也是离线完成。有些文档库版本会把 convert 和 build 合并成一步，不要硬找单独的命令，按文档库“编译 / 部署”章节给出的流程走。
# 编译生成 NPU 部署包 pulsar2 build \ --model ./deploy/model_quant.pulsar \ --output ./deploy/npu_model.bin说明：产物可能是单一 bin 文件，也可能是指令、权重、配置多个文件，以实际输出清单为准。拿到部署包后，板端用 C/C++ 接口加载，常见形态如下：
// 伪代码：接口名以文档库 Runtime API 实际版本为准 PulsarEngine engine; engine.init(); engine.load("./npu_model.bin"); // 加载 NPU 部署包 std::vector<float> input(1 * 3 * 640 * 640); // 预处理后的输入 engine.set_input(0, input.data()); // 绑定输入内存 engine.run(); // 执行推理 const auto* output = engine.get_output(0); // 获取输出说明：set_input 的维度必须和编译时的 fixed-shape 一致。有些版本提供预分配内存接口，建议优先使用文档推荐的内存分配方式，不要随手用普通 malloc，NPU 对输入输出有对齐要求，后面避坑章节会展开。
3.4 先用文档库示例工程做对照：确保链路通
第一次跑完整流程，我建议先不上自己的模型，而是用文档库自带的检测示例工程跑通一遍。示例工程的价值在于它把“预处理、推理、后处理”整套代码写好了，哪怕先照着抄，也能看到一个可用的检测输出。
在这个基础上，再把示例里的模型换成自己的网络。替换项只有模型文件和输入预处理，后处理逻辑可以保持不变，这样能少走弯路。判断链路是否跑通，看三个信号：加载时没有版本报错，推理耗时稳定，输出结果和 PC 端浮点模型比没有明显离谱的偏差。三点都过，再进入调优环节。
4. 部署 AXera SoC 最容易翻车的 5 个地方：避坑与排查记录
4.1 量化校准导致精度“玄学掉点”
现象是转换、编译全成功，但 mAP 比浮点模型低 10 个点以上，小目标几乎全丢，而且复现性很差。原因大概率在校准集：全是白天的图、场景单一，或者只有几十张，激活值范围统计偏了，量化参数不适配真实数据分布。更细一点说，很多校准工具默认只统计激活值的 min/max 或百分位，不关心语义信息。校准集只有 100 张但全是车载场景的图，换到室内场景马上掉点。
解决方法是重挑校准集，选 100 到 200 张覆盖白天黑夜、远近目标、不同光照的图，保证和验证集同分布。如果仍掉点，用文档库的敏感层分析工具定位精度损失严重的层，单独回退到 FP16 或 INT16。建议同时在校准脚本里固定随机种子，让校准结果可复现，不然同一份代码每次跑的量化结果都不一样，排错会非常痛苦。
4.2 算子不支持导致整条链路中断
现象是 convert 阶段直接报 unsupported op，或者 convert 过了但在 quantize 时才挂。原因多是模型用了过新 opset 的算子，或某些实现方式较特殊的算子没有被工具链覆盖。排查时要先判断是算子语义未实现，还是转换出来的子图触发了工具链的边界情况。
解决方法是先在算子支持清单核对每个关键算子，再用 onnx-simplifier 把子图折叠。仍不支持的算子，在 host 侧用预处理或后处理代替，或者用 Pulsar2 的自定义算子扩展机制把它落在 CPU 侧执行。切忌绕过报错硬转，后面运行期会以更难看的方式暴露。遇到能稳定复现的不支持场景，记下最小网络用例，下次文档库更新后再验证一次，很多算子支持是逐步补全的。
4.3 动态 shape 让编译拖很久甚至失败
现象是编译阶段耗时异常拉长，或板端推理时崩溃。原因是模型导出时保留了动态维度。NPU 指令按固定 shape 放置数据流和布局内存，动态维度会触发工具链的兜底逻辑，轻则编译变慢，重则失败。
解决办法是在导出模型前固定 batch 和输入分辨率，部署统一用固定 shape。如果业务确实需要多档分辨率，查文档库是否支持多 shape 编译，提前编好几个常用分辨率，运行时切换，不要直接传任意值。还有一个兜底招数：很多检测模型的动态 shape 波动范围集中，可以把宽高按 stride 对齐后填成最大 shape，用中心缩放代替等比缩放，虽然浪费点算力，但稳定性好很多。
4.4 固件和工具链版本不匹配：SoC 启动就报错
现象是部署包在板端加载时报版本错误、NPU 初始化失败，极端情况下 SoC 芯片启动过程就不正常。原因是 Pulsar2 编译产物和板端 NPU 固件是配套的，固件升级后，旧工具链编出来的指令文件可能不兼容。
解决方法是先看文档库的版本匹配表，把板端固件烧录到配套版本。工具链和固件尽量一起升级，不要单独升其中一个。还有一个隐蔽坑：开发机上的工具链版本可能被其他人升级过，但你不知道。建议在工程里锁版本，比如在 Dockerfile 里固定镜像 tag，部署记录里写清固件版本号。这样 root cause 会少很多。
4.5 内存分配不对：推理时间莫名抖动
现象是推理耗时忽高忽低，跑一段时间后性能明显退化，内存持续增长。原因是输入输出 buffer 用了普通 DDR 内存，未满足 NPU 的对齐和连续要求，驱动只能额外做内存搬运，每次推理又反复 malloc 和 free。
解决方法是按文档库 Runtime 章节的推荐方式申请 buffer，进程启动时一次性预分配，推理过程复用。另一个细节是输入数据的通道排布 HWC/NCHW 要和编译时一致，否则数据重排又会引入额外耗时。这类问题在文档里的描述往往不太起眼，但影响比想象中大，属于遇到一次就长记性的类型。
5. 把 Pulsar2 文档库用成调试手册：三个进阶习惯
5.1 把算子支持清单当成边界地图
我每次拿到新网络，第一件事不是跑代码，而是打开算子支持清单，把网络里涉及的算子逐个过一遍。算子支持文档会标注版本和限制条件，比如某类 reshape 模式在某个版本后才支持。提前排查等于先做了一次可行性论证，省下的时间远比读文档多。
5.2 用 profile 信息判断瓶颈在哪
帧率不达标时，很多人会怀疑工具链没有榨干 NPU。其实编译工具通常会把性能报告一起给出来，里面能看到算力利用率和带宽占用。如果 ALU 利用率已经接近上限，应该考虑精简网络结构；如果利用率不高但耗时高，大概率卡在 DDR 带宽或预处理链路上。先看报告再决定优化方向，比反复改编译参数更靠谱。
5.3 建立环境基线，把版本记进部署记录
吃过几次版本不匹配的亏后，我开始在每次部署时固定记录三行：工具链版本、固件版本、模型 SHA 值。文档库更新后，先对照 release notes 确认影响面，再决定要不要升级。这样遇到“昨天还能跑，今天挂了”的问题，三分钟就能定位是版本变化还是模型变化。
工具链的“第二个”意味着上一代的经验只能信一半，遇到问题先查文档库对应版本，而不是套老方案。希望这篇笔记能帮你少走一些弯路，落地顺利。
本文还有配套的精品资源，点击获取
