跳转到主要内容

​
安装 / pip

常见于启用了 TLS 检测的网络——包括 Qualcomm Developer Cloud（QDC）。预先下载 SDK 并把 pip 指向本地文件。完整 PowerShell 片段见 Python 安装。
.exe 尚未代码签名。在 SmartScreen 对话框中点击 More info → Run anyway。

​
CLI

安装包不会自动加入 PATH。运行：
Set-Alias geniex (where.exe geniex)
Qualcomm AI Engine Direct 仅支持 NPU。请使用 --compute npu（或省略该标志——npu 是 qairt 的默认值）。如需在 CPU/GPU 上运行，改用 llama.cpp 运行环境的 GGUF 模型。

​
服务器

服务器不会自动下载。先拉取模型：
geniex pull ai-hub-models/Qwen3-4B-Instruct-2507
随后重启 geniex serve。
NPU 访问必须带 --privileged 标志。确认你的 docker run 包含它，以及 /usr/lib 的卷挂载。详见 CLI 安装（Docker）。

​
Linux

需要同时满足两点：
  1. 镜像仓库登录。 Docker Hub（docker.io/qualcomm/geniex）是公开的，无需登录。Qualcomm Container Registry 则需先登录：
    bash
    # Qualcomm Container Registry:
docker login docker-registry.qualcomm.com -u '$app' -p GB2S6KXMJXTPV8VHNFNS7Q6LVH75LOOBTLT8D723WUX6PSFZMTX95GIQG4EFWH5C021ONZ5763VI9IDHU96Q7VAZJ2830CLX3NPI6STQOJWRYXLLA2ZYTL1S
    出现 Login Succeeded 即成功。
  2. 加入 docker 用户组。 若 docker pull 返回 permission denied while trying to connect to the docker API at unix:///var/run/docker.sock，说明当前用户不在 docker 组：
    bash
    sudo usermod -aG docker $USER
newgrp docker        # apply the new group in the current shell
    然后重新执行拉取。
在全新的 Ubuntu 24.04 ARM64 主机（例如 IQ9075 EVK）上，install.sh——以及 Docker 场景下的预检脚本 check.sh / 容器入口脚本 entrypoint.sh——会检查 libCB.so.1、libOpenCL_adreno.so.1、libcdsprpc.so.1.0.0、libgsl.so.1、libllvm-*.so.1、libpropertyvault.so.0.0.0、libdmabufheap.so.0.0.0，以及 Debian 的 libatomic1 / libglib2.0-0 等库。请在宿主机上分两步安装——如果当前在 geniex 容器内，请先 exit。1. 标准 APT 包满足 geniex 安装器报告的 libatomic1 与 libglib2.0-0 依赖，并提供通用 OpenCL ICD loader：
bash
sudo apt update
sudo apt install -y \
  libatomic1 \
  libglib2.0-0 \
  ocl-icd-libopencl1
ocl-icd-libopencl1 会在下一步被 qcom-adreno1 替换。
2. 高通驱动包（来自 ubuntu-qcom-iot PPA）提供 geniex 所需的高通专有库：
Missing libraryProvided by
libOpenCL_adreno.so.1, libCB.so.1, libadreno_utils.so.1, libgsl.so.1, libllvm-*.so.1qcom-adreno1
libdmabufheap.so.0.0.0qcom-libdmabufheap (auto-dep of qcom-adreno1)
libpropertyvault.so.0.0.0qcom-property-vault (auto-dep of qcom-adreno1)
libcdsprpc.so.1.0.0qcom-fastrpc1
bash
sudo apt-get install -y qcom-adreno1 qcom-fastrpc1
PPA（ppa:ubuntu-qcom-iot/qcom-ppa）在 IQ9075 EVK Ubuntu 镜像中已预配置。qcom-adreno1 会自动拉入 qcom-libdmabufheap 与 qcom-property-vault。完成后在裸机上重新运行 install.sh，或重启容器来验证；“Linking host NPU libraries” 步骤即可成功。若裸机上 libcdsprpc.so / libadsprpc.so 软链接仍缺失，请重新运行 install.sh 重建。
容器无法访问 NPU。确认 docker run 带 --privileged 与 /usr/lib 挂载，并且主机已安装高通驱动包（qcom-adreno1、qcom-fastrpc1）——参见上面的缺少共享库条目。

​
Android

demo（或你的代码）把原始用户文本传给了 generateStreamFlow，而非 chat template 化后的 prompt。Qualcomm AI Engine Direct 流水线把输入视为已格式化——请传 applyChatTemplate().formattedText，而不是原始用户消息。
Android 上 Qualcomm AI Hub 拉取必须显式传 chipset——自动识别仅在骁龙 Windows 上生效。把 ModelPullInput.chipset 设为 "SM8750"（骁龙 8 至尊版）或 "SM8850"（骁龙 8 至尊版 Gen 5）。详见 Android API 参考 → ModelPullInput。
Qualcomm AI Hub 返回的 model id 必须匹配 Qualcomm AI Engine Direct 运行环境注册表中的条目（qwen3_4b_instruct_2507、qwen2_5_vl_7b_instruct 等）。新增 Qualcomm AI Hub 模型需先在 C++ 侧注册——见 third-party/geniex-qairt/models/{llm,vlm}_model_registry.h。
Qualcomm AI Hub 模型在编译期固化了 KV 缓存与上下文长度。请保持 nGpuLayers 与 nCtx 为默认值，改用 max_tokens 与 enable_thinking 调节。

​
仍有问题？

GitHub Issues

提交 bug、提需求或浏览开放的 Issue。

Slack

开发者协作。