📚 课程目录第3章边缘AI视觉开发环境搭建

3. 边缘AI视觉开发环境搭建

在骁龙边缘AI视觉平台上做开发，最先遇到的不是模型精度问题，而是“工具链能不能跑通”。Qualcomm 提供了三条互补的路径：Qualcomm AI Hub 负责云端模型编译、性能预估与真机验证；SNPE SDK（Snapdragon Neural Processing Engine）是较早期的端侧推理框架，生态成熟、文档丰富；QNN SDK（Qualcomm AI Engine Direct）是新一代统一后端，直接对接 Hexagon NPU、Adreno GPU 与 CPU，是当前新项目的首选。三者并非替代关系，而是“云端验证—端侧部署—底层加速”的分工。本节围绕安装、配置与版本兼容性管理展开，目标是让读者能在 Ubuntu 主机上搭出一套可复现、可切换、可验证的环境。

一、三条工具链的定位与协作关系

理解协作关系比记住安装命令更重要。典型流程是：在 AI Hub 上提交模型（如 YOLOv8、MobileNetV3），云端自动完成量化、编译并给出目标设备上的时延与内存预估；确认可行后，用 QNN SDK 在本地把模型转成 .cpp/.bin 或 .dlc 格式，通过 QNN Context 在设备上加载；若项目基于旧代码或需要 SNPE 的特定算子，则用 SNPE SDK 的 snpe-xxx 工具链完成转换与推理。三者共享同一套底层驱动与 HTP（Hexagon Tensor Processor）运行时，因此版本必须与设备固件匹配。

二、主机环境准备与 SDK 安装

推荐使用 Ubuntu 22.04 LTS，内核 5.15 以上，至少 16 GB 内存与 100 GB 磁盘。先安装基础依赖：

sudo apt update
sudo apt install -y python3.10 python3.10-venv python3-pip \
  build-essential cmake git wget unzip libprotobuf-dev protobuf-compiler \
  android-tools-adb libusb-1.0-0-dev

接着创建隔离的 Python 虚拟环境，避免不同 SDK 的依赖冲突：

python3.10 -m venv ~/qnn_env
source ~/qnn_env/bin/activate
pip install --upgrade pip
pip install qai-hub qai-hub-models
qai-hub configure --api_token YOUR_API_TOKEN

QNN SDK 与 SNPE SDK 需要从 Qualcomm 开发者账号下载。以 QNN SDK 2.28 为例，解压后设置环境变量：

export QNN_SDK_ROOT=~/qnn/qnn-2.28.0.241029
export SNPE_ROOT=~/snpe/snpe-2.28.0.241029
export PATH=$QNN_SDK_ROOT/bin/x86_64-linux-clang:$PATH
export LD_LIBRARY_PATH=$QNN_SDK_ROOT/lib/x86_64-linux-clang:$LD_LIBRARY_PATH
export PYTHONPATH=$QNN_SDK_ROOT/lib/python:$PYTHONPATH

验证安装是否成功，可运行 qnn-onnx-converter --version 与 snpe-onnx-to-dlc --version，两者都应输出版本号且与下载包一致。若出现 libQnnHtp.so not found，通常是 LD_LIBRARY_PATH 未包含对应架构目录，需检查 x86_64-linux-clang 与 aarch64-android 两个路径是否都加入。

三、版本兼容性管理策略

版本兼容性是本节最容易踩坑的部分。核心原则有三条：第一，SDK 版本不能高于设备固件支持的 HTP 架构版本。例如 SM8650 的 HTP 为 v75，若使用仅支持到 v73 的旧版 QNN，编译会失败或回退到 CPU。可通过 adb shell cat /sys/class/msm_htp/version 或 QNN 的 qnn-device-info 工具查询。第二，SNPE 与 QNN 共存时，两者依赖的 libc++_shared.so 与 protobuf 版本需一致，否则会出现符号冲突。建议在同一虚拟环境中只保留一套主版本。第三，Python 绑定与 SDK 主版本对齐，qai-hub 的 API 在 0.x 与 1.x 之间变化较大，升级前先锁定 requirements.txt。

实用建议：用 pip freeze > requirements.txt 固化 Python 依赖；用 git 管理 SDK 路径的环境变量脚本；在项目根目录放置 env_check.sh，每次切换设备前自动校验 SDK 版本与固件版本是否匹配。

四、一个可复现的环境检查脚本

下面给出一个可直接使用的检查脚本，用于在部署前快速判断环境是否就绪。它依次检查 Python 版本、SDK 路径、设备连接与 HTP 版本，并输出结论。

#!/bin/bash
# env_check.sh — 骁龙边缘AI视觉环境自检
set -e

echo "=== 1. Python 版本 ==="
python3 --version | grep -q "3.10" && echo "OK" || echo "WARN: 建议 3.10"

echo "=== 2. SDK 路径 ==="
[ -d "$QNN_SDK_ROOT" ] && echo "QNN: $QNN_SDK_ROOT" || echo "FAIL: QNN_SDK_ROOT 未设置"
[ -d "$SNPE_ROOT" ] && echo "SNPE: $SNPE_ROOT" || echo "WARN: SNPE_ROOT 未设置"

echo "=== 3. 设备连接 ==="
adb devices | grep -q "device$" && echo "OK" || echo "FAIL: 无设备"

echo "=== 4. HTP 版本 ==="
HTP_VER=$(adb shell cat /sys/class/msm_htp/version 2>/dev/null | tr -d '\r')
echo "设备 HTP: $HTP_VER"
echo "SDK 支持: 请对照 QNN 文档中的 HTP 架构表"

echo "=== 5. 结论 ==="
echo "若以上无 FAIL，可进入模型转换与部署阶段。"

运行该脚本后，若第 4 步输出的 HTP 版本高于 SDK 支持列表，应优先升级 SDK 或更换目标设备，而不是强行编译。实际项目中，建议把该脚本纳入 CI 流程，在每次构建前自动执行，避免因环境漂移导致的“本地能跑、设备报错”。

五、常见问题与判断依据

安装配置阶段的高频问题包括：qai-hub 提交任务后长时间排队，通常是 API Token 权限不足或模型超出免费额度；snpe-onnx-to-dlc 报算子不支持，需检查 ONNX opset 是否高于 SDK 支持上限（SNPE 2.28 支持 opset 17）；QNN 转换后推理结果与 ONNX Runtime 不一致，优先排查量化校准数据是否覆盖真实场景分布。判断环境是否真正就绪，最直接的依据是：能在目标设备上跑通一个最小视觉模型（如 MobileNetV3-Small），并输出与云端预估时延偏差在 20% 以内的实测值。若偏差过大，说明 HTP 未真正启用，需检查 QnnHtp 后端是否被正确加载。