> ## 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.

# 运行图像分类示例应用程序

> 运行 gst-ai-classification 示例应用程序。

`gst-ai-classification` 示例应用程序演示了在视频流上进行硬件加速的图像分类。该管线接收来自摄像头、文件源、实时流传输协议 (RTSP) 流或 USB 摄像头的输入,执行预处理,在 AI 硬件上运行推理,并将结果显示在屏幕上。

<img src="https://mintcdn.com/qualcomm-staging/uWQLnBcS9sxlZhgB/Key-Documents/AI-Developer-Workflow/_images/gst_ai_classification_pipeline.svg?fit=max&auto=format&n=uWQLnBcS9sxlZhgB&q=85&s=29d398bc0513621b5bc0b66e745496f1" alt="gst-ai-classification 管线图" width="1382" height="718" data-path="Key-Documents/AI-Developer-Workflow/_images/gst_ai_classification_pipeline.svg" />

`gst-ai-classification` 应用程序是 Qualcomm Intelligent Multimedia (QIM) SDK 的一部分,刷机后即可在设备上使用。在运行该应用程序之前,您必须先将模型和标签文件推送到设备。

## 下载模型和标签文件

<Steps>
  <Step title="在设备上启用 Wi-Fi 和 SSH">
    设备需要互联网连接才能下载运行示例应用程序所需的构件。如果已配置 SSH 和 Wi-Fi,请跳过此步骤。

    请按照[设置 SSH 连接](https://dragonwingdocs.qualcomm.com/Technologies/Wi-Fi/setup-wi-fi#set-up-uart/ssh)在设备上启用 Wi-Fi 和 SSH。
  </Step>

  <Step title="在主机上设置用户环境变量">
    ```shell theme={null}
    export USER=root
    ```
  </Step>

  <Step title="使用 SSH 登录目标设备">
    ```shell theme={null}
    ssh $USER@<IP_ADDRESS_OF_TARGET_DEVICE>
    ```
  </Step>

  <Step title="下载并运行 download_artifacts_2.x.sh 脚本">
    ```shell theme={null}
    cd /tmp
    curl -L -O https://raw.githubusercontent.com/qualcomm/sample-apps-for-qualcomm-linux/refs/heads/main/qualcomm-linux/scripts/download_artifacts_2.x.sh
    chmod +x download_artifacts_2.x.sh 
    ./download_artifacts_2.x.sh
    ```
  </Step>

  <Step title="启用 qticamsrc">
    在目标设备的终端中,运行以下命令以启用摄像头:

    ```shell theme={null}
    echo -n "camx" > /var/data
    efivar -n 882f8c2b-9646-435f-8de5-f208ff80c1bd-VendorDtbOverlays -w -f /var/data
    efivar -n 882f8c2b-9646-435f-8de5-f208ff80c1bd-VendorDtbOverlays -p
    sync
    reboot
    ```

    <Note>
      `IQ-2390` 不支持 `camera` 用例。
    </Note>
  </Step>

  <Step title="(可选) 下载 YOLOv8 模型">
    使用以下方法之一:

    <Tabs>
      <Tab title="使用脚本下载">
        <Steps>
          <Step title="创建 Qualcomm AI Hub 账户">
            创建 [Qualcomm AI Hub 账户](https://app.aihub.qualcomm.com/account/)。
          </Step>

          <Step title="复制您的 API key">
            前往右上角的 **Settings** 并复制您的 API key。
          </Step>

          <Step title="在主机上运行导出脚本">
            ```shell theme={null}
            curl -L -O https://raw.githubusercontent.com/qualcomm/sample-apps-for-qualcomm-linux/refs/heads/main/qualcomm-linux/scripts/export_model.sh
            chmod +x export_model.sh
            ```

            将 `<API_KEY>` 替换为您的 API key:

            ```shell theme={null}
            ./export_model.sh --api-key=<API_KEY>
            ```

            模型将下载到 `export_assets` 目录。
          </Step>

          <Step title="将模型复制到设备上的 `${HOME}/Downloads/qimsdk_samples/models/` 目录">
            ```shell theme={null}
            scp <working-directory>/export_assets/yolov8_det-tflite-w8a8/yolov8_det.tflite $USER@<IP_ADDRESS_OF_TARGET_DEVICE>:~/Downloads/qimsdk_samples/models/
            ```
          </Step>
        </Steps>
      </Tab>

      <Tab title="使用 AI Hub API 导出">
        使用来自 AI Hub 的 [YOLOv8-Detection-Quantized](https://github.com/qualcomm/ai-hub-models/tree/v0.52.0/src/qai_hub_models/models/yolov8_det) 模型。

        当前版本使用以下 SDK 版本:

        * Qualcomm Linux (GA 2.1): Qualcomm AI Runtime SDK v2.50.0.260828

        例如,要导出 YOLOv8 QNN 模型,请运行:

        ```shell theme={null}
        qai-hub-models export yolov8_det --quantize w8a8 --target-runtime=qnn_context_binary --device="Dragonwing RB3 Gen 2 Vision Kit" --compile-options="--qairt_version 2.50" --profile-options "--qairt_version 2.50"
        ```

        更新 `--qairt_version` 以匹配您的**目标设备**上安装的版本。要检查已安装的版本:

        ```shell theme={null}
        qairt-net-run --version
        ```

        要列出 AI Hub 支持用于导出命令的 QAIRT SDK 版本,请在**主机设备**上运行以下命令:

        ```shell theme={null}
        qai-hub list-frameworks
        ```

        要列出支持的设备,请在**主机设备**上运行以下命令:

        ```shell theme={null}
        qai-hub list-devices
        ```

        例如,要导出 YOLOv8 LiteRT 模型,请运行:

        ```shell theme={null}
        qai-hub-models export yolov8_det --quantize w8a8 --target-runtime=tflite --device="Dragonwing RB3 Gen 2 Vision Kit"
        ```
      </Tab>

      <Tab title="生成批处理模型">
        要更改批处理大小,请在以下导出命令中更新 `<N>`:

        ```shell theme={null}
        qai-hub-models export <Model_Name> --batch-size <N> --device="Dragonwing RB3 Gen 2 Vision Kit"
        ```

        例如,要导出批处理大小为 4 的 YOLOv8 LiteRT 模型:

        ```shell theme={null}
        qai-hub-models export yolov8_det --quantize w8a8 --target-runtime=tflite --device="Dragonwing RB3 Gen 2 Vision Kit" --batch-size 4
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## 运行示例应用程序

<Steps>
  <Step title="在主机上设置用户环境变量">
    ```shell theme={null}
    export USER=root
    ```
  </Step>

  <Step title="使用 SSH 登录设备">
    ```shell theme={null}
    ssh $USER@<IP_ADDRESS_OF_TARGET_DEVICE>
    ```
  </Step>

  <Step title="使用示例配置文件运行应用程序">
    要使用示例配置文件运行应用程序,请使用:

    ```bash theme={null}
    gst-ai-classification --config-file=/etc/configs/config_classification.json
    ```

    此命令使用 `/etc/configs/config_classification.json` 中的示例配置运行应用程序。

    要查看可用的命令行选项,请运行:

    ```bash theme={null}
    gst-ai-classification -h
    ```

    按 **CTRL + C** 停止执行。
  </Step>

  <Step title="使用自定义配置文件运行应用程序(可选)">
    您可以通过 `--config-file` 指定路径来使用自定义配置文件:

    ```bash theme={null}
    gst-ai-classification --config-file=/path/to/config_classification.json
    ```

    如果指定了 `--config-file`,应用程序将使用该文件。否则,它将按以下顺序搜索 `config_classification.json`:

    | 优先级 | 位置 | 说明 |
    | :-: | :- | :- |
    | 1 | 通过 `--config-file` 提供的路径。 | 使用命令行中指定的配置文件。 |
    | 2 | `$XDG_CONFIG_HOME/qimsdk_samples/config_classification.json` | 设置了该环境变量时,使用用户定义的配置目录。 |
    | 3 | `$HOME/.config/qimsdk_samples/config_classification.json` | 在 `XDG_CONFIG_HOME` 中未找到文件时,使用默认的用户配置目录。 |
    | 4 | `/etc/configs/config_classification.json` | 使用系统级配置文件作为最终回退。 |

    要创建用户专属配置,请将示例文件复制到用户配置目录:

    ```bash theme={null}
    export XDG_CONFIG_HOME="$HOME/.config"
    mkdir -p "$XDG_CONFIG_HOME/qimsdk_samples"
    cp /etc/configs/config_classification.json "$XDG_CONFIG_HOME/qimsdk_samples/config_classification.json"
    ```

    <Note>
      修改复制的配置文件以指定所需参数。自定义配置文件必须遵循 [`configurations`](#configure-the-application) 中定义的架构。
    </Note>

    运行应用程序:

    ```bash theme={null}
    gst-ai-classification
    ```
  </Step>
</Steps>

应用程序会在视频流上叠加分类的对象标签和置信度得分,并在配置的输出上显示结果。要停止应用程序,请按 `Ctrl+C`。

## 配置应用程序

编辑 `config_classification.json` 文件,以指定您的模型、输入源和输出首选项。

**配置模板**

```json theme={null}
{
  "file-path": "<path-to-input-video>",
  "ml-framework": "<snpe or tflite or qnn or onnx>",
  "model": "<path-to-model-file>",
  "labels": "<path-to-label-file>",
  "threshold": "<postprocessing threshold, integer value from 1 to 100>",
  "runtime": "<dsp, gpu, or cpu>",
  "output-type": "<waylandsink, filesink, or rtspsink>"
}
```

**示例配置 — 使用 DSP 运行时在视频文件上运行 LiteRT 模型:**

```json theme={null}
{
  "file-path": "video.mp4",
  "ml-framework": "tflite",
  "model":" inception_v3_quantized.tflite",
  "labels": "classification.json",
  "threshold": 40,
  "runtime": "dsp",
  "output-type": "waylandsink"
}
```

<Info>
  本节使用以下默认文件位置:

  * `${HOME}/Downloads/qimsdk_samples/models/` — 模型文件
  * `${HOME}/Downloads/qimsdk_samples/labels/` — 标签文件
  * `${HOME}/Downloads/qimsdk_samples/media/` — 视频文件
</Info>

**JSON 配置字段说明**

| 字段 | 说明 |
| - | - |
| `ml-framework` | <ul><li>`snpe`: Qualcomm Neural Processing SDK</li><li>`tflite`: LiteRT</li><li>`qnn`: Qualcomm AI Engine Direct</li><li>`onnx`: ONNX Runtime</li></ul> |
| `runtime` | <ul><li>`cpu`</li><li>`gpu`</li><li>`dsp`</li></ul> |
| `output-ip-address` | 输出服务器 IP 地址 |
| `port` | 输出服务器端口 |
| `video-format` | USB 摄像头格式: `nv12`、`yuy2` 或 `mjpeg`,以及 `width`、`height` 和 `framerate` 参数 |
| `output-file` | 输出文件的名称。默认值: `output_classification.mp4` |
| `output-type` | <ul><li>`waylandsink`: 在 Wayland 上显示</li><li>`filesink`: 保存到文件</li><li>`rtspsink`: 流式传输到 RTSP 服务器</li></ul> |
| `file-path` | 输入视频文件的路径 |
| `rtsp-ip-port` | RTSP 输入流,格式为 `rtsp://<ip>:<port>/<stream>` |
| `camera` | 摄像头索引: 主摄像头 (`0`) 或副摄像头 (`1`) |

## 注意事项

* 要停止应用程序,请按 `Ctrl+C`。
* 要启用 GStreamer 调试日志,请设置 `GST_DEBUG` 环境变量。例如,要记录所有警告:

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

  有关更多故障排除选项,请参阅[故障排除](../topic/troubleshooting)。