把 ONNX 模型迁到骁龙平台第一直觉往往是“转个格式不就完事了”。我最早在 Android 端用 QNN SDK 做部署时也是这么想的结果光环境就折腾了两天真正上手才发现模型转换、DLC 生成、HTP 加载、int8 量化精度调优每一个环节都有隐藏的雷。这篇就把我在 Android 端实战 QNN SDK 的完整流程、避坑经验和排查思路整理出来给准备在骁龙平台部署模型的同行一个可以少走弯路的参考。内容覆盖 ONNX 模型清洗、qnn-onnx-converter 转换、Android 工程集成、量化校准与精度定位适合模型部署工程师、算法工程师以及自己调模型想在真机上跑通的应用开发者。1. 环境准备工具链版本对不上后面全是白干1.1 版本选型思路先看 SDK 再看 Python 和 NDKQNN SDK 的发布节奏不算慢不同大版本之间工具链差异很大尤其体现在转换器的参数名、量化配置格式、以及背后依赖的 ONNX 解析能力上。我建议直接去高通官网下载最新的 release不要用两三个版本之前的旧包除非你的模型是在旧版本上验证过、并且针动的话成本很高。下载之后先看目录结构QNN SDK 解压出来通常包含 bin、lib、python、include 等目录。bin 下面有按宿主机平台区分的可执行文件比如 x86_64-linux-clanglib 下面也按平台分了目录 include 里是 QNN 的 C API 头文件。搞清楚这些目录位置后面配置环境变量才不容易懵。宿主机的 Python 环境建议用独立的虚拟环境管理推荐 Python 3.8 到 3.10 区间太老或者太新的版本都可能在安装 onnx、numpy、pyyaml 这些依赖时出问题。如果你机器上同时有多个 AI 相关的 SDK强烈建议用 conda 或者 venv 隔离避免某个包版本被全局环境里的旧版本干扰。NDK 方面QNN 的 C API 是纯 C 接口对 NDK 版本要求不算苛刻但实测 r23 及以上配合 Android Studio 自带的 AGP 比较稳太老的 NDK 在链接时容易报一些奇怪的符号错误。还有一个容易被忽略的点宿主机建议直接用 Linux。QNN 的量化工具、context binary 生成工具、以及各种调试工具对 Linux 的支持是最完整的。Windows 上虽然也能用但经常要额外装 WSL 或者折腾动态库路径没必要一开始就给自己上难度。1.2 环境变量配置与验证别等报错了才回来查路径配置环境变量是第一个能卡住人的地方。QNN 的工具链依赖 bin 和 lib 都能被正确找到所以 PATH、LD_LIBRARY_PATH 和 PYTHONPATH 三者都要配。我自己习惯把配置写成一个 qnn_env.sh 脚本每次开终端直接 source避免反复手敲。export QNN_SDK_ROOT/opt/qcom/aistack/qnn/2.30.0.250109 export PATH$QNN_SDK_ROOT/bin/x86_64-linux-clang:$PATH export LD_LIBRARY_PATH$QNN_SDK_ROOT/lib/x86_64-linux-clang:$LD_LIBRARY_PATH export PYTHONPATH$QNN_SDK_ROOT/python:$PYTHONPATH注意上面路径里的版本号要替换成你实际解压出来的目录。配置完成后先别急着转模型验证一下环境通不通。运行qnn-onnx-converter -h能看到帮助信息基本说明可执行文件路径没问题再运行一下 SDK 自带的 sample 转换脚本确认依赖库也正常加载。这一步多花五分钟能帮你排除掉后面一大半的“Command not found”和“libQnnModelTools.so not found”之类的莫名问题。另外提醒一句PATH 里不要出现多个 QNN 相关路径尤其当电脑上装过旧版 SDK 或者其它厂商的 AI 工具链时版本冲突很难排查。用which qnn-onnx-converter看一眼实际指向确保是你要用的那个版本。1.3 先跑通官方 Sample再碰自己的模型环境就绪后我强烈建议先跑一遍 QNN SDK 自带的 QnnSampleApp不要在环境没验证的情况下直接拿自己的模型上。Sample 程序的构建流程和使用方式本身就是最好的学习材料你可以在里面看到 QNN Backend 初始化、Context 创建、Graph 执行、Tensor 读写这几个核心步骤是怎么串起来的后面集成进 Android 工程时要做的也是同样的事。跑 Sample 的时候注意观察日志输出里面会打印 SDK 版本、后端名称、图结构信息这些信息后面排查问题都会用到。Sample 跑通了说明环境、工具链、底层库链路都是好的这时再拿自己的 ONNX 模型做转换如果报错就能大概率确定问题出在模型本身而不是环境。2. ONNX 模型转换模型清洗比敲命令更花时间2.1 模型清洗固定动态维度简化算子很多人在转换前忽略了一个关键点QNN 生成的是 DLC 静态图对动态 shape 的支持非常有限。如果你的 ONNX 模型输入是动态 batch、动态分辨率或者中间层有动态维度转换时大概率会直接报错甚至转换成功后在手机上加载也会异常。所以第一步先固定模型的输入 shape。用 onnx-simplifier 可以顺便做算子简化和输入 shape 固定python -m onnxsim input.onnx output_sim.onnx --overwrite-input-shape input:1,3,224,224这里假设输入名是 input想固定成 batch1、通道 3、分辨率 224x224。如果你的模型输入名不同先用下面这个 Python 脚本查一下模型结构import onnx m onnx.load(model.onnx) print(inputs:, [(i.name, [d.dim_value for d in i.type.tensor_type.shape.dim]) for i in m.graph.input]) print(outputs:, [(o.name, [d.dim_value for d in o.type.tensor_type.shape.dim]) for o in m.graph.output]) for node in m.graph.node: print(node.op_type, node.name, list(node.input), list(node.output))打印出来的算子列表非常有用你可以提前知道模型里有没有 QNN 支持不好的算子。常见的问题算子包括一些过新的 op比如 opset 17 之后新增的某些写法、动态 Shape 相关的算子、以及个别奇奇怪怪的组合。通用做法是导 ONNX 时把 opset 设置在 13 左右太低的话一些算子表达不了太高的话转换器不一定认识。2.2 qnn-onnx-converter 转换从 ONNX 到 DLC 的实质ONNX 模型清洗完成后就到了核心转换这一步。转换工具 qnn-onnx-converter 做的事情本质上是把 ONNX 计算图解析成 QNN 的中间表示再封装成 DLCDeep Learning Container文件。转换成功后模型结构、权重、量化信息都会打包进 DLC。最简单的转换命令qnn-onnx-converter -i output_sim.onnx -o model.dlc如果你的模型有多个输入或者转换时需要指定输入名和维度可以查看qnn-onnx-converter -h用对应的参数传入 input 信息。不同 SDK 版本在输入指定方式上略有差异但基本都支持通过一个 input_list 文件来声明每个输入的名字和维度文件内容大概是input1,1,3,224,224这样的写法具体格式以你所用版本的帮助文档为准。转换结束后先检查生成日志重点关注有没有 Warning比如某个算子被分解成了多个子算子、或者某个算子的参数被强制转换这些 Warning 往往预示着后续精度或者性能的坑。另外转换成功后可以先在 PC 上用 SDK 自带工具或者 SampleApp 简单跑一下 DLC确认输出数值正常再进下一步。这一步相当于把转换链路的错误隔离在 PC 端不至于等到手机上才发现问题。2.3 转换报错定位从报错信息反推模型问题转换报错是常态关键是怎么快速定位。我整理了下面这张自查表基本覆盖了 90% 的转换问题报错特征可能原因常用解法Unsupported Op / Validation failed算子不在 QNN 支持列表内用 onnxsim 简化或重写模型中对应层Dynamic dimension 相关报错输入或中间层存在动态维度固定输入 shape删除动态 opFailed to load ONNX modelonnx Python 包版本不匹配在虚拟环境装匹配的 onnx 版本shape 不匹配报错模型内部有 concat 或 broadcast 问题先用 onnxruntime 导出并检查各层输出 shape转换过程中内存爆炸大模型或超大中间特征换更大内存机器或分批处理/简化模型最有效的排查方式是先用 onnxruntime 把 ONNX 模型在 PC 上完整跑一遍确认原始模型本身是通的。很多时候你以为报错是 QNN 转换器的问题实际是模型本身就存在动态维度、非法 shape 或者某些算子在 onnxruntime 里都跑不通。先证明 ONNX 源头是好的再谈转换排查范围一下就缩小了。3. Android 端集成让 DLC 在真机上跑起来3.1 工程文件清单so 库和模型资源怎么放DLC 转换完成后进入 Android 工程集成。首先需要明确包里要放哪些东西。模型文件建议放在 assets 目录运行时拷贝到应用私有目录或者直接读取。QNN 原生接口需要一个文件路径稳妥起见先拷贝到getApplicationContext().getFilesDir()下再加载避免 assets 路径解析问题。so 库放在app/src/main/jniLibs/arm64-v8a/下常见的包括libQnnSystem.so、libQnnHtp.so、对应不同代际芯片的 HTP stub 和 skel比如 libQnnHtpV73Stub.so、libQnnHtpV75Stub.so、libQnnHtpV79Stub.so 这类、以及可选的 CPU fallback 库 libQnnCpu.so。不同 SDK 版本的名字可能略有差异但大体思路一致就是“主入口库 后端库 后端对应平台的支撑库”。你可以直接从 QNN SDK 包的 lib/arm64-v8a 目录里把你需要的 so 全部拷进来省得漏。如果你希望 GPU 也参与计算还可以加 libQnnGpu.so。不过 HTP 才是 QNN 的主场GPU 一般作为备选方案日常跑模型先不要混用后端避免引入不必要的变量。3.2 JNI 封装与推理流程骨架照着 QnnSampleApp 改就行Android 端和 QNN 交互的实际路径绝大多数是通过 JNI 调 C/C 接口。虽然 QNN 也提供了 Java 层的封装某些版本里有但工程实践中我见到的还是 JNI 为主原因是 C API 最完整、性能开销最小、也最好对照官方 SampleApp 抄。整个推理流程的核心步骤可以简化成下面的伪代码骨架// 1. 加载 QNN HTP 后端 void* handle dlopen(libQnnHtp.so, RTLD_NOW); QnnInterface_getProviders(provider, num_providers); const QnnInterface* iface provider[0]-getInterface(); // 获取当前版本接口表 // 2. 初始化后端与创建上下文 iface-backendInit(backend_handle); iface-contextCreate(context_handle, backend_handle, nullptr); // 3. 从 DLC 加载图并 finalize iface-graphRetrieve(context_handle, model_name, graph_handle); iface-graphFinalize(graph_handle, nullptr, nullptr); // 4. 准备输入输出 tensor // 设置 tensor 名称、shape、数据类型、内存 // 输入数据 memcpy 进输入缓冲 // 5. 执行推理 iface-graphExecute(graph_handle, input_tensors, output_tensors, nullptr); // 6. 读取输出缓冲反量化后返回给 Java 层这里不逐字列出所有 API 名称因为 QNN SDK 不同版本在接口表结构上有差异。实际编码时直接把 QnnSampleApp 里对应的初始化、加载、执行代码拿过来改比自己从零写要快得多也准确得多。3.3 输入预处理与输出解读最容易糊弄、也最容易翻车Android 端跑模型预处理往往比模型本身更容易出问题。QNN 接收的输入数据是连续内存块通常 ONNX 模型期望的是 NCHW 布局的 float 数据。你在 Android 端从 Bitmap 拿到的数据是 HWC 的 RGBA 或者 RGB要先转成 CHW 排列再做归一化。转换的时候要注意三点一是色彩通道顺序模型训练时如果用的是 RGB你就别传 BGR 进去二是归一化参数训练时的 mean/std 是谁就是谁别自己改三是输入数据类型模型期望 float32 就转成 float32期望 uint8 就直接给 uint8。把这些参数整理成一个 Java 层的配置类别散落在代码各个地方后期调精度时你会感谢自己的。输出解读同样不能想当然。量化模型int8的输出默认是 uint8/int8 的 raw 值不是真正意义上的“预测值”。需要按每一路输出的 scale 和 zeroPoint 反量化公式是float_value (raw_value - zeroPoint) * scale。很多第一次接触 QNN 的人拿到全 0 的输出以为模型坏了其实只是没做反量化。3.4 用 context binary 优化加载提前编译图形结构DLC 文件虽然好用但在手机上每次启动都要重新解析图结构、分配工作空间大模型甚至要几秒钟才能完成 first inference。QNN 提供了 context binary 机制可以在开发机上提前把图和后端相关的信息编译成一个二进制文件运行时直接加载速度提升非常明显体验接近于“加载一个已经编译好的计算包”。生成 context binary 的大致命令思路如下qnn-context-binary-generator --model model.dlc --backend libQnnHtp.so --output_dir ./context生成的 context binary 文件放到 assets 里运行时通过 QNN 的 context 缓存加载接口读取。注意 context binary 跟后端版本、芯片平台强相关建议在目标机型对应的 SDK 版本下生成跨机型使用时要在真机上做好验证。第一次加载变快的同时文件体积可能比 DLC 大一些取舍看你的场景。4. 精度调优int8 量化不是赌运气4.1 先跑 FP32 基线确认转换链路是干净的精度调优的第一件事不是上来就调量化而是先建立一个可靠的 FP32 基线。具体做法是先用 qnn-onnx-converter 转换一份全 float32 的 DLC在 Android 端也可以在 PC 端跑一批固定输入数据记录输出再用 onnxruntime 在 CPU 上跑同一份输入记录输出两者对比用余弦相似度或者最大绝对误差来衡量一致性。这一步的目的是确认“ONNX → DLC → HTP 推理”这条链路的数值一致性是好的。如果 FP32 阶段就有明显差异说明问题出在转换或者后端支持层面这时候去做量化调优是浪费时间的。实际经验中如果 FP32 输出余弦相似度能到 0.999 以上这个模型之后量化掉点的“锅”就可以基本甩给量化本身了。对比脚本可以自己写固定输入几组数据就行不用搞很复杂。关键是“固定输入、固定随机种子”保证同一份输入在两条链路上跑对比才有意义。4.2 校准数据是量化的灵魂两百张高质量样本胜过两千张垃圾样本QNN 的 int8 量化属于后训练量化PTQ需要一组校准数据来统计每一层激活值的分布从而确定 scale 和 zeroPoint。校准数据选得不好后面再怎么调都是治标不治本。数量上常见场景 200~500 张就能产生一个比较稳定的统计结果。重点是质量校准数据必须贴近真实业务场景并且类别分布均衡。比如你做车牌识别校准集里 90% 是蓝牌、没有绿牌和黄牌那模型量化后对绿牌的精度大概率会崩。校准数据的预处理必须和线上完全一致。这里是最容易埋雷的地方训练时 resize 用的是双线性校准数据也必须是双线性训练时归一化是 mean/std校准数据也必须一样。我见过不少项目模型在训练集上精度很高上线量化后全乱了最后发现只是校准数据生成脚本里 resize 方法和线上不一致。校准数据准备好后把它按模型输入顺序保存成 float32 的裸数据文件.raw可以用 numpy 的 tofile 生成import numpy as np # img 是预处理后的 [1,3,224,224] float32 img.astype(np.float32).tofile(calib_0001.raw)然后写一个 input_list.txt把校准数据文件路径按行列出来。量化时在转换器里通过量化配置引用这个列表。具体的量化参数在不同 SDK 版本里有差异核心思想是告诉量化工具使用哪种激活统计策略、权重用多少 bit、激活用多少 bit。4.3 量化掉点怎么定位逐层对比是最笨也最有效的方式如果 int8 量化后精度明显下滑先不要慌着到处改参用逐层对比的方式定位“敏感层”。具体做法是先把量化 DLC 和 FP32 DLC 在相同输入下分别 dump 出每一层的中间激活值然后计算每一层的绝对误差和相对误差找出误差最大的前几个层。实际操作中敏感层往往有这些特点层输出范围很大且有长尾分布、层后面接的是敏感算子比如 softmax 前的 logits、层本身是反卷积或者多分支相加。定位到敏感层后常见的解法有下面几种策略适用场景说明用 percentile 替代 min_max激活值存在明显离群点时避免个别异常样本拉宽量化范围per-channel 量化卷积权重分布不均衡时每通道独立 scale精度改善明显对敏感层做混合精度整网 int8 掉点集中在少数层时让极少数层保持 FP16其余仍走 int8校准数据去异常样本校准集里混入了真实场景不会出现的极端样本防止激活范围被异常值污染我在实际项目里最常用的一招是先看模型输出里“什么类出了问题”。如果只是某一类精度崩很大概率是校准数据里这类样本太少如果整体全崩优先怀疑预处理或校准数据流程如果是单层误差离谱才考虑混合精度。调优的顺序很重要不要一开始就上混合精度那是成本比较高的方案能通过校准数据解决的就不要动模型结构。4.4 混合精度与工具链QNN 之外还有一个高阶选项QNN 原生转换器提供了基本的量化配置能力但一些比较复杂的精度问题原生工具不一定能快速解决。高通还有一个 AI 模型效率工具包 AIMET新版本叫 AI Model Efficiency Toolkit简称 AIT支持更精细的 PTQ 和混合精度量化搜索甚至可以自动找出哪些层适合低比特、哪些层需要保持高精度再导出给 QNN 使用。如果你的项目对精度要求很高、且模型结构复杂建议了解一下 AIT。它的学习曲线比直接调 qnn-onnx-converter 要陡一些但面对“怎么优化都掉点”的模型往往能给出更靠谱的答案。不过大部分实际场景先做好校准数据、先尝试 percentile 和 per-channel已经能解决掉九成问题不要一上来就上重武器。5. 常见问题与排查技巧实录5.1 真机运行闪退、加载失败速查表把我在真机集成阶段碰到的高频问题整理成一张表可以对照自查现象可能原因处理方式dlopen failed: library not foundso 文件缺失或路径不对确认 libQnn*.so 都放进 jniLibs/arm64-v8aHTP backend 初始化失败芯片平台与 so 版本不匹配换对应代际的 HTP stub/skel或调低 SDK 版本TF tensor 创建失败 / invalid shape输入 shape 传错打印 DLC 实际输入 shape 和代码里传的 shape 对比Graph finalize 报错模型里含动态维度或未支持算子回到转换阶段检查 ONNX 模型清洗是否彻底输出全为 0 或数值明显不对量化输出未反量化或输入预处理不一致检查 scale/zeroPoint 换算检查归一化参数首次推理非常慢图结构解析或工作空间分配耗时改用 context binary预热后时序复测5.2 几个不容易想到的怪坑第一个坑是 so 文件都放了但系统仍然提示找不到库。这往往不是 so 缺失而是 Android 的 native library 解压机制在作怪。APK 安装后系统是否从 APK 中解压 so受 manifest 里android:extractNativeLibs影响。某些设备、某些打包方式下如果这个属性被设置成 false而应用又没有走系统 so 加载路径就会出现“文件明明在 APK 里但 dlopen 找不到”的情况。遇到这种问题可以显式设置android:extractNativeLibstrue或者改用从 assets 拷贝到私有目录再 dlopen 的方案。第二个坑是 stub 和 skel 版本对不上。QNN HTP 后端依赖一串带代际标识的 so 文件比如 V73、V75、V79 分别对应不同代的 Hexagon 处理器。如果你只放了一个版本而真机是另一代芯片初始化时不会有明显报错但推理时可能挂在某个奇怪的阶段。解决办法是把目标机型的芯片代际确认好对应版本放进工程最稳妥的方式是把几个常用版本的 stub/skel 都放进去让运行时按设备能力去匹配。当然代价是 APK 体积会变大取舍本身也是一门学问。第三个坑是模型量化的反量化忘了做。QNN 的 int8 输出本质上是“整数索引”你要按照模型输出层的 scale 和 zeroPoint 换算回实数才能拿去和 FP32 输出对比、或者直接用于业务判断。我第一次在 Android 端看到输出全是 7 和 8 这种整数时一度以为是模型坏了后来才意识到是反量化漏了。这里建议在 Java 层写一个 DisplayOutput 的工具方法把反量化逻辑固定封装起来调试时直接打印真实浮点数能省很多事。第四个坑是手机上不同运行环境对 HTP 的影响。开发者选项里某些功耗或性能模式设置可能导致 HTP 跑在低功耗状态推理时延波动很大还有一些系统会在后台回收推理进程的显存或上下文资源。遇到“一会儿快一会儿慢”或者“跑一段时间后突然失败”先检查是否进程被杀、Context 是否被回收必要时在推理前做一次环境自检确认 HTP 可用再继续。5.3 一个排查思路从“哪一层”到“为什么”真机上出问题最忌讳的是乱试。我自己的排查顺序通常是这样的先复现固定输入和参数确认问题是否稳定复现再隔离用 PC 端 SampleApp 跑同一份 DLC排除手机环境因素然后分阶段FP32 全链路是否一致、量化链路是否一致、最终输出是否一致找到第一个出现问题的环节最后再精确定位到层、到算子。这套流程虽然慢但每次都能走到正确方向上比乱试参数高效十倍。遇到精度问题时同理先定位到层再分析这层的结构和激活分布特征判断是量化范围问题、校准数据问题还是层本身太敏感。定位的越细解决方案就越可靠。跑完全部流程我最深的体会是QNN SDK 这套工具链本身并不复杂真正复杂的是对“环境、版本、数据预处理一致性”这些细节的敏感度。任何一步偷懒最后都会以精度下降、加载失败或者运行时崩溃的形式来找你。如果你正在往这个方向踩坑我的建议很简单第一步永远先把 FP32 链路完整跑通再做量化校准数据一定要贴近真实业务排查问题时分步隔离不要乱试。把这些基础打牢剩下的大多数问题其实都只是时间问题。