企业官网建设流程全解析

1. 为什么要在Android上折腾QNN SDK

第一次把训练好的ONNX模型往Android手机上塞的时候，我天真地以为跟PC端一样，装个推理框架跑起来就完事了。结果实测下来，CPU推理一张图动辄三四百毫秒，稍微复杂点的检测模型直接飙到一秒以上，手机背面烫得能煎鸡蛋。后来才意识到，高通平台上的Hexagon NPU才是真正该用的算力单元，而QNN SDK就是打开这扇门的钥匙。

QNN全称Qualcomm Neural Network，是高通给自家骁龙平台提供的神经网络推理SDK。它跟通用的NNAPI不一样，NNAPI是个抽象层，底层具体走CPU、GPU还是NPU由厂商驱动决定，你控制不了；而QNN SDK是直接面向Hexagon DSP和HTP（Hexagon Tensor Processor）的，能拿到更细粒度的控制权，也能榨出更极致的性能。代价就是工具链更复杂，模型转换、量化、图切分这些环节都得自己盯着。

这篇内容适合两类人：一类是已经在Android端跑通了ONNX Runtime或者TFLite，但发现性能瓶颈卡在CPU上，想往NPU迁移的开发者；另一类是手里有训练好的ONNX模型，准备在骁龙设备上做端侧部署，但对QNN这套工具链完全没概念的人。我会把从ONNX模型转换、量化校准、图编译到精度调优的完整链路拆开讲，重点放在那些官方文档一笔带过、但实际踩坑率极高的环节上。

需要提前说明的是，QNN SDK的版本迭代比较快，不同版本之间API和工具行为有差异。我下面讲的内容基于QNN 2.x系列的常见实践，具体到你的环境时，建议先确认SDK版本和对应的文档。另外，整个流程涉及的工具比较多，我会在每个环节说明为什么这么选、有没有替代方案。

2. 环境搭建：别急着装SDK，先把版本对齐这件事做对

2.1 QNN SDK版本与骁龙平台的对应关系

很多人拿到SDK压缩包就开始解压配置，结果编译出来的模型在设备上加载失败，报一堆看不懂的HTP错误。十有八九是SDK版本和目标设备的Hexagon架构版本没对上。

QNN SDK的发布是跟骁龙芯片代际绑定的。比如骁龙888对应Hexagon 780，骁龙8 Gen 1对应Hexagon 790，8 Gen 2是Hexagon 800。每个Hexagon版本支持的HTP算子集和量化策略都有差异。SDK里通常会有多个DSP架构的库文件，你需要根据目标设备选择正确的那个。

我的建议是：先确定你的目标机型，查清楚它的Hexagon版本，然后去下对应版本的SDK。不要盲目用最新版，最新版可能对老设备支持反而变差。另外，SDK里的libQnnHtp.so和libQnnHtpV68Stub.so这类库文件，名字里的V68、V69就是Hexagon架构代号，选错了直接加载失败。

2.2 主机端工具链的依赖坑

QNN SDK的主机端工具主要在Linux上跑，官方推荐Ubuntu 20.04或22.04。Windows下虽然也有部分工具，但模型转换和量化校准这块，Linux环境稳定得多。

装之前先确认几个依赖：Python版本建议3.8到3.10之间，太高了有些工具脚本会报语法错误；protobuf版本要跟SDK里的要求一致，这个特别容易出问题，因为系统里可能已经装了别的版本；还有numpy、onnx这些包，版本也要对齐。

我踩过最坑的一次是protobuf版本冲突。系统里装的是3.20，SDK要求3.19，结果模型转换工具跑一半直接段错误，没有任何有用报错。后来用virtualenv建了个干净环境，按SDK文档里的requirements.txt严格装，才解决。

提示：强烈建议用Python虚拟环境隔离QNN SDK的依赖，不要跟系统Python混用。SDK目录下一般有requirements.txt，直接pip install -r装。

环境变量这块，需要把SDK的bin目录加到PATH，把lib目录加到LD_LIBRARY_PATH。具体路径根据你的解压位置调整。配完之后跑一下qnn-onnx-converter --help，能正常输出帮助信息就说明基本环境OK了。

2.3 Android端运行时的集成方式

设备端集成有两种路子：一种是用QNN SDK提供的预编译库，直接放到你的Android工程里通过JNI调用；另一种是用QNN的Android AAR包（如果SDK版本提供的话）。

第一种方式更灵活，但需要自己写JNI桥接代码。核心是加载libQnnHtp.so、libQnnSystem.so这些库，然后通过QNN的C API创建context、加载模型、执行推理。第二种方式省事，但封装的粒度比较粗，有些底层配置改不了。

我一般选第一种，因为精度调优阶段经常需要改HTP的配置参数，AAR包不一定暴露这些接口。JNI这块的代码量不算大，主要就是几个函数：初始化backend、创建device、加载模型binary、准备输入输出tensor、执行推理。网上有QNN的sample code可以参考，但要注意sample的SDK版本跟你的是否一致。

3. ONNX模型转换：从通用格式到QNN专属格式的关键一跃

3.1 转换前的模型体检

拿到一个ONNX模型，别急着往qnn-onnx-converter里扔。先做几项体检，能省掉后面大量调试时间。

第一项，用Netron打开模型，看看输入输出的shape和dtype。QNN对动态shape的支持有限，如果你的模型输入是[batch, 3, -1, -1]这种动态维度，转换时大概率会报错。需要先把shape固定下来，比如改成[1, 3, 224, 224]。

第二项，检查算子集。QNN HTP支持的算子列表是有限的，有些ONNX算子它不认，比如某些自定义算子或者比较新的算子。用onnxruntime跑一遍模型，确认能正常推理，然后再看QNN转换工具报不报不支持的算子。

第三项，看模型大小和参数量。HTP的片上内存有限，模型太大可能需要做图切分，把一部分放到CPU上跑。这个后面会细说。

我一般会写个小脚本，用onnx的Python API遍历一遍节点，把算子类型统计出来，跟QNN文档里的支持列表对一遍。不支持的算子要么找替代实现，要么改模型结构。

3.2 qnn-onnx-converter的参数怎么配

qnn-onnx-converter是核心转换工具，它的参数直接决定生成的模型能不能在HTP上跑、跑得好不好。

最基本的用法是：

qnn-onnx-converter \ --input_network model.onnx \ --output_path model.cpp \ --input_dim "input" 1,3,224,224 \ --out_node "output" \ --float_bias_bits 16

这里几个关键参数解释一下。--input_dim指定输入名字和维度，多个输入就写多行。--out_node指定输出节点名字，不指定的话工具会自己推断，但有时候推断出来的输出不是你想要的。--float_bias_bits控制bias的位宽，16位是常用值，设太高会增加模型体积，设太低影响精度。

还有一个重要参数是--quantization_overrides，用来指定哪些层做量化、用什么校准参数。这个在精度调优阶段会反复用到。

转换完成后会生成一个.cpp文件和一个.bin文件。.cpp里是模型结构的C++描述，.bin是权重数据。设备端加载的是这两个文件编译后的产物。

注意：转换工具对ONNX的opset版本有要求，太新的opset可能不支持。如果报opset相关错误，用onnx.version_converter把模型降到支持的版本。

3.3 算子不支持时的图切分策略

QNN HTP不是万能的，有些算子它就是不支持。这时候有两个选择：一是改模型，用支持的算子替换；二是做图切分，把不支持的层放到CPU上跑。

改模型是首选，因为图切分会导致数据在NPU和CPU之间来回拷贝，性能损失很大。比如有些模型用了NonMaxSuppression，QNN HTP不支持，但你可以把它挪到后处理里用CPU做，模型本身只输出原始检测框。

如果实在改不了，就得切分。QNN SDK提供了图切分的工具和API，可以在转换阶段指定切分点。切分的原则是尽量让计算量大的层留在NPU上，把零碎的不支持层扔给CPU。切分点选得好不好，直接决定最终性能。

我做过一个检测模型，骨干网络在NPU上跑，后处理里的NMS在CPU上跑，整体延迟比全CPU快了将近四倍。但如果切分点选得不好，比如在卷积中间切一刀，数据来回拷贝的开销能把NPU的加速全吃掉。

4. 量化：INT8精度调优的核心战场

4.1 为什么必须做量化

HTP对INT8量化的支持是最好的，FP16也能跑但性能差一截，FP32基本就别想了。量化不只是为了省内存，更重要的是HTP的INT8计算单元吞吐量远高于FP16。

但量化必然带来精度损失。关键在于怎么把损失控制在可接受范围内。QNN的量化流程分两步：先用校准数据集统计各层的激活值分布，确定量化参数（scale和zero point）；然后把FP32权重和激活值映射到INT8。

校准数据集的选择很讲究。它应该能代表实际推理时遇到的数据分布。如果你用随机噪声做校准，量化参数会偏得离谱，精度崩掉。一般从训练集或验证集里抽几百张图就够了，但一定要覆盖各种场景。

4.2 校准数据的准备与预处理

校准数据的预处理必须跟模型训练时的预处理完全一致。归一化参数、通道顺序、resize方式，任何一项对不上，校准出来的量化参数都会有偏差。

我一般会把校准数据整理成一个文件夹，图片按模型输入的要求预处理好后存成npy或者raw格式。QNN的校准工具支持多种输入格式，用npy比较方便，因为可以直接控制dtype和shape。

校准数据量方面，官方建议100到500张。我实测下来，200张左右是个比较平衡的点。太少统计不充分，太多收益递减还费时间。如果模型有多个输入分支，每个分支都要准备对应的校准数据。

还有一个细节：校准数据的batch size。QNN校准工具一般一次处理一个batch，batch size设成1就行，设大了反而可能因为内存问题跑不动。

4.3 逐层量化配置与混合精度

QNN默认会对所有能量化的层做INT8量化。但有些层对精度特别敏感，比如第一层卷积、最后的分类层、或者某些attention结构。这些层如果强行INT8，精度可能掉好几个点。

这时候就需要混合精度：敏感层保持FP16，其他层INT8。QNN支持通过--quantization_overrides参数指定每层的量化策略。你可以传一个JSON文件，里面列出哪些层用FP16、哪些用INT8。

怎么判断哪些层敏感？我的做法是：先全INT8跑一遍，看精度掉多少；然后逐层把可疑层改成FP16，看精度恢复情况。这个过程比较耗时，但能精确定位问题层。另一个偷懒的办法是参考类似模型的量化经验，一般第一层和最后一层保持FP16是稳妥的选择。

4.4 量化精度评估的完整链路

量化完不能只看模型文件大小，必须跑精度评估。评估链路要跟实际部署一致：用同样的预处理、同样的后处理、同样的评估指标。

我一般会在PC端先用QNN的模拟器跑一遍量化后的模型，跟FP32的ONNX模型对比输出差异。QNN SDK提供了qnn-net-run工具，可以在x86上模拟HTP的行为。虽然模拟器不能完全代表设备端表现，但能快速发现大的精度问题。

设备端评估就更直接了，把量化模型推到手机上跑，用真实数据测精度。这一步不能省，因为模拟器和真实HTP之间可能有差异，尤其是涉及一些硬件特有的近似计算时。

评估指标方面，分类模型看top-1/top-5准确率，检测模型看mAP，分割模型看mIoU。跟FP32基线对比，一般要求掉点不超过1%到2%，具体看业务容忍度。

5. 精度掉点排查：从现象到根因的完整链路

5.1 先确认掉点发生在哪个环节

精度掉点可能发生在多个环节：ONNX转QNN时、量化校准时、图切分时、设备端执行时。排查的第一步是定位环节。

我的做法是分段验证。先把FP32的ONNX模型转成QNN格式但不量化，在设备上跑，看精度跟ONNX Runtime比有没有差异。如果没有差异，说明转换环节没问题，问题出在量化。如果有差异，那就是转换环节的算子映射或者图优化出了问题。

量化环节再细分：用模拟器跑量化模型，跟FP32 QNN模型对比。如果模拟器上精度就掉了，那是量化参数的问题；如果模拟器上没问题但设备上掉了，那可能是HTP的硬件近似计算导致的。

这个分段排查的思路能快速缩小范围，避免盲目调参。

5.2 校准数据分布不匹配的典型表现

校准数据分布不匹配是精度掉点最常见的原因。典型表现是：模型在某些类别的样本上精度正常，但在另一些类别上崩得厉害。

比如我做过一个车牌识别模型，校准数据用的是白天场景，结果夜间场景的识别率直接腰斩。因为夜间图像的亮度分布跟白天差异很大，校准出来的量化参数对夜间数据不适用。

解决办法是让校准数据覆盖所有目标场景。如果某些场景数据少，可以做过采样。另外，校准数据的预处理一定要跟推理时一致，我见过有人校准用RGB、推理用BGR，精度不掉才怪。

5.3 敏感层定位的二分法

如果怀疑是某些层量化敏感，可以用二分法快速定位。把模型从中间切成两半，前半部分保持FP16，后半部分INT8，看精度。如果精度恢复明显，说明敏感层在前半部分；反之在后半部分。然后继续二分，直到定位到具体层。

这个方法比逐层试快得多，尤其适合层数多的模型。定位到敏感层后，把它改成FP16，再整体评估精度。通常只需要把少数几层改成FP16，就能把精度拉回可接受范围，而对性能的影响很小。

5.4 图切分引入的精度问题

图切分本身不会改变计算结果，但切分点两侧的数据类型转换可能引入误差。比如NPU侧输出INT8，CPU侧期望FP32，中间有个反量化过程，如果scale选得不好，会有精度损失。

另外，切分后有些融合算子可能被拆开，比如Conv+BN+ReLU原本是一个融合算子，切分后BN被分到CPU侧，融合优化就失效了，精度和性能都可能受影响。

排查这类问题，可以对比切分前后的模型输出。如果切分前精度正常、切分后掉了，那就是切分点的问题。调整切分点，尽量让融合算子保持完整。

6. 性能调优：让NPU真正跑满

6.1 HTP配置参数的调优空间

QNN HTP有一组配置参数可以调，影响性能和精度。比如htp_performance_mode可以设成burst、balanced、power_saver等，burst模式性能最高但功耗也最高。htp_graph_finalization控制图编译的优化级别，级别越高编译越慢但运行时越快。

这些参数通过QNN的API在创建context时传入。我一般会在开发阶段用burst模式加最高优化级别，把性能上限摸清楚，然后再根据实际功耗要求往回调。

还有一个重要参数是vtcm_size，控制HTP的片上内存分配。VTCM是HTP的紧耦合内存，访问速度远快于DDR。如果模型能全部塞进VTCM，性能会有质的提升。但VTCM容量有限，一般几MB，大模型塞不下，需要权衡。

6.2 模型结构层面的优化

除了SDK参数，模型结构本身也有很多优化空间。HTP对某些算子有硬件加速，比如3x3卷积、depthwise卷积，这些算子用好了性能很好。相反，一些不规则的算子比如大kernel卷积、空洞卷积，HTP支持得不好，能换就换。

另一个优化点是减少内存搬运。HTP的计算单元和内存之间的带宽是瓶颈，如果模型中间特征图太大，频繁读写DDR，性能就上不去。可以通过减少通道数、降低特征图分辨率来缓解。

还有算子融合。QNN在编译阶段会自动做算子融合，但有些融合需要模型结构配合。比如Conv+BN+ReLU这种经典组合，如果BN的参数能折叠进Conv，就能省一次内存读写。训练时用BN，推理前把BN折叠掉，是个常规操作。

6.3 多线程与异步推理

QNN支持异步推理，可以在一个模型执行的同时准备下一个输入。对于视频流这种连续推理场景，异步能显著提高吞吐量。

实现上，QNN的QnnContext和QnnGraph支持多线程访问，但要注意线程安全。一般是一个线程负责准备输入数据，另一个线程负责执行推理，通过信号量同步。

不过异步推理会增加代码复杂度，如果单帧延迟已经满足要求，没必要上异步。我一般是在吞吐量不够时才考虑这个优化。

7. 设备端部署的实战细节

7.1 JNI接口的设计与内存管理

Android端通过JNI调用QNN的C API，接口设计要尽量简洁，避免频繁的JNI调用开销。我一般会把整个推理流程封装成一个native函数，输入是预处理好的数据，输出是推理结果，中间的所有QNN调用都在native层完成。

内存管理是个容易出问题的地方。QNN的tensor内存需要手动分配和释放，如果忘记释放会内存泄漏，如果提前释放会导致野指针。我一般用RAII的方式封装QNN的资源，确保异常情况下也能正确释放。

输入数据的拷贝也要注意。如果输入数据在Java层，需要通过JNI传到native层，这个拷贝开销不小。优化方法是直接在native层分配输入buffer，Java层往里面写数据，避免二次拷贝。

7.2 模型加载速度的优化

QNN模型加载包括两个阶段：一是从文件读取模型binary，二是HTP编译图。编译阶段比较耗时，大模型可能要几秒。如果每次启动都重新编译，用户体验很差。

优化方法是把编译结果缓存起来。QNN支持把编译后的图序列化到文件，下次加载时直接反序列化，省去编译时间。这个缓存的key要跟模型版本、SDK版本、HTP配置绑定，任何一项变了都要重新编译。

我实测过一个中等规模的检测模型，首次编译要3秒多，缓存后加载只要200毫秒左右，提升很明显。

7.3 不同骁龙机型的兼容性处理

同一份QNN模型binary在不同骁龙机型上的表现可能不一样。新机型的HTP可能支持更多算子、有更大的VTCM，老机型则相反。如果模型用到了新机型特有的特性，在老机型上可能加载失败。

兼容性处理有两种思路：一是针对不同机型编译不同的模型binary，运行时根据设备型号加载对应的版本；二是用一个兼容性最好的配置编译一份binary，牺牲一点性能换通用性。

我一般选第二种，因为维护多份binary的成本太高。但如果性能要求极致，第一种也是值得的。关键是做好设备型号到模型版本的映射，别加载错了。

8. 我踩过的几个印象深刻的坑

第一个坑是量化校准数据的预处理。当时模型训练用的是ImageNet的均值和方差做归一化，我校准的时候忘了这一步，直接拿原始像素值去校准。结果量化参数完全不对，精度掉了十几个点。排查了大半天才想起来是预处理的问题。这个教训是：校准数据的预处理必须跟训练和推理完全一致，一个参数都不能差。

第二个坑是HTP的VTCM配置。有个模型在模拟器上跑得好好的，到设备上就报内存不足。后来发现是VTCM设得太小，模型中间特征图放不下。把VTCM调大后解决。但VTCM不是越大越好，设太大可能影响其他模块使用。需要根据模型实际需求调。

第三个坑是图切分点的选择。有个模型我切在了两个卷积之间，结果性能比全CPU还差。原因是切分点两侧的数据类型不匹配，NPU输出INT8，CPU输入FP32，中间加了个反量化层，数据来回拷贝的开销把NPU的加速全抵消了。后来把切分点挪到模型末尾，只把后处理切给CPU，性能才正常。

第四个坑是SDK版本升级。有次手贱把SDK从2.14升到2.16，结果原来跑得好好的模型加载失败。查了半天发现是新版本对某个算子的量化策略改了，需要重新校准。所以升级SDK前一定要做好回归测试，别盲目追新。

9. 一些实用的调试技巧

QNN SDK提供了几个很有用的调试工具。qnn-profile-viewer可以看模型各层的执行时间和内存占用，定位性能瓶颈很直观。qnn-net-run可以在PC上模拟HTP执行，快速验证模型正确性。还有qnn-op-package-generator可以查看当前SDK支持的算子列表。

日志方面，QNN的日志级别可以调。开发阶段把日志开到verbose，能看到很多底层信息，比如图优化做了哪些变换、量化参数是多少。但verbose日志量很大，生产环境要关掉。

还有一个技巧是用QNN的--dump_profile参数把profiling数据导出来，用Chrome的tracing工具打开，能看到时间线上的详细执行情况。这个对分析流水线并行、内存拷贝开销特别有用。

最后，建议在PC端把整个流程跑通再往设备上迁。PC端的调试工具更丰富，出了问题也更容易定位。设备端只做最终验证，这样效率最高。