用于 Ultralytics YOLO 模型的 Qualcomm QNN 导出#

在高通 Snapdragon 设备上部署计算机视觉模型需要针对高通 AI Engine Direct (QNN) 运行时进行调优的模型格式。将 Ultralytics YOLO 模型导出为 QNN 格式，可让你在数十亿手机、笔记本电脑、汽车系统和物联网设备搭载的 Snapdragon CPU、Adreno GPU 以及 Hexagon NPU 硬件上运行加速的端侧推理。本指南将介绍如何将 YOLO 导出到高通 QNN，并将其部署以在 Snapdragon 硬件上进行快速、低功耗的推理。

什么是 Qualcomm QNN？#

Qualcomm AI Engine Direct（通常称为 QNN，作为高通 AI Runtime (QAIRT) SDK 的一部分分发）是高通针对 Snapdragon 处理器的底层推理技术栈。它提供了一个统一的 API，带有针对 Snapdragon CPU、Adreno GPU 以及现代 Snapdragon SoC 内部专用神经网络处理单元 (NPU) —— 六边形张量处理器 (HTP) 的后端特定库。QNN 让开发者能够全栈访问这些 Snapdragon AI 加速器，它是较旧的 Snapdragon Neural Processing Engine (SNPE) SDK 的现代继任者。它为 Snapdragon 8 Gen 2、8 Gen 3 和 8 Elite 移动平台、Snapdragon X 笔记本电脑以及汽车和 XR 产品提供端侧 AI 支持。

为什么要导出到 Qualcomm QNN？#

Snapdragon 是全球部署最广泛的移动计算平台。将 Ultralytics YOLO 导出为 Qualcomm QNN 格式可以解锁这些设备上的专用 AI 硬件：

• Hexagon NPU 加速：在 Hexagon 张量处理器上运行 YOLO 可以提供比 CPU 推理显著更高的吞吐量和更低的功耗 —— 是 Snapdragon 上实时推理和全天候计算机视觉的理想选择。
• 设备端且离线：QNN 推理完全在 Snapdragon 设备上运行，因此没有云端往返，延迟保持在较低水平，并且数据绝不会离开设备。
• 量化效率：QNN 导出将 YOLO 量化为带有 16 位激活值的 INT8 权重，这是 Hexagon NPU 偏好的准确度/性能平衡，能够在电池供电的硬件上缩小模型尺寸并最大化每秒帧数。
• 一种格式，多种设备：单个 Qualcomm QNN 导出即可覆盖 Snapdragon 8 Gen 2、8 Gen 3 和 8 Elite 系列及后续产品中的 Snapdragon CPU、Adreno GPU 和 Hexagon NPU。
• 生产就绪的 Qualcomm AI 栈：QNN (Qualcomm AI Engine Direct / QAIRT) 是 Qualcomm 当前积极维护的设备端 AI 运行时，也是 SNPE 的推荐替代方案。

QNN 导出格式#

Ultralytics 使用 ONNX Runtime QNN 执行提供程序（可通过 pip 安装的 onnxruntime-qnn 包，其中捆绑了 QAIRT 库）在本地将 YOLO 模型编译为 QNN。导出器将你的模型转换为 ONNX，使用校准数据将其量化为 16 位激活值和 INT8 权重（Hexagon NPU 的推荐平衡），然后初始化一个启用了上下文二进制缓存的 ONNX Runtime 会话 —— 这会将量化图编译为嵌入在 <model>_qnn.onnx 中的 QNN 上下文二进制文件。无需高通账号、云端上传或单独下载 SDK。

与需要在高通托管的 Snapdragon 设备上编译和分析模型并需要高通账号的基于云的 Qualcomm AI Hub 不同，Ultralytics QNN 导出完全在你的本地机器上通过单次 export(format="qnn", imgsz=640) 调用（分类使用 imgsz=224）运行。你无需注册、上传限制或排队时间，即可获得相同的 QNN/QAIRT 运行时目标（Snapdragon CPU、Adreno GPU 和 Hexagon NPU），并且它可以直接无缝接入标准的 YOLO 导出工作流。

导出的 *_qnn.onnx 文件是自包含的：它内嵌了 QNN 上下文二进制文件以及诸如类名、图像大小和任务等 ONNX 元数据。

QNN 模型的主要特点#

• 量化：模型使用 ONNX Runtime QNN QDQ 流程和校准数据集被量化为 16 位激活值和 INT8 权重，这是 Hexagon NPU 推荐的准确度/性能平衡。了解有关模型量化的更多信息。
• 完全本地编译：上下文二进制文件完全在你的主机上生成——无需 Qualcomm 帐户、API 令牌或云端上传。
• 全 Snapdragon 加速：通过统一的运行时在 Hexagon NPU (HTP)、Adreno GPU 或 CPU 上运行推理。
• 广泛的设备覆盖范围：针对广泛应用于手机、PC（Windows on Snapdragon）、汽车、XR 和嵌入式产品的 Snapdragon 平台。
• 预编译上下文二进制文件：交付上下文二进制文件可最大限度地减少设备上的图编译，从而降低目标设备上的模型加载延迟。
• 自包含输出：导出的 ONNX 文件包含预编译的 QNN 上下文二进制文件和元数据，便于直接部署。

性能测试#

Android 手机#

**硬件：**搭载 12 GB LPDDR5X 内存和 Android 16 / API 36 的 Xiaomi 17。其 3 nm Snapdragon 8 Elite Gen 5 (SM8850) 拥有 8 核高通 Oryon CPU（2 个最高 4.6 GHz 的超大核和 6 个最高 3.62 GHz 的性能核）、 Adreno GPU 以及 Hexagon NPU (HTP v81)。

• 速度值是单图突发延迟 —— 在 bus.jpg 上经过 3 次预热运行后的 15 次运行的平均值， 使用 Flutter plugin's 的 0.6.10 端侧基准测试 工具和标准化的 v0.6.6 资产进行测量。后端顺序在一次连续扫描中按任务轮换。 原生日志确认每一行 CPU 都使用了 LiteRT CPU/XNNPACK，每一行 GPU 都将完整图委托给了 LiteRT OpenCL (LITERT_CL)，每一行 NPU 都使用了 QNN Hexagon HTP 后端。
• 详细的基准测试记录位于 Flutter performance doc 中。
• 在 LiteRT integration 中比较其他 Android 设备，在 CoreML integration 中比较 Apple 设备。

运行 Windows 的 Snapdragon 笔记本电脑#

此历史扫描使用了预标准化的 v73 QNN 二进制文件；semantic 和 OBB 使用了 1024px 输入。它在一台拥有 32 GB 内存和 Windows 11 的联想 笔记本电脑上运行。其 Snapdragon X Elite (X1E78100) 拥有 12 核高通 Oryon CPU、Adreno GPU 和 Hexagon NPU (HTP v73)；未记录具体的联想型号。 此 Windows-on-Snapdragon 比较将大多数桌面开发者所采用的原生 PyTorch FP32 CPU 基准与 ONNX Runtime QNN Hexagon HTP 路径进行了对比。 每个单元格显示完整的 model.predict() 墙上时间，其下方附有报告的预处理/推理/后处理耗时； 总计可能包含这三个阶段之外的框架开销。CPU 数字是 PyTorch FP32 (torch==2.10.0+cpu)， NPU 数字是 ONNX Runtime QNN (onnxruntime-qnn==2.2.0，INT8 权重 / 16 位激活值)。

• 速度值是单图突发延迟 —— 在热状态稳定的设备上，围绕完整的 model.predict() 调用使用 time.perf_counter() 在 bus.jpg 上经过 10 次预热运行后的 100 次运行的平均值（ultralytics==8.4.67，Python 3.12.10）。
• Hexagon NPU 在 640-1024 px 任务上的运行速度大约比 PyTorch CPU 基准快 2-4 倍（检测任务约 3.4 倍），而在 224 px 分类任务上差距缩小至约 1.3 倍，这是因为固定的预处理开销在微小工作负载中占主导地位。

支持的任务#

Qualcomm QNN 导出支持所有七个 Ultralytics 任务。语义分割和深度估计仅在 YOLO26（唯一带有这些输出头的系列）中可用。

导出到 QNN：转换你的 YOLO 模型#

将 Ultralytics YOLO 模型导出为 QNN 格式，以便在高通硬件上部署。上下文二进制文件针对目标 Hexagon 张量处理器 (HTP) 架构或受支持的 SoC 进行定稿，你可以使用 name 参数来选择它 —— 这与在 RKNN export 中用于指定芯片的参数相同。

受支持的 HTP 目标#

通过 name（例如 name="73" 或 name="iq-8275"）传递目标架构或 SoC。支持情况由 HTP 目标决定，因此下面的 Snapdragon 行代表的是代表性平台，而非穷举所有 SoC 的完整列表。 Dragonwing 设备会单独列出。

Dragonwing IQ-615 无法使用 Ultralytics QNN 上下文二进制导出，因为 ONNX Runtime 未将其 v66 DSP 暴露为离线 HTP 目标。标准的 ONNX 导出仍然可以与板级 BSP 支持的 CPU 或 GPU 执行提供程序单独集成。

from ultralytics import YOLO

model = YOLO("best.pt")
model.export(format="qnn", name="iq-8275", imgsz=640)

安装#

要安装所需的软件包，请运行：

# Install the required package for YOLO
pip install ultralytics

onnxruntime-qnn 包（提供 ONNX Runtime QNN 执行提供程序并捆绑了 QAIRT 库）会在首次导出时自动安装。有关与安装过程相关的详细说明和最佳实践，请查阅我们的 Ultralytics Installation guide。如果在为 YOLO 安装所需包的过程中遇到任何困难，请参考我们的 Common Issues guide 获取解决方案和提示。

用法#

QNN 格式支持 Export、Predict 和 Validate 模式。推理和验证通过 ONNX Runtime 的 QNN 执行提供程序在高通 Snapdragon 硬件上运行（用于导出的同款 onnxruntime-qnn 包）。导出你的模型，然后在 Snapdragon 设备上加载导出的模型以运行推理或验证其准确度。

from ultralytics import YOLO

# Load a YOLO26 model
model = YOLO("yolo26n.pt")

# Export to Qualcomm QNN format (INT8, enforced automatically) for the default v73 HTP target
model.export(format="qnn", name="73", imgsz=640)  # use imgsz=224 for classification

from ultralytics import YOLO

# Load the exported QNN model (on a Snapdragon device with onnxruntime-qnn)
model = YOLO("yolo26n_qnn.onnx")

# Run inference
results = model("https://ultralytics.com/images/bus.jpg")

from ultralytics import YOLO

# Load the exported QNN model (on a Snapdragon device with onnxruntime-qnn)
model = YOLO("yolo26n_qnn.onnx")

# Validate accuracy on the COCO8 dataset
metrics = model.val(data="coco8.yaml")

导出参数#

有关导出过程的更多详细信息，请访问 Ultralytics 关于导出的文档页面。

输出结构#

成功导出后，将创建一个自包含的 ONNX 文件：

yolo26n_qnn.onnx 文件内嵌了 QNN 上下文二进制文件，并在 Snapdragon 设备上通过 QNN 执行提供程序由 ONNX Runtime 加载。它还在 ONNX metadata_props 中携带有诸如类名、图像大小和任务等模型元数据。

部署导出的 YOLO QNN 模型#

QNN 模型可在受支持的高通硬件上运行，这使得端侧模型部署变得十分简单。在安装了 onnxruntime-qnn 的兼容设备上，使用 Ultralytics API（yolo predict/yolo val，参见上方的 Usage）直接运行导出的模型 —— Ultralytics 通过 ONNX Runtime QNN Execution Provider 加载 HTP 上下文二进制文件。

对于自定义流水线，你还可以直接使用 ONNX Runtime 加载上下文二进制 ONNX。onnxruntime-qnn 是一个插件执行提供程序，因此请在运行时注册它：

import onnxruntime as ort
import onnxruntime_qnn as qnn_ep

# On the Snapdragon device, register the QNN plugin EP and select its device(s)
ort.register_execution_provider_library("QNNExecutionProvider", qnn_ep.get_library_path())
devices = [d for d in ort.get_ep_devices() if d.ep_name == "QNNExecutionProvider"]

options = ort.SessionOptions()
options.add_provider_for_devices(devices, {"backend_path": qnn_ep.get_qnn_htp_path()})
session = ort.InferenceSession("yolo26n_qnn.onnx", sess_options=options)
input_info = session.get_inputs()[0]
outputs = session.run(None, {input_info.name: input_tensor})  # input_tensor: float32 NHWC

由于 QNN 上下文二进制文件是预编译的，会话可以快速加载，而无需在设备上重新编译图。

Linux 和 Yocto BSP 要求#

目标板必须提供相互兼容的高通运行时和 BSP。对于 HTP 推理，这包括 ONNX Runtime QNN 执行提供程序、libQnnSystem.so、libQnnHtp.so、针对 IQ-8275 的 v75 HTP stub 和 skeleton 库、诸如 libcdsprpc.so 之类的 FastRPC 用户空间支持、DSP 固件以及相应的 FastRPC/内核驱动程序。skeleton 库必须能够通过 BSP 的 DSP 库路径被发现。

这些目标端组件来自板卡供应商的启用了 QAIRT/QNN 的 BSP；它们没有嵌入到导出的模型中。相反，GPU 执行需要 libQnnGpu.so 和匹配的 Adreno 用户空间驱动程序栈。Ultralytics format=qnn 的输出是 HTP 特定的上下文二进制文件，因此 GPU 或 CPU 部署应从标准的 ONNX 导出开始，而不是使用预编译的 *_qnn.onnx 文件。

推荐工作流程#

1. 使用 Ultralytics 训练模式训练你的模型
2. 在受支持的平台上使用 model.export(format="qnn", name="iq-8275", imgsz=640) 导出为 QNN 格式（分类请使用 imgsz=224）
3. 将导出的 *_qnn.onnx 文件部署到你的高通设备
4. 使用 ONNX Runtime 和带有 HTP 后端的 QNN Execution Provider 运行推理

实际应用场景#

在高通 Snapdragon 硬件上运行的 YOLO 模型非常适合广泛的边缘 AI 应用：

• 智能手机：在相机和相册应用中借助 NPU 加速实现实时的目标检测和场景理解。
• Windows on Snapdragon：在 Copilot+ PC 上实现设备端计算机视觉，无需卸载到云端。
• 汽车：在 Snapdragon Digital Chassis 平台上实现驾驶员监控、乘客检测和 ADAS 功能。
• XR 和可穿戴设备：为 AR/VR 头显和智能眼镜提供低功耗、低延迟的感知能力。
• 物联网和机器人：在基于 Snapdragon 的相机、无人机和嵌入式系统上实现高效的视觉推理。

总结#

在本指南中，你已学习了如何使用 ONNX Runtime QNN 执行提供程序在本地将 Ultralytics YOLO 模型导出为高通 QNN 格式。导出流水线将你的模型转换为 ONNX，然后将其在你的主机上编译为 QNN 上下文二进制文件 —— 无需高通账号或云端 —— 生成一个针对 Snapdragon CPU、Adreno GPU 和 Hexagon NPU 硬件通过 QNN/QAIRT 运行时进行了优化的 *_qnn.onnx 文件。

Ultralytics YOLO 与高通端侧 AI 技术栈的结合，为在广阔的 Snapdragon 生态系统中运行高级计算机视觉工作负载提供了有效的解决方案。

有关其他端侧和移动端部署目标，请参阅相关的 ONNX、CoreML、NCNN、LiteRT、ExecuTorch、RKNN、Sony IMX500 和 TensorRT 导出指南。若要在发布前比较格式，请使用 Benchmark mode。有关格式和选项的完整列表，请访问 Export mode 文档和集成指南页面。

常见问题解答#