> ## 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 的一部分,刷机后即可在设备上使用。在运行该应用程序之前,您必须先将模型和标签文件推送到设备。

## 下载模型和标签文件

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 key。

       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 key:

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