常见问题解答（FAQ）

如何使用调试日志来调试示例应用？

在运行 AI 示例应用或 gst-launch-1.0 时，如需排查执行失败问题，请启用调试日志。要在 GStreamer 示例应用中启用调试日志，请使用 GST_DEBUG 环境变量设置调试级别。GST_DEBUG 环境变量控制调试输出的详细程度。您可以将其设置为不同的级别，例如：

0：无（不输出调试信息）
1：ERROR（记录所有致命错误）
2：WARNING（记录所有警告）
3：FIXME（记录未完成的代码路径）
4：INFO（记录信息性消息）
5：DEBUG（记录一般调试消息）
6：LOG（记录所有日志消息）
7：TRACE（记录跟踪消息）
9：MEMDUMP（记录内存转储）

例如，要将调试级别设置为 ERROR，可以在终端中使用以下命令：

export GST_DEBUG=2

如果您想筛选特定类别的调试日志，可以在 GST_DEBUG 变量中指定它们。例如，要为 ML 推理插件和 FPS 启用调试日志，可以使用：

export GST_DEBUG=qtiml*:fps*:5

哪些常见问题会影响 AI 示例应用的快速开箱即用体验？

AI 示例应用的开箱即用体验设计得非常快捷。然而，以下问题是阻碍快速开箱体验的最常见问题。

加载模型文件失败

0:00:00.042355885 4275 0x5579b9f760 ERROR ml-tflite-engine ml-tflite-engine-c-api.cc:578:gst_ml_tflite_engine_new: Failed to load model file '$HOME/Downloads/qimsdk_samples/models/googlenet_quantized.tflite'!

当模型文件缺失或格式不正确时会出现此问题。将模型文件复制到正确的路径，并确保在模型转换/量化时和目标设备上使用相同的 SDK 版本。

反序列化标签失败
0:00:00.543394063 4676 0x55aca865e0 ERROR mlmodule gstmlmodule.c:301:gst_ml_parse_labels: Failed to deserialize labels!
当指定路径下的标签文件不存在时会出现此问题。确保标签文件已复制到设备上且指定的路径正确。
设置模块选项失败
0:00:00.55129740 4958 0x5561019180 WARN qtimlvclassification mlvclassification.c:986:gst_ml_video_classification_set_caps:<mlvideoclassification0> error: Failed to set module options!
在为 LiteRT/Qualcomm AI Engine Direct 用例设置常量时会出现此问题。请参阅 Discover SDKs → IM SDKs 了解如何正确读取和设置模型常量。

如何测量 AI 示例应用的性能分析数据？

预处理时间在将输入送入 AI 推理插件之前，必须对输入进行预处理（包括归一化、缩放和颜色反转）。该任务由预处理插件 qtimlvconverter 负责。您可以通过执行以下命令来测量预处理时间：
export GST_DEBUG=qtimlvconverter:6
预处理时间会显示在日志中。
LOG qtimlvconverter mlconverter.c:1830:gst_ml_video_converter_transform:<qtimlvconverter> Conversion took 2.743 ms
模型推理时间 Qualcomm Intelligent Multimedia SDK 支持三个 AI 推理插件，分别使用 Qualcomm Neural Processing SDK、LiteRT 和 Qualcomm AI Engine Direct 框架。
- qtimlsnpe
- qtimltflite
- qtimlqnn
这些插件可以在多种硬件上运行推理，例如 CPU、GPU 和 HTP。要确定硬件上的 AI 推理时间，请使用以下命令。
export GST_DEBUG=qtiml*:6
LOG qtimlvtflite mltflite.c:561:gst_ml_tflite_transform:<qtimltflite> Execute took 3.445 ms LOG qtimlvtflite mltflite.c:561:gst_ml_tflite_transform:<qtimltflite> Execute took 3.555 ms
后处理时间 AI 推理插件的输出由后处理插件处理。这些插件获取 AI 模型的结果并生成可以叠加在输入流上或用于进一步计算的元素。例如，分类用例的文本框、分割用例的分割掩码等。要测量这些插件的处理时间，请使用以下命令。
export GST_DEBUG=qtimlv*:6
后处理时间会显示在日志中。以下以 qtimlvclassification 插件为例。
LOG qtimlvclassification mlvclassification.c:1068:gst_ml_video_classification_transform:<qtimlvclassification> Categorization tookExecute took 1.962 ms

如何测量用例的端到端 FPS？

要测量 GStreamer 流水线中的每秒帧数（FPS），请使用 fpsdisplaysink 元素。该元素可以将当前帧率和平均帧率以叠加形式显示在视频上，或打印到控制台。示例应用使用 fpsdisplaysink 插件将流水线的 FPS 直接显示在 HDMI 显示器上。

在参考应用中用自定义模型替换现有模型的最简单方法是什么？

确保您为示例应用使用了正确的模型和标签文件。在相应的示例应用配置文件中提供模型和标签文件路径。示例应用将使用指定位置的模型和标签文件。有关更多信息，请参阅 Discover SDKs → IM SDKs。

用户在参考应用中替换了另一个受支持的模型

如何调试性能和精度问题？要测量模型的性能和精度问题，请使用 AI SDK 工具并遵循以下步骤：

性能测量：
使用 SDK 基准测试工具。例如，如果您使用的是 Qualcomm Neural Processing Engine SDK，请使用 snpe-bench-py
精度调试：
- AI Hub 模型：
  1. 确保您使用的是 AI Hub 中的最新模型。
  2. 为所选模型正确填写常量。有关更多信息，请参阅 Discover SDKs → IM SDKs。
  3. 如需就 AI Hub 模型精度问题获得进一步支持，请在 Qualcomm AI Hub slack 上报告您的问题。
- 自定义模型
  1. 模型量化是精度下降的常见原因。确保您在模型量化时使用了正确的数据集。用户应使用与实际部署环境近似的部分数据集进行训练后量化（PTQ）。为使 PTQ 获得良好效果，用户需要提供足够数量的数据来量化模型，例如大约 25-30 张 RAW 图像。
  2. 尝试不同的模型精度，例如 W8A16 和 W16A16，看看模型精度是否有所提升。
  3. 使用 AIMET 进行训练后量化（PTQ）和量化感知训练（QAT）等高级量化技术。有关更多详细信息，请参阅 AIMET 文档。

使用 AI SDK 进行模型量化的最佳实践有哪些？

准备校准数据使用与模型在生产环境中将遇到的数据高度匹配的代表性校准数据。这有助于准确确定量化所需的缩放因子和零点。
选择合适的量化方法
- 训练后量化（PTQ）：这种方法更简单、更快，适用于可以接受轻微精度损失的模型。它将预训练的浮点模型转换为量化模型，无需重新训练。
- 量化感知训练（QAT）：这种方法在训练模型时就考虑量化，有助于保持更高的精度。它更复杂，但对精度要求较高的模型很有益。
有关详细步骤，请参阅 AIMET 文档。

LiteRT 模型是否需要转换为 DLC 才能进行 NPU 加速？

您不一定要将 LiteRT 模型转换为 DLC 才能在 NPU 上加速。 Qualcomm 的 AI SDK 支持使用 LiteRT delegate 直接在 NPU 上运行 LiteRT 模型。这意味着您无需将 LiteRT 模型转换为 DLC 格式即可利用 NPU 能力。

PyTorch、ONNX 和 TensorFlow 模型最快的部署路径是什么？

先将模型转换为 ONNX，再转换为 DLC，通常是最快且最灵活的部署方式。

用户如何知道模型是否正在 NPU 上运行？

请使用 Qualcomm 提供的以下工具：

Qualcomm profiler
Sysmon
如果您有 Hexagon SDK 的访问权限，请参阅位于 <Hexagon_sdk_path>/<version>/tools/sysmon_app.html 的 sysmon 文档

用户如何在不同的硬件核心上运行模型？

AI SDK 工具和 API 提供了选择运行时（CPU、GPU 或 DSP）的选项。您可以通过命令行参数选择合适的运行时，或使用特定的 C/C++ API。有关更多详细信息，请参阅 snpe-net-run。AI 示例应用默认使用 DSP 运行时。您可以通过示例应用配置更改运行时。例如，在 gst-ai-object-detection 示例应用中，修改 config_detection.json 文件中的 runtime 参数。运行时：

"cpu"
"gpu"
"dsp"

如果使用 AI SDK 进行模型转换失败，该如何处理？

请联系 Qualcomm 支持论坛获取支持。

如何调试量化模型在 CPU 和 NPU 上精度不佳的问题？

可能存在与模型量化相关的问题，请参阅用户替换模型常见问题以获取模型量化方面的指导

如何调试在 NPU 上精度不准确的量化模型？

qnn-net-run 的 --debug 选项会转储逐层数值，因此您可以比较 CPU 与 NPU 推理的差异。

如何调试示例应用没有 HDMI 输出的问题？

请按照显示调试来调试 HDMI 显示问题。

是否可以使用 HDMI 电视运行示例应用？

在大多数情况下可以正常工作。如果不行，请改用 HDMI 显示器。

如何检查 AI 示例应用的硬件运行时？

许多 GStreamer 示例应用支持在多种运行时（CPU、GPU 和 DSP）上进行推理。要确定应用将使用哪种运行时进行推理，请观察日志。

CPU

Running app with model: /usr/models/inception_v3_quantized.tflite and labels: /usr/labels/classification.labels
Using CPU Delegate
Adding all elements to the pipeline...

GPU

Running app with model: /usr/models/inception_v3_quantized.tflite and labels: /usr/labels/classification.labels
Using GPU Delegate
Adding all elements to the pipeline...

DSP

Running app with model: /usr/models/inception_v3_quantized.tflite and labels: /usr/labels/classification.labels
Using DSP Delegate
Adding all elements to the pipeline...

什么是 devtool 完整性检查（sanity check）错误？如何调试？

有时您可能会看到 devtool 显示完整性检查错误。确保您对主机拥有 sudo 权限。如果错误仍然存在，请执行以下变通方法：

更新权限

umask a+rx

禁用 BitBake 完整性检查

在 $ESDK_ROOT/layers/poky/meta/conf/sanity.conf 文件中禁用 BitBake 完整性检查。

BB_MIN_VERSION = "1.53.1"
SANITY_ABIFILE = "${TMPDIR}/abi_version"
SANITY_VERSION ?= "1"
LOCALCONF_VERSION ?= "2"
LAYER_CONF_VERSION ?= "7"
SITE_CONF_VERSION ?= "1"

#INHERIT += "sanity"

如何在目标设备上旁加载（sideload）Qualcomm Neural Processing Engine SDK

准备目标设备

进入目标设备 shell 并运行以下命令：

ssh root@<ip-address of target device>

mount -o rw,remount /

exit

将 SDK 文件复制到目标设备

进入主机上的 QAIRT SDK 根文件夹并运行以下命令：以下命令适用于 QCS6490。

对于 QCS8275：将 hexagon-v68 替换为 hexagon-v75
对于 QCS9075：将 hexagon-v68 替换为 hexagon-v73
对于 IQ-X5121：将 hexagon-v68 替换为 hexagon-v73
对于 IQ-X7181：将 hexagon-v68 替换为 hexagon-v73

scp lib/aarch64-oe-linux-gcc11.2/* root@<target-ip-address>:/usr/lib/

scp lib/hexagon-v68/unsigned/* root@<target-ip-address>:/usr/lib/rfsa/adsp/

scp bin/aarch64-oe-linux-gcc11.2/* root@<target-ip-address>:/usr/bin/

ssh root@<target-ip-address>

chmod -R 777 /usr/bin/

验证 SDK 版本

验证新的 SDK 版本：

qairt-net-run --version

有关下载 Qualcomm AI Runtime SDK 的更多信息，请参阅 Qualcomm package manager。

如何使用 SNPE 对 QIM SDK 预处理后的张量运行推理

生成预处理的原始张量

从视频文件生成预处理的原始张量。

创建用于保存原始张量的文件夹

创建一个用于保存原始张量的文件夹。

mkdir -p /opt/frames/

使用 GStreamer 转储原始张量

运行 GStreamer 流水线，将原始张量转储到该文件夹。

gst-launch-1.0 -v -e filesrc location=$HOME/Downloads/qimsdk_samples/media/video.mp4  ! qtdemux ! queue ! h264parse ! v4l2h264dec capture-io-mode=4 output-io-mode=4 ! queue ! qtimlvconverter ! queue ! neural-network/tensors,type=FLOAT32,rate=30000/1000,dimensions="<<1,520,520,3>>" ! queue ! multifilesink location="/opt/frames/frame_%03d.raw"

请根据您使用的视频和模型，按需调整 rate（输入视频的 FPS）和 dimensions（模型的输入尺寸）。

使用 SNPE 或 QNN 运行推理

使用 SNPE 或 QNN 运行推理。

创建输入列表

创建一个包含原始文件绝对路径的 input_list.txt 文件，如下所示。对 input_list.txt 文件中列出的每个文件执行推理。input_list.txt 中的示例内容

/opt/frames/frame_000.raw
/opt/frames/frame_001.raw

在 HTP 后端上运行模型

在 HTP 后端上运行 SNPE DLC 或 QNN 模型。

SNPE
QNN

snpe-net-run --container <model>.dlc --input_list input_list.txt --output_dir output_htp --use_dsp

qnn-net-run --model <model>.so --backend libQnnHtp.so --input_list input_list.txt --output_dir output_htp

有关更多详细信息，请参阅使用 Neural Processing Engine 或 AI Engine Direct 部署模型。

简介

架构

关键文档

技术

系统

发布说明

更多支持

简介

架构

关键文档

技术

系统

发布说明

​更多支持

更多支持