dev-ansh-r QAIRT / QNN SDK preflight
Confirms the SDK on this machine can actually convert a model, and points at docs for the version installed rather than the newest published.
Needs QC_QNN_SDK_ROOT from .qualcomm-env — see First run below.
First run
This skill reads .qualcomm-env. Check the marker, not the file — a config
can exist and be half-written:
grep -q '^QC_SETUP_VERSION=' .qualcomm-env 2>/dev/null && echo ready || echo "run setup"
If it says run setup, run the qualcomm-setup skill first. It probes your
machines, asks only what it cannot discover, and writes the config once so no
other skill has to ask again.
If qualcomm-setup is not installed — you copied this skill on its own —
do not stop. Ask the two questions it would have asked, then continue:
- Which host runs the QAIRT SDK? (x86_64 Linux only; a Windows or macOS workstation must drive a remote one, and WSL2 counts as Linux)
- How is the board reached — SSH, ADB, or not available yet?
An empty field is not a blocker by itself. Where this skill needs one it will say which, and why.
Part 0 — can this host run the SDK at all?
Check this before anything else. It is a different question from "is the SDK installed", and it has a different answer.
uname -s # Linux / MINGW64_NT-* / Darwin
uname -m # must be x86_64
The QAIRT converters ship only as bin/x86_64-linux-clang. There is no
Windows or macOS build. On a non-Linux host the answer is not "install the
SDK" — it is "use a different host", and no amount of installing will change
that. Say so immediately rather than working through Part 1 and reporting seven
failures that all have one cause.
| Host | Verdict |
|---|---|
| x86_64 Linux | Can be the build host. Continue to Part 1 |
| Windows | Cannot. Git Bash and MSYS do not help — they are not Linux. WSL2 does, and is the usual answer |
| macOS | Cannot. Drive a Linux build host from it |
| aarch64 (the board) | Not a build host. It runs the output, it does not produce it |
A Windows or macOS workstation is still perfectly useful — it edits the source,
drives the build over SSH and deploys. That is the normal arrangement, not a
degraded one. See qualcomm-cross-compile for the loop.
Part 1 — dependency check
Run the vendor's own checker first
QAIRT ships a dependency script. It is authoritative for the platform packages; run it before diagnosing anything by hand.
source "$QNN_SDK_ROOT/bin/envsetup.sh"
bash "$QNN_SDK_ROOT/bin/check-python-dependency"
sudo bash "$QNN_SDK_ROOT/bin/check-linux-dependency.sh"
Both exist across the 2.2x–2.3x line. If either is missing, note the exact path that failed and continue with the manual checks — a missing checker is usually a partial extraction of the SDK tarball.
What a complete install has
| Check | Command | Failure meaning |
|---|---|---|
| x86 tool dir | ls $QNN_SDK_ROOT/bin/x86_64-linux-clang/ |
Tarball extracted partially |
| HTP arch libs | ls -d $QNN_SDK_ROOT/lib/hexagon-v*/ |
Blocks HTP entirely — see below |
| x86 backend libs | ls $QNN_SDK_ROOT/lib/x86_64-linux-clang/libQnn*.so |
No host-side simulation/validation |
| aarch64 runtime | ls $QNN_SDK_ROOT/lib/aarch64-oe-linux-gcc*/ |
Nothing to deploy to the board |
| Python bindings | python3 -c "import qti.aisw" |
Converters are Python; this is fatal |
| ONNX | pip show onnx onnxruntime |
Converter parses via onnx |
The HTP architecture check is the one that bites
ls -d "$QNN_SDK_ROOT"/lib/hexagon-v*/ 2>/dev/null
The v68 / v73 / v75 in those directory names is the Hexagon HTP
architecture version. This tells you what the SDK can build for; which one
your part needs is a separate question — determine it with
qualcomm-env-discovery (SoC id) and qualcomm-sdk-docs (the mapping, from
your SDK's own documentation).
Do not infer the architecture from the part number. Hexagon versions do not track SoC model numbers in any extrapolable pattern.
If your target architecture is absent, a context binary still builds on the host and then fails to load on the board, with a backend error that reads like a corrupt file. This costs hours if you do not check it up front. Fix by installing the matching Hexagon / HTP support package, not by rebuilding the model.
Python version compatibility
The converters pin a narrow Python range per QAIRT release, and it is often
older than the system Python. Symptom is an import error deep inside
qti.aisw, not a clean "unsupported version" message.
If import qti.aisw fails on a system Python, check the SDK's own bundled
Python or its documented version before debugging the traceback.
numpy and onnx versions can break the converter
numpy 2.x breaks QAIRT 2.37's shape inference [measured]. A working pin is
numpy 1.26.4 / onnx 1.12.0 in a dedicated converter virtualenv.
This is worth isolating deliberately: AIMET wants a recent torch/numpy, the converter wants an old numpy, and one environment cannot satisfy both. Two virtualenvs on the same host is the normal arrangement —
source ~/venvs/aimet/bin/activate # torch 2.5.x, aimet_onnx 2.x
source ~/venvs/convenv/bin/activate # numpy 1.26.4, onnx 1.12.0 <- converter
A converter failing deep inside shape inference, on a model that is fine, is the signature of this.
ONNX opset
Export models at opset 17 for QAIRT 2.37.x [measured] — the pipeline in
this repo's reference material was set explicitly with
g.opset_import[0].version = 17. Higher opsets may parse and then lower badly.
Part 2 — finding the right documentation
Order matters. The SDK-local docs match your install; the website does not.
For anything beyond a quick look, use the
qualcomm-sdk-docsskill — it extracts tool flags, operator tables and architecture identifiers out of your installed SDK into a greppable local cache, and checks a model's operators against it. The rest of this section is the manual equivalent.
1. SDK-local docs — always first
ls "$QNN_SDK_ROOT/docs/"
find "$QNN_SDK_ROOT/docs" -name 'index.html' | head
QAIRT ships a full HTML doc tree. It is version-exact — flags, supported ops and backend notes are for the bits on disk. Open it locally rather than searching the web.
The two pages worth knowing:
- Operator support / backend op definitions — which ONNX ops each backend (HTP, GPU, CPU) implements. This is what answers "will my model run on the NPU", and it is per HTP arch version.
- Tool reference — the real flag list for
qnn-onnx-converter,qairt-converter,qnn-context-binary-generatorfor this version.
2. Per-tool help — second
qnn-onnx-converter --help
qairt-converter --help
qnn-context-binary-generator --help
Authoritative and instant. Prefer this over any example in any skill, including the ones in this repo, when the two disagree.
3. Vendor site — last
Qualcomm's public docs sit behind a developer account and default to the
latest release. When you use them, pin the version explicitly and confirm
against --help before trusting a flag.
Useful public sources that are not auth-walled:
- AIMET docs and API reference (
quic.github.io/aimet-pages) — open source - The
quic/aimetGitHub repo — the actual API surface - Qualcomm AI Hub model zoo — working export configs for common architectures
Do not start this skill with a web fetch. If the SDK is installed, the answer is on disk.
Part 3 — report
Produce a go/no-go, not a log dump:
If Part 0 failed, the report is one line, not a table:
VERDICT: this host cannot run the QAIRT toolchain (Windows/macOS).
Nothing to install. Use a Linux build host (WSL2 counts) and
re-run this skill there.
Otherwise:
Host x86_64 Linux OK
QAIRT 2.37.1.250807 OK
HTP archs hexagon-v68,v73 OK (v68 present - QCS6490 target)
Python bindings qti.aisw importable OK
onnx / ort 1.16.0 / 1.17.1 OK
aarch64 runtime gcc11.2 OK
eSDK found OK
AIMET not installed -> QAIRT/DLC path unavailable on this host
Docs $QNN_SDK_ROOT/docs/index.html
VERDICT: ready for the classic flow (qnn-model-export).
For context binaries, AIMET must run on a separate host.
State the verdict in terms of which flow is open, since that is the decision the user is about to make. See the repo README for the fork.