1. 简介

本文将围绕 QAI AppBuilder 3.0 展开，介绍其在高通平台 Windows on Snapdragon（WoS）与 Linux 环境下的安装、配置、示例运行以及典型应用体验。与以往主要聚焦“模型推理接口封装”的版本相比，QAI AppBuilder 3.0 的定位更加完整：它不仅帮助开发者更方便地在 Qualcomm NPU/HTP 上运行 QNN、DLC 和 Genie 等模型能力，也进一步引入了以 AI Agent 为核心的一站式应用开发流程。开发者可以用自然语言描述目标应用，由 Agent 辅助完成模型获取、格式转换、工程生成、运行验证和部署集成，从而显著降低端侧 AI 应用从原型到落地的门槛。

对于首次接触 QAI AppBuilder 的开发者，建议先登录高通开发者账号，并按照官方仓库 Get Started 部分提供的 下载 链接下载QAI AppBuilder，登录高通账号后，开发者就可以获得 1000 万免费 Token（通过Route 1使用），用于体验 QAI AppBuilder 3.0 的 Agent 能力，包括自然语言生成应用、调用云端 Agent 辅助构建工程，以及将生成结果部署到本地高通平台进行验证。本文作为系列第一篇，将先聚焦 QAI AppBuilder 基础的推理引擎功能、以及环境搭建与示例运行；后续文章会继续深入介绍 ModelBuilder、Agent 工作流以及更复杂的端侧 AI 应用开发实践。

1.1 什么是 QAI AppBuilder？

QAI AppBuilder（Quick AI Application Builder）是高通面向端侧 AI 应用开发推出的开源开发框架，构建在 Qualcomm® AI Runtime SDK 之上，面向 Windows on Snapdragon、Linux 等高通平台提供统一的模型加载、推理执行与应用集成能力。它将底层 Qualcomm AI Runtime / QNN 接口封装为更易使用的 Python 与 C++ API，使开发者能够更快速地在 CPU、GPU 和 NPU（HTP）等不同计算单元上部署和运行 AI 模型。

在 QAI AppBuilder 3.0 中，它的价值不再只是“更简单的推理引擎”，而是进一步扩展为 Agent 驱动的一站式 AI 应用开发平台。开发者可以从一个自然语言需求出发，让 AI Agent 帮助完成应用框架搭建、模型下载与选择、模型格式转换、端侧运行配置、示例代码生成以及部署验证等步骤。对于希望快速验证端侧 AI 创意、构建原型 Demo 或将模型能力集成到实际应用中的开发者，这种方式可以显著减少手写工程代码和反复查阅底层接口文档的成本。

因此，QAI AppBuilder 3.0 可以理解为连接“模型能力”和“端侧应用”的中间层：向下，它屏蔽不同硬件后端、运行时和模型格式的复杂差异；向上，它提供示例、API、WebUI、Genie 服务以及 Agent 化开发入口，让开发者能够以更低门槛在 Qualcomm NPU 上构建视觉、语音、多模态和大语言模型应用。通过高通开发者账号登录并使用 Route 1，开发者还可以获得 1000 万免费 Token，用于体验 3.0 版本的一站式 Agent 开发流程。

1.2 主要新特性

✅ NPU/GPU/CPU 推理支持

支持在 骁龙设备上加载和运行以下模型格式：

• QNN Context Binary（.bin）
• QNN Model Library（.dll）
• SNPE DLC（.dlc）

可利用：

• NPU（Hexagon）
• GPU
• CPU

进行硬件加速推理。

✅ 双语言 API

提供完整的：

• C++ API
• Python API

方便与现有项目集成。

✅ 跨平台支持

采用统一 API 设计，同步支持：

• Windows on Snapdragon（ARM64）
• Linux 环境

✅ 预构建模型

可自动从高通预优化模型库下载并运行经过优化的模型，无需额外进行模型转换或适配。

✅ 大语言模型支持（Genie）

通过 GenieAPIService 在本地离线运行：

• Llama 3
• Qwen 3
• Gemma 2

提供兼容 OpenAI API 的接口。

✅ 原生量化输入输出

支持：

• Native Quantized I/O
• Float I/O
• Multi-Graph Session
• LoRA Adapter

提高吞吐量与灵活性。

✅ 多模态 AI 支持

支持：

• 视觉处理
• 语音处理
• 文本处理

内置模型包括：

• Whisper（语音识别）
• MeloTTS（语音合成）
• PP-OCR（OCR识别）
• 超分辨率
• 目标检测模型

1.3 系统架构

1.4 适用平台

• Windows on Snapdragon (WoS)：骁龙AI PC
• Linux：高通跃龙™ IQ-9075, QCM6490 Ubuntu
• Android: 骁龙® 8 至尊版，第五代骁龙® 8 至尊版
• 架构支持：ARM64, ARM64EC

1.5 QAI AppBuilder 3.0功能

新增QAI AppBuilder 3.0功能，开发者只需通过自然语言描述需求，即可完成模型下载、格式转换、量化优化、推理验证和部署集成，从而显著降低端侧 AI 应用的开发与部署门槛。

2. 环境准备和编译

2.1 Windows 环境配置

步骤 1：安装依赖软件

1. 安装 Git

# 下载 Git for ARM64
https://github.com/dennisameling/git/releases/download/v2.47.0.windows.2/Git-2.47.0.2-arm64.exe

2. 安装 Python 3.12.8

使用 x64 版本 可获得更好的 Python 扩展生态(当前相对来说，有更多的 Python 扩展可在x64 Python 环境中运行，而对于 ARM64 Python，有部分扩展需要自己编译)：

# 下载 Python 3.12.8 x64
https://www.python.org/ftp/python/3.12.8/python-3.12.8-amd64.exe

或使用 ARM64 版本 以获得更好的性能：

# 下载 Python 3.12.8 ARM64
https://www.python.org/ftp/python/3.12.8/python-3.12.8-arm64.exe

⚠️ 重要提示：

• 安装时必须勾选 "Add python.exe to PATH"
• 如果系统中有多个 Python 版本，确保新安装的版本在 PATH 环境变量的首位

验证 Python 版本顺序：

where python

3. 安装 Visual C++ Redistributable

# 下载并安装
https://aka.ms/vs/17/release/vc_redist.x64.exe
https://aka.ms/vs/17/release/vc_redist.arm64.exe

步骤 2：克隆 QAI AppBuilder 仓库

# 克隆仓库
git clone https://github.com/qualcomm/qai-appbuilder.git --recursive

# 如果已克隆，更新代码
cd qai-appbuilder
git pull --recurse-submodules

步骤 3：安装或编译 QAI AppBuilder Python 扩展

1. 直接运行'pip install qai-appbuilder'来安装， 或者从 GitHub Release 下载对应版本的 .whl 文件，再运行：

# 对于 x64 Python
pip install qai_appbuilder-{version}-cp312-cp312-win_amd64.whl

# 对于 ARM64 Python
pip install qai_appbuilder-{version}-cp312-cp312-win_arm64.whl

2. 编译自己需要的qai-appbuilder whl版本

下载安装Qualcomm® AI Runtime SDK： Qualcomm® Software Center

安装Visual Studio 2022:  Visual Studio 2022 Release History | Microsoft Learn

安装x64 或者arm64 python 3.12版本，并安装依赖项

pip install wheel==0.45.1 setuptools==80.9.0 pybind11==2.13.6 build==1.4.0

将环境变量“QNN_SDK_ROOT”设置为您正在使用的Qualcomm® AI Runtime SDK路径。例如：

Set QNN_SDK_ROOT=C:\Qualcomm\AIStack\QAIRT\2.48.40.260702\

使用以下命令构建并安装Python扩展（*.whl）：

*注：请从支持的骁龙设备列表中获取与您的设备对应的“支持的工具链”和“Hexagon架构”。

cd qai-appbuilder

Note: 务必在常规的Windows命令提示符中构建——而非在“VS 2022 ARM64原生工具命令提示符”或“PowerShell”窗口中。

set QNN_SDK_ROOT=C:/Qualcomm/AIStack/QAIRT/2.48.40.260702/

python -m build -w

# 安装wheel安装包:
pip install --force-reinstall dist\qai_appbuilder-2.48.40

2.2 Linux 环境配置

步骤 1：安装依赖软件

1. 安装基础工具

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y git python3.12 python3.12-dev python3-pip build-essential

# 验证安装
python3 --version
pip3 –version

2. 安装 Python 依赖

# 安装常用的 Python 库
pip3 install numpy pillow opencv-python wheel==0.45.1 setuptools==80.9.0 pybind11==2.13.6 build==1.4.0

3.下载 Qualcomm® AI Runtime（QAIRT）SDK

下载QAIRT SDK 包
wget 
https://softwarecenter.qualcomm.com/api/download/software/sdks/Qualcomm_AI_Runtime_Community/All/2.48.40.260702/v2.48.40.260702.zip

# 解压文件
unzip v2.48.40.260702.zip

# 验证文件
ls v2.48.40.260702/

步骤 2：克隆 QAI AppBuilder 仓库

# 克隆仓库
git clone https://github.com/qualcomm/qai-appbuilder.git --recursive

# 如果已克隆，更新代码
cd qai-appbuilder
git pull --recurse-submodules

步骤 3：安装或编译 QAI AppBuilder Python 扩展

1.直接运行'pip install qai-appbuilder'来安装， 或者从 GitHub Release 下载对应版本的 .whl 文件，再运行：

# 对于 Linux ARM64
pip3 install qai_appbuilder-{version}-cp312-cp312-linux_aarch64.whl

2.或者编译自己需要的qai-appbuilder whl版本：

将环境变量“QNN_SDK_ROOT”设置为您正在使用的Qualcomm® AI Runtime SDK路径。例如：

export QNN_SDK_ROOT=<path_to_v2.48.40.260702>

编译命令：

python -m build -w

编译完成后，生成的wheel包将保存在dist/目录下面

安装wheel包：

python -m pip install dist/qai_appbuilder-*.whl

Note: 版本号是基于你QNN SDK的版本

验证安装包：

python -c "import qai_appbuilder; print('QAI AppBuilder installed successfully')"

3. QAI AppBuilder 示例代码运行指南

samples目录包含所有 QAI AppBuilder 示例代码，按类别组织。示例涵盖 28 个 AI 模型的 Python 推理脚本、Gradio Web UI 应用、Genie LLM API 服务等示例— 所有这些都通过 QAI AppBuilder 在 Qualcomm NPU (HTP) 上运行。

目录结构：

samples/

├── run_inference.py          # 所有 Python 推理示例的交互式启动器
├── models/                   # AI 模型推理示例（按领域划分）
│   ├── audio/                # 音频模型（语音合成、语音识别、音频分类等）
│   ├── computer_vision/      # 计算机视觉模型
│   ├── generative_ai/        # 生成式 AI 模型（Stable Diffusion 等）
│   └── multimodal/           # 多模态模型（OCR、翻译、CLIP、视觉语言模型等）
├── apps/                     # 完整的 AI 应用程序
│   ├── webui/                # 基于 Gradio 的 WebUI 应用（image-repair、stable-diffusion、genie-chat）
│   ├── android/              # Android 示例应用（genie-chat、super-resolution）
│   ├── genie-flet-ui/        # 基于 Flet 的桌面端 UI
│   └── story-seed/           # 自动化故事生成应用
├── genie/                    # Genie 大语言模型 API 服务
│   ├── python/               # Python 版 OpenAI 兼容服务（GenieAPIService.py）
│   └── c++/                  # C++ 版 OpenAI 兼容服务（Service/、Android/）
├── shared/                   # 公共工具与共享组件
│   ├── python/               # 共享 Python 模块（install.py、 image_processing.py 等）
│   └── cpp/                  # 共享 C++ 依赖库（OpenCV）
└── tools/                    # 实用工具（wget、aria2c）

`run_inference.py` 是所有 Python 推理示例的交互式启动器。从 `samples/` 目录运行：

cd qai-appbuilder\samples

# 交互式菜单
python run_inference.py

# 列出所有可用模型
python run_inference.py --list

# 直接运行特定模型
python run_inference.py --model <model_name>

# 带参数运行
python run_inference.py --model <model_name> --args "<extra_args>"

# 查看模型帮助
python run_inference.py --help-model <model_name>

3.1环境配置和python脚本运行：

步骤1：安装python依赖项

pip install huggingface_hub==0.33.1 Pillow==10.4.0 numpy==1.26.4 torch==2.4.1 torchvision==0.19.1 torchaudio==2.4.1 transformers==4.46.3 sentencepiece diffusers==0.32.2 tqdm==4.67.1 scikit-image==0.25.2 pygame==2.6.1 ftfy==6.3.1 av==15.0.0 resampy==0.4.3 soundfile==0.13.1 easyocr==1.7.2 samplerate==0.2.1 audio2numpy==0.1.2 ultralytics==8.0.193 opencv-python-headless==4.11.0.86 opencv-python==4.10.0.84 openai-whisper==20250625 openai-clip==1.0.1 gruut==2.4.0

ARM64 Windows 注意（`easyocr`）：在 ARM64 Windows（Python 3.13+）上，`easyocr` 无法直接安装，因为其依赖 `Shapely` 没有预编译的 ARM64 wheel。使用以下两步安装：
 

pip install scikit-image python-bidi pyclipper ninja imageio tifffile lazy-loader

pip install easyocr --no-deps

你也可以通过QAI AppBuilder Launcher（tools/launcher or launcher_linux）下面，通过对应步骤的脚本去安装环境

步骤2：设置QAI AppBuilder和QNN库

cd qai-appbuilder\samples\shared\python
python setup.py

Note：该配置步骤仅适用于 Windows on Snapdragon（WoS）平台。

Python 推理示例：

运行python run_inference.py

先选择需要的模型选项，然后输入需要的参数，比如目前samples支持WoS和9075，6490两个linux平台

输入参数，例如：--chipset 9075

程序将会匹配对应的平台和模型，然后下载模型后，进行推理导出结果

Linux系统支持的Qwen-vl模型：

1.安装Python依赖项安装：

pip install requests==2.32.3 \

         py3-wget==1.0.12 \

         tqdm==4.67.1 \

         importlib-metadata==8.5.0 \

         qai-hub==0.30.0 \

         opencv-python==4.10.0.82 \

         gradio



pip install transformers==4.57.0 torch==2.9.1

pip install torchvision>=0.9.0

pip install qwen-vl-utils

2.下载模型：

wget https://www.aidevhome.com/data/adh2/models/suggested/qwen2vl2b.zip

unzip qwen2vl2b.zip

3.运行命令：

Qwen2-VL (default):

python models/multimodal/vision_language_model/qwen_vl/python/qwen_vl.py --model qwen2 --path models/multimodal/vision_language_model/qwen_vl/models/qwen2

3.2 Genie LLM API 服务

Genie LLM API Service 是一套兼容 OpenAI API 规范的大语言模型服务框架，可基于 Genie SDK 在 Qualcomm NPU 上本地部署并运行 LLM。

特性：

• - OpenAI 兼容 REST API（端口 8910）
• - 流式和非流式响应模式
• - 工具/函数调用支持
• - 思考模式（支持的模型）
• - 运行时模型切换
• - 通过 Stable Diffusion v2.1 生成图像

安装依赖：

pip install uvicorn==0.34.0 pydantic_settings==2.10.1 fastapi==0.115.8 langchain==0.3.19 langchain_core==0.3.45 langchain_community==0.3.18 sse_starlette==2.2.1 pypdf==5.3.0 python-pptx==1.0.2 docx2txt==0.8 openai==1.63.2 json-repair==0.47.4

下载模型：

wget https://qaihub-public-assets.s3.us-west-2.amazonaws.com/qai-hub-models/models/ibm_granite_v3_1_8b_instruct/v1/snapdragon_x_elite/models.zip

wget https://huggingface.co/ibm-granite/granite-3.1-8b-base/resolve/main/tokenizer.json

将解压后模型和tokenizer 文件放到对应的qai-appbuilder/samples/genie/python/models/IBM-Granite-v3.1-8B

启动服务：

cd qai-appbuilder\samples

python genie\python\GenieAPIService.py --modelname "IBM-Granite-v3.1-8B" --loadmodel –profile

3.2 WebUI 应用

基于 Gradio 的 Web 应用，在Qualcomm NPU 上运行。

3.2.1 ImageRepairApp

图像超分辨率应用，使用 Real-ESRGAN General x4v3。上传图像 → 4× 增强输出，带前后对比滑块。

运行命令：

python apps\webui\image-repair\ImageRepairApp.py –soc_id wos

3.2.2 GenieWebUI

LLM 聊天应用。通过 OpenAI 兼容 API 连接到 GenieAPIService。先启动 GenieAPIService。

运行命令：

python apps\webui\genie-chat\GenieWebUI.py

Note: 需先启动GenieAPIService才能正常启动GenieWebUI

支持LLM模型：

Model	Source
IBM Granite v3.1 8B	高通预优化模型库
Phi 3.5 Mini Instruct	高通预优化模型库
Qwen2-7B-SSD	aidevhome.com
Llama 3.2 3B	aidevhome.com
Llama 3.1 8B	aidevhome.com

3.2.3 StableDiffusionApp

文生图应用，使用 Stable Diffusion v2.1。支持提示词、负面提示词、步数、引导、种子、批次数。

运行命令：

python apps\webui\stable-diffusion\StableDiffusionApp.py

重要说明

1. 模型自动下载：所有 Python 推理示例在首次运行时自动从 高通预优化模型库 下载所需的 QNN 模型二进制文件，需要互联网连接。

2. WoS 上的 NMS：`torchvision.ops.nms` 需要 CUDA，在 Windows on Snapdragon 上可能无法工作。`_pose_estimation.py` 模块提供了兼容的实现。

3. ultralytics 版本：对于 `yolov8_det`，使用 `ultralytics==8.0.193`：  

pip install ultralytics==8.0.193

4. HuggingFace 访问：如果 HuggingFace 无法访问，设置：

set HF_ENDPOINT=https://hf-api.gitee.com

5. 平台支持：HTP (NPU) 运行时仅在骁龙平台上可用。在 x86 Windows 上，模型回退到 CPU + DLC 格式。

4. 总结与后续预告

作为 QAI AppBuilder 3.0 系列文章的第一篇，本文主要围绕 QAI AppBuilder 过去已经相对成熟的传统功能展开，包括 Windows on Snapdragon 与 Linux 环境下的安装配置、Python/C++ 推理接口、示例模型运行、Genie LLM API Service 以及 WebUI 应用等内容。通过这些基础实践，开发者可以先熟悉 QAI AppBuilder 作为端侧 AI 推理引擎和应用集成框架的基本使用方式，为后续进一步使用 3.0 版本的新能力打下基础。

在接下来的系列文章中，我们将不再局限于传统推理接口和示例运行，而是进一步展开 QAI AppBuilder 3.0 所强调的自然语言驱动开发体验。后续内容会陆续覆盖自动模型转换、量化与优化、Agent 编排、Skill 能力扩展等新特性，帮助开发者理解如何从一句自然语言需求出发，逐步完成模型准备、端侧优化、应用生成和运行验证。同时，我们也会结合更具体的实践场景，介绍如何基于 QAI AppBuilder 完成模型转换，并进一步开发面向视觉的端侧 AI 应用。整体来看，本系列将从“能跑起来”逐步过渡到“能自动化构建”和“能开发实际应用”，帮助开发者更系统地掌握 QAI AppBuilder 3.0 的完整开发链路。

作者姓名:  高通工程师，戴忠忠（Zhongzhong Dai）