AIPC, AI Porting Conversion. Tools and workflows for QAIRT/AIPC project setup, model conversion, inspection, operator patching, quantization, context-binary generation, and inference on Qualcomm platforms. Use this skill when creating or initializing an AIPC project, exporting AI models to ONNX, converting ONNX models to QNN or SNPE/DLC, converting models to FP16/FP32, patching unsupported operators, generating context binaries, or implementing inference for QNN/SNPE DLC.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
AIPC, AI Porting Conversion. Tools and workflows for QAIRT/AIPC project setup, model conversion, inspection, operator patching, quantization, context-binary generation, and inference on Qualcomm platforms. Use this skill when creating or initializing an AIPC project, exporting AI models to ONNX, converting ONNX models to QNN or SNPE/DLC, converting models to FP16/FP32, patching unsupported operators, generating context binaries, or implementing inference for QNN/SNPE DLC.
AIPC Toolkit
Trigger Phrases
Always activate this skill when the user mentions:
Conversion
"convert model to qnn" / "qnn conversion" / "convert to qnn"
"convert model to dlc" / "snpe conversion" / "convert to dlc"
Use this skill for Qualcomm QAIRT/QNN/SNPE model bring-up:
Export model to ONNX
Inspect ONNX I/O
Convert to QNN or SNPE/DLC
Quantize model
Generate context binaries
Run inference and validation
Create QAIRT/AIPC project
Required Guardrails
Run skill scripts from their original skill path unless explicitly noted
Do not swap out QAIRT toolchains ad-hoc
QAIRT_SDK_ROOT must be set
QAIRT_TMP_DIR — set when /tmp is full: qnn-onnx-converter copies external-data ONNX
weights to a temp directory before processing. On servers where /tmp is a small tmpfs, this
fails with Failed to copy external data to the disk at: /tmp/... permission or space issue.
Set QAIRT_TMP_DIR to a path with at least 2× the model's weight file size free:
export QAIRT_TMP_DIR=/path/with/enough/space # e.g. /workspace/qairt_tmp
Check before any converter call: df -h /tmp — if Use% is 100%, set QAIRT_TMP_DIR.
LONG-RUNNING JOBS — CRASH RESILIENCE (MANDATORY): Any operation expected to take >2 minutes
(conversion, context binary generation, inference) MUST be launched as a detached systemd service
so it survives agent session crashes:
NEVER use nohup ... & or tmux — both are killed when the agent session ends.
On Windows, do not rely on Python arch detection — use OS-native arch commands
On ARM64 Windows, platform.machine() returns AMD64 under x86_64 emulation.
Prefer the minimal QAIRT device probe script for SoC detection. Avoid CIM/WMI when possible.
Model library target must match the Python process arch, not the CPU arch:
Python scripts via subprocess.run() — no shell quoting issues
Inference execution policy (MANDATORY):
Run inference via scripts/aipc wrapper only.
MANDATORY: You MUST use the onnxwrapper.py provided within the aipc-toolkit skill (scripts/onnxwrapper.py).
PROHIBITED: NEVER use or fallback to the onnxwrapper.py bundled with the QAIRT SDK or qai_appbuilder package (e.g., from site-packages/qai_appbuilder/onnxwrapper.py). The skill version contains critical patches for AIPC workflows.
Before any final inference run, perform wrapper artifact preflight:
print which QNN artifact will be selected for {ONNX_FILE}
remove or quarantine stale matched artifacts (platform-dependent: <model>.onnx.dll.bin on Windows, <model>.onnx.so.bin on Linux) before deploying a new one
in context-binary mode, prefer ONNX-matching deployment filename: <model>.onnx.dll.bin on Windows, <model>.onnx.so.bin on Linux
the wrapper discovers context binaries by appending platform-specific suffixes to the ONNX path; see onnxwrapper.py:_find_qnn_model_file() for the full candidate list
If remote target execution is configured (for example RETMOE_DEVICE_INFO is set in project config),
you MUST skip local host inference runs.
In this mode, acceptance and validation MUST be executed on the remote target only.
Local host inference is not allowed as an acceptance substitute.
Do NOT call snpe-net-run, qnn-net-run, or raw backend CLIs directly for final inference/validation.
Linux ARM runtime-libs pinning (MANDATORY for remote acceptance):
Do not rely on implicit wrapper auto-resolution when multiple target toolchain lib folders exist.
Explicitly set QAI_QNN_LIBS_DIR to the intended runtime directory for deployment and prepend it to LD_LIBRARY_PATH.
Escalation: If conversion still fails after export/patch/retry, do not silently replace model architecture. Record error + logs + ONNX snapshot → escalate with full bundle. For B3/B4/B7 criteria → open references/operator_patching.md.
Dynamic-input ONNX: If ONNX has dynamic inputs, pass explicit shapes during conversion. See references/qnn_conversion.md (QNN: --input-dim) or references/snpe_conversion.md (SNPE: --source-model-input-shape).
⚠️ CRITICAL: Context Binary & Model Library Architecture (DO NOT SKIP)
Context binary (.dll.bin / .so.bin):
ARM Windows: PREFERRED for fixed-SoC deployment — .dll (with ARM64X/CHPE runtime) also works.
ARM Linux: OPTIONAL — .so works directly.
The binary is SoC-specific and platform-independent — same .bin works whether host is x86 or ARM64.
Model library (.dll / .so):
Must match the host process architecture, not the target CPU.
On ARM64 Windows, the QAIRT Python venv runs under x86_64 emulation → qnn-model-lib-generator tool compile with -t windows-x86_64.
Compiling for windows-aarch64 produces a DLL that the x86_64 emulated Python cannot load.
Context binary generation runs on the HOST (x86), not on the target device.
The host uses qnn-context-binary-generator with soc_id/dsp_arch config to compile a binary for the target SoC.
--model input must be a model library matching the host toolchain arch: windows-x86_64 on Windows, x86_64-linux-clang on Linux.
The resulting .bin is then deployed to the target for inference.
Do not add target cross-compilation steps unless the user explicitly asks for target model-library build.
soc_id and dsp_arch are mandatory — identify them from the target device before generation.
Do not use /sys/devices/soc0/soc_id — that is the Linux kernel ID, not the QAIRT soc_id.
For how to read soc_id/dsp_arch from the target and full generation commands → open references/host_context_binary_gen.md.
For platform table, troubleshooting flow, and usage → open references/host_context_binary_gen.md.
ARM64X/CHPE note: On ARM64 Windows, QNN ships ARM64X hybrid DLLs (arm64x-windows-msvc/)
that load from both x86_64-emulated and ARM64-native processes. The aipc wrapper +
qai_appbuilder bundled libs use these automatically. Do not override QAI_QNN_LIBS_DIR
or ADSP_LIBRARY_PATH to arm64x-windows-msvc unless the SDK version requires it.
Minimal device info probe: If CIM/WMI is unavailable, use registry + DriverStore
inspection plus the QNN SoC enum table and qnn-platform-validator core-version
output to resolve soc_id and dsp_arch. This is enough for context-binary
generation on Snapdragon Windows hosts, and avoids device-specific hardcoding.
Continue patching ALL unsupported ops until no replacement patterns exist. Never fall back to CPU.
For patching rules, escalation policy (B3/B4/B7), and code templates → open references/operator_patching.md.
⚠️ CRITICAL: Project Setup Rules (DO NOT SKIP)
When the user requests "create project", "init project", or any project setup workflow for qairt:
you must follow the AIPC skill end-to-end for all project setup actions. This is a required, certified workflow with defined acceptance criteria. Do not improvise, skip steps, or replace the workflow with manual setup. If this instruction is not followed exactly, the resulting work is considered invalid and must not be presented as compliant.
NEVER create local files, folders, or scripts yourself. Do not write any project files manually or spawn agents to do so.
ALWAYS run aipc_project_setup.py — never write AGENTS.md, CLAUDE.md, or aipc_plan.md manually.
Verify after the script: CLAUDE.md must be a symlink to AGENTS.md. Note: On Windows systems where symlink creation is restricted by local security policies (WinError 1314), the setup script's automatic copy fallback (copying AGENTS.md directly to CLAUDE.md) is fully acceptable and must NOT be treated as a setup failure.
Before auto-filling aipc_plan.md, inform the user that some Config values require their input (model name, target device, env script path, flow, etc.) and ask them to provide or confirm these before proceeding.
Then auto-fill derived and default values from the user's answers.
Never shortcut: manual file creation produces an incomplete scaffold (missing CLAUDE.md, wrong template, no sentinel). The script is the only correct path.
1. Can you access PyTorch model BEFORE ONNX export?
├─ YES → Go to 2
└─ NO → Use ONNX Surgery (Approach 3)
2. Is the operator an explicit PyTorch module?
├─ YES → In-Memory Module Replacement (Approach 1)
└─ NO → Go to 3
3. Is the operator generated during ONNX export?
├─ YES → Custom Symbolic Handlers (Approach 2)
└─ NO → ONNX Surgery (Approach 3)
Approach 1: In-Memory Model Patch (Preferred)
Modify model.forward() or replace module instances
Use references/operator_patching.md templates
Export patched model → model_patched.onnx
Approach 2: Custom Symbolic Handlers (Excellent)
Register handlers before export: register_custom_op_symbolic()
Define ONNX graph for unsupported aten ops
Export with handlers active → model_patched.onnx
Approach 3: ONNX Surgery (Fallback)
Use when source model is not accessible
Directly modify ONNX graph to replace unsupported ops
QAIRT SoC and DSP/HTP architecture auto-detection (Windows on Snapdragon)
⚠️ Inference must use scripts/aipc wrapper (including remote target runs). Direct snpe-net-run/qnn-net-run is for diagnostics only, not acceptance validation.
⚠️ Always prefer the wrapper scripts (aipc_convert_fp.py, aipc_convert_int.py, aipc_convert_aimet.py) over calling qnn-onnx-converter or qnn-model-lib-generator directly.
Avoid PowerShell inline pipelines and variables ($_, $env:, !) in command arguments passed via -Command (e.g., Where-Object { $_.LastWriteTime } gets expanded to { .LastWriteTime } by the outer shell, breaking syntax). Always write PowerShell pipelines to a temporary .ps1 file and execute it using the -File parameter, or use Python globbing/filesystem functions instead.
Console Encoding Guardrail: Local Windows shells can use non-UTF-8 encodings (such as cp950 or cp437), which frequently trigger UnicodeEncodeError or UnicodeDecodeError when processing console outputs with special characters. Always enforce UTF-8 encoding/decoding where possible, and use errors='replace' or errors='ignore' in Python subprocess handling.
