尧图网页设计 
ONNX Runtime QNN 执行器测试实战构建、过滤运行与中间产物调试指南【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime本文为 ONNX Runtime 的 Qualcomm QNN 执行器QNN EP测试套件提供一份可落地的操作手册如何在标准构建中生成 QNN 测试可执行文件、如何用 Google Test 过滤器按后端CPU/HTP/GPU/IR挑选用例运行以及如何通过四个环境变量把测试过程中的 ONNX 模型、QNN 图 JSON 和编译产物 DLC 保存到磁盘用于问题排查。读完后你可以独立复现 QNN EP 的集成测试结果并在 QNN 后端出现问题时快速定位到具体的中间产物。一、测试目录定位QNN EP 集成测试是什么onnxruntime/test/providers/qnn目录包含 QNN 执行器的集成测试。其核心验证思路是将 ONNX 模型放到 QNN EP 上执行再把推理结果与 CPU EP 的结果进行比对。这一思路在工具头文件 qnn_test_utils.h 中得到体现其中定义了三种主力测试入口TestQDQModelAccuracy约 L611针对 QDQ量化模型依次执行 3 次推理——float32 模型在 CPU EP 上作为基线、QDQ 模型在 CPU EP 上、QDQ 模型在 QNN EP 上并检查 QNN EP 的精度不劣于 CPU EP默认容差 0.4%见下文第四节TestFp16ModelAccuracy约 L850针对 FP16 模型做同样的“三次推理 精度比对”流程RunQnnModelTestqnn_test_utils.cc把测试模型跑在 QNN EP 上验证 EP 节点分配情况并确认 QNN 与 CPU EP 的输出在可接受误差内一致。从目录结构看测试覆盖了大量算子文件如 conv_test.cc、matmul_test.cpp、gemm_op_test.cc、lstm_test.cc、resize_test.cc、pad_op_test.cpp 等此外还有两个子目录承载更专题化的用例qnn_node_group/节点组融合测试如gelu_fusion_test.cc、lpbqgemm_fusion_test.cc、scale_softmax_fusion_test.cc顶层还包含 qnn_ep_context_test.ccEP 上下文相关与 qnn_basic_test.cc 等基础用例。所有测试文件共享 qnn_test_utils.h / qnn_test_utils.cc 这套工具层后文所有环境变量行为均由该工具层实现。二、构建测试QNN 测试随标准构建生成这些测试不需要单独构建——它们是常规 ONNX Runtime 构建的一部分。构建成功后会得到测试可执行文件平台可执行文件Windowsonnxruntime_provider_test.exeLinux/macOSonnxruntime_provider_test需要注意的适用前提QNN EP 本身是有条件编译的。从 build_args.py 与 build.py 的构建参数定义看构建脚本提供--use_qnn选项对应 CMake 的-Donnxruntime_USE_QNNONbuild.py 中可见相关拼接逻辑且支持static_lib/shared_lib等不同链接形态Android 的 AAR 打包流水线中也通过USE_QNN开关决定是否包含 QNN见 build_aar_and_copy_artifacts.sh。从源码结构看只有开启 QNN 支持并完成构建后onnxruntime_provider_test中才包含 QNN 相关用例在未启用 QNN 的构建中运行这些过滤器只会得到“没有匹配的测试”。三、运行测试用 gtest 过滤器按后端挑选用例QNN 支持多个后端。每个后端对应一个 Google Test 测试夹具fixture可以按标准 gtest 语法过滤运行# QNN CPU 后端 onnxruntime_provider_test.exe --gtest_filterQnnCPUBackendTests.* # QNN HTP 后端 onnxruntime_provider_test.exe --gtest_filterQnnHTPBackendTests.* # QNN GPU 后端 onnxruntime_provider_test.exe --gtest_filterQnnGPUBackendTests.* # QNN IR 后端 onnxruntime_provider_test.exe --gtest_filterQnnIRBackendTests.*这四个过滤前缀并非凭空而来它们在 qnn_test_utils.h 中定义QnnHTPBackendTests、QnnGPUBackendTests、QnnCPUBackendTests、QnnIRBackendTests都是继承自::testing::Test的夹具类。源码同时说明了夹具的运行语义每个夹具在SetUp()中先检查对应后端是否可用后端不可用时测试会被跳过skip而非失败——注释明确指出这种情况可能发生在 Windows ARM64 及其虚拟机构建环境中QnnHTPBackendTests额外缓存了平台属性HTP 架构、SoC 型号、VTCM 大小、SDK 版本等并提供ShouldSkipIfHtpFp16Unsupported()、ShouldSkipIfHtpArchIsLessThanOrEqualTo()等静态判断供具体用例按硬件能力做条件跳过配合头文件末尾定义的QNN_SKIP_TEST_IF_HTP_FP16_UNSUPPORTED等宏使用。因此“测试被跳过”通常不代表回归而是当前运行平台不具备相应 QNN 后端能力。四、保存中间产物四个调试环境变量排查 QNN 后端问题时保存测试产生的中间文件往往非常有帮助。测试二进制识别以下环境变量解析逻辑集中在 qnn_test_utils.h 的QNNTestEnvironment单例中环境变量作用底层实现QNN_DUMP_ONNX保存测试实际使用的 ONNX 模型调用Model::Save写入dumped_*_model.onnxQNN_DUMP_JSON保存 QNN 图 JSON注入 provider 选项dump_json_qnn_graph1及json_qnn_graph_dirQNN_DUMP_DLC保存编译后的 QNN DLC 文件注入dump_qnn_ir_dlc1、dump_qnn_ir_dlc_dir并将qnn_ir_backend_path指向QnnIr.dllWindows或libQnnIr.soLinux/macOSQNN_VERBOSE将 ONNX Runtime 日志级别提升到ORT_LOGGING_LEVEL_VERBOSE将日志严重级别设为kVERBOSE并移除 ETW 日志 sink几个从源码可以确认的细节有助于正确使用这些开关取值判定IsEnvVarSet的实现规定变量“已设置”当且仅当其非空且不是字符串0qnn_test_utils.h所以export QNN_DUMP_ONNX0等价于未开启。产物目录命名只要开启了任一 dump 开关CreateTestcaseDirs()就会按当前工作目录/TestSuite_TestName创建输出目录qnn_test_utils.h因此所有产物都落在启动测试二进制时所在的工作目录下。不同测试类型 dump 的 ONNX 模型文件名不同RunQnnModelTest路径下保存dumped_f32_model.onnxqnn_test_utils.ccTestQDQModelAccuracy会同时保存dumped_f32_model.onnx基线 float 模型与dumped_qdq_model.onnxQDQ 模型TestFp16ModelAccuracy则保存dumped_f32_model.onnx与dumped_f16_model.onnx。一次开启全部开关后的典型目录结构如下与 README 中的示例一致. ├── QnnCPUBackendTests_BatchNorm2D_fp32 # RunQnnModelTest │ ├── dumped_f32_model.onnx # float32 ONNX 模型 │ ├── QNNExecutionProvider_QNN_XXXX_X_X.dlc │ └── QNNExecutionProvider_QNN_XXXX_X_X.json ├── QnnHTPBackendTests_BatchNorm_FP16 # TestFp16ModelAccuracy │ ├── dumped_f16_model.onnx # float16 ONNX 模型 │ ├── dumped_f32_model.onnx # float32 ONNX 模型 │ ├── QNNExecutionProvider_QNN_XXXX_X_X.dlc │ └── QNNExecutionProvider_QNN_XXXX_X_X.json └── QnnHTPBackendTests_BatchNorm2D_U8U8S32 # TestQDQModelAccuracy ├── dumped_f32_model.onnx # float32 ONNX 模型 ├── dumped_qdq_model.onnx # QDQ ONNX 模型 ├── QNNExecutionProvider_QNN_XXXX_X_X.dlc └── QNNExecutionProvider_QNN_XXXX_X_X.json # 所有产物文件均位于调用测试二进制时所在的工作目录下这些产物可以直接用于离线复现ONNX 模型可交给任意工具检查图结构DLC 文件是 QNN IR 后端的编译产物可提交给 QNN SDK 侧进一步分析。五、按平台启用环境变量四个变量可以任意组合启用。Linux/macOSexport QNN_DUMP_ONNX1 export QNN_DUMP_JSON1 export QNN_DUMP_DLC1 export QNN_VERBOSE1WindowsCMDset QNN_DUMP_ONNX1 set QNN_DUMP_JSON1 set QNN_DUMP_DLC1 set QNN_VERBOSE1WindowsPowerShell$Env:QNN_DUMP_ONNX 1 $Env:QNN_DUMP_JSON 1 $Env:QNN_DUMP_DLC 1 $Env:QNN_VERBOSE 1六、进阶调试用 QNN Saver 后端抓取完整 API 调用序列除了上述四个变量工具层还暴露了一个更深层的调试开关这一点 README 未展开但源码中有明确说明。在 qnn_test_utils.cc 的TryEnableQNNSaver中设置环境变量ORT_UNIT_TEST_ENABLE_QNN_SAVER1后测试会在 QNN EP 的 provider 选项中注入qnn_saver_path取值为QnnSaver.dllWindows或libQnnSaver.so其他平台启用 QNN Saver 后端后测试会把 QNN API 调用及权重转储到磁盘saver_output/saver_output.c包含全部 QNN API 调用的 C 文件和saver_output/params.bintensor 创建、算子配置校验、图执行过程中提供的全部输入/输出/参数张量数据的二进制文件该后端有两个显著副作用所有 QNN API 调用都会返回成功且推理输出返回的是假数据dummy data——因此它只适合调试调用序列不适合验证精度由于 QNN Saver 的输出文件总是被覆盖建议配合--gtest_filter一次只跑单个用例例如--gtest_filterQnnHTPBackendTests.Resize_DownSample_Linear_AlignCorners。七、结果判定机制QNN EP 到底被允许“偏”多少理解容差机制有助于解读测试失败信息。以 QDQ 模型为例qnn_test_utils.h 中的QDQTolerance定义了默认容差DEFAULT_QDQ_TOLERANCE 0.0040.4%注释说明其等价于 1 个 int8 量化单位或 262 个 int16 量化单位。对每个输出元素测试同时检查两条标准满足其一即通过见 qnn_test_utils.hQNN EP 相对 f32CPU 基线的归一化误差不大于 QDQCPU 的归一化误差即 QNN 至少和 CPU 一样准或abs(qdqQNN_EP − qdqCPU_EP) / output_range落在容差之内。失败时日志会打印output_range、tolerance以及期望值与两侧实际值的详细对比为避免大数据量用例刷屏错误明细最多打印 10 条max_error_count 10。FP16 精度测试使用相对误差做类似判定默认容差同为 0.004。RunQnnModelTest则对 fp32 输出采用绝对误差上限默认fp32_abs_err 1e-5。八、已知限制与收尾建议README 的 Note 部分给出两点必须注意的事项使用调试产物时尤其要记住QNN 后端自身的缺陷可能导致测试产物保存失败——即使打开了 dump 开关个别用例也可能拿不到 DLC/JSON 产物这属于 QNN 侧问题而非测试框架问题测试二进制不会自动清理产物目录——TestSuite_TestName目录一旦生成就会保留在工作目录中一次调试会话结束后建议自行清理这些目录避免陈旧产物干扰后续分析。综合起来一次完整的 QNN EP 测试排查流程可以是用--gtest_filter精确锁定失败用例 → 开启QNN_DUMP_ONNX/QNN_DUMP_JSON/QNN_DUMP_DLC/QNN_VERBOSE重跑 → 在TestSuite_TestName目录中拿到模型、图与编译产物 → 需要更底层信息时再叠加ORT_UNIT_TEST_ENABLE_QNN_SAVER1抓取完整 QNN API 调用序列。相关实现与用例均可在当前仓库中按上文给出的相对路径查阅验证。【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ONNX Runtime QNN 执行器测试实战：构建、过滤运行与中间产物调试指南
ONNX Runtime QNN 执行器测试实战构建、过滤运行与中间产物调试指南【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime本文为 ONNX Runtime 的 Qualcomm QNN 执行器QNN EP测试套件提供一份可落地的操作手册如何在标准构建中生成 QNN 测试可执行文件、如何用 Google Test 过滤器按后端CPU/HTP/GPU/IR挑选用例运行以及如何通过四个环境变量把测试过程中的 ONNX 模型、QNN 图 JSON 和编译产物 DLC 保存到磁盘用于问题排查。读完后你可以独立复现 QNN EP 的集成测试结果并在 QNN 后端出现问题时快速定位到具体的中间产物。一、测试目录定位QNN EP 集成测试是什么onnxruntime/test/providers/qnn目录包含 QNN 执行器的集成测试。其核心验证思路是将 ONNX 模型放到 QNN EP 上执行再把推理结果与 CPU EP 的结果进行比对。这一思路在工具头文件 qnn_test_utils.h 中得到体现其中定义了三种主力测试入口TestQDQModelAccuracy约 L611针对 QDQ量化模型依次执行 3 次推理——float32 模型在 CPU EP 上作为基线、QDQ 模型在 CPU EP 上、QDQ 模型在 QNN EP 上并检查 QNN EP 的精度不劣于 CPU EP默认容差 0.4%见下文第四节TestFp16ModelAccuracy约 L850针对 FP16 模型做同样的“三次推理 精度比对”流程RunQnnModelTestqnn_test_utils.cc把测试模型跑在 QNN EP 上验证 EP 节点分配情况并确认 QNN 与 CPU EP 的输出在可接受误差内一致。从目录结构看测试覆盖了大量算子文件如 conv_test.cc、matmul_test.cpp、gemm_op_test.cc、lstm_test.cc、resize_test.cc、pad_op_test.cpp 等此外还有两个子目录承载更专题化的用例qnn_node_group/节点组融合测试如gelu_fusion_test.cc、lpbqgemm_fusion_test.cc、scale_softmax_fusion_test.cc顶层还包含 qnn_ep_context_test.ccEP 上下文相关与 qnn_basic_test.cc 等基础用例。所有测试文件共享 qnn_test_utils.h / qnn_test_utils.cc 这套工具层后文所有环境变量行为均由该工具层实现。二、构建测试QNN 测试随标准构建生成这些测试不需要单独构建——它们是常规 ONNX Runtime 构建的一部分。构建成功后会得到测试可执行文件平台可执行文件Windowsonnxruntime_provider_test.exeLinux/macOSonnxruntime_provider_test需要注意的适用前提QNN EP 本身是有条件编译的。从 build_args.py 与 build.py 的构建参数定义看构建脚本提供--use_qnn选项对应 CMake 的-Donnxruntime_USE_QNNONbuild.py 中可见相关拼接逻辑且支持static_lib/shared_lib等不同链接形态Android 的 AAR 打包流水线中也通过USE_QNN开关决定是否包含 QNN见 build_aar_and_copy_artifacts.sh。从源码结构看只有开启 QNN 支持并完成构建后onnxruntime_provider_test中才包含 QNN 相关用例在未启用 QNN 的构建中运行这些过滤器只会得到“没有匹配的测试”。三、运行测试用 gtest 过滤器按后端挑选用例QNN 支持多个后端。每个后端对应一个 Google Test 测试夹具fixture可以按标准 gtest 语法过滤运行# QNN CPU 后端 onnxruntime_provider_test.exe --gtest_filterQnnCPUBackendTests.* # QNN HTP 后端 onnxruntime_provider_test.exe --gtest_filterQnnHTPBackendTests.* # QNN GPU 后端 onnxruntime_provider_test.exe --gtest_filterQnnGPUBackendTests.* # QNN IR 后端 onnxruntime_provider_test.exe --gtest_filterQnnIRBackendTests.*这四个过滤前缀并非凭空而来它们在 qnn_test_utils.h 中定义QnnHTPBackendTests、QnnGPUBackendTests、QnnCPUBackendTests、QnnIRBackendTests都是继承自::testing::Test的夹具类。源码同时说明了夹具的运行语义每个夹具在SetUp()中先检查对应后端是否可用后端不可用时测试会被跳过skip而非失败——注释明确指出这种情况可能发生在 Windows ARM64 及其虚拟机构建环境中QnnHTPBackendTests额外缓存了平台属性HTP 架构、SoC 型号、VTCM 大小、SDK 版本等并提供ShouldSkipIfHtpFp16Unsupported()、ShouldSkipIfHtpArchIsLessThanOrEqualTo()等静态判断供具体用例按硬件能力做条件跳过配合头文件末尾定义的QNN_SKIP_TEST_IF_HTP_FP16_UNSUPPORTED等宏使用。因此“测试被跳过”通常不代表回归而是当前运行平台不具备相应 QNN 后端能力。四、保存中间产物四个调试环境变量排查 QNN 后端问题时保存测试产生的中间文件往往非常有帮助。测试二进制识别以下环境变量解析逻辑集中在 qnn_test_utils.h 的QNNTestEnvironment单例中环境变量作用底层实现QNN_DUMP_ONNX保存测试实际使用的 ONNX 模型调用Model::Save写入dumped_*_model.onnxQNN_DUMP_JSON保存 QNN 图 JSON注入 provider 选项dump_json_qnn_graph1及json_qnn_graph_dirQNN_DUMP_DLC保存编译后的 QNN DLC 文件注入dump_qnn_ir_dlc1、dump_qnn_ir_dlc_dir并将qnn_ir_backend_path指向QnnIr.dllWindows或libQnnIr.soLinux/macOSQNN_VERBOSE将 ONNX Runtime 日志级别提升到ORT_LOGGING_LEVEL_VERBOSE将日志严重级别设为kVERBOSE并移除 ETW 日志 sink几个从源码可以确认的细节有助于正确使用这些开关取值判定IsEnvVarSet的实现规定变量“已设置”当且仅当其非空且不是字符串0qnn_test_utils.h所以export QNN_DUMP_ONNX0等价于未开启。产物目录命名只要开启了任一 dump 开关CreateTestcaseDirs()就会按当前工作目录/TestSuite_TestName创建输出目录qnn_test_utils.h因此所有产物都落在启动测试二进制时所在的工作目录下。不同测试类型 dump 的 ONNX 模型文件名不同RunQnnModelTest路径下保存dumped_f32_model.onnxqnn_test_utils.ccTestQDQModelAccuracy会同时保存dumped_f32_model.onnx基线 float 模型与dumped_qdq_model.onnxQDQ 模型TestFp16ModelAccuracy则保存dumped_f32_model.onnx与dumped_f16_model.onnx。一次开启全部开关后的典型目录结构如下与 README 中的示例一致. ├── QnnCPUBackendTests_BatchNorm2D_fp32 # RunQnnModelTest │ ├── dumped_f32_model.onnx # float32 ONNX 模型 │ ├── QNNExecutionProvider_QNN_XXXX_X_X.dlc │ └── QNNExecutionProvider_QNN_XXXX_X_X.json ├── QnnHTPBackendTests_BatchNorm_FP16 # TestFp16ModelAccuracy │ ├── dumped_f16_model.onnx # float16 ONNX 模型 │ ├── dumped_f32_model.onnx # float32 ONNX 模型 │ ├── QNNExecutionProvider_QNN_XXXX_X_X.dlc │ └── QNNExecutionProvider_QNN_XXXX_X_X.json └── QnnHTPBackendTests_BatchNorm2D_U8U8S32 # TestQDQModelAccuracy ├── dumped_f32_model.onnx # float32 ONNX 模型 ├── dumped_qdq_model.onnx # QDQ ONNX 模型 ├── QNNExecutionProvider_QNN_XXXX_X_X.dlc └── QNNExecutionProvider_QNN_XXXX_X_X.json # 所有产物文件均位于调用测试二进制时所在的工作目录下这些产物可以直接用于离线复现ONNX 模型可交给任意工具检查图结构DLC 文件是 QNN IR 后端的编译产物可提交给 QNN SDK 侧进一步分析。五、按平台启用环境变量四个变量可以任意组合启用。Linux/macOSexport QNN_DUMP_ONNX1 export QNN_DUMP_JSON1 export QNN_DUMP_DLC1 export QNN_VERBOSE1WindowsCMDset QNN_DUMP_ONNX1 set QNN_DUMP_JSON1 set QNN_DUMP_DLC1 set QNN_VERBOSE1WindowsPowerShell$Env:QNN_DUMP_ONNX 1 $Env:QNN_DUMP_JSON 1 $Env:QNN_DUMP_DLC 1 $Env:QNN_VERBOSE 1六、进阶调试用 QNN Saver 后端抓取完整 API 调用序列除了上述四个变量工具层还暴露了一个更深层的调试开关这一点 README 未展开但源码中有明确说明。在 qnn_test_utils.cc 的TryEnableQNNSaver中设置环境变量ORT_UNIT_TEST_ENABLE_QNN_SAVER1后测试会在 QNN EP 的 provider 选项中注入qnn_saver_path取值为QnnSaver.dllWindows或libQnnSaver.so其他平台启用 QNN Saver 后端后测试会把 QNN API 调用及权重转储到磁盘saver_output/saver_output.c包含全部 QNN API 调用的 C 文件和saver_output/params.bintensor 创建、算子配置校验、图执行过程中提供的全部输入/输出/参数张量数据的二进制文件该后端有两个显著副作用所有 QNN API 调用都会返回成功且推理输出返回的是假数据dummy data——因此它只适合调试调用序列不适合验证精度由于 QNN Saver 的输出文件总是被覆盖建议配合--gtest_filter一次只跑单个用例例如--gtest_filterQnnHTPBackendTests.Resize_DownSample_Linear_AlignCorners。七、结果判定机制QNN EP 到底被允许“偏”多少理解容差机制有助于解读测试失败信息。以 QDQ 模型为例qnn_test_utils.h 中的QDQTolerance定义了默认容差DEFAULT_QDQ_TOLERANCE 0.0040.4%注释说明其等价于 1 个 int8 量化单位或 262 个 int16 量化单位。对每个输出元素测试同时检查两条标准满足其一即通过见 qnn_test_utils.hQNN EP 相对 f32CPU 基线的归一化误差不大于 QDQCPU 的归一化误差即 QNN 至少和 CPU 一样准或abs(qdqQNN_EP − qdqCPU_EP) / output_range落在容差之内。失败时日志会打印output_range、tolerance以及期望值与两侧实际值的详细对比为避免大数据量用例刷屏错误明细最多打印 10 条max_error_count 10。FP16 精度测试使用相对误差做类似判定默认容差同为 0.004。RunQnnModelTest则对 fp32 输出采用绝对误差上限默认fp32_abs_err 1e-5。八、已知限制与收尾建议README 的 Note 部分给出两点必须注意的事项使用调试产物时尤其要记住QNN 后端自身的缺陷可能导致测试产物保存失败——即使打开了 dump 开关个别用例也可能拿不到 DLC/JSON 产物这属于 QNN 侧问题而非测试框架问题测试二进制不会自动清理产物目录——TestSuite_TestName目录一旦生成就会保留在工作目录中一次调试会话结束后建议自行清理这些目录避免陈旧产物干扰后续分析。综合起来一次完整的 QNN EP 测试排查流程可以是用--gtest_filter精确锁定失败用例 → 开启QNN_DUMP_ONNX/QNN_DUMP_JSON/QNN_DUMP_DLC/QNN_VERBOSE重跑 → 在TestSuite_TestName目录中拿到模型、图与编译产物 → 需要更底层信息时再叠加ORT_UNIT_TEST_ENABLE_QNN_SAVER1抓取完整 QNN API 调用序列。相关实现与用例均可在当前仓库中按上文给出的相对路径查阅验证。【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考