故障排查 - Nexa Sdk

import Feedback from "/snippets/page-feedback.mdx";

安装 / pip

<AccordionGroup> <Accordion title="pip 安装时出现 SSL 或证书错误（企业代理 / QDC）"> 常见于启用了 TLS 检测的网络——包括 **Qualcomm Developer Cloud（QDC）**。预先下载 SDK 并把 pip 指向本地文件。完整 PowerShell 片段见 [Python 安装](/cn/run/python/install#通过-pip-安装)。 </Accordion> <Accordion title="Windows SmartScreen 拦截 CLI 安装包"> `.exe` 尚未代码签名。在 SmartScreen 对话框中点击 **More info → Run anyway**。 </Accordion> </AccordionGroup>

CLI

<AccordionGroup> <Accordion title="安装后 `geniex` 找不到"> 安装包不会自动加入 `PATH`。运行：

```powershell
Set-Alias geniex (where.exe geniex)
```

</Accordion> <Accordion title="`--compute cpu` 或 `--compute gpu` 在 Qualcomm AI Hub 模型上报错"> Qualcomm AI Engine Direct 仅支持 NPU。请使用 `--compute npu`（或省略该标志——`npu` 是 `qairt` 的默认值）。如需在 CPU/GPU 上运行，改用 [llama.cpp 运行环境](/cn/get-started/platforms#llamacpp)的 GGUF 模型。 </Accordion> <Accordion title="长对话中出现 `Context length exceeded`"> 对话增长超过了上下文窗口（`--nctx`，默认 4096）。

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

参见[增大上下文长度](/cn/run/cli/reference#增大上下文长度)。

</Accordion> </AccordionGroup>

服务器

<AccordionGroup> <Accordion title="`geniex serve` 返回 'model not found'"> 服务器不会自动下载。先拉取模型：

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

随后重启 `geniex serve`。

</Accordion> <Accordion title="Docker 容器看不到 NPU"> NPU 访问必须带 `--privileged` 标志。确认你的 `docker run` 包含它，以及 `/usr/lib` 的卷挂载。详见 [CLI 安装（Docker）](/cn/run/cli/install)。 </Accordion> </AccordionGroup>

Linux

<AccordionGroup> <Accordion title="`docker pull` 报权限错误 / 未授权"> 需要同时满足两点：

1. **镜像仓库登录。** Docker Hub（`docker.io/qualcomm/geniex`）是公开的，无需登录。Qualcomm Container Registry 则需先登录：

   ```bash 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 bash
   sudo usermod -aG docker $USER
   newgrp docker        # apply the new group in the current shell
   ```

   然后重新执行拉取。

</Accordion> <Accordion title="容器内可加载模型但推理报 `Failed to create device: 14001`"> 容器无法访问 NPU。确认 `docker run` 带 `--privileged` 与 `/usr/lib` 挂载，并且主机已安装高通驱动包（`qcom-adreno1`、`qcom-fastrpc1`）——参见 [Linux 安装 → 安装宿主机依赖](/cn/run/linux/install#安装宿主机依赖)。 </Accordion> <Accordion title="`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 bash
LD_SHOW_AUXV=1 /bin/true | grep AT_HWCAP   # 查找 atomics、asimdrdm、asimddp、fphp、asimdhp
cat /proc/cpuinfo | grep Features          # 相同特性，内核使用的名称
```

若缺少这些特性，请改用 **CPU-only（仅 CPU）** 版本：它以纯 `armv8.0-a`（不带任何 ISA 扩展）编译，只包含 CPU 推理（不含 QAIRT/NPU、OpenCL/GPU、Hexagon），速度也相应更慢——缺少 `dotprod`/`fp16` 时 ggml 会退回 fp32 量化内核。所有渠道都需要显式指定，不做自动探测：

```bash bash
curl -fsSL https://raw.githubusercontent.com/qualcomm/GenieX/main/cli/release/linux/install.sh | sh -s -- --cpu-only
```

| 渠道 | 如何选中 CPU-only 版本 |
| --- | --- |
| `install.sh` | `--cpu-only` |
| `pip install geniex` | `GENIEX_SDK_VARIANT=cpu` |
| Docker | `-cpu` tag —— `docker.io/qualcomm/geniex:latest-cpu` |

`geniex-qairt` 没有 CPU-only 版本：QAIRT 需要 NPU，而这类板子并没有。请改用 `geniex-llama-cpp`（或 `geniex` 元包，它会在这类板子上自动去掉 QAIRT 后端）。

若 CPU-only 版本仍然失败，请带上以上输出到 [GitHub Issues](https://github.com/qualcomm/GenieX/issues) 或 Slack 反馈。

</Accordion> </AccordionGroup>

Android

<AccordionGroup> <Accordion title="模型可加载，但生成自我重复或无输出"> demo（或你的代码）把**原始用户文本**传给了 `generateStreamFlow`，而非 chat template 化后的 prompt。Qualcomm AI Engine Direct 流水线把输入视为已格式化——请传 `applyChatTemplate().formattedText`，而不是原始用户消息。 </Accordion> <Accordion title="Qualcomm AI Hub 拉取报 `INVALID_INPUT`"> Android 上 Qualcomm AI Hub 拉取必须显式传 `chipset`——自动识别仅在骁龙 Windows 上生效。把 `ModelPullInput.chipset` 设为 `"SM8750"`（骁龙 8 至尊版）或 `"SM8850"`（骁龙 8 至尊版 Gen 5）。详见 [Android API 参考 → ModelPullInput](/cn/run/android/api-reference#modelpullinput)。 </Accordion> <Accordion title="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`。 </Accordion> <Accordion title="Qualcomm AI Engine Direct 拒绝 `nGpuLayers` 或 `nCtx`"> Qualcomm AI Hub 模型在编译期固化了 KV 缓存与上下文长度。请保持 `nGpuLayers` 与 `nCtx` 为默认值，改用 `max_tokens` 与 `enable_thinking` 调节。 </Accordion> <Accordion title="初始化报 'this device's CPU lacks features required by geniex'"> 与 Linux 上同一处启动检查。默认 AAR 按 **armv8.7-a** 编译，带 `fp16`、`dotprod`、`i8mm` 扩展，而 `minSdk` 27 仍覆盖早于这些扩展的机型，因此 `geniex_init` 直接返回 `NOT_SUPPORTED`，而不是在运行中途以裸 `SIGILL` 崩溃。

这类设备请改用 **CPU-only** AAR——[release 资产](https://github.com/qualcomm/GenieX/releases)中的 `geniex-android-aar-cpu-<tag>.aar`。它按纯 `armv8.0-a` 编译、不带任何 ISA 扩展，只提供 CPU 推理（无 Qualcomm AI Engine Direct、无 OpenCL、无 Hexagon），因而相应更慢。除此之外可直接替换：`com.geniex.sdk` 命名空间与 API 完全一致。Maven Central 上只发布默认 AAR。

</Accordion> </AccordionGroup>

仍有问题？

<CardGroup cols={2}> <Card title="GitHub Issues" icon="github" href="https://github.com/qualcomm/GenieX/issues"> 提交 bug、提需求或浏览开放的 Issue。 </Card> <Card title="Slack" icon="slack" href="https://aihub.qualcomm.com/community/slack"> 开发者协作。 </Card> </CardGroup> <Feedback/>