Skip to main content

​
Install / pip

Common on networks with TLS inspection — including Qualcomm Developer Cloud (QDC). Pre-download the SDK and point pip at the local file. See the full PowerShell snippet in Python install.
The .exe is not yet code-signed. Click More info → Run anyway in the SmartScreen dialog.

​
CLI

The installer doesn’t add itself to PATH. Run:
Set-Alias geniex (where.exe geniex)
Qualcomm AI Engine Direct is NPU-only. Use --compute npu (or omit the flag — npu is the default for qairt). To run on CPU/GPU, switch to a GGUF model on the llama.cpp runtime.

​
Server

The server doesn’t auto-download. Pull the model first:
geniex pull ai-hub-models/Qwen3-4B-Instruct-2507
Then restart geniex serve.
The --privileged flag is required for NPU access. Make sure your docker run includes it, plus the volume mounts for /usr/lib. See CLI install (Docker).

​
Linux

Two separate things have to be right:
  1. Registry login. Docker Hub (docker.io/qualcomm/geniex) is public and needs no login. For the Qualcomm Container Registry, log in first:
    bash
    # Qualcomm Container Registry:
docker login docker-registry.qualcomm.com -u '$app' -p GB2S6KXMJXTPV8VHNFNS7Q6LVH75LOOBTLT8D723WUX6PSFZMTX95GIQG4EFWH5C021ONZ5763VI9IDHU96Q7VAZJ2830CLX3NPI6STQOJWRYXLLA2ZYTL1S
    You should see Login Succeeded.
  2. Docker group membership. If docker pull returns permission denied while trying to connect to the docker API at unix:///var/run/docker.sock, your user isn’t in the docker group:
    bash
    sudo usermod -aG docker $USER
newgrp docker        # apply the new group in the current shell
    Then retry the pull.
The container can’t reach the NPU. Make sure your docker run includes --privileged and the /usr/lib mount, and that the host’s Qualcomm driver packages (qcom-adreno1, qcom-fastrpc1) are installed — see Linux install → Install host dependencies.
The llama.cpp Hexagon backend dlopens the unversioned libcdsprpc.so, but qcom-fastrpc1 only ships libcdsprpc.so.1. On bare metal install.sh creates the symlink; if you deployed the release tarball directly (no install.sh), create it yourself:
bash
sudo ln -sf /usr/lib/aarch64-linux-gnu/libcdsprpc.so.1 /usr/lib/aarch64-linux-gnu/libcdsprpc.so
sudo ln -sf /usr/lib/aarch64-linux-gnu/libadsprpc.so.1 /usr/lib/aarch64-linux-gnu/libadsprpc.so
sudo ldconfig
If the Hexagon driver can’t load (see the entry above), hybrid still produces correct output — it just runs entirely on CPU, so the failure is silent. Confirm the NPU is actually engaged by running with GGML_HEX_VERBOSE=1; you should see Hexagon Arch version vNN and a libggml-htp-vNN.so session. No such lines means it fell back to CPU.

​
Android

The demo (or your code) is passing the raw user text into generateStreamFlow instead of the chat-templated prompt. Qualcomm AI Engine Direct pipelines treat their input as already-templated — pass applyChatTemplate().formattedText, not the raw user message.
Android needs an explicit chipset for Qualcomm AI Hub pulls — auto-detect only runs on Windows on Snapdragon. Set ModelPullInput.chipset to "SM8750" (Snapdragon 8 Elite) or "SM8850" (Snapdragon 8 Elite Gen 5). See Android API reference → ModelPullInput.
The model id returned by Qualcomm AI Hub must match an entry in the Qualcomm AI Engine Direct runtime’s registry (qwen3_4b_instruct_2507, qwen2_5_vl_7b_instruct, etc.). To add a new Qualcomm AI Hub Model, register it on the C++ side first — see third-party/geniex-qairt/models/{llm,vlm}_model_registry.h.
Qualcomm AI Hub Models are compiled with fixed KV cache and context length. Leave both nGpuLayers and nCtx at their defaults; tune max_tokens and enable_thinking instead.

​
Still stuck?

GitHub Issues

File a bug, request a feature, or browse open issues.

Slack

Developer collaboration.