qtimlqnn 仅在 qcom-multimedia-proprietary-image 中可用
有关 QLI 镜像的更多信息，请参阅 Qualcomm Linux 发行版

概述

qtimlqnn 是一个 GStreamer 推理元素，使用 Qualcomm AI Engine Direct（QNN）运行时执行神经网络模型。该元素完全以张量模式运行：它在 sink pad 上接收输入张量，并根据模型声明的输入和输出规范在 source pad 上生成输出张量。 qtimlqnn 设计用于运行为 QNN 运行时准备的模型，通常为 **QNN 上下文二进制文件（context binary）**形式。要使用此元素，必须先使用 Qualcomm AI Runtime（QAIRT）SDK 将模型导出为与 QNN 兼容的格式。更多详细信息，请参阅 QAIRT 文档。该元素仅限于模型执行。它不执行预处理、张量重塑、批处理、布局转换或特定于模型的后处理。这些功能应由流水线中的相邻元素处理。 qtimlqnn 支持多种 QNN 执行后端，包括 CPU、GPU 和 NPU 目标。这使得相同的流水线结构可以部署到不同的硬件配置，并针对不同的性能、延迟和功耗需求进行调优。该元素面向实时和嵌入式 AI 流水线，其中推理是更大的模块化处理流程中的一个阶段。

主要职责

qtimlqnn 负责：

加载并执行 QNN 模型构件，例如模型库（.so）或缓存的二进制文件（.bin）
接收来自上游元素的预格式化输入张量
生成与模型输出签名匹配的输出张量
与相邻流水线元素协商张量数据类型和维度
传播下游元素所需的张量元数据
通过 GstMLBufferPool 管理 DMA 后备缓冲区，以减少不必要的内存复制

在实际使用中，qtimlqnn 充当流水线中的推理阶段，而张量准备和结果解释则由外部处理。

示例流水线

下载所需文件

文件	下载	保存为
Yolov8 检测 W8A8 模型	从 Qualcomm AI Hub 导出	`yolov8_det_w8a8.bin`
检测标签	yolov8.json	`yolov8.json`
示例视频	输入视频	`Draw_1080p_180s_30FPS.mp4`

将文件复制到设备

# Replace $HOME to the appropriate device path before running the commands.
# For QLI:    /root
# For Ubuntu: /home/ubuntu
# Modify this based on your platform and ensure files are copied to the correct location on the device.
# Run from your host machine — replace <user> and <device-ip>

ssh <user>@<device-ip> "mkdir -p $HOME/{models,labels,media,media/output}"
scp yolov8_det_w8a8.bin          <user>@<device-ip>:$HOME/models/
scp yolov8.json                  <user>@<device-ip>:$HOME/labels/
scp Draw_1080p_180s_30FPS.mp4    <user>@<device-ip>:$HOME/media/

连接到设备

# Run from your host machine — replace <user> and <device-ip>
ssh <user>@<device-ip>

设置环境变量

在设备上运行以下命令

mkdir -p $HOME/{models,labels,media,media/output}
export MODEL_NAME=yolov8_det_w8a8.bin
export LABELS_NAME=yolov8.json
export SRC_VIDEO_NAME=Draw_1080p_180s_30FPS.mp4

运行流水线

gst-launch-1.0 -e --gst-debug=2 \
filesrc location=$HOME/media/$SRC_VIDEO_NAME ! qtdemux ! h264parse ! \
v4l2h264dec capture-io-mode=4 output-io-mode=4 ! video/x-raw,format=NV12 ! queue ! \
tee name=t ! queue ! qtimetamux name=obj_mux ! qtivoverlay ! waylandsink fullscreen=true sync=false \
t. ! queue ! qtimlvconverter ! queue ! \
qtimlqnn model=$HOME/models/$MODEL_NAME backend=/usr/lib/libQnnHtp.so tensors="<boxes,scores,class_idx>" ! queue ! \
qtimlpostprocess module=yolov8 labels=$HOME/labels/$LABELS_NAME settings="{\"confidence\": 51.0}" ! text/x-raw ! queue ! obj_mux.

层次结构

GObject
   GstObject
      GstElement
         GstBaseTransform
            qtimlqnn

Pad 模板

sink

能力
`neural-network/tensors`	`format: { INT8, UINT8, INT16, UINT16, INT32, UINT32, FLOAT16, FLOAT32 }`
可用性：Always
方向：sink

src

能力
`neural-network/tensors`	`format: { INT8, UINT8, INT16, UINT16, INT32, UINT32, FLOAT16, FLOAT32 }`
可用性：Always
方向：source

元素属性

属性	描述
`backend`	QNN 后端库的路径。选择用于推理的执行后端。根据所使用的库，支持的后端包括 CPU、HTP 或 NPU、GPU 以及 DSP 实现。 `Type: String` `Default: "/usr/lib/libQnnCpu.so"` `Flags: readable/writable`
`backend-device-id`	后端设备选择器。依赖于平台，用于某些 DSP 或 HTP 变体以选择特定的硬件实例。 `Type: Unsigned Integer` `Default: 0` `Flags: readable/writable`
`model`	QNN 模型文件的路径。该属性为必填项，且必须引用有效的 `.so` 模型或缓存的 `.bin` 文件。 `Type: String` `Default: NULL` `Flags: readable/writable`
`system`	QNN 运行时初始化所需的 QNN 系统库的路径。 `Type: String` `Default: "/usr/lib/libQnnSystem.so"` `Flags: readable/writable`
`tensors`	输出张量过滤器。设置后，仅在 source pad 上发出指定名称的输出张量。为空时，发出所有模型输出。 `Type: GstValueArray of type gchararray` `Default: "< >"` `Flags: readable/writable`

输入与输出行为

输入张量

qtimlqnn 暴露单个 sink pad，但同时支持单输入和多输入模型。对于多输入模型，所有所需张量以张量集的形式通过同一个 sink pad 传递。输入张量必须在到达 qtimlqnn 之前完全准备好。预期的张量布局、形状、数据类型和批量大小由以下因素决定：

QNN 模型输入签名
与上游元素的 caps 协商

典型的上游元素包括：

qtimlvconverter — 用于缩放、颜色转换、归一化和量化（如需要）

qtimlqnn 不会修改、重塑、批处理或重新解释传入的张量。它按接收到的原样将其传递给 QNN 运行时。

输出张量

qtimlqnn 暴露单个 source pad，并生成符合模型声明的输出签名的输出张量。完全支持具有多个输出张量的模型，所有输出会在 source pad 上一起发出。支持的输出行为包括：

单张量和多张量输出
任意张量形状和秩，包括批量维度和深度维度
量化和浮点张量类型
使用 tensors 属性选择性地发出输出张量

生成的输出张量供下游后处理阶段使用，后者负责解码特定于模型的结果，例如分类输出、检测结果、分割掩码、关键点数据以及其他结构化推理输出。

支持的数据类型

qtimlqnn 支持 QNN 运行时和所选执行后端提供的张量数据类型，具体取决于与相邻元素的 caps 协商。支持的数据类型包括：

INT8
UINT8
INT16
UINT16
INT32
UINT32
FLOAT16
FLOAT32

除了运行时、所选后端以及协商的流水线 caps 所要求的限制之外，该元素不会施加额外的数据类型限制。

后端

QNN 后端定义了运行模型所使用的硬件目标。后端使 qtimlqnn 能够将推理从默认的 CPU 解释器卸载到经过优化的硬件加速器。通过 backend 属性选择后端，它控制 QNN 运行时在推理期间如何分派模型操作。

NPU — libQnnHtp.so

在 AI 加速器（NPU）上运行模型。

后端：Qualcomm AI 加速器 / NPU
使用场景：如果可用则为首选后端。对量化模型具有最佳的性能和能效。
附加配置：设置 backend=libQnnHtp.so；对于多设备平台，可选设置 backend-device-id

GPU — libQnnGpu.so

通过 QNN GPU 后端运行受支持的操作。

后端：GPU
使用场景：浮点模型以及受益于 GPU 并行性的工作负载。
附加配置：设置 backend=/usr/lib/libQnnGpu.so

CPU — libQnnCpu.so

在默认的 QNN CPU 后端上运行模型。

后端：CPU
使用场景：参考执行、调试、启动验证（bring-up）或没有硬件加速的系统。
附加配置：无需

运行时内存行为与 GAP 处理

QNN 内存模型

qtimlqnn 在 QNN 运行时的内存模型内运行。该元素通过 GstMLBufferPool 使用 DMA 缓冲区，以最大限度地减少内存复制，并尽可能保持零拷贝传输。 QNN 使用运行时管理的内存来分配：

输入张量
中间激活张量
输出张量

元素在模型加载时发现输入/输出张量元数据（数量、形状、类型），并相应地配置缓冲池。

GAP 缓冲区处理

qtimlqnn 支持 GAP 感知，能够正确处理标记了 GST_BUFFER_FLAG_GAP 的输入缓冲区。当收到 GAP 缓冲区时，元素跳过推理并将缓冲区向下游转发。这在保持时序和同步的同时，明确表明该时间戳没有可用的有效推理输入。 GAP 缓冲区常见于条件式 AI 流水线，例如级联工作流，其中只有当前面的阶段产生有效的感兴趣区域时，后续推理阶段才会运行。

用法

实时摄像头流上的单阶段 AI 推理（HTP）

本示例演示了使用带 HTP 后端的单个 qtimlqnn 实例，在实时摄像头流上进行实时推理。推理结果作为 MLMeta 附加到每个 GstBuffer，使下游元素可以直接从帧中访问同步的元数据。叠加阶段随后使用此元数据在显示或进一步处理之前渲染边界框、标签或关键点等注释。

下载所需文件

文件	下载	保存为
Yolov8 检测 W8A8 模型	从 Qualcomm AI Hub 导出	`yolov8_det_w8a8.bin`
检测标签	yolov8.json	`yolov8.json`

将文件复制到设备

# Run from your host machine — replace <user> and <device-ip>
ssh <user>@<device-ip> "mkdir -p $HOME/{models,labels}"
scp yolov8_det_w8a8.bin   <user>@<device-ip>:$HOME/models/
scp yolov8.json           <user>@<device-ip>:$HOME/labels/

连接到设备

# Run from your host machine — replace <user> and <device-ip>
ssh <user>@<device-ip>

设置环境变量

在设备上运行以下命令

mkdir -p $HOME/{models,labels}
export MODEL_NAME=yolov8_det_w8a8.bin
export LABELS_NAME=yolov8.json

运行流水线

Run the pipeline

gst-launch-1.0 -e --gst-debug=2 \
qticamsrc name=camsrc ! video/x-raw,format=NV12,width=1920,height=1080,framerate=30/1 ! queue ! \
tee name=t ! queue ! qtimetamux name=obj_mux ! qtivoverlay ! waylandsink fullscreen=true sync=false \
t. ! queue ! qtimlvconverter ! queue ! \
qtimlqnn model=$HOME/models/$MODEL_NAME backend=/usr/lib/libQnnHtp.so tensors="<boxes,scores,class_idx>" ! queue ! \
qtimlpostprocess module=yolov8 labels=$HOME/labels/$LABELS_NAME settings="{\"confidence\": 51.0}" ! text/x-raw ! queue ! obj_mux.

实时摄像头流上的单阶段 AI 推理（GPU）

本示例演示了相同的单阶段推理工作流，但使用 GPU 后端而非 HTP。适用于浮点模型或受益于 GPU 并行性的工作负载。

下载所需文件

文件	下载	保存为
Yolov8 检测浮点模型	从 Qualcomm AI Hub 导出	`yolov8_det_float.bin`
检测标签	yolov8.json	`yolov8.json`

将文件复制到设备

# Run from your host machine — replace <user> and <device-ip>
ssh <user>@<device-ip> "mkdir -p $HOME/{models,labels}"
scp yolov8_det_float.bin   <user>@<device-ip>:$HOME/models/
scp yolov8.json            <user>@<device-ip>:$HOME/labels/

连接到设备

# Run from your host machine — replace <user> and <device-ip>
ssh <user>@<device-ip>

设置环境变量

在设备上运行以下命令

mkdir -p $HOME/{models,labels}
export MODEL_NAME=yolov8_det_float.bin
export LABELS_NAME=yolov8.json

运行流水线

Run the pipeline

gst-launch-1.0 -e --gst-debug=2 \
qticamsrc name=camsrc ! video/x-raw,format=NV12,width=1920,height=1080,framerate=30/1 ! queue ! \
tee name=t ! queue ! qtimetamux name=obj_mux ! qtivoverlay ! waylandsink fullscreen=true sync=false \
t. ! queue ! qtimlvconverter ! queue ! \
qtimlqnn model=$HOME/models/$MODEL_NAME backend=/usr/lib/libQnnGpu.so tensors="<boxes,scores,class_idx>" ! queue ! \
qtimlpostprocess module=yolov8 labels=$HOME/labels/$LABELS_NAME settings="{\"confidence\": 51.0}" ! text/x-raw ! queue ! obj_mux.

Introduction

Architecture

Key Documents

Technologies

System

Release Notes

qtimlqnn

概述

主要职责

示例流水线

层次结构

Pad 模板

sink

src

元素属性

输入与输出行为

输入张量

输出张量

支持的数据类型

后端

NPU — libQnnHtp.so

GPU — libQnnGpu.so

CPU — libQnnCpu.so

运行时内存行为与 GAP 处理

QNN 内存模型

GAP 缓冲区处理

用法

实时摄像头流上的单阶段 AI 推理（HTP）

实时摄像头流上的单阶段 AI 推理（GPU）

​概述

​主要职责

​示例流水线

​层次结构

​Pad 模板

​sink

​src

​元素属性

​输入与输出行为

​输入张量

​输出张量

​支持的数据类型

​后端

​NPU — libQnnHtp.so

​GPU — libQnnGpu.so

​CPU — libQnnCpu.so

​运行时内存行为与 GAP 处理

​QNN 内存模型

​GAP 缓冲区处理

​用法

​实时摄像头流上的单阶段 AI 推理（HTP）

​实时摄像头流上的单阶段 AI 推理（GPU）

概述

主要职责

示例流水线

层次结构

Pad 模板

sink

src

元素属性

输入与输出行为

输入张量

输出张量

支持的数据类型

后端

NPU — libQnnHtp.so

GPU — libQnnGpu.so

CPU — libQnnCpu.so

运行时内存行为与 GAP 处理

QNN 内存模型

GAP 缓冲区处理

用法

实时摄像头流上的单阶段 AI 推理（HTP）

实时摄像头流上的单阶段 AI 推理（GPU）