> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 常见问题解答（FAQ）

> 解答在 Qualcomm Dragonwing IoT 平台上运行 AI 示例应用、调试、性能分析、模型量化以及硬件运行时相关的常见问题。

<Steps>
  <Step title="如何使用调试日志来调试示例应用？">
    在运行 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，可以在终端中使用以下命令：

    ```shell theme={null}
    export GST_DEBUG=2
    ```

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

    ```shell theme={null}
    export GST_DEBUG=qtiml*:fps*:5
    ```
  </Step>

  <Step title="哪些常见问题会影响 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](https://imsdkdocs.qualcomm.com) 了解如何正确读取和设置模型常量。
  </Step>

  <Step title="如何测量 AI 示例应用的性能分析数据？">
    * 预处理时间

      在将输入送入 AI 推理插件之前，必须对输入进行预处理（包括归一化、缩放和颜色反转）。
      该任务由预处理插件 `qtimlvconverter` 负责。您可以通过执行以下命令来测量预处理时间：

      ```shell theme={null}
      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 模型的结果并生成可以叠加在输入流上或用于进一步计算的元素。
      例如，分类用例的文本框、分割用例的分割掩码等。

      要测量这些插件的处理时间，请使用以下命令。

      ```shell theme={null}
      export GST_DEBUG=qtimlv*:6
      ```

      后处理时间会显示在日志中。以下以 `qtimlvclassification` 插件为例。

      ```
      LOG    qtimlvclassification mlvclassification.c:1068:gst_ml_video_classification_transform:<qtimlvclassification> Categorization tookExecute took 1.962 ms
      ```
  </Step>

  <Step title="如何测量用例的端到端 FPS？">
    要测量 GStreamer 流水线中的每秒帧数（FPS），请使用 `fpsdisplaysink` 元素。
    该元素可以将当前帧率和平均帧率以叠加形式显示在视频上，或打印到控制台。

    示例应用使用 `fpsdisplaysink` 插件将流水线的 FPS 直接显示在 HDMI 显示器上。
  </Step>

  <Step title="在参考应用中用自定义模型替换现有模型的最简单方法是什么？">
    确保您为示例应用使用了正确的模型和标签文件。

    在相应的示例应用配置文件中提供模型和标签文件路径。

    示例应用将使用指定位置的模型和标签文件。

    有关更多信息，请参阅 [Discover SDKs → IM SDKs](https://imsdkdocs.qualcomm.com)。
  </Step>

  <Step title="用户在参考应用中替换了另一个受支持的模型">
    <a id="user-replaced-model" />

    如何调试性能和精度问题？

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

    * 性能测量：<br />
      使用 SDK 基准测试工具。例如，如果您使用的是 Qualcomm Neural Processing Engine SDK，请使用 [snpe-bench-py](https://docs.qualcomm.com/doc/80-63442-10/topic/SNPE_general_tools.html#snpe_bench-py)

    * 精度调试：
      * AI Hub 模型：<br />
        1. 确保您使用的是 AI Hub 中的最新模型。<br />
        2. 为所选模型正确填写常量。有关更多信息，请参阅 [Discover SDKs → IM SDKs](https://imsdkdocs.qualcomm.com)。<br />
        3. 如需就 AI Hub 模型精度问题获得进一步支持，请在 [Qualcomm AI Hub slack](https://qualcomm-ai-hub.slack.com) 上报告您的问题。<br /><br />
      * 自定义模型 <br />
        1. 模型量化是精度下降的常见原因。确保您在模型量化时使用了正确的数据集。用户应使用与实际部署环境近似的部分数据集进行训练后量化（PTQ）。为使 PTQ 获得良好效果，用户需要提供足够数量的数据来量化模型，例如大约 25-30 张 RAW 图像。<br />
        2. 尝试不同的模型精度，例如 W8A16 和 W16A16，看看模型精度是否有所提升。<br />
        3. 使用 AIMET 进行训练后量化（PTQ）和量化感知训练（QAT）等高级量化技术。有关更多详细信息，请参阅 [AIMET 文档](https://quic.github.io/aimet-pages/releases/latest/index.html)。<br /><br />
  </Step>

  <Step title="使用 AI SDK 进行模型量化的最佳实践有哪些？">
    * 准备校准数据

      使用与模型在生产环境中将遇到的数据高度匹配的代表性校准数据。
      这有助于准确确定量化所需的缩放因子和零点。

    * 选择合适的量化方法

      * 训练后量化（PTQ）：这种方法更简单、更快，适用于可以接受轻微精度损失的模型。它将预训练的浮点模型转换为量化模型，无需重新训练。
      * 量化感知训练（QAT）：这种方法在训练模型时就考虑量化，有助于保持更高的精度。它更复杂，但对精度要求较高的模型很有益。

      有关详细步骤，请参阅 [AIMET 文档](https://quic.github.io/aimet-pages/releases/latest/index.html)。
  </Step>

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

  <Step title="PyTorch、ONNX 和 TensorFlow 模型最快的部署路径是什么？">
    先将模型转换为 ONNX，再转换为 DLC，通常是最快且最灵活的部署方式。
  </Step>

  <Step title="用户如何知道模型是否正在 NPU 上运行？">
    请使用 Qualcomm 提供的以下工具：

    1. [Qualcomm profiler](https://dragonwingdocs.qualcomm.com/System/Performance/analyze-performance-with-tools#qualcomm-profiler-cli)
    2. Sysmon

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

  <Step title="用户如何在不同的硬件核心上运行模型？">
    AI SDK 工具和 API 提供了选择运行时（CPU、GPU 或 DSP）的选项。您可以通过命令行参数选择合适的运行时，或使用特定的 C/C++ API。
    有关更多详细信息，请参阅 [snpe-net-run](https://docs.qualcomm.com/doc/80-63442-10/topic/SNPE_general_tools.html#snpe-net-run)。

    AI 示例应用默认使用 DSP 运行时。您可以通过示例应用配置更改运行时。

    例如，在 `gst-ai-object-detection` 示例应用中，修改 `config_detection.json` 文件中的 `runtime` 参数。

    运行时：

    * `"cpu"`
    * `"gpu"`
    * `"dsp"`
  </Step>

  <Step title="如果使用 AI SDK 进行模型转换失败，该如何处理？">
    请联系 [Qualcomm 支持论坛](https://mysupport.qualcomm.com/supportforums/s/) 获取支持。
  </Step>

  <Step title="如何调试量化模型在 CPU 和 NPU 上精度不佳的问题？">
    可能存在与模型量化相关的问题，请参阅[用户替换模型](#user-replaced-model)常见问题以获取模型量化方面的指导
  </Step>

  <Step title="如何调试在 NPU 上精度不准确的量化模型？">
    `qnn-net-run` 的 `--debug` 选项会转储逐层数值，因此您可以比较 CPU 与 NPU 推理的差异。
  </Step>

  <Step title="如何调试示例应用没有 HDMI 输出的问题？">
    请按照[显示调试](https://dragonwingdocs.qualcomm.com/Technologies/Display/troubleshoot-debug-hdmi)来调试 HDMI 显示问题。
  </Step>

  <Step title="是否可以使用 HDMI 电视运行示例应用？">
    在大多数情况下可以正常工作。如果不行，请改用 HDMI 显示器。
  </Step>

  <Step title="如何检查 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...
      ```
  </Step>

  <Step title="什么是 devtool 完整性检查（sanity check）错误？如何调试？">
    有时您可能会看到 devtool 显示完整性检查错误。

    确保您对主机拥有 sudo 权限。如果错误仍然存在，请执行以下变通方法：

    <Steps>
      <Step title="更新权限">
        ```shell theme={null}
        umask a+rx
        ```
      </Step>

      <Step title="禁用 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"
        ```
      </Step>
    </Steps>
  </Step>

  <Step title="如何在目标设备上旁加载（sideload）Qualcomm Neural Processing Engine SDK">
    <Steps>
      <Step title="准备目标设备">
        进入目标设备 shell 并运行以下命令：

        ```shell theme={null}
        ssh root@<ip-address of target device>
        ```

        ```shell theme={null}
        mount -o rw,remount /
        ```

        ```
        exit
        ```
      </Step>

      <Step title="将 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`

        ```shell theme={null}
        scp lib/aarch64-oe-linux-gcc11.2/* root@<target-ip-address>:/usr/lib/
        ```

        ```shell theme={null}
        scp lib/hexagon-v68/unsigned/* root@<target-ip-address>:/usr/lib/rfsa/adsp/
        ```

        ```shell theme={null}
        scp bin/aarch64-oe-linux-gcc11.2/* root@<target-ip-address>:/usr/bin/
        ```

        ```shell theme={null}
        ssh root@<target-ip-address>
        ```

        ```shell theme={null}
        chmod -R 777 /usr/bin/
        ```
      </Step>

      <Step title="验证 SDK 版本">
        验证新的 SDK 版本：

        ```shell theme={null}
        qairt-net-run --version
        ```
      </Step>
    </Steps>

    有关下载 Qualcomm AI Runtime SDK 的更多信息，请参阅 [Qualcomm package manager](../topic/qairt-install#qairt-qpm)。
  </Step>

  <Step title="如何使用 SNPE 对 QIM SDK 预处理后的张量运行推理">
    <Steps>
      <Step title="生成预处理的原始张量">
        从视频文件生成预处理的原始张量。

        <Steps>
          <Step title="创建用于保存原始张量的文件夹">
            创建一个用于保存原始张量的文件夹。

            ```shell theme={null}
            mkdir -p /opt/frames/
            ```
          </Step>

          <Step title="使用 GStreamer 转储原始张量">
            运行 GStreamer 流水线，将原始张量转储到该文件夹。

            ```shell theme={null}
            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"
            ```

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

      <Step title="使用 SNPE 或 QNN 运行推理">
        使用 SNPE 或 QNN 运行推理。

        <Steps>
          <Step title="创建输入列表">
            创建一个包含原始文件绝对路径的 `input_list.txt` 文件，如下所示。

            对 `input_list.txt` 文件中列出的每个文件执行推理。

            `input_list.txt` 中的示例内容

            ```
            /opt/frames/frame_000.raw
            /opt/frames/frame_001.raw
            ```
          </Step>

          <Step title="在 HTP 后端上运行模型">
            在 HTP 后端上运行 SNPE DLC 或 QNN 模型。

            <Tabs>
              <Tab title="SNPE">
                ```
                snpe-net-run --container <model>.dlc --input_list input_list.txt --output_dir output_htp --use_dsp
                ```
              </Tab>

              <Tab title="QNN">
                ```
                qnn-net-run --model <model>.so --backend libQnnHtp.so --input_list input_list.txt --output_dir output_htp
                ```
              </Tab>
            </Tabs>

            有关更多详细信息，请参阅使用 [Neural Processing Engine](../topic/run-models/#neural-processing-engine) 或 [AI Engine Direct](../topic/run-models/#ai-engine-direct) 部署模型。
          </Step>
        </Steps>
      </Step>
    </Steps>
  </Step>
</Steps>

## 更多支持

请在 [Qualcomm 支持论坛](https://mysupport.qualcomm.com/supportforums/s/)上提出您的问题。

对本文档中使用的术语或缩写不熟悉？请参阅[术语表](../topic/glossary)。