常见问题解答（FAQ）

1. 如何使用调试日志调试示例应用？ 在运行 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
   
2. 哪些常见问题会妨碍 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 了解正确读取和设置模型常量的步骤。
3. 如何测量 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
     
4. 如何测量用例的端到端 FPS？ 要在 GStreamer 管线中测量每秒帧数（FPS），请使用 fpsdisplaysink 元素。 该元素可以将当前帧率和平均帧率以叠加方式显示在视频上，或打印到控制台。 示例应用使用 fpsdisplaysink 插件将管线的 FPS 直接显示在 HDMI 显示器上。
5. 在参考应用中用自定义模型替换现有模型的最简单方法是什么？ 请确保为示例应用使用正确的模型和标签文件。 在相应的示例应用配置文件中提供模型和标签文件路径。 示例应用将使用指定位置的模型和标签文件。 更多信息请参阅 Discover SDKs → IM SDKs。
6. 用户在参考应用中替换了另一个受支持的模型（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 文档。
          
          
7. 使用 AI SDK 进行模型量化的最佳实践是什么？
   • 准备校准数据 使用与模型在生产环境中将遇到的数据高度相似的代表性校准数据。 这有助于准确确定量化的缩放因子和零点。
   • 选择正确的量化方法
     • 训练后量化（PTQ）：此方法更简单、更快速。适用于可以接受轻微准确性损失的模型。它将预训练的浮点模型转换为量化模型，无需重新训练。
     • 量化感知训练（QAT）：此方法在训练模型时考虑量化因素，有助于保持更高的准确性。它更复杂，但对准确性至关重要的模型很有益。
     详细步骤请参阅 AIMET 文档。
8. AI SDK 提供了将 LiteRT 转换为 DLC 的工具。用户必须将 LiteRT 模型转换为 DLC 吗？还是 LiteRT 模型可以直接在 NPU 上加速？ 您不一定需要将 LiteRT 模型转换为 DLC 才能在 NPU 上加速。 Qualcomm 的 AI SDK 支持使用 LiteRT delegate 直接在 NPU 上运行 LiteRT 模型。 这意味着您可以利用 NPU 的能力，而无需将 LiteRT 模型转换为 DLC 格式。
9. AI SDK 提供了将 PyTorch、Onnx 和 Tensorflow 模型转换为 DLC 的工具。哪种是最快的部署路径？ 先将模型转换为 ONNX，再转换为 DLC，通常是最快且最灵活的部署方式。
10. 用户如何知道模型是否运行在 NPU 上？ 使用 Qualcomm 提供的以下工具：
    1. Qualcomm profiler
    2. Sysmon
       如果您有 Hexagon SDK 的访问权限，请参阅位于 <Hexagon_sdk_path>/<version>/tools/sysmon_app.html 的 sysmon 文档
11. 用户如何获得 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 参数。 Runtime：
    • "cpu"
    • "gpu"
    • "dsp"
12. 如果使用 AI SDK 进行模型转换失败，该如何处理？ 请联系 Qualcomm 支持论坛获取支持。
13. 自定义浮点模型在 CPU 上准确性良好，但量化模型在 CPU 和 NPU 上准确性都很差。如何调试？ 可能存在与模型量化相关的问题，请参阅用户替换模型FAQ 获取模型量化的指导。
14. 自定义量化模型在 CPU 上按预期运行，但相同的模型在 NPU 上运行不准确。如何调试？ qnn-net-run 的 --debug 选项会转储逐层数值，因此您可以对比 CPU 和 NPU 推理的结果。
15. 运行示例应用时，HDMI 屏幕上没有输出。如何调试？ 请按照显示调试来调试 HDMI 显示问题。
16. 是否可以使用 HDMI 电视代替 HDMI 显示器来运行示例应用？ 大多数情况下可以正常工作。如果不行，请改用 HDMI 显示器。
17. 如何查看 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...
      
18. 什么是 devtool 完整性检查（sanity check）错误？如何调试？ 有时您可能会看到 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"
       
19. 在目标设备上旁加载（sideload）Qualcomm Neural Processing Engine SDK 的步骤。
    1. 进入目标设备 shell 并运行以下命令：
       ssh root@<ip-address of target device>
       
       mount -o rw,remount /
       
       exit
       
    2. 在主机上进入 QAIRT SDK 根文件夹并运行以下命令： 以下命令适用于 QCS6490。
       • 对于 QCS8275：将 hexagon-v68 替换为 hexagon-v75
       • 对于 QCS9075：将 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/
       
    3. 验证新的 SDK 版本：
       snpe-net-run --version
       
    有关下载 Qualcomm AI Runtime SDK 的更多信息，请参阅 Qualcomm package manager。
20. 从 QIM SDK 获取预处理张量并使用 SNPE 运行推理的调试步骤。
    1. 从视频文件生成预处理的原始张量。
       1. 创建用于保存原始张量的文件夹。
       mkdir -p /opt/frames/
       
       1. 运行 GStreamer 管线，将原始张量转储到该文件夹。
       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 运行推理。 i. 创建一个 input_list.txt 文件，其中包含原始文件的绝对路径，如下所示。 推理会针对 input_list.txt 文件中列出的每个文件执行。 input_list.txt 的示例内容
       /opt/frames/frame_000.raw
       /opt/frames/frame_001.raw
       
       1. 在 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 部署模型。

​

更多支持