> ## 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://mintcdn.com/qualcomm-prod/L-jqwrTTz49ZAgVX/Key-Documents/AI-Developer-Workflow/_images/gst_ai_classification_pipeline.svg?fit=max&auto=format&n=L-jqwrTTz49ZAgVX&q=85&s=09014ef9b320471e74bee98c493fc64a" 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 智能多媒体（QIM）SDK 的一部分，刷机后即可在设备上使用。在运行该应用程序之前，您必须将模型和标签文件推送到设备。

## 下载模型和标签文件

1. 在设备上启用 Wi-Fi 和 SSH。

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

   按照[设置 SSH 连接](https://dragonwingdocs.qualcomm.com/Technologies/Ethernet/get-started-with-ethernet#set-up-an-ssh-connection)在设备上启用 Wi-Fi 和 SSH。

2. 在主机上，设置用户环境变量：

   ```shell theme={null}
   export USER=root
   ```

3. 使用 SSH 登录目标设备：

   ```shell theme={null}
   ssh $USER@<IP_ADDRESS_OF_TARGET_DEVICE>
   ```

4. 在目标设备上，下载并运行 `download_artifacts.sh` 脚本以下载模型和标签文件：

   ```shell theme={null}
   cd /tmp
   curl -fsSL https://raw.githubusercontent.com/qualcomm/sample-apps-for-qualcomm-linux/refs/heads/main/qualcomm-linux/scripts/download_artifacts.sh | bash
   ```

5. （可选）下载 YOLOv8 模型，该模型不包含在默认下载中。

   使用以下方法之一：

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

       2. 前往右上角的 **Settings** 并复制您的 API 密钥。

       3. 在主机上运行以下命令：

          ```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 密钥：

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

          模型将下载到 `export_assets` 目录。

       4. 将模型复制到设备上的 `/etc/models/` 目录：

          ```shell theme={null}
          scp <working-directory>/export_assets/yolov8_det-tflite-w8a8/yolov8_det.tflite $USER@<IP_ADDRESS_OF_TARGET_DEVICE>:/etc/models/
          ```
     </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.0）：Qualcomm AI Runtime SDK v2.47.0.260601

       例如，要导出 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>

## 运行示例应用程序

1. 在主机上，设置用户环境变量：

   ```shell theme={null}
   export USER=root
   ```

2. 使用 SSH 登录设备：

   ```shell theme={null}
   ssh $USER@<IP_ADDRESS_OF_TARGET_DEVICE>
   ```

3. 运行示例应用程序：

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

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

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

该应用程序将分类的对象标签和置信度分数叠加在视频流上，并在配置的输出上显示结果。要停止应用程序，请按 `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)。