故障排查

常见错误及处理方法。

​

安装 / pip

pip 安装时出现 SSL 或证书错误（企业代理 / QDC）

常见于启用了 TLS 检测的网络——包括 Qualcomm Developer Cloud（QDC）。预先下载 SDK 并把 pip 指向本地文件。完整 PowerShell 片段见 Python 安装。

Windows SmartScreen 拦截 CLI 安装包

.exe 尚未代码签名。在 SmartScreen 对话框中点击 More info → Run anyway。

​

CLI

安装后 `geniex` 找不到

安装包不会自动加入 PATH。运行：

Set-Alias geniex (where.exe geniex)

`--compute cpu` 或 `--compute gpu` 在 Qualcomm AI Hub 模型上报错

Qualcomm AI Engine Direct 仅支持 NPU。请使用 --compute npu（或省略该标志——npu 是 qairt 的默认值）。如需在 CPU/GPU 上运行，改用 llama.cpp 运行环境的 GGUF 模型。

长对话中出现 `Context length exceeded`

对话增长超过了上下文窗口（--nctx，默认 4096）。

• llama.cpp (GGUF)： 可在运行时抬升，例如 geniex infer <model> --nctx 8192，上限为模型训练时的最大值。窗口越大占用内存越多。
• Qualcomm AI Engine Direct (NPU)： 窗口固化在编译好的模型包中，--nctx 不生效。加 --sliding-window 以继续对话（驱逐最旧的上下文），或获取按更长上下文编译的模型包。

参见增大上下文长度。

​

服务器

`geniex serve` 返回 'model not found'

服务器不会自动下载。先拉取模型：

geniex pull ai-hub-models/Qwen3-4B-Instruct-2507

随后重启 geniex serve。

Docker 容器看不到 NPU

NPU 访问必须带 --privileged 标志。确认你的 docker run 包含它，以及 /usr/lib 的卷挂载。详见 CLI 安装（Docker）。

​

Linux

`docker pull` 报权限错误 / 未授权

需要同时满足两点：

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
   

   然后重新执行拉取。

容器内可加载模型但推理报 `Failed to create device: 14001`

容器无法访问 NPU。确认 docker run 带 --privileged 与 /usr/lib 挂载，并且主机已安装高通驱动包（qcom-adreno1、qcom-fastrpc1）——参见 Linux 安装 → 安装宿主机依赖。

`geniex` 启动即退出并提示 'device is missing CPU features geniex requires'

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

LD_SHOW_AUXV=1 /bin/true | grep AT_HWCAP   # 查找 atomics、asimdrdm、asimddp、fphp、asimdhp
cat /proc/cpuinfo | grep Features          # 相同特性，内核使用的名称

若缺少这些特性，该设备无法运行当前版本。请带上以上输出到 GitHub Issues 或 Slack 反馈。

​

Android

模型可加载，但生成自我重复或无输出

demo（或你的代码）把原始用户文本传给了 generateStreamFlow，而非 chat template 化后的 prompt。Qualcomm AI Engine Direct 流水线把输入视为已格式化——请传 applyChatTemplate().formattedText，而不是原始用户消息。

Qualcomm AI Hub 拉取报 `INVALID_INPUT`

Android 上 Qualcomm AI Hub 拉取必须显式传 chipset——自动识别仅在骁龙 Windows 上生效。把 ModelPullInput.chipset 设为 "SM8750"（骁龙 8 至尊版）或 "SM8850"（骁龙 8 至尊版 Gen 5）。详见 Android API 参考 → ModelPullInput。

Qualcomm AI Engine Direct 加载报 'unknown model name'

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 Engine Direct 拒绝 `nGpuLayers` 或 `nCtx`

Qualcomm AI Hub 模型在编译期固化了 KV 缓存与上下文长度。请保持 nGpuLayers 与 nCtx 为默认值，改用 max_tokens 与 enable_thinking 调节。

​

仍有问题？

GitHub Issues

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

Slack

开发者协作。

Was this page helpful?

Yes

No