一、下载 QNN SDK 工具高通 AI 运行时Qualcomm AI Runtime, QNNSDK 是用于在高通平台上部署和运行 AI 模型的核心工具包。以下是获取和初步设置步骤# 下载 QNN SDK 社区版版本 2.35.0.250530wgethttps://apigwx-aws.qualcomm.com/qsc/public/v1/api/download/software/sdks/Qualcomm_AI_Runtime_Community/All/2.35.0.250530/v2.35.0.250530.zip# 解压并进入工具目录unzipv2.35.0.250530.zipcdqairt/2.35.0.250530/bin/# 设置环境变量包含 QNN_SDK_ROOT 等source./envsetup.sh# 下载 Android NDK用于交叉编译 Android 应用wgethttps://dl.google.com/android/repository/android-ndk-r26c-linux.zip说明envsetup.sh会设置QNN_SDK_ROOT等重要环境变量后续转换和编译命令依赖此变量。Android NDK 是编译 Android 平台库和示例应用的必要工具。二、关键信息与示例应用1. 示例应用SampleApp路径qairt/2.35.0.250530/examples/QNN/SampleApp/SampleApp此示例是一个完整的 QNN 模型加载与推理演示程序可用于编译生成 Android 可执行程序通过配置编译脚本可生成适用于 Android 设备的 APK 或可执行文件。环境验证将编译好的应用通过adb push推送到 Android 设备运行可以加载模型.so或.bin格式并执行推理。错误诊断该应用在运行时会输出详细的日志有助于排查环境配置、库依赖或模型兼容性问题。以下是完整的 Android 交叉编译脚本示例#!/bin/bashset-e# 设置 CMake 和 NDK 路径请根据实际安装位置调整exportPATH~/Android/Sdk/cmake/3.22.1/bin:$PATHexportANDROID_NDK_ROOT~/android-ndk-r26c/#!/usr/bin/env sh# 设置 Android NDK 路径NDK_ROOT${ANDROID_NDK_ROOT}echo----------------------echo${ANDROID_NDK_ROOT}SCRIPT$(readlink-f$0)WD$(dirname$SCRIPT)LIB_ROOT$WDecho$LIB_ROOT# 输出路径设置BUILD_DIR${LIB_ROOT}/buildINSTALL_DIR${WD}/android_libN_JOBS${N_JOBS:-8}# 支持的 ABI 列表可根据需要注释掉不需要的架构declare-aANDROID_ABI_LIST(arm64-v8aarmeabi-v7a)# declare -a ANDROID_ABI_LIST(arm64-v8a)API_LEVEL21# 设置最低 API 级别# 清理并创建构建目录rm-rf$BUILD_DIRmkdir-p$BUILD_DIRcd$BUILD_DIR||exit# 编译函数functionbuild_library{ABI$1echoBuilding for$ABI# echo $NDK_ROOTmkdir-pbuild_$ABIcdbuild_$ABI||exitcmake..-DCMAKE_BUILD_WITH_INSTALL_RPATHON\-DCMAKE_TOOLCHAIN_FILE~/android-ndk-r26c/build/cmake/android.toolchain.cmake\-DANDROID_NDK${NDK_ROOT}\-DANDROID_NATIVE_API_LEVEL${API_LEVEL}\-DANDROID_ABI$ABI\-DBUILD_SHARED_LIBSON\-DCMAKE_BUILD_TYPERelease\-DANDROID_STLc_static\$LIB_ROOTmake-j${N_JOBS}cd..}# 遍历所有 ABI 构建库forABIin${ANDROID_ABI_LIST[]};doecho$NDK_ROOTbuild_library$ABIdonecd$WD||exit2. 平台与后端库说明QNN SDK 支持多种计算后端对应不同的硬件加速单元libQnnHtp.so高通 Hexagon Tensor ProcessorHTP后端即 NPU神经网络处理器专用库提供最高性能的 AI 推理加速。libQnnCpu.soCPU 后端在没有 NPU 或需要调试时使用完全在 CPU 上执行计算。选择建议部署到实际设备时优先使用libQnnHtp.so以获得最佳性能在 x86 开发机调试或兼容性测试时可使用libQnnCpu.so。3. HTP 后端使用注意事项当使用libQnnHtp.soNPU 后端时必须提供--input_list INPUT_LIST参数并启用静态量化选项。这是因为 HTP 硬件需要预先知道输入张量的形状和数据类型以进行图编译和优化。4. Android 环境变量配置在 Android 设备上运行 QNN 应用时需要设置以下环境变量可通过adb shell设置或在应用启动脚本中配置# 添加 QNN 库路径到动态链接库搜索路径exportLD_LIBRARY_PATH$LD_LIBRARY_PATH:/data/user/0/com.mms.densenapplication/files/desensitize/qnn_lib/:/vendor/lib64:/vendor/lib:/# ★ 必须设置指定 Hexagon DSP 库路径否则会报 找不到设备 错误exportADSP_LIBRARY_PATH/data/user/0/com.mms.densenapplication/files/desensitize/qnn_lib# 可选指定厂商库路径exportVENDOR_LIB/vendor/lib64/关键点ADSP_LIBRARY_PATH是 HTP/DSP 运行时查找所需固件和库的路径若不设置会导致Failed to create device等错误。5. 模型简化工具在转换模型前如果原始 ONNX 模型结构复杂包含冗余算子或复杂控制流建议先使用简化工具优化# 使用 onnx-simplifier 简化模型pipinstallonnx-simplifier python-monnxsim input.onnx output_simplified.onnx项目地址https://github.com/daquexian/onnx-simplifier简化后的模型通常转换成功率更高且生成的 QNN 模型文件更小、推理效率更好。三、模型转换与推理命令1. ONNX 转 QNN 模型生成 .cpp 和 .bin# onnx 转 cpp、bin./qairt/2.35.0.250530/bin/x86_64-linux-clang/qnn-onnx-converter\-ionnx_models/deeplabv3_resnet101_simplified.onnx\-dinput_image1,3,640,640\-omodel/model.cpp\--param_quantizerenhanced参数说明-i输入 ONNX 模型路径-d指定输入节点名称和形状格式名称 批次,通道,高,宽-o输出 C 模型定义文件--param_quantizer enhanced使用增强型量化器推荐2. 生成模型库.so# cpp 转 so生成平台特定的模型库./qairt/2.35.0.250530/bin/x86_64-linux-clang/qnn-model-lib-generator\-cmodel/model.cpp\-bmodel/model.bin\-tx86_64-linux-clang\-omodel_libs参数说明-c上一步生成的 .cpp 文件-b上一步生成的 .bin 权重文件-t目标平台此处为 x86_64 Linux 开发机-o输出目录3. 生成序列化上下文.serialized.bin# graph 转 bin生成可部署的序列化上下文./qairt/2.35.0.250530/bin/x86_64-linux-clang/qnn-context-binary-generator\--backend${QNN_SDK_ROOT}/lib/x86_64-linux-clang/libQnnHtp.so\--modelmodel_libs/x86_64-linux-clang/libmodel.so\--binary_filedesensity_quantized_qpc.serialized此步骤将模型图与权重打包为单个二进制文件便于部署。4. 推理测试方式一使用 .serialized.bin 文件推理# 推理 so使用序列化上下文./qairt/2.35.0.250530/bin/x86_64-linux-clang/qnn-net-run\--modeloutput/desensity_quantized_qpc.serialized.bin\--backend${QNN_SDK_ROOT}/lib/x86_64-linux-clang/libQnnHtp.so\--input_listimg_raw_list.txt方式二直接使用 .bin 上下文推理# 推理 bin直接加载上下文./qairt/2.35.0.250530/bin/x86_64-linux-clang/qnn-net-run\--retrieve_context./output/desensity_quantized_qpc.serialized.bin\--backend${QNN_SDK_ROOT}/lib/x86_64-linux-clang/libQnnHtp.so\--input_listimg_raw_list.txt输入列表文件格式img_raw_list.txtinput_image:input1.bin input_image:input2.bin每行格式为输入节点名称:二进制数据文件文件为原始二进制数据无头信息。四、常见问题与排查找不到 HTP 设备检查ADSP_LIBRARY_PATH是否设置正确且路径中包含libQnnHtp.so和 DSP 固件。模型转换失败尝试使用 onnx-simplifier 简化模型检查输入形状是否与模型匹配。推理精度下降调整量化参数如使用--param_quantizer enhanced检查输入数据预处理是否与训练时一致。性能不佳确保使用libQnnHtp.so而非 CPU 后端检查模型是否已针对 HTP 进行图优化。五、参考资料Qualcomm AI 开发者工作流程官方文档QNN SDK 介绍与入门指南CSDN 博客QNN 模型部署实战知乎专栏高通 NPU 架构深入解析总结关键点包括正确设置环境变量尤其是ADSP_LIBRARY_PATH根据目标平台选择合适的后端库HTP 或 CPU使用模型简化工具提高转换成功率遵循标准的模型转换流程ONNX → .cpp/.bin → .so → .serialized.bin
