教程:VENTUNO Q/Qualcomm AI Hub

概述

Qualcomm AI Hub 是一个预训练、预量化 AI 模型库，可直接下载并在 Dragonwing™ 硬件上运行；Arduino® VENTUNO™ Q 正基于该硬件（Qualcomm® Dragonwing™ QCS8275）。

模型提供 TFLite（w8a8）与 ONNX 格式，直接针对 NPU。

在本指南中我们将涵盖：

1. 访问 VENTUNO Q 的 shell。
2. 在 VENTUNO Q 上创建 Python 虚拟环境。
3. 在 VENTUNO Q 上设置 Qualcomm AI Hub 工具链。
4. 为 VENTUNO Q 查找兼容模型。
5. 导出并下载已编译模型。
6. 在 VENTUNO Q 的 NPU 上运行导出的模型。
7. 在 VENTUNO Q 上运行模型的参考演示。

说明：

说明： 本教程使用的 QAI Hub Models 包 约占 5–8 GB 磁盘空间。开始本教程前请确保有可靠的互联网连接与足够磁盘空间。完整已安装包列表请点击上方链接。

硬件与软件要求

硬件

• Arduino® VENTUNO™ Q
• Arduino® USB-C Power Supply (65W)

说明：

说明： 若将此开发板用作单板电脑（SBC），你将需要键盘、鼠标和显示器。

软件

要访问 VENTUNO Q 的 shell，你的本地机器（mac/Windows/Linux）需要支持 SSH 或 ADB。你也可以将其设置为单板电脑，直接在 VENTUNO Q 上运行命令。

其他软件要求将在指南中介绍。

设置环境

本指南中的所有命令都在 VENTUNO Q 上 运行。使用以下方法之一连接到开发板：

Shell 访问

• SSH： ssh arduino@<device-ip>
• ADB： adb shell
• 直接： 连接键盘、鼠标和显示器（VENTUNO Q 运行完整的 Linux 桌面）。

获得 shell 访问后，我们就可以开始在开发板上运行命令。

创建虚拟环境

访问 VENTUNO Q 的 shell 后，创建并激活 Python 虚拟环境以隔离依赖：

python3 -m venv .venv
source .venv/bin/activate

说明：

如果激活环境失败，你可能需要通过运行 sudo apt install python3.12-venv 手动安装 -venv。

提示中的 (venv) 前缀确认环境已激活。每次会话在运行下面任何命令之前再次激活它。

安装 AI Hub Python 包

虚拟环境激活后，安装 qai-hub-models 包：

pip install qai-hub-models

说明：

说明： 这是一个大型包，需要快速且稳定的互联网连接来下载。

某些模型需要额外依赖。检查模型的 README 了解任何额外要求，例如：

pip install "qai-hub-models[yolov7]"

Qualcomm® ID 与 API Token

AI Hub Workbench 需要 Qualcomm® ID，以便在云托管硬件上编译与分析模型。

1. 如果还没有，请 创建 Qualcomm® ID。
2. 登录 Qualcomm® AI Hub Workbench。
3. 转到你的 账户页面 并复制 API token。

<img src="" alt="查找 API token" />

使用你的 token 配置 CLI：

qai-hub configure --api_token YOUR_API_TOKEN

说明：

仅在 AI Hub Workbench 上进行编译与分析时才需要 API token 访问。你可以浏览模型库并从 aihub.qualcomm.com/models 下载预编译模型，无需账户。

查找兼容模型

转到 AI Hub 模型列表 并按以下条件筛选：

• Chipset： Qualcomm QCS8275 (Proxy)
• Model precision： Quantized

<img src="" alt="QAI Hub" />

量化模型在 NPU 上提供最佳吞吐量与最小文件大小，因此是推荐的起点。不过未量化模型也未被排除：NPU 不能执行 FP32，但运行时在加载时会将浮点图转换为 FP16，因此 float 导出仍会在 NPU 上运行。两者之间的权衡见 NPU 指南。

每个模型页面都链接到一个参考仓库，展示确切的输入预处理与输出后处理代码。请仔细阅读——输入分辨率、颜色通道顺序与归一化值等细节很容易弄错。

导出并编译模型

配置好 API token 后，使用导出脚本为 VENTUNO Q 编译模型，并将其直接下载到 VENTUNO Q：

# Example: export YOLOv7 for the VENTUNO Q (TFLite runtime)
python3 -m qai_hub_models.models.yolov7.export --target-runtime tflite --device "Arduino VENTUNO Q"

AI Hub 将 VENTUNO Q 本身列为目标设备，因此你可以针对真实开发板而非代理芯片组进行编译。要查看匹配此硅片的每个设备，运行：

qai-hub list-devices | grep -i 8275

这会返回两个可用目标：

Device	OS	Notes
Arduino VENTUNO Q	Ubuntu 24.04	实际开发板——请使用这个。
QCS8275 (Proxy)	Android 14	相同芯片组的代理，可用作后备。

导出脚本将：

1. 为 QCS8275 目标与所选运行时编译模型。
2. 在适用时量化模型。
3. 在真实云托管设备上分析它。
4. 将已编译模型（.tflite）下载到 VENTUNO Q 上的工作目录。

任务完成后，脚本会打印来自云设备的分析摘要并保存模型。对于上面的 YOLOv7 示例，产物位于 export-out/yolov7-tflite-float/，摘要报告图如何分布在开发板的各处理器上：

Device                          : Arduino VENTUNO Q (UBUNTU 24.04)
Runtime                         : TFLITE
Estimated inference time (ms)   : 10.8
Compute Unit(s)                 : npu (201 ops) gpu (0 ops) cpu (0 ops)

全部 201 个操作都被放在 NPU 上，这正是进入下一步之前你希望看到的。

说明：

说明： 并非 AI Hub 库中的每个模型都能从源重新导出。有些会失败并提示 Model cannot be published: no release assets available——本教程稍后使用的 face_det_lite 模型目前就是其中之一，这就是为什么上面的导出示例使用 YOLOv7。这只影响 export；已编译资源仍可用 qai-hub-models fetch <model> --runtime tflite --precision w8a8 下载，这也是 Face Detection 教程获取它的方式。

在 NPU 上运行导出的模型

导出步骤为你提供已为此开发板编译的 .tflite 文件。要在 Hexagon™ NPU 上执行它，请通过带有 QNN HTP delegate 的 LiteRT 加载它。

安装 Qualcomm AI Runtime

delegate 库由 Qualcomm® AI Runtime（QAIRT） 提供，默认未安装，也不会被任何 pip 包拉取。从开发板的 apt 仓库安装：

sudo apt update
sudo apt install qairt-libs qairt-dsp-binaries

继续之前验证 delegate 是否存在：

ls /usr/lib/libQnnTFLiteDelegate.so

运行模型

将 LiteRT 安装到你的虚拟环境：

pip install ai-edge-litert==1.3.0

注意：

重要： 版本很重要。本教程前面安装的 qai-hub-models 依赖 ai-edge-litert>=2.0.2，并且已经拉取了 2.x 版本，因此上面的命令是刻意降级。版本 2.x 无法与 QNN HTP delegate 配合工作——它会以 Failed to validate op ... Conv2d 拒绝每个卷积，静默回退到 CPU，并因额外的委托开销而比普通 CPU 执行更慢。继续之前请确认版本：

pip show ai-edge-litert | grep Version   # must report 1.3.0

说明：

说明： pip 会打印以 ERROR: 开头的行，报告 qai-hub-models 需要更新的 ai-edge-litert。降级仍然会成功，且之后 qai-hub-models fetch 仍可工作，因此可以忽略此消息。

然后创建 benchmark.py，它加载导出的模型，并在有/无 NPU delegate 的情况下计时：

import sys, time, numpy as np
from ai_edge_litert.interpreter import Interpreter, load_delegate

MODEL = "export-out/yolov7-tflite-float/yolov7.tflite"
use_npu = "--use-npu" in sys.argv

if use_npu:
    delegate = load_delegate("libQnnTFLiteDelegate.so", options={"backend_type": "htp"})
    interpreter = Interpreter(model_path=MODEL, experimental_delegates=[delegate])
else:
    interpreter = Interpreter(model_path=MODEL)

interpreter.allocate_tensors()
input_details = interpreter.get_input_details()[0]

sample = np.zeros(input_details["shape"], dtype=input_details["dtype"])
interpreter.set_tensor(input_details["index"], sample)
interpreter.invoke()  # warm-up pass

runs = 20
start = time.perf_counter()
for _ in range(runs):
    interpreter.invoke()
elapsed = (time.perf_counter() - start) / runs * 1000

print("Mode: %s" % ("NPU" if use_npu else "CPU"))
print("Average latency: %.2f ms" % elapsed)

先在 CPU 上运行，然后在 NPU 上运行：

python3 benchmark.py
python3 benchmark.py --use-npu

在运行 Ubuntu 24.04 的 VENTUNO Q 上，结果为：

Mode	Average latency	Speedup
CPU	440.42 ms	—
NPU	12.60 ms	~35x

测得的 NPU 数据接近导出期间 AI Hub 估计的 10.8 ms，这是图按分析器预测方式运行的好迹象。

说明：

说明： 第一次 NPU 运行比后续运行明显更长。delegate 必须在第一次推理前为 Hexagon™ 硬件准备并完成图，这就是为什么上面的脚本在计时前执行预热过程。

运行模型的参考演示

除了自己运行导出的模型外，qai-hub-models 还为每个模型附带参考演示。这些对于检查模型是否按预期表现，以及查看模型所需的确切前/后处理很有用。

说明：

说明： 这些演示在 CPU 上运行模型的原始 PyTorch 权重，而不是在 NPU 上。--quantize w8a8 标志模拟量化模型的数值，但不会将图调度到 Hexagon™ 硬件。演示的 --eval-mode on-device 选项通过 AI Hub Workbench 在云托管设备上运行，而不是在你的开发板上。要在 VENTUNO Q 本身上使用 NPU，请遵循上方的 在 NPU 上运行导出的模型。

人脸检测示例

Lightweight Face Detection 模型是一个很好的起步示例。

对于此示例，有两种测试方式：

• 在静态图像上运行，见下文。
• 在来自相机的实时画面上运行，见 Real-Time Face Detection 教程（这需要将 USB 相机连接到 VENTUNO Q 的 USB-A 连接器）。

要设置它，请按以下步骤操作：

1. 通过运行 source .venv/bin/activate 激活我们之前创建的虚拟环境
2. 安装依赖 pip3 install numpy setuptools Cython shapely ai-edge-litert==1.3.0 Pillow
3. 通过运行 pip3 install --no-build-isolation "qai-hub-models[face-det-lite]" 安装人脸检测模型
4. 为示例创建目录，例如 face-detection-example，并使用 cd 进入该目录。

静态图像示例

运行静态图像示例很直接。首先，我们需要一张用于运行模型的示例图像。可通过以下命令直接下载：

wget https://cdn.edgeimpulse.com/qc-ai-docs/example-images/three-people-640-480.jpg

然后，运行推理：

python3 -m qai_hub_models.models.face_det_lite.demo --quantize w8a8 --image ./three-people-640-480.jpg --output-dir out/

首次运行会下载模型权重（约 3.6 MB），因此在推理开始前请多留一点时间。

这将在图像上运行推理，并在人脸上绘制方框。两个文件会写入 out/：

• FaceDetLitebNet_output.png — 在检测到的人脸上绘制了边界框的输入图像。
• FaceDetLitebNet_output.json — 原始检测结果。

图像已保存，可通过 adb pull /path/to/image 或 scp arduino@<ipaddress>:/path/to/image /path/to/local/folder 取回。图像路径 应该 是 ~/face-detection-example/out/FaceDetLitebNet_output.png。

结果应如下图所示：

<img src="" alt="处理后的图像" />

实时画面示例

模型也可以在来自 USB 相机的实时画面上运行，结果实时绘制在屏幕上。以下每个演练——包括完整脚本、模型下载步骤以及 CPU vs. NPU 对比——都已移至各自的教程：

• Real-Time Face Detection on the VENTUNO Q：使用 face_det_lite 模型进行实时人脸检测。
• Real-Time Face Mesh on the VENTUNO Q：使用 mediapipe_face 模型进行实时人脸检测与 468 点人脸网格。
• Real-Time Semantic Segmentation on the VENTUNO Q：使用 segformer_base 模型进行实时逐像素场景分割。

---

原文：https://docs.arduino.cc/tutorials/ventuno-q/getting-started-qc-ai-hub/ 本页为 Arduino 官方教程的中文翻译，供内部查阅。命令与代码保持原文。