常见问题解答(FAQ) - Qualcomm Dragonwing Documentation

如何使用调试日志调试示例应用? 要在运行 AI 示例应用或 gst-launch-1.0 时排查执行失败,请启用调试日志。要在 GStreamer 示例应用中启用调试日志,请使用 GST_DEBUG 环境变量设置调试级别。 GST_DEBUG 环境变量控制调试输出的详细程度。您可以将其设置为不同的级别,例如:
- 0:None(无调试信息)
- 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 '/etc/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、ONNX 和 Qualcomm AI Engine Direct 框架。
  - qtimlsnpe
  - qtimltflite
  - qtimlqnn
  - qtimlonnx
  这些插件可以在各种硬件上运行推理,例如 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 插件直接在 HDMI 显示器上显示流水线的 FPS。
在参考应用中用自定义模型替换现有模型最简单的方法是什么? 请确保您为示例应用使用了正确的模型和标签文件。在相应的示例应用配置文件中提供模型和标签文件路径。示例应用将从指定位置使用模型和标签文件。有关更多信息,请参阅 Discover SDKs → IM SDKs。
用户在参考应用中替换了另一个受支持的模型(IMSDK 支持)。如何调试性能和精度问题? 要测量模型的性能和精度问题,请使用 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 文档。
AI SDK 提供了将 LiteRT 转换为 DLC 的工具。用户是必须将 LiteRT 模型转换为 DLC,还是可以在 NPU 上直接加速 LiteRT 模型? 您不一定需要将 LiteRT 模型转换为 DLC 才能在 NPU 上对其进行加速。 Qualcomm 的 AI SDK 支持使用 LiteRT 委托(delegate)直接在 NPU 上运行 LiteRT 模型。这意味着您可以无需将 LiteRT 模型转换为 DLC 格式,就能利用 NPU 的能力。
AI SDK 提供了将 PyTorch、Onnx 和 Tensorflow 模型转换为 DLC 的工具。其中哪种是最快的部署路径? 先将模型转换为 ONNX,再转换为 DLC,通常是最快、最灵活的部署方法。
用户如何知道模型是否在 NPU 上运行? 使用以下 Qualcomm 提供的工具:
1. Qualcomm profiler
2. Sysmon
  如果您有权访问 Hexagon SDK,请参阅位于以下路径的 sysmon 文档: <Hexagon_sdk_path>/<version>/tools/sysmon_app.html
用户如何获得 Snapdragon 平台异构 AI 引擎的优势?用户如何在不同的硬件核心(GPU、NPU 等)上运行不同的 AI 模型? 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 上精度良好,但量化模型在 CPU 和 NPU 上精度都很差。如何调试? 这可能与模型量化有关,请参阅用户替换模型常见问题解答,获取有关模型量化的指导
自定义量化模型在 CPU 上按预期运行,但同一模型在 NPU 上运行不准确。如何调试? qnn-net-run 的 --debug 选项会转储每层的值,以便您可以比较 CPU 和 NPU 推理的差异。
运行示例应用时,HDMI 屏幕上没有输出。如何调试? 请按照显示调试的说明,调试 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 完整性检查错误?如何调试? 有时,您可能会看到 devtool 显示完整性检查错误。请确保您对主机具有 sudo 访问权限。如果错误仍然存在,请执行以下解决方法:
1
更新权限
umask a+rx
2
在 $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"

在目标设备上侧载 Qualcomm Neural Processing Engine SDK 的步骤。

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

ssh ubuntu@<ip-address of target device>

sudo mount -o rw,remount /

exit

在主机上进入 QAIRT SDK 根文件夹并运行以下命令

以下命令适用于 QCS6490。

对于 QCS8275:将 hexagon-v68 替换为 hexagon-v75
对于 QCS9075:将 hexagon-v68 替换为 hexagon-v73

scp lib/aarch64-oe-linux-gcc11.2/* ubuntu@<target-ip-address>:/home/ubuntu/
ssh ubuntu@<ip-address>
cp /home/ubuntu/* /usr/lib/
rm *
exit

scp lib/hexagon-v68/unsigned/* ubuntu@<target-ip-address>:/home/ubuntu/
ssh ubuntu@<ip-address>
cp /home/ubuntu/* /usr/lib/rfsa/adsp/
rm *
exit

scp bin/aarch64-oe-linux-gcc11.2/* ubuntu@<target-ip-address>:/home/ubuntu/
ssh ubuntu@<ip-address>
cp /home/ubuntu/* /usr/bin/
exit

ssh ubuntu@<target-ip-address>

chmod -R 777 /usr/bin/

验证新的 SDK 版本

snpe-net-run --version

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

从 QIM SDK 获取预处理张量并使用 SNPE 运行推理的调试步骤。
1
从视频文件生成预处理的 raw 张量
1
创建一个文件夹来保存 raw 张量
mkdir -p /opt/frames/
2
运行 GStreamer 流水线,将 raw 张量转储到该文件夹
gst-launch-1.0 -v -e filesrc location=/etc/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(模型的输入维度)。
2
使用 SNPE 或 QNN 运行推理
1
创建一个 input_list.txt 文件,包含指向 raw 文件的绝对路径
推理在 input_list.txt 文件中列出的每个文件上执行。input_list.txt 中的示例内容
/opt/frames/frame_000.raw /opt/frames/frame_001.raw
2
在 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 部署模型。

进一步支持

请在 Qualcomm 支持论坛上提问。不熟悉本文档中使用的某个术语或缩略语?请参阅术语表。

​进一步支持

进一步支持