> ## Documentation Index
> Fetch the complete documentation index at: https://qualcomm-0801e48b-fix-serve-reasoning-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 故障排查
> 常见错误及处理方法。
## **安装 / pip**
常见于启用了 TLS 检测的网络——包括 **Qualcomm Developer Cloud（QDC）**。预先下载 SDK 并把 pip 指向本地文件。完整 PowerShell 片段见 [Python 安装](/cn/run/python/install#通过-pip-安装)。
`.exe` 尚未代码签名。在 SmartScreen 对话框中点击 **More info → Run anyway**。
## **CLI**
安装包不会自动加入 `PATH`。运行：
```powershell theme={null}
Set-Alias geniex (where.exe geniex)
```
Qualcomm AI Engine Direct 仅支持 NPU。请使用 `--compute npu`（或省略该标志——`npu` 是 `qairt` 的默认值）。如需在 CPU/GPU 上运行，改用 [llama.cpp 运行环境](/cn/get-started/platforms#llamacpp)的 GGUF 模型。
对话增长超过了上下文窗口（`--nctx`，默认 4096）。
* **llama.cpp (GGUF)：** 可在运行时抬升，例如 `geniex infer --nctx 8192`，上限为模型训练时的最大值。窗口越大占用内存越多。
* **Qualcomm AI Engine Direct (NPU)：** 窗口固化在编译好的模型包中，`--nctx` 不生效。加 `--sliding-window` 以继续对话（驱逐最旧的上下文），或获取按更长上下文编译的模型包。
参见[增大上下文长度](/cn/run/cli/reference#增大上下文长度)。
## **服务器**
服务器不会自动下载。先拉取模型：
```bash theme={null}
geniex pull ai-hub-models/Qwen3-4B-Instruct-2507
```
随后重启 `geniex serve`。
NPU 访问必须带 `--privileged` 标志。确认你的 `docker run` 包含它，以及 `/usr/lib` 的卷挂载。详见 [CLI 安装（Docker）](/cn/run/cli/install)。
## **Linux**
需要同时满足两点：
1. **镜像仓库登录。** Docker Hub（`docker.io/qualcomm/geniex`）是公开的，无需登录。Qualcomm Container Registry 则需先登录：
```bash bash theme={null}
# 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 theme={null}
sudo usermod -aG docker $USER
newgrp docker # apply the new group in the current shell
```
然后重新执行拉取。
容器无法访问 NPU。确认 `docker run` 带 `--privileged` 与 `/usr/lib` 挂载，并且主机已安装高通驱动包（`qcom-adreno1`、`qcom-fastrpc1`）——参见 [Linux 安装 → 安装宿主机依赖](/cn/run/linux/install#安装宿主机依赖)。
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 theme={null}
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 反馈。
## **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](/cn/run/android/api-reference#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` 调节。
## **仍有问题？**
提交 bug、提需求或浏览开放的 Issue。
开发者协作。