> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.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://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/AI-Developer-Workflow-Ubuntu/_images/gst_ai_classification_pipeline.svg" alt="gst-ai-classification 管道图" />

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

## 下载模型和标签文件

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

    按照[设置 SSH 连接](https://dragonwingdocs.qualcomm.com/Ubuntu/devices/iq9075-evk/set-up-the-device#connect-over-ssh)在设备上启用 Wi-Fi 和 SSH。
  </Step>

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

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

  <Step title="下载并运行 download_artifacts.sh 脚本">
    在目标设备上，下载并运行 `download_artifacts.sh` 脚本以下载模型和标签文件：

    ```shell theme={null}
    cd /home/ubuntu 
    curl -L -O https://raw.githubusercontent.com/qualcomm/sample-apps-for-qualcomm-linux/refs/heads/main/qualcomm-linux/scripts/download_artifacts.sh
    sudo chmod +x download_artifacts.sh 
    sudo ./download_artifacts.sh
    ```
  </Step>

  <Step title="（可选）下载 YOLOv8 模型">
    <Note>
      YOLOv8 适用于检测场景，分类场景无需使用。
    </Note>

    默认下载中不包含 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="将模型复制到设备上的 /etc/models/ 目录">
            ```shell theme={null}
            scp <working-directory>/export_assets/yolov8_det-tflite-w8a8/yolov8_det.tflite $USER@<IP_ADDRESS_OF_TARGET_DEVICE>:/home/ubuntu/
            ssh $USER@<IP_ADDRESS_OF_TARGET_DEVICE>
            sudo cp /home/ubuntu/yolov8_det.tflite /etc/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 版本：

        * Ubuntu：Qualcomm AI Runtime SDK v2.46.0.260424

        例如，要导出 YOLOv8 QNN 模型，请运行：

        ```shell theme={null}
        python -m qai_hub_models.models.yolov8_det.export --quantize w8a8 --target-runtime=qnn_context_binary --device="Dragonwing RB3 Gen 2 Vision Kit" --compile-options="--qairt_version 2.45" --profile-options "--qairt_version 2.45"
        ```

        更新 `--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}
        python -m qai_hub_models.models.yolov8_det.export --quantize w8a8 --target-runtime=tflite --device="Dragonwing RB3 Gen 2 Vision Kit"
        ```
      </Tab>

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

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

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

        ```shell theme={null}
        python -m qai_hub_models.models.yolov8_det.export --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=ubuntu
    ```
  </Step>

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

  <Step title="运行示例应用程序">
    ```shell theme={null}
    gst-ai-classification --config-file=/etc/configs/config_classification.json
    ```

    有关配置字段或可用选项的更多信息，请使用帮助命令：

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

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

## 配置应用程序

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

  * `/etc/models/` — 模型文件
  * `/etc/labels/` — 标签文件
  * `/etc/media/` — 视频文件
  * `/etc/configs/` — 配置文件
</Info>

编辑 `/etc/configs/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": "/etc/media/video.mp4",
  "ml-framework": "tflite",
  "model": "/etc/models/inception_v3_quantized.tflite",
  "labels": "/etc/labels/classification.json",
  "threshold": 40,
  "runtime": "dsp"
}
```

**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)。