# ONNX Runtime with QNN

## 概述

ONNX Runtime 与 Qualcomm QNN 执行提供程序是 [RVC4](/hardware/platform/rvc/rvc4.md) 设备的替代推理路径。 它允许独立的 OAK
应用程序使用标准 ONNX Runtime API 加载 `.onnx` 模型，同时 QNN 在 RVC4 Hexagon Tensor Processor (HTP) 上执行支持的操作。

此路径仅在 RVC4 独立应用程序中可用。 它不适用于 RVC2 设备或在单独的主机上运行的应用程序。 应用程序会附带 ONNX 文件，当首次创建 ONNX Runtime 会话时，QNN 会为 HTP 编译该文件。

> **何时使用此路径**
> 当您的应用程序已经使用 ONNX 模型或集成需要 ONNX Runtime API，并且您希望在不先将每个模型转换为原生 RVC4 工件的情况下获得硬件加速时，请使用 ONNX Runtime 与 QNN。 对于与 DepthAI 管道最直接的集成，转换为内置 `NeuralNetwork` 节点的模型仍然是主要的部署路径。

典型用例包括：

 * 在 OAK 应用程序中从 Python 代码运行仅 ONNX 模型。
 * 加速创建 ONNX Runtime 会话的第三方库。
 * 在评估原生转换是否值得时，将模型保留为 ONNX 格式。
 * 与原生 DepthAI 神经网络一起运行辅助模型，例如文本编码器。

## 部署路径

以下所有四种路径都在 RVC4 设备上本地运行，但它们具有不同的集成和模型准备要求。

| 路径 | 模型工件 | 执行目标 | 最适合 |
| --- | --- | --- | --- |
| ONNX Runtime CPU | `.onnx` | RVC4 ARM CPU | 兼容性测试、调试和回退 |
| ONNX Runtime QNN | `.onnx`，在会话启动时创建编译的 QNN 上下文 | HTP | ONNX 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 应用程序](/software-v3/oak-apps.md)。
 * QNN/FastRPC 设备和 OS 提供的 NPU 运行时已挂载到应用程序容器中。
 * `depthai-nodes`，它提供了 [`onnx_qnn_session`](https://github.com/luxonis/depthai-nodes/blob/main/depthai_nodes/runtime/onnx_qnn.py)
   助手。
 * 具有静态形状和 QNN HTP 后端支持的操作的 ONNX 图。

`oakapp-base` 的 ONNX Runtime 变体包含 `onnxruntime`、`onnxruntime-qnn`、QNN 库以及定位设备 NPU 运行时所需的环境。 使用 `/entrypoint.sh`，以便在 Python
应用程序启动之前配置此环境。

### OAK 应用程序配置

以下 `oakapp.toml` 包含最小 Python 应用程序的 QNN 特定设置。 将基本镜像版本替换为为您的应用程序选择的版本。

```toml
identifier = "com.example.onnx-qnn"
app_version = "1.0.0"
base_image = "luxonis/oakapp-base:1.4.0-onnxruntime"

entrypoint = ["/entrypoint.sh", "python3.12", "-u", "/app/main.py"]

prepare_container = [
    { type = "COPY", source = "requirements.txt", target = "requirements.txt" },
    { type = "RUN", command = "python3.12 -m pip install --no-cache-dir -r /app/requirements.txt" },
]

optional_devices = [
    "/dev/fastrpc-cdsp",
    "/dev/adsprpc-smd",
    "/dev/dma_heap/qcom,system",
    "/dev/dma_heap/system",
]
optional_mounts = [
    "/opt/luxonis/npu-runtime:/opt/luxonis/npu-runtime:ro,rbind",
]
allowed_devices = [{ allow = true, access = "rw" }]
```

基本镜像已经提供了其兼容的 ONNX Runtime 包。 在安装其他依赖项时，避免间接替换 `onnxruntime` 或 `onnxruntime-qnn`；如果包更改了它们，请明确恢复所选基本镜像提供的版本。 有关完整的应用程序清单参考，请参阅
[`oakapp.toml` 配置](/software-v3/oak-apps/configuration.md)。

## 准备 ONNX 模型

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

### 使用静态形状

所有输入维度必须具有固定的正值；此路径不支持动态批处理、图像、序列和其他维度。 固定输入后，运行 ONNX 形状推断并验证输出也是静态的。 数据相关的输出形状或操作仍然可以阻止完整的 HTP 放置。

例如，使用 ONNX Runtime 助手将模型输入固定为 NCHW 批大小 1：

```bash
python -m onnxruntime.tools.make_dynamic_shape_fixed \
    --input_name images \
    --input_shape 1,3,288,512 \
    model.onnx model.fixed.onnx
```

如果应用程序需要多种形状，请为每种形状创建一个固定模型。 对于可变长度输入，一种实用的方法是定义一组小的静态桶，将每个输入填充到最近的桶，并为每个桶缓存编译的 QNN 上下文。

### 检查运算符和数据类型

QNN 支持 ONNX 运算符的子集，并且支持的数据类型和属性因运算符和后端而异。 不支持 `Loop` 和 `If` 等控制流运算符。 请检查 ONNX Runtime [QNN
支持的运算符列表](https://onnxruntime.ai/docs/execution-providers/QNN-ExecutionProvider.html#supported-onnx-operators)，以了解您的基本镜像使用的运行时版本。

当图未完全支持时：

 * 使用兼容的 ONNX opset 和静态轴重新导出模型。
 * 折叠常量并简化冗余图操作。
 * 用支持的等效运算符替换或分解不支持的运算符。
 * 将不兼容的预处理或后处理（例如数据相关的选择）从 ONNX 图中移出并放入应用程序代码中。
 * 在重写模型时，保留模型的输入名称、顺序、布局、数据类型、归一化和输出约定。

始终使用代表性输入将准备好的模型与原始模型进行比较。 启用 FP16 执行或更改图可能会引入数值差异。

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

QNN 助手默认使用 CPU 回退，以便在 HTP 不可用或图的一部分不受支持时应用程序可以继续运行。 这可能会隐藏部署问题，并使会话在某些或所有操作实际上在 CPU 上运行时显得加速。

在模型资格认证期间，设置两个严格选项：

```python
session = onnx_qnn_session(
    "model.fixed.onnx",
    fallback_to_cpu=False,
    runtime_fallback="raise",
)
```

仅当降级操作对应用程序可接受时才恢复 CPU 回退。

## 通用示例

以下示例使用 DepthAI 捕获相机帧，准备 `1x3x288x512` float32 张量，并通过 QNN 调用 ONNX 模型。 其大小调整、RGB 转换、归一化和输出处理是占位符；请根据您的模型约定进行匹配。

```python
import cv2
import depthai as dai
import numpy as np

from depthai_nodes.runtime import onnx_qnn_session

MODEL_PATH = "/app/model.fixed.onnx"
MODEL_SIZE = (512, 288)  # 宽度，高度

# 助手注册 QNN 执行提供程序，选择 HTP 后端，
# 为 FP32 图启用 FP16 执行，并缓存编译的上下文。
session = onnx_qnn_session(
    MODEL_PATH,
    fp16=True,
    cache_context=True,
    performance_mode="burst",
    fallback_to_cpu=False,
    runtime_fallback="raise",
)
model_input = session.get_inputs()[0]

with dai.Pipeline() as pipeline:
    camera = pipeline.create(dai.node.Camera).build()
    frame_queue = camera.requestOutput(size=MODEL_SIZE).createOutputQueue()

    pipeline.start()

    while pipeline.isRunning():
        frame_bgr = frame_queue.get().getCvFrame()

        # 仅示例预处理。遵循模型的输入约定。
        frame_rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB)
        input_tensor = frame_rgb.astype(np.float32) / 255.0
        input_tensor = np.transpose(input_tensor, (2, 0, 1))[None, ...]

        outputs = session.run(None, {model_input.name: input_tensor})

        # 根据模型约定解码或使用输出。
        print([output.shape for output in outputs])
```

完整的助手实现及其配置参数可在 [`onnx_qnn.py`](https://github.com/luxonis/depthai-nodes/blob/main/depthai_nodes/runtime/onnx_qnn.py) 中找到。

### 编译上下文缓存

QNN 图编译发生在第一次会话创建期间，不属于推理延迟。 当 `cache_context=True` 时，`onnx_qnn_session` 会在 ONNX 模型旁边的 `.oak4ort_cache` 目录中存储一个 EPContext
模型，前提是该位置可写。 设置 `OAK4ORT_CACHE_DIR` 以选择不同的可写缓存目录。

缓存特定于模型文件、ONNX Runtime 和 QNN 包版本以及提供程序选项。 更改其中任何一个都可能触发新的编译。 如果热启动时间在应用程序替换或容器重新创建时很重要，请将缓存保留在持久存储上。

## 性能比较

> **首次启动可能很慢**
> 会话创建已从报告的推理延迟中排除。在某些情况下，这可能需要几分钟。编译的上下文缓存允许后续会话创建跳过 HTP 图编译。

该表比较了 OAK4-D 上使用 [模型动物园](/software-v3/ai-inference/model-source/zoo.md)中的模型进行单线程推理的平均 FPS。

| 模型 | ONNX CPU | ONNX QNN FP16 | SNPE FP16 | SNPE INT8 |
| --- | --- | --- | --- | --- |
| `luxonis/deeplab-v3-plus:512x288` | 2.23 | 67.66 | 77.15 | 217.17 |
| `luxonis/depth-anything-v2:vit-s-336x252` | 2.36 | 72.68 | 72.61 | 143.55 |
| `luxonis/paddle-text-recognition:320x48` | 36.81 | 137.69 | 88.88 | 239.53 |
| `luxonis/yoloe-v8-l:640x640` | 0.37 | 25.61 | 27.67 | 78.86 |
| `luxonis/yolov6-nano:r2-coco-512x288` | 17.58 | 442.16 | 436.26 | 557.96 |
| `luxonis/yolov8-large-pose-estimation:coco-640x352` | 0.84 | 53.07 | 55.71 | 149.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 示例使用此部署路径：

 * [ONNXRuntime Track Anything](https://github.com/luxonis/oak-examples/tree/main/apps/onnxruntime-track-anything) 使用 MobileSAM 和
   TrackAnything 模型，并通过 ONNX Runtime 和 QNN 后端进行加速。
 * [YOLO World](https://github.com/luxonis/oak-examples/tree/main/neural-networks/object-detection/yolo-world) 在创建 QNN
   会话之前修复了文本编码器的动态维度。
 * [Open-Vocabulary Object
   Detection](https://github.com/luxonis/oak-examples/tree/main/custom-frontend/open-vocabulary-object-detection) 为提示编码器使用静态输入桶。
 * [Data Collection](https://github.com/luxonis/oak-examples/tree/main/apps/data-collection) 在独立模式下加速 ONNX 提示编码工作流。
 * [Roboflow Workflow](https://github.com/luxonis/oak-examples/tree/main/integrations/roboflow-workflow) 通过 QNN 路由兼容的 ONNX Runtime
   会话，并公开严格和仅 CPU 调试模式。
