故障排查 - 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> </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          # 相同特性，内核使用的名称
```

若缺少这些特性，该设备无法运行当前版本。请带上以上输出到 [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> </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/>