此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 概述
  • 部署路径
  • 要求
  • OAK 应用程序配置
  • 准备 ONNX 模型
  • 使用静态形状
  • 检查运算符和数据类型
  • 在没有 CPU 回退的情况下进行验证
  • 通用示例
  • 编译上下文缓存
  • 性能比较
  • 限制
  • 示例
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

ONNX Runtime with QNN

最后更新
Supported on:RVC4

概述

ONNX Runtime 与 Qualcomm QNN 执行提供程序是 RVC4 设备的替代推理路径。 它允许独立的 OAK 应用程序使用标准 ONNX Runtime API 加载 .onnx 模型,同时 QNN 在 RVC4 Hexagon Tensor Processor (HTP) 上执行支持的操作。此路径仅在 RVC4 独立应用程序中可用。 它不适用于 RVC2 设备或在单独的主机上运行的应用程序。 应用程序会附带 ONNX 文件,当首次创建 ONNX Runtime 会话时,QNN 会为 HTP 编译该文件。典型用例包括:
  • 在 OAK 应用程序中从 Python 代码运行仅 ONNX 模型。
  • 加速创建 ONNX Runtime 会话的第三方库。
  • 在评估原生转换是否值得时,将模型保留为 ONNX 格式。
  • 与原生 DepthAI 神经网络一起运行辅助模型,例如文本编码器。

部署路径

以下所有四种路径都在 RVC4 设备上本地运行,但它们具有不同的集成和模型准备要求。
路径模型工件执行目标最适合
ONNX Runtime CPU.onnxRVC4 ARM CPU兼容性测试、调试和回退
ONNX Runtime QNN.onnx,在会话启动时创建编译的 QNN 上下文HTPONNX Runtime 集成和尚未转换为原生 DepthAI 部署的模型
原生 SNPE FP16转换后的 RVC4 模型,通常通过 NN Archive 提供HTP具有浮点精度的第一类 NeuralNetwork 节点集成
原生 SNPE INT8经过量化、转换的 RVC4 模型,具有代表性校准HTP当满足精度和转换要求时,吞吐量最高
QNN 路由在 OAK 应用程序进程中运行,并通过 ONNX Runtime 交换 NumPy 数组。 原生 SNPE 路由通过 dai.node.NeuralNetwork 运行,因此帧和推理消息仍然是 DepthAI 图的一部分。

要求

您需要:
  • 运行 Luxonis OS 1.40.0 或更高版本的基于 RVC4 的 OAK 设备。
  • 基于 luxonis/oakapp-base:<version>-onnxruntime 镜像的 独立 OAK 应用程序。
  • QNN/FastRPC 设备和 OS 提供的 NPU 运行时已挂载到应用程序容器中。
  • depthai-nodes,它提供了 onnx_qnn_session 助手。
  • 具有静态形状和 QNN HTP 后端支持的操作的 ONNX 图。
oakapp-base 的 ONNX Runtime 变体包含 onnxruntime、onnxruntime-qnn、QNN 库以及定位设备 NPU 运行时所需的环境。 使用 /entrypoint.sh,以便在 Python 应用程序启动之前配置此环境。

OAK 应用程序配置

以下 oakapp.toml 包含最小 Python 应用程序的 QNN 特定设置。 将基本镜像版本替换为为您的应用程序选择的版本。
Toml
1identifier = "com.example.onnx-qnn"
2app_version = "1.0.0"
3base_image = "luxonis/oakapp-base:1.4.0-onnxruntime"
4
5entrypoint = ["/entrypoint.sh", "python3.12", "-u", "/app/main.py"]
6
7prepare_container = [
8    { type = "COPY", source = "requirements.txt", target = "requirements.txt" },
9    { type = "RUN", command = "python3.12 -m pip install --no-cache-dir -r /app/requirements.txt" },
10]
11
12optional_devices = [
13    "/dev/fastrpc-cdsp",
14    "/dev/adsprpc-smd",
15    "/dev/dma_heap/qcom,system",
16    "/dev/dma_heap/system",
17]
18optional_mounts = [
19    "/opt/luxonis/npu-runtime:/opt/luxonis/npu-runtime:ro,rbind",
20]
21allowed_devices = [{ allow = true, access = "rw" }]
基本镜像已经提供了其兼容的 ONNX Runtime 包。 在安装其他依赖项时,避免间接替换 onnxruntime 或 onnxruntime-qnn;如果包更改了它们,请明确恢复所选基本镜像提供的版本。 有关完整的应用程序清单参考,请参阅 oakapp.toml 配置。

准备 ONNX 模型

QNN 比 ONNX Runtime CPU 执行提供程序具有更严格的图要求。 在 CPU 上工作的模型不一定完全符合 HTP 执行的条件。

使用静态形状

所有输入维度必须具有固定的正值;此路径不支持动态批处理、图像、序列和其他维度。 固定输入后,运行 ONNX 形状推断并验证输出也是静态的。 数据相关的输出形状或操作仍然可以阻止完整的 HTP 放置。例如,使用 ONNX Runtime 助手将模型输入固定为 NCHW 批大小 1:
Command Line
1python -m onnxruntime.tools.make_dynamic_shape_fixed \
2    --input_name images \
3    --input_shape 1,3,288,512 \
4    model.onnx model.fixed.onnx
如果应用程序需要多种形状,请为每种形状创建一个固定模型。 对于可变长度输入,一种实用的方法是定义一组小的静态桶,将每个输入填充到最近的桶,并为每个桶缓存编译的 QNN 上下文。

检查运算符和数据类型

QNN 支持 ONNX 运算符的子集,并且支持的数据类型和属性因运算符和后端而异。 不支持 Loop 和 If 等控制流运算符。 请检查 ONNX Runtime QNN 支持的运算符列表,以了解您的基本镜像使用的运行时版本。当图未完全支持时:
  • 使用兼容的 ONNX opset 和静态轴重新导出模型。
  • 折叠常量并简化冗余图操作。
  • 用支持的等效运算符替换或分解不支持的运算符。
  • 将不兼容的预处理或后处理(例如数据相关的选择)从 ONNX 图中移出并放入应用程序代码中。
  • 在重写模型时,保留模型的输入名称、顺序、布局、数据类型、归一化和输出约定。
始终使用代表性输入将准备好的模型与原始模型进行比较。 启用 FP16 执行或更改图可能会引入数值差异。

在没有 CPU 回退的情况下进行验证

QNN 助手默认使用 CPU 回退,以便在 HTP 不可用或图的一部分不受支持时应用程序可以继续运行。 这可能会隐藏部署问题,并使会话在某些或所有操作实际上在 CPU 上运行时显得加速。在模型资格认证期间,设置两个严格选项:
Python
1session = onnx_qnn_session(
2    "model.fixed.onnx",
3    fallback_to_cpu=False,
4    runtime_fallback="raise",
5)
仅当降级操作对应用程序可接受时才恢复 CPU 回退。

通用示例

以下示例使用 DepthAI 捕获相机帧,准备 1x3x288x512 float32 张量,并通过 QNN 调用 ONNX 模型。 其大小调整、RGB 转换、归一化和输出处理是占位符;请根据您的模型约定进行匹配。
Python
1import cv2
2import depthai as dai
3import numpy as np
4
5from depthai_nodes.runtime import onnx_qnn_session
6
7
8MODEL_PATH = "/app/model.fixed.onnx"
9MODEL_SIZE = (512, 288)  # 宽度,高度
10
11# 助手注册 QNN 执行提供程序,选择 HTP 后端,
12# 为 FP32 图启用 FP16 执行,并缓存编译的上下文。
13session = onnx_qnn_session(
14    MODEL_PATH,
15    fp16=True,
16    cache_context=True,
17    performance_mode="burst",
18    fallback_to_cpu=False,
19    runtime_fallback="raise",
20)
21model_input = session.get_inputs()[0]
22
23with dai.Pipeline() as pipeline:
24    camera = pipeline.create(dai.node.Camera).build()
25    frame_queue = camera.requestOutput(size=MODEL_SIZE).createOutputQueue()
26
27    pipeline.start()
28
29    while pipeline.isRunning():
30        frame_bgr = frame_queue.get().getCvFrame()
31
32        # 仅示例预处理。遵循模型的输入约定。
33        frame_rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB)
34        input_tensor = frame_rgb.astype(np.float32) / 255.0
35        input_tensor = np.transpose(input_tensor, (2, 0, 1))[None, ...]
36
37        outputs = session.run(None, {model_input.name: input_tensor})
38
39        # 根据模型约定解码或使用输出。
40        print([output.shape for output in outputs])
完整的助手实现及其配置参数可在 onnx_qnn.py 中找到。

编译上下文缓存

QNN 图编译发生在第一次会话创建期间,不属于推理延迟。 当 cache_context=True 时,onnx_qnn_session 会在 ONNX 模型旁边的 .oak4ort_cache 目录中存储一个 EPContext 模型,前提是该位置可写。 设置 OAK4ORT_CACHE_DIR 以选择不同的可写缓存目录。缓存特定于模型文件、ONNX Runtime 和 QNN 包版本以及提供程序选项。 更改其中任何一个都可能触发新的编译。 如果热启动时间在应用程序替换或容器重新创建时很重要,请将缓存保留在持久存储上。

性能比较

该表比较了 OAK4-D 上使用 模型动物园中的模型进行单线程推理的平均 FPS。
模型ONNX CPUONNX QNN FP16SNPE FP16SNPE INT8
luxonis/deeplab-v3-plus:512x2882.2367.6677.15217.17
luxonis/depth-anything-v2:vit-s-336x2522.3672.6872.61143.55
luxonis/paddle-text-recognition:320x4836.81137.6988.88239.53
luxonis/yoloe-v8-l:640x6400.3725.6127.6778.86
luxonis/yolov6-nano:r2-coco-512x28817.58442.16436.26557.96
luxonis/yolov8-large-pose-estimation:coco-640x3520.8453.0755.71149.10
在这些模型中,QNN 的吞吐量大约是单线程 ONNX Runtime CPU 执行的 3.7 倍到 69.4 倍。 QNN FP16 与原生 SNPE FP16 相当,而 SNPE INT8 路径始终是最快的,但由于量化可能会导致精度下降。

限制

  • **仅限 RVC4 独立版:**所需的 QNN 库、HTP 设备和 FastRPC 传输由 RVC4 设备和应用程序容器环境提供。
  • **静态图形状:**每个部署的形状都需要单独准备的模型,并且可能需要单独编译的上下文。
  • **部分 ONNX 支持:**不支持的运算符、属性或数据类型需要图更改或 CPU 回退。
  • **启动成本:**第一个会话可能会花费大量时间编译图;缓存上下文并相应地设计启动健康检查。
  • **与 DepthAI 图分离:**预处理、后处理、调度和 NumPy 数据移动由应用程序管理,而不是内置的 NeuralNetwork 节点。
  • **回退可能掩盖性能:**CPU 回退提高了兼容性,但可能使提供程序选择和延迟不那么明显。首先在严格模式下进行验证。
  • 必须验证精度:fp16=True 允许 QNN 在 HTP 上以 FP16 精度运行 FP32 图。量化的 QDQ 模型保持其量化行为。测试这两种选项的应用程序级精度。

示例

以下 OAK 示例使用此部署路径: