> ## Documentation Index
> Fetch the complete documentation index at: https://geniex.aihub.qualcomm.com/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={"dark"}
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 模型。
## **服务器**
服务器不会自动下载。先拉取模型：
```bash theme={"dark"}
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={"dark"}
# 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={"dark"}
sudo usermod -aG docker $USER
newgrp docker # apply the new group in the current shell
```
然后重新执行拉取。
在全新的 Ubuntu 24.04 ARM64 主机（例如 IQ9075 EVK）上，`install.sh`——以及 Docker 场景下的预检脚本 `check.sh` / 容器入口脚本 `entrypoint.sh`——会检查 `libCB.so.1`、`libOpenCL_adreno.so.1`、`libcdsprpc.so.1.0.0`、`libgsl.so.1`、`libllvm-*.so.1`、`libpropertyvault.so.0.0.0`、`libdmabufheap.so.0.0.0`，以及 Debian 的 `libatomic1` / `libglib2.0-0` 等库。请在**宿主机**上分两步安装——如果当前在 geniex 容器内，请先 `exit`。
**1. 标准 APT 包**
满足 `geniex` 安装器报告的 `libatomic1` 与 `libglib2.0-0` 依赖，并提供通用 OpenCL ICD loader：
```bash bash theme={"dark"}
sudo apt update
sudo apt install -y \
libatomic1 \
libglib2.0-0 \
ocl-icd-libopencl1
```
`ocl-icd-libopencl1` 会在下一步被 `qcom-adreno1` 替换。
**2. 高通驱动包（来自 `ubuntu-qcom-iot` PPA）**
提供 `geniex` 所需的高通专有库：
| Missing library | Provided by |
| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `libOpenCL_adreno.so.1`, `libCB.so.1`, `libadreno_utils.so.1`, `libgsl.so.1`, `libllvm-*.so.1` | `qcom-adreno1` |
| `libdmabufheap.so.0.0.0` | `qcom-libdmabufheap` *(auto-dep of `qcom-adreno1`)* |
| `libpropertyvault.so.0.0.0` | `qcom-property-vault` *(auto-dep of `qcom-adreno1`)* |
| `libcdsprpc.so.1.0.0` | `qcom-fastrpc1` |
```bash bash theme={"dark"}
sudo apt-get install -y qcom-adreno1 qcom-fastrpc1
```
PPA（`ppa:ubuntu-qcom-iot/qcom-ppa`）在 IQ9075 EVK Ubuntu 镜像中已预配置。`qcom-adreno1` 会自动拉入 `qcom-libdmabufheap` 与 `qcom-property-vault`。
完成后在裸机上重新运行 `install.sh`，或重启容器来验证；"Linking host NPU libraries" 步骤即可成功。若裸机上 `libcdsprpc.so` / `libadsprpc.so` 软链接仍缺失，请重新运行 `install.sh` 重建。
容器无法访问 NPU。确认 `docker run` 带 `--privileged` 与 `/usr/lib` 挂载，并且主机已安装高通驱动包（`qcom-adreno1`、`qcom-fastrpc1`）——参见上面的缺少共享库条目。
## **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。
开发者协作。