在 Dragon Q6A（QCS6490）上部署 Qualcomm QAIRT SDK 2.42.0.251225

[azouyana]

平台：Radxa Dragon Q6A / Qualcomm QCS6490（Hexagon NPU = HTP v68）
系统：Ubuntu 24.04.4 LTS (Noble) aarch64
内核：6.18.2-3-qcom
QAIRT：2.42.0.251225（官方指定版本）
部署日期：2026-11-10

---

一、QAIRT 是什么

QAIRT（Qualcomm® AI Runtime）SDK 是一个集成包，包含三个主要产品：

QAIRT 支持把 PyTorch / TensorFlow / TFLite / ONNX 模型移植到高通硬件上，推理时可用 CPU、GPU、NPU。

模型移植的整体流程：

flowchart LR
    A[预训练浮点模型<br/>pt/tf/tflite/onnx] --> B[qairt-converter<br/>→ 浮点 DLC]
    B --> C[qairt-quantizer<br/>→ 量化 DLC]
    C --> D[qnn-context-binary-generator<br/>→ context binary .bin]
    D --> E[板端 qnn-net-run<br/>NPU 推理]

⚠️ 关键点：前 3 步必须在 x86 Linux 主机上完成，板端只负责推理。

---

二、环境检查

uname -a
# Linux radxa-dragon-q6a 6.18.2-3-qcom #3 SMP PREEMPT_DYNAMIC ... aarch64 GNU/Linux

cat /etc/os-release | head -3
# PRETTY_NAME="Ubuntu 24.04.4 LTS"
# NAME="Ubuntu"
# VERSION_ID="24.04"

nproc        # 8
free -h      # 5.1 GiB
df -h /      # 28G，可用 21G

QAIRT SDK 解压后约 3.6 GB，加上压缩包（1.4 GB），建议预留 ≥ 8 GB 空闲空间。

---

三、下载 SDK

官方文档给出的命令是：

wget https://softwarecenter.qualcomm.com/api/download/software/sdks/Qualcomm_AI_Runtime_Community/All/${QAIRT_VERSION}/v${QAIRT_VERSION}.zip

🕳 坑 1：QAIRT_VERSION 未设置 → 404

如果直接复制这条命令而没先 export QAIRT_VERSION，URL 会变成 /All//v.zip：

--2026-11-10 06:30:11--  .../Qualcomm_AI_Runtime_Community/All//v.zip
HTTP request sent, awaiting response... 404 Not Found
2026-11-10 06:30:13 ERROR 404: Not Found.

正确做法：QCS6490 必须使用 2.42.0.251225 这个版本。

export QAIRT_VERSION=2.42.0.251225

mkdir -p ~/QAIRT && cd ~/QAIRT
wget -c --progress=dot:giga -O "v${QAIRT_VERSION}.zip" \
  "https://softwarecenter.qualcomm.com/api/download/software/sdks/Qualcomm_AI_Runtime_Community/All/${QAIRT_VERSION}/v${QAIRT_VERSION}.zip"

下载过程说明：

• 链接会 301 跳转到 apigwx-aws.qualcomm.com，wget 会自动跟随；
• 文件大小 1,543,955,191 字节（约 1.4 GiB）；
• 我这边下载到 70% 时连接被服务器断开，-c 自动断点续传并顺利完成，**强烈建议加上 -c**。

2026-11-10 06:41:59 (3.15 MB/s) - Connection closed at byte 1083138280. Retrying.
2026-11-10 06:42:00 - (try: 2) ... 206 Partial Content
2026-11-10 06:42:42 (10.7 MB/s) - 'v2.42.0.251225.zip' saved [1543955191/1543955191]

---

四、解压 SDK

sudo apt install -y unzip
cd ~/QAIRT
unzip -q v${QAIRT_VERSION}.zip

解压后目录结构：

~/QAIRT/qairt/2.42.0.251225/
├── bin/          # x86_64-linux-clang（主机工具）+ aarch64-*-linux-gcc*（板端运行库）
├── lib/          # 各架构的动态库 + hexagon-v68 等 NPU 骨架库
├── include/      # QNN / SNPE / Genie 头文件
├── examples/     # 示例代码与模型
├── docs/         # QNN / SNPE / Genie 离线文档
└── sdk.yaml      # 版本信息

🕳 坑 2：用 python3 -m zipfile 解压会丢失可执行权限

如果系统没有 unzip（Ubuntu 24.04 最小镜像默认没有），退而求其次用 Python 解压时，可执行位会丢失，之后运行工具会直接报：

bash: ./bin/aarch64-oe-linux-gcc11.2/qnn-platform-validator: Permission denied

两种修复方式：

# 方式一：装好 unzip 重新解压
sudo apt install -y unzip && unzip -q -o v${QAIRT_VERSION}.zip

# 方式二：直接补可执行权限
find qairt/${QAIRT_VERSION}/bin -type f -exec chmod +x {} \;

---

五、安装系统依赖

sudo apt update
sudo apt install -y unzip clang python3-dev libgtk-3-dev libasound2-dev \
     libgbm-dev libflatbuffers-dev flatbuffers-compiler rename \
     libc++-dev libc++abi-dev nodejs npm

用 SDK 自带的检查脚本确认：

cd ~/QAIRT/qairt/2.42.0.251225
./bin/check-linux-dependency.sh -n     # -n = dry run，只检查不安装

实际输出（Ubuntu 24.04）：

Warning: Ubuntu Versions 20.04 and 22.04 are supported. Detected Ubuntu version 24.04
Checking for libncurses5
dpkg-query: no packages found matching libncurses5
Checking for libgl1
Checking for clang
Checking for libc++-dev
Checking for libc++abi-dev
Checking for flatbuffers-compiler
Checking for libflatbuffers-dev
Checking for rename
=============================================================
Missing required packages: libncurses5

🕳 坑 3：libncurses5 在 Ubuntu 24.04 已不存在

libncurses5 在 Noble 源里已经被移除，装不上也不影响 NPU 推理（只是老版本终端 UI 工具需要）。
在 24.04 上跑 bin/check-python-dependency 还会直接报：

[ERROR] Unsupported Ubuntu version 24.04.

—— 这是脚本自己写死了只认 20.04 / 22.04，忽略即可。工具链检查则正常：

./bin/envcheck -c
# Checking Clang Environment
# [INFO] Found clang++ at /usr/bin/clang++

---

六、配置环境变量

🕳 坑 4：bin/envsetup.sh 是给 x86 主机用的

SDK 自带的 envsetup.sh 会把 PATH / LD_LIBRARY_PATH 指向 x86_64-linux-clang：

# envsetup.sh 内部逻辑（节选）
export PATH=${QAIRT_SDK_ROOT}/bin/x86_64-linux-clang:${PATH}
export LD_LIBRARY_PATH=${QAIRT_SDK_ROOT}/lib/x86_64-linux-clang

在 aarch64 板子上 source 之后，qnn-net-run 会被解析到 x86 二进制，执行时报 Exec format error。
板端必须改成 aarch64 目录，所以我自己写了一个 qairt_env.sh：

cat > ~/QAIRT/qairt_env.sh << 'EOF'
#!/bin/bash
# QAIRT SDK 环境变量 (Radxa Dragon Q6A / QCS6490, aarch64 目标端)
export QAIRT_VERSION=2.42.0.251225
export QAIRT_SDK_ROOT=${HOME}/QAIRT/qairt/${QAIRT_VERSION}

# QNN / SNPE 向后兼容变量
export QNN_SDK_ROOT=${QAIRT_SDK_ROOT}
export SNPE_ROOT=${QAIRT_SDK_ROOT}

# 板端(aarch64)可执行工具
case ":${PATH}:" in
  *":${QAIRT_SDK_ROOT}/bin/aarch64-oe-linux-gcc11.2:"*) ;;
  *) export PATH=${QAIRT_SDK_ROOT}/bin/aarch64-oe-linux-gcc11.2:${PATH} ;;
esac

# 板端(aarch64)动态库
case ":${LD_LIBRARY_PATH}:" in
  *":${QAIRT_SDK_ROOT}/lib/aarch64-oe-linux-gcc11.2:"*) ;;
  *) export LD_LIBRARY_PATH=${QAIRT_SDK_ROOT}/lib/aarch64-oe-linux-gcc11.2${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} ;;
esac

# Hexagon NPU 骨架库（QCS6490 = HTP v68）
export ADSP_LIBRARY_PATH="${QAIRT_SDK_ROOT}/lib/hexagon-v68/unsigned;/dsp"

# QAIRT Python API
case ":${PYTHONPATH}:" in
  *":${QAIRT_SDK_ROOT}/lib/python:"*) ;;
  *) export PYTHONPATH=${QAIRT_SDK_ROOT}/lib/python${PYTHONPATH:+:${PYTHONPATH}} ;;
esac

echo "[INFO] QAIRT ${QAIRT_VERSION} 环境已配置"
echo "[INFO] QAIRT_SDK_ROOT = ${QAIRT_SDK_ROOT}"
echo "[INFO] NPU arch        = v68 (QCS6490)"
EOF

chmod +x ~/QAIRT/qairt_env.sh
source ~/QAIRT/qairt_env.sh

验证：

which qnn-net-run
# /home/radxa/QAIRT/qairt/2.42.0.251225/bin/aarch64-oe-linux-gcc11.2/qnn-net-run

建议把这句 source ~/QAIRT/qairt_env.sh 写进 ~/.bashrc。

关于 ADSP_LIBRARY_PATH

NPU 推理时，HTP 后端需要从 DSP 侧加载骨架库（skel）：

lib/hexagon-v68/unsigned/
├── libQnnHtpV68Skel.so      # QNN NPU 骨架库
├── libSnpeHtpV68Skel.so     # SNPE NPU 骨架库
├── libQnnHtpV68.so
├── libQnnSystem.so
├── libQnnSaver.so
└── libCalculator_skel.so

所以 ADSP_LIBRARY_PATH 必须同时包含宿主机路径和 /dsp（DSP 默认搜索路径）：

export ADSP_LIBRARY_PATH="$QAIRT_SDK_ROOT/lib/hexagon-v68/unsigned;/dsp"

---

七、验证 NPU 是否可用

1) 后端能力检查

qnn-platform-validator --backend all

Backend GPU Prerequisites: Present.
Backend DSP Prerequisites: Present.
*********** Results Summary ***********
Backend = GPU
{
  Backend Hardware  : Supported
  Backend Libraries : Found
  ...
}
Backend = DSP
{
  Backend Hardware  : Supported
  Backend Libraries : Found
  ...
}

出现 Error in saving the results 属于该工具在 Ubuntu 24.04 上的小毛病（它想把结果写到默认路径失败），不影响校验结论。

2) 在 NPU 上跑一次真实计算（强烈推荐）

qnn-platform-validator --backend dsp --testBackend

PF_VALIDATOR: DEBUG: dlOpen successfull for library : libcdsprpc.so
Backend DSP Prerequisites: Present.
PF_VALIDATOR: DEBUG: Starting calculator test
PF_VALIDATOR: DEBUG: Loading sample stub: libQnnHtpV68CalculatorStub.so
PF_VALIDATOR: DEBUG: Success in executing the sum function
Unit Test on the backend DSP: Passed.
QNN is supported for backend DSP on the device.

这一步会真的把计算下发到 Hexagon NPU 并取回结果，出现 Passed 就说明 NPU 栈完全打通了。

3) 确认 NPU 架构与版本

qnn-platform-validator --backend dsp --libVersion --coreVersion

Backend = DSP
{
  Backend Hardware  : Supported
  Backend Libraries : Found
  Core Version      : Hexagon Architecture V68
  ...
}

V68 正是 QCS6490 的 NPU 架构（对应转换配置中的 dsp_arch: v68 / soc_id: 35）。

---

八、跑模型

🕳 坑 5：板端不能做模型转换

qairt-converter 虽然是个 Python 脚本，但依赖原生扩展 libDlModelToolsPy，SDK 里只提供了 linux-x86_64 版本：

lib/python/qti/aisw/dlc_utils/
├── linux-x86_64/     ← 只有这个
├── windows-x86_64/
└── windows-arm64ec/

在板子上强行运行会报：

ImportError: libpython3.10.so.1.0: cannot open shared object file: No such file or directory
ImportError: cannot import name 'libDlModelToolsPy' ...

所以 ONNX/TFLite/TF/Torch → DLC → context binary 这一整套流程必须在 x86 Ubuntu 22.04 + Python 3.10 主机上完成，
板端只拿最终产物。

主机端（x86）流程速查

# 1. 转 DLC
qairt-converter --input_network resnet50.onnx --output_path resnet50.dlc -d input 1,3,224,224

# 2. 量化（需要校准数据 raw + 列表文件）
qairt-quantizer --input_dlc resnet50.dlc --input_list calib_list.txt --output_dlc resnet50_quantized.dlc

# 3. 生成 context binary（QCS6490 配置）
cat > config_backend.json << 'EOF'
{
  "graphs": [ { "graph_names": ["resnet50"], "vtcm_mb": 0 } ],
  "devices": [ { "dsp_arch": "v68", "soc_id": 35 } ]
}
EOF
cat > config_file.json << 'EOF'
{
  "backend_extensions": {
    "shared_library_path": "libQnnHtpNetRunExtensions.so",
    "config_file_path": "config_backend.json"
  }
}
EOF

qnn-context-binary-generator --model libQnnModelDlc.so --backend libQnnHtp.so \
    --dlc_path resnet50_quantized.dlc --output_dir output \
    --binary_file resnet50 --config_file config_file.json

SoC	dsp_arch	soc_id
QCS6490	v68	35
SC8280XP	v68	37
QCS9075	v73	77

板端（QCS6490）推理

✅ 前置条件：以下 3 个文件必须由 x86 主机生成后拷到板端，缺一不可：

1. resnet50_quantized.bin —— 主机上用 dsp_arch: v68 / soc_id: 35 生成的 context binary
2. test_list.txt —— 每行一个 .raw 输入文件的路径
3. *.raw 测试输入数据（resnet50 为 1x3x224x224 float32）

source ~/QAIRT/qairt_env.sh
cd ~/resnet50_qairt_example/model

qnn-net-run \
  --backend $QAIRT_SDK_ROOT/lib/aarch64-oe-linux-gcc11.2/libQnnHtp.so \
  --retrieve_context ./resnet50_quantized.bin \
  --input_list ./test_list.txt \
  --output_dir ./output_bin

如果文件没准备好，会直接报错（实测）：

 <W> Initializing HtpProvider
     0.9ms [ ERROR ] Failed to open input file: ./test_list.txt
Could not readInputListsV2

🕳 坑 6：SDK 自带的示例 .bin 不能在 6490 上加载

examples/QNN/converter/models/ 下自带两个 context binary：

qnn_model_float.bin
qnn_model_8bit_quantized.bin

它们在 QCS6490 上加载会报（因为是为其它 HTP 架构生成的）：

Creating context from binary file: ./models/qnn_model_8bit_quantized.bin
   348.7ms [ ERROR ] Could not create context from binary
Create From Binary failure

context binary 与 backend 架构强绑定，必须用 dsp_arch: v68 / soc_id: 35 重新生成。

---

九、常见问题 FAQ

现象	原因	解决
ERROR 404: Not Found，URL 里出现 /All//v.zip	没设置 QAIRT_VERSION	export QAIRT_VERSION=2.42.0.251225
Permission denied（运行 bin 下工具）	用 python3 -m zipfile 解压丢了执行位	find bin -type f -exec chmod +x {} \;
Exec format error	source 了给 x86 用的 envsetup.sh	板端改用 aarch64 路径（见第六章）
Could not create context from binary	context binary 的 dsp_arch/soc_id 与设备不符	用 v68 / 35 重新生成
libncurses5 装不上	Ubuntu 24.04 已移除该包	忽略，不影响 NPU
Unsupported Ubuntu version 24.04	SDK 脚本写死只支持 20.04/22.04	忽略检查脚本告警
SNPE 校验报 libadsprpc.so 缺失	SNPE 校验器找的是旧库名，QCS6490 用的是 libcdsprpc.so	以 QNN 校验结果为准
板端跑 qairt-converter 报 libpython3.10.so.1.0	转换器无 aarch64 原生扩展	转换放在 x86 主机做

---

十、备选方案：用官方 Docker 镜像

不想手动折腾的话，Radxa 提供了已经装好 QAIRT 的 ARM64 镜像：

sudo apt install -y docker.io
sudo docker pull radxazifeng278/qairt-npu-v68:v1.2

sudo docker run --privileged -it -v /dev:/dev -v $(pwd):/workspace \
  --name qairt-sdk radxazifeng278/qairt-npu-v68:v1.2 /bin/bash

---

十一、部署成果汇总

项目	结果
SDK 版本	QAIRT 2.42.0.251225（QNN backend API 2.18.0）
解压路径	~/QAIRT/qairt/2.42.0.251225（3.6 GB）
环境脚本	~/QAIRT/qairt_env.sh
GPU 后端	✅ Supported
DSP/NPU 后端	✅ Supported
NPU 架构	Hexagon V68（QCS6490）
NPU 单元测试	✅ Passed
磁盘占用	28G 中已用 13G（部署前 5.9G）

---

十二、参考链接

• Radxa 官方文档：https://docs.radxa.com/dragon/q6a/app-dev/npu-dev/qairt-install
• QAIRT 使用示例：https://docs.radxa.com/dragon/q6a/app-dev/npu-dev/qairt-usage
• QAIRT CLI 工具：https://docs.radxa.com/dragon/q6a/app-dev/npu-dev/qairt-tools
• Qualcomm QNN 文档：https://docs.qualcomm.com/bundle/publicresource/topics/80-63442-50/introduction.html
• Qualcomm SNPE 文档：https://docs.qualcomm.com/bundle/publicresource/topics/80-63442-2/overview.html
• Qualcomm Genie 文档：https://docs.qualcomm.com/bundle/publicresource/topics/80-63442-100/introduction.html
• 离线文档（SDK 内）：qairt/2.42.0.251225/docs/{QNN,SNPE,Genie}

[azouyana]

下一步计划使用qairt-converter把模型转成 DLC，跑在这块板子上

[azouyana]

下一步计划使用qairt-converter把模型转成 DLC，跑在这块板子上