# Android-qnn

**Repository Path**: jackroing/android-qnn

## Basic Information

- **Project Name**: Android-qnn
- **Description**: 安卓上运行QNN后端
- **Primary Language**: C++
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-24
- **Last Updated**: 2026-02-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Android - ONNX Runtime QNN

<div align="center">

## 基于 ONNX Runtime 和高通 QNN 的优化 YOLOv10 物体检测

**在 Snapdragon 移动平台上使用 ONNX Runtime 和 QNN 执行提供高效的 AI 推理**

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Snapdragon-green.svg)](PLATFORMS.md)
[![ONNX Runtime](https://img.shields.io/badge/ONNX%20Runtime-v1.23+-orange.svg)](https://github.com/microsoft/onnxruntime)

</div>

## 📋 目录

- [概述](#概述)
- [支持的芯片组](#支持的芯片组)
- [硬件要求](#硬件要求)
- [软件要求](#软件要求)
- [环境搭建](#环境搭建)
- [构建说明](#构建说明)
- [设备配置](#设备配置)
- [测试与验证](#测试与验证)
- [故障排除](#故障排除)
- [性能基准](#性能基准)

```shell
.
├── android                             # Android 工具链，包含 NDK、SDK、CMD Tool等
├── android_lib                         # Android 库，包含 ONNX Runtime QNN 库
├── Android.mk                          # Android 构建配置，用于编译项目
├── build                               # C++构建输出目录
├── build.sh                            # Android 构建脚本，用于编译项目
├── CMakeLists.txt                      # C++ 构建配置，用于编译项目
├── gen_raw.py                          # 生成测试用原始数据脚本
├── includes                            # 包含ORT头文件目录
├── libs                                # 包含ORT库文件目录
├── main.cpp                            # 测试用例
├── models                              # 包含模型文件目录
├── obj                                 # 包含Android编译输出目录
├── platform.png                        # Android 平台QNN验证
├── qnn                                 # 包含 QNN SDK v2.43
├── README.md                           # 项目说明文档
└── res.png                             # 测试用例输出示例图
```

## 概述

本项目展示了基于 ONNX Runtime 和高通神经处理 SDK (QNN) 在 Snapdragon 移动平台上运行的优化 YOLOv10 物体检测。该解决方案利用 Hexagon DSP 实现加速推理，提供高效的边缘 AI 功能。

### 主要特性
- 🚀 使用 QNN 执行提供程序优化的 YOLOv10 推理
- ⚡ 在 Snapdragon 平台上的低延迟处理
- 🧠 高效使用 Hexagon DSP 进行神经网络加速
- 📦 基于 ONNX 的模型兼容性
- 📱 准备就绪的 Android 部署

## 支持的芯片组

| Snapdragon 代次 | 架构 | Hexagon 版本 |
|----------------------|--------------|-----------------|
| 8 Gen 1              | SM8450       | v69             |
| 8 Gen 2              | SM8550       | v73             |
| 8 Gen 3              | SM8650       | v75             |
| 8 Elite              | SM8750       | v79             |

> **注意：** 根据目标设备架构选择适当的 Hexagon 版本。

## 硬件要求

### 开发环境
- ✅ Linux 开发主机 (推荐 Ubuntu 20.04 LTS 或更高版本)
- ✅ 最小 8GB 内存 (推荐 16GB)
- ✅ 50GB 可用磁盘空间用于 SDK 和构建产物
- ✅ 稳定的互联网连接用于下载依赖项

### 目标设备
- ✅ 搭载 Snapdragon 8 Gen 1/2/3/Elite 芯片组的 Android 设备
- ✅ Android 10+ (API 级别 29+)
- ✅ 已启用开发者选项和 USB 调试
- ✅ USB Type-C 数据线用于设备连接

## 软件要求

### 主机系统依赖
- [Android SDK](https://developer.android.com/studio#command-tools) 包含 Build Tools 36.0.0-rc1
- [Android NDK](https://developer.android.com/ndk/downloads) r29 (29.0.14206865)
- [OpenJDK 21](https://openjdk.org/projects/jdk/21/) (JDK 和 JRE)
- [ADB (Android Debug Bridge)](https://developer.android.com/tools/adb) 工具
- [QNN SDK](https://www.qualcomm.com/developer/software/qualcomm-ai-engine-direct-sdk) v2.43
- [ONNX Runtime](https://github.com/microsoft/onnxruntime) 包含 QNN 执行提供程序

### 目标设备依赖
- 设备上安装的 QNN 运行时库
- 适当的 Hexagon DSP 固件

## 环境搭建

### 1. 安装主机依赖

> **注意：** `sdkmanager` 工具位于 `android/Sdk/cmdline-tools/latest/bin/`

```bash
# 安装系统包
sudo apt update
sudo apt install adb openjdk-21-jdk openjdk-21-jre

# 安装 Android 构建工具
sdkmanager "build-tools;36.0.0-rc1"
sdkmanager "ndk;29.0.14206865"
sdkmanager "platforms;android-Baklava"
```

### 2. 配置环境变量

将以下内容添加到 `~/.bashrc` 文件并执行 `source ~/.bashrc` 以应用更改：

```bash
# Android 编译环境配置
export ANDROID_HOME=/usr/local/android/Sdk
export ANDROID_NDK=/usr/local/android/Sdk/ndk/29.0.14206865
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

# QNN 环境配置
source /opt/qcom/aistack/qairt/2.43.0.260128/bin/envsetup.sh
export ADSP_LIBRARY_PATH=/opt/qcom/aistack/qairt/2.43.0.260128/lib/hexagon-v73/unsigned/

# 常规环境变量
export PATH=$ANDROID_NDK:$ANDROID_HOME/cmdline-tools/latest/bin:$JAVA_HOME/bin:$PATH
export LD_LIBRARY_PATH=/opt/qcom/aistack/qairt/2.43.0.260128/lib/aarch64-android/:$LD_LIBRARY_PATH
```

### 3. 验证安装

```bash
# 检查 Android SDK 安装
adb version
ndk-build --version

# 检查 Java 安装
java -version
javac -version
```

## 构建说明

### 1. 项目编译

```bash
# 使用构建脚本构建项目
bash build.sh

# 或使用 CMake 手动构建
mkdir build && cd build
cmake ..
cmake --build .
```

### 2. 预期输出

成功编译后，你应该在 `obj/yolo_qnn_demo/main` 处获得可执行文件。

## 设备配置

### 1. 启用开发者选项
- 导航至 设置 > 关于手机
- 连续点击“版本号”7次以启用开发者选项
- 返回 设置 > 开发者选项
- 启用“USB 调试”

### 2. 连接设备
```bash
# 验证设备连接
adb devices

# 应显示连接的设备
List of devices attached
<device_id>    device
```

## 测试与验证

### 1. 部署应用程序到设备

```bash
# 将编译后的二进制文件推送到设备
adb -s <device_id> push obj/yolo_qnn_demo /data/local/tmp/

# 设置可执行权限
adb -s <device_id> shell chmod +x /data/local/tmp/yolo_qnn_demo/main
```

### 2. 验证 QNN 环境

在 Android 设备 shell 中执行：

```bash
# 进入设备 shell
adb -s <device_id> shell

# 设置 QNN 环境 (根据设备调整 hexagon 版本)
source /opt/qcom/aistack/qairt/2.43.0.260128/bin/envsetup.sh
export ADSP_LIBRARY_PATH=/opt/qcom/aistack/qairt/2.43.0.260128/lib/hexagon-v73/unsigned/

# 验证 QNN 平台
qnn-platform-validator --backend all --coreVersion --libVersion --testBackend
```

✅ **预期结果：** QNN 环境验证应成功通过。

![qnn-platform-validator](./sources/platform.png)

### 3. 运行 YOLOv10 推理

```bash
# 导航到应用程序目录
cd /data/local/tmp/yolo_qnn_demo

# 执行推理
./main --qnn ./models/yolov10_qnn_onnx/model.onnx ./test.raw
```

> **注意：** `test.raw` 文件由 `gen_raw.py` 生成并包含原始图像数据。实际检测结果可能因输入数据而异。

✅ **预期结果：** 应用程序应成功运行并显示检测结果。

![测试用例](./sources/res.png)

## 故障排除

### 常见问题

| 问题 | 解决方案 |
|-------|----------|
| ADB 未检测到设备 | 确保已启用 USB 调试且数据线连接正常 |
| 缺少 QNN 库 | 验证 QNN SDK 安装和环境变量 |
| Hexagon 版本不匹配 | 调整 `ADSP_LIBRARY_PATH` 以匹配设备的 Hexagon 版本 |
| 权限被拒绝 | 使用 `chmod +x` 确保正确的文件权限 |
| 模型加载失败 | 验证模型文件是否存在且具有正确的 ONNX 格式 |

### 调试技巧

1. **检查 ADB 连接**：
   ```bash
   adb devices -l
   adb logcat &
   ```

2. **验证库依赖**：
   ```bash
   adb shell ldd /data/local/tmp/yolo_qnn_demo/main
   ```

3. **监控性能**：
   ```bash
   adb shell top -p $(pidof yolo_qnn_demo)
   ```

## 性能基准

### 不同平台的预期性能

| 平台 | 推理时间 | 功耗 | 注释 |
|----------|----------------|-------------------|--------|
| Snapdragon 8 Gen 1 | ~15ms | 中等 | Hexagon v69 |
| Snapdragon 8 Gen 2 | ~12ms | 低 | Hexagon v73，效率提升 |
| Snapdragon 8 Gen 3 | ~10ms | 低 | Hexagon v75，最新优化 |
| Snapdragon 8 Elite | ~8ms | 很低 | Hexagon v79，高级功能 |

> **注意：** 实际性能可能因模型复杂度、输入分辨率和设备热状态条件而异。

## 贡献

我们欢迎对此项目的贡献！请阅读我们的 [贡献指南](CONTRIBUTING.md) 了解行为准则和提交拉取请求的流程详情。

## 许可证

此项目根据 Apache 许可证 2.0 版授权 - 详见 [LICENSE](LICENSE) 文件。

## 致谢

- 高通技术公司提供 QNN SDK
- 微软提供 ONNX Runtime

<div align="center">

**为边缘 AI 社区倾心打造 ❤️**

</div>