Skip to main content

​
安装 / pip

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

​
CLI

安装包不会自动加入 PATH。运行：
Qualcomm AI Engine Direct 仅支持 NPU。请使用 --compute npu（或省略该标志——npu 是 qairt 的默认值）。如需在 CPU/GPU 上运行，改用 llama.cpp 运行环境的 GGUF 模型。
对话增长超过了上下文窗口（--nctx，默认 4096）。
  • llama.cpp (GGUF)： 可在运行时抬升，例如 geniex infer <model> --nctx 8192，上限为模型训练时的最大值。窗口越大占用内存越多。
  • Qualcomm AI Engine Direct (NPU)： 窗口固化在编译好的模型包中，--nctx 不生效。加 --sliding-window 以继续对话（驱逐最旧的上下文），或获取按更长上下文编译的模型包。
参见增大上下文长度。

​
服务器

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

​
Linux

需要同时满足两点：
  1. 镜像仓库登录。 Docker Hub（docker.io/qualcomm/geniex）是公开的，无需登录。Qualcomm Container Registry 则需先登录：
    bash
    出现 Login Succeeded 即成功。
  2. 加入 docker 用户组。 若 docker pull 返回 permission denied while trying to connect to the docker API at unix:///var/run/docker.sock，说明当前用户不在 docker 组：
    bash
    然后重新执行拉取。
容器无法访问 NPU。确认 docker run 带 --privileged 与 /usr/lib 挂载，并且主机已安装高通驱动包（qcom-adreno1、qcom-fastrpc1）——参见 Linux 安装 → 安装宿主机依赖。
aarch64 Linux 版本以 armv8.2-a 编译，启用了 fp16、dotprod、lse（原子指令）与 rdm 扩展。基线 armv8.0 的板子（部分无 NPU 的 Dragonwing IoT SoC）不实现这些指令，因此 geniex 会在启动时给出明确错误并退出，而不是在运行中途抛出原始的 SIGILL: illegal instruction。该检查是全局的：所有后端都需要这些指令，因此把 --compute 切到 cpu、gpu 或 npu 都无济于事。查看你的 CPU 报告了哪些特性：
bash
若缺少这些特性，请改用 CPU-only（仅 CPU） 版本：它以纯 armv8.0-a（不带任何 ISA 扩展）编译，只包含 CPU 推理（不含 QAIRT/NPU、OpenCL/GPU、Hexagon），速度也相应更慢——缺少 dotprod/fp16 时 ggml 会退回 fp32 量化内核。所有渠道都需要显式指定，不做自动探测：
bash
geniex-qairt 没有 CPU-only 版本：QAIRT 需要 NPU，而这类板子并没有。请改用 geniex-llama-cpp（或 geniex 元包，它会在这类板子上自动去掉 QAIRT 后端）。若 CPU-only 版本仍然失败，请带上以上输出到 GitHub Issues 或 Slack 反馈。
该模型按 VLM 加载需要约 4.94 GB——3.04 GB 的 Q4_0 权重加上 1.9 GB 的 F32 mmproj 投影器——而这块板子可用内存约 4.7 GB，因此内核会在加载投影器时杀掉进程：
把模型记录为 llm，只跑其文本路径——这会跳过投影器，内存即可容纳。此模式下无法使用图像与音频输入。
bash
参见 geniex model set-type。

​
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 调节。
与 Linux 上同一处启动检查。默认 AAR 按 armv8.7-a 编译，带 fp16、dotprod、i8mm 扩展，而 minSdk 27 仍覆盖早于这些扩展的机型，因此 geniex_init 直接返回 NOT_SUPPORTED，而不是在运行中途以裸 SIGILL 崩溃。这类设备请改用 CPU-only AAR——release 资产中的 geniex-android-aar-cpu-<tag>.aar。它按纯 armv8.0-a 编译、不带任何 ISA 扩展，只提供 CPU 推理（无 Qualcomm AI Engine Direct、无 OpenCL、无 Hexagon），因而相应更慢。除此之外可直接替换：com.geniex.sdk 命名空间与 API 完全一致。Maven Central 上只发布默认 AAR。

​
仍有问题？

GitHub Issues

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

Slack

开发者协作。