# 故障排除和常见问题解答 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（记录内存dump） 例如，要将调试级别设置为错误，您可以在终端中使用以下命令： export GST_DEBUG=2 Copy to clipboard 如果要过滤特定类别的调试日志，可以在 `GST_DEBUG` 变量中指定。例如，要启用 ML 推理插件和 FPS 的调试日志，您可以使用： export GST_DEBUG=qtiml*:fps*:5 Copy to clipboard 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'! Copy to clipboard 当模型文件丢失或格式不正确时，就会出现此问题。 将模型文件复制到正确的路径，并确保模型转换/量化和目标设备使用相同的 SDK 版本。 - 反序列化标签失败 0:00:00.543394063 4676 0x55aca865e0 ERROR mlmodule gstmlmodule.c:301:gst_ml_parse_labels: Failed to deserialize labels! Copy to clipboard 当指定路径下的标签文件不存在时，就会出现这种情况。请确保标签文件复制到设备，且指定的路径正确。 - 模块选项设置失败 0:00:00.55129740 4958 0x5561019180 WARN qtimlvclassification mlvclassification.c:986:gst_ml_video_classification_set_caps: error: Failed to set module options! Copy to clipboard 当为 LiteRT/Qualcomm AI 引擎直接用例设置常量时，会发生这种情况。请参阅 [在应用程序中集成 AI Hub 模型](https://docs.qualcomm.com/doc/80-70020-15BY/topic/integrate-ai-hub-models.html) 了解正确读取和设置模型常量的步骤。 3. 如何衡量 AI 示例应用程序分析？ - 预处理时间 在将输入提供给 AI 推理插件之前，必须对输入进行预处理（包括标准化、重新缩放和颜色反转）。该任务由预处理插件 `qtimlvconverter` 管理。可以通过执行以下命令来测量预处理时间： export GST_DEBUG=qtimlvconverter:6 Copy to clipboard 预处理时间显示在日志中。 LOG qtimlvconverter mlconverter.c:1830:gst\_ml\_video\_converter\_transform:<qtimlvconverter> Conversion took 2.743 ms - 模型推理时间 Qualcomm Intelligent Multimedia SDK支持三个AI推理插件，这三个AI推理插件分别利用Qualcomm Intelligent Multimedia SDK、LiteRT和Qualcomm AI Engine Direct框架。 - qtimlsnpe - qtimltflite - qtimlqnn 这些插件可以在各种硬件上运行推理，例如 CPU、GPU 和 HTP。要确定硬件上的 AI 推理时间，请使用以下命令。 export GST_DEBUG=qtiml*:6 Copy to clipboard 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 推理插件的输出由后处理插件处理。这些插件获取人工智能模型的结果并生成可以覆盖在输入流上或用于进一步计算的元素。例如，`qtimlvclassification` 的文本框，`qtimlvsegmentation` 的分割掩码等。 要测定这些插件的处理时间，请使用以下命令。 .. code-block: export GST_DEBUG=qtimlv*:6 Copy to clipboard 后处理时间显示在日志中。下面以 `qtimlvclassification` 插件为例进行说明。 LOG qtimlvclassification mlvclassification.c:1068:gst\_ml\_video\_classification\_transform:<qtimlvclassification> Categorization tookExecute took 1.962 ms 4. 如何测量用例的端到端 FPS？ 要测量 GStreamer 流水线中的每秒帧数 (FPS)，请使用 `fpsdisplaysink` 元素。该元素可以将当前和平均帧速率显示为视频上的叠加或通过将其打印到控制台来显示。 示例应用程序使用 `fpsdisplaysink` 插件直接在 HDMI 显示器上显示流水线的 FPS。 5. 在参考应用程序中，用自定义模型替换现有模型的最简单方法是什么？ 确保您对示例应用程序使用了正确的模型和标签文件。 在相应的示例应用程序配置文件中提供模型和标签文件路径。 示例应用程序将使用来自指定位置的模型和标签文件。 如需了解更多信息，请参阅 [在应用程序中集成 AI Hub 模型](https://docs.qualcomm.com/doc/80-70020-15BY/topic/integrate-ai-hub-models.html)。 6. 用户在参考应用程序中替换了另一个支持的模型（支持 IMSDK）。如何调试性能和准确率问题？ 要测量模型的性能和准确率问题，请使用 AI SDK工具，您可以按照以下步骤操作： - 性能测量： 使用 SDK 基准测试工具。例如，如果您使用 Qualcomm Neural Processing Engine SDK，请使用 [snpe-bench-py](https://docs.qualcomm.com/bundle/publicresource/topics/80-63442-2/tools.html#snpe-bench-py) - 准确率调试器： - AI Hub 模型： 1. 确保您使用的是 AI Hub 的最新模型。 2. 正确填充所选模型的常量。如需了解更多信息，请参阅 [在应用程序中集成 AI Hub 模型](https://docs.qualcomm.com/doc/80-70020-15BY/topic/integrate-ai-hub-models.html)。 3. 如需要 AI Hub 模型准确率问题的进一步支持，请在 [Qualcomm AI Hub slack](https://qualcomm-ai-hub.slack.com/join/shared_invite/zt-2ur7psfuu-CygEMlDFjoHTbPKIRCVYuQ%23/shared-invite/email) 上提交您的问题。 - 自定义模型 1. 模型量化是精度下降的常见原因。确保您使用正确的数据集进行模型量化。预计用户将使用数据集的一部分，它是训练后量化（PTQ）的实际部署环境的粗略估算。为了使 PTQ 获得良好的效果，用户需要输入相当数量的数据来量化模型，例如大约 25-30 个 RAW 镜像。 2. 尝试不同的模型精度，例如W8A16和W16A16，看看模型精度是否有提高。 3. 使用 AIMET 进行训练后量化 (PTQ) 和量化感知训练 (QAT) 技术进行高级量化。如需了解更多信息，请参阅 [AIMET 文档](https://quic.github.io/aimet-pages/releases/latest/user_guide/index.html)。 7. 使用 AI SDK 进行模型量化的最佳实践是什么？ - 准备校准数据 使用那些与模型在生产中遇到的数据非常匹配的代表性校准数据。这有助于准确确定量化的缩放因子和零点 - 选择正确的量化方法 - 训练后量化（PTQ）：这种方法更简单，更快速。适用于可以接受轻微准确率损失的模型。它将预训练的浮点模型转换为量化模型，无需重新训练。 - 量化感知训练 (QAT)：这种方法涉及在训练模型时考虑量化，这有助于保持更高的准确率。这会更复杂一些，但对于那些对准确性要求至关重要的模型来说是有益的。 如需了解更多信息，请参阅 [AIMET 文档](https://quic.github.io/aimet-pages/releases/latest/user_guide/index.html)。 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](https://docs.qualcomm.com/bundle/publicresource/topics/80-54323-2/command-line-interface.html) 2. Sysmon（链接待定） 11. 用户如何获取 Snapdragon 平台异构 AI 引擎的益处？用户如何在不同的硬件核心上运行不同的 AI 模型？（GPU、NPU等） AI SDK 工具和 API 提供了选择 runtime（CPU、GPU 或 DSP）的选项。您可以选择适当的 runtime 作为命令行参数或使用特定的 C/C++ API。如需了解更多信息，请参阅 [snpe-net-run](https://docs.qualcomm.com/bundle/publicresource/topics/80-63442-2/tools.html#snpe-net-run)。 默认情况下，AI 示例应用程序使用 DSP runtime。您可以使用示例应用程序配置更改 runtime。 例如，在 `gst-ai-object-detection` 示例应用程序中修改 `config_detection.json` 文件中的 `runtime` 参数。 Runtime： - `"cpu"` - `"gpu"` - `"dsp"` 12. 如果使用 AI SDK 进行模型转换失败，该怎么办？ 联系 [Qualcomm Support Forums](https://mysupport.qualcomm.com/supportforums/s/) 来获取支持。 13. 自定义浮点模型在 CPU 上提供了良好的准确率，但量化模型准确率在 CPU 和 NPU 上均较差。如何调试？ 可能存在与模型量化相关的问题，请参阅[用户更换模型](https://docs.qualcomm.com/doc/80-70020-15BY/topic/troubleshooting.html#user-replaced-model) FAQ 来获取模型量化指导。 14. 自定义量化模型在 CPU 上按预期运行，但同一模型在 NPU 上运行不准确。如何调试？ 待定 15. 运行示例应用程序时，HDMI 屏幕上无输出。如何调试？ 按照[显示调试](https://docs.qualcomm.com/bundle/publicresource/topics/80-70020-20/bring-up.html#debug-video)的说明来调试 HDMI 显示问题。 16. 是否可以使用 HDMI 电视代替 HDMI 显示器来运行示例应用程序？ 大多数情况下它可以工作，如果不工作，请使用 HDMI 显示器。 17. 如何检查 AI 示例应用程序的硬件 runtime？ 许多 GStreamer 示例应用程序支持在各种 runtime（CPU、GPU 和 DSP）上进行推理。要确定应用程序将使用哪个 runtime 进行推理，请查看日志。 - 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 健全性检查错误？如何调试它们？ 有时，您可能会看到 devtool 显示健全性检查错误。 确保您有主机的 sudo 访问权限。如果错误仍然存​在，请尝试以下解决方法： 1. 更新权限。 umask a+rx Copy to clipboard 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" Copy to clipboard 19. 在目标设备上侧载 Snapdragon Neural Processing SDK 引擎的步骤。 1. 进入目标设备 shell 并运行以下命令： ssh root@ Copy to clipboard mount -o rw,remount /usr Copy to clipboard exit Copy to clipboard 2. 进入主机上的 SNPE SDK 根文件夹并运行以下命令： 以下命令适用于 QCS6490。 - 对于 QCS8275：将 `hexagon-v68` 替换为 `hexagon-v75` - 对于 QCS9075：将 `hexagon-v68` 替换为 `hexagon-v73` scp lib/aarch64-oe-linux-gcc11.2/* root@:/usr/lib/ Copy to clipboard scp lib/hexagon-v68/unsigned/* root@:/usr/lib/rfsa/adsp/ Copy to clipboard scp bin/aarch64-oe-linux-gcc11.2/* root@:/usr/bin/ Copy to clipboard ssh root@ Copy to clipboard chmod -R 777 /usr/bin/ Copy to clipboard 3. 验证新的 SDK 版本： snpe-net-run --version Copy to clipboard 如需了解下载 Qualcomm AI Runtime SDK 的更多信息，请参阅 [Qualcomm Package Manager](https://docs.qualcomm.com/doc/80-70020-15BY/topic/qairt-install.html#qairt-qpm)。 20. 调试步骤：从 QIM SDK 获取预处理张量并使用 SNPE 进行推理。 1. 从视频文件生成预处理 raw 张量。 1. 创建一个文件夹来保存 raw 张量。 mkdir -p /opt/frames/ Copy to clipboard 2. 启用显示器。 export XDG_RUNTIME_DIR=/dev/socket/weston && export WAYLAND_DISPLAY=wayland-1 Copy to clipboard 3. 运行 GStreamer pipeline 将 raw 张量 dump 到该文件夹。 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" Copy to clipboard Note 根据所使用的视频和模型调整速率（输入视频的 FPS）和尺寸（模型的输入尺寸）。 2. 使用 SNPE 或 QNN 运行推理。 1. 创建一个 `input_list.txt` 文件，其中包含 raw 文件的绝对路径，如下所示如下。 对 `input_list.txt` 文件中列出的每个文件执行推理。 `input_list.txt` 中的示例内容 /opt/frames/frame_000.raw /opt/frames/frame_001.raw Copy to clipboard 2. 在 HTP 后端运行 SNPE DLC 或 QNN 模型。 Tab SNPE Tab QNN snpe-net-run --container .dlc --input_list input_list.txt --output_dir output_htp --use_dsp Copy to clipboard qnn-net-run --model .so --backend libQnnHtp.so --input_list input_list.txt --output_dir output_htp Copy to clipboard 如需了解更多信息，请参阅使用 [Neural Processing Engine](https://docs.qualcomm.com/doc/80-70020-15BY/topic/run-models.html#snpe-run) 或 [AI Engine Direct](https://docs.qualcomm.com/doc/80-70020-15BY/topic/run-models.html#qnn-run) 部署模型。 ## 进一步支持 在 [Qualcomm support forum](https://mysupport.qualcomm.com/supportforums/s/) 上提出您的问题。 Last Published: Oct 12, 2025 [Previous Topic 使用超分辨率对图像进行放大](https://docs.qualcomm.com/bundle/publicresource/80-70020-15BY/topics/super-resolution.md) [Next Topic 模型移植最佳实践](https://docs.qualcomm.com/bundle/publicresource/80-70020-15BY/topics/appx-export-yolov8.md)