> ## 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.
# 常见问题
> 关于 GenieX、其运行环境及支持芯片的常见问题。
## **通用**
面向高通骁龙的多平台 AI 推理 SDK。GenieX 在 Hexagon NPU、Adreno GPU 或 CPU 计算单元上端侧运行前沿 LLM 与 VLM，覆盖 Windows ARM64、Android 与 Linux ARM64。详见 [GenieX 是什么](/cn/get-started/what-is-geniex)。
* **试用、写脚本** —— Windows ARM64 或 Linux ARM64 上的 [CLI](/cn/run/cli/install)。
* **构建应用** —— [本地服务器](/cn/run/cli/local-server)（兼容 OpenAI 协议的 HTTP）或 [Python SDK](/cn/run/python/install)。
* **移动端** —— [Android SDK](/cn/run/android/install)（Kotlin，Maven Central）。
* **可复现的 IoT 部署** —— Linux ARM64 EVK 上的 [Docker 镜像](/cn/run/cli/install)，锁定到指定 release tag。
[快速入门](/cn/get-started/quickstart)是这四条路径的统一入口。
[支持的平台](/cn/get-started/platforms) —— Windows ARM64 上的 骁龙 X、Android 上的骁龙 8 至尊版、Linux ARM64 上的跃龙 QCS9075。
## **运行环境**
* **llama.cpp** —— 运行任意 GGUF 模型，支持 NPU/GPU/CPU 计算单元。最适合试用社区模型。
* **[Qualcomm® AI Engine Direct](https://www.qualcomm.com/developer/software/qualcomm-ai-engine-direct-sdk)**（`qairt`）—— 运行 Qualcomm AI Hub 预编译模型，仅 NPU。当模型在 Qualcomm AI Hub 可用时，通常是最快路径。
详见[平台与运行环境](/cn/get-started/platforms#geniex-运行环境)。
如果不传计算单元：
* `llama_cpp` 默认 `hybrid`（HTP + CPU 按张量调度——骁龙上的快速路径）。
* `qairt` 默认 `npu`。
部分模型会覆盖默认值——例如 `gpt-oss` 在 `llama_cpp` 下回退到 `npu`。
llama.cpp 在骁龙 NPU 上请用 **`Q4_0`**——它在 Hexagon NPU 上支持最佳。Qualcomm AI Hub 模型已预量化——无需选择。详见[支持的精度（量化）](/cn/models/supported#支持的精度量化)。
## **模型**
llama.cpp 运行环境可执行任意 **GGUF** 模型。详见[运行 Hugging Face 上的 GGUF 模型](/cn/models/supported#运行-hugging-face-上的-gguf-模型)。
Qualcomm AI Engine Direct 需要预编译的 Qualcomm AI Hub 模型——新增模型需先在 C++ 侧注册。
部分 Hugging Face 模型需要你接受许可协议并进行身份验证。设置以下环境变量之一：
* **Windows：** `$env:HF_TOKEN = "hf_..."`（或 `$env:GENIEX_HFTOKEN = "hf_..."`）
* **Linux：** `export HF_TOKEN="hf_..."`（或 `export GENIEX_HFTOKEN="hf_..."`）
也可运行 `huggingface-cli login` 将令牌持久化到 `~/.cache/huggingface/token`。
优先级：`GENIEX_HFTOKEN` > `HF_TOKEN` > 令牌文件。在 [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) 获取令牌。完整设置步骤见[设置 Hugging Face 令牌](/cn/models/supported#设置-hugging-face-令牌)。
[模型](/cn/models/supported) —— 按运行环境拆分（Qualcomm AI Engine Direct、llama.cpp）。
## **芯片与设备**
是。GenieX 面向高通骁龙芯片——Hexagon NPU、Adreno GPU 与骁龙 ARM CPU 计算单元。不支持 x86 或非骁龙 ARM 设备。如手头无设备，可使用 [Qualcomm Developer Cloud / Device Cloud](/cn/get-started/platforms)。
不能。Qualcomm AI Engine Direct 设计上仅支持 NPU。`cpu` 与 `gpu` 别名会被自动转为 NPU 并打印告警。如需 CPU/GPU 回退，请改用 llama.cpp 运行环境（GGUF 模型）。
## **QDC（Qualcomm Device Cloud）**
不需要。登录 [Qualcomm Developer Cloud](https://qdc.qualcomm.com/)，选择一台骁龙设备，启动交互式会话——整个流程就是这样。关于哪些芯片在支持范围内，详见[支持的平台](/cn/get-started/platforms)。
在 QDC 控制台中前往 **Interactive Sessions** 页面，点击 **Connect** 查看 SSH 连接说明。
打开终端，运行 QDC 提供的 SSH 隧道命令，把 `` 替换为你的私钥路径。
**`WARNING: UNPROTECTED PRIVATE KEY FILE!`** —— 你的 `.pem` 文件权限过宽。SSH 要求私钥仅文件所有者可读：
```bash theme={"dark"}
chmod 600 /path/to/your-key.pem
```
在新终端中通过转发端口 SSH 进入设备。默认密码为 `oelinux123`：
```bash theme={"dark"}
ssh -o StrictHostKeychecking=no -o UserKnownHostsFile=/dev/null -p 2222 root@localhost
```
在 QDC 上使用 **骁龙 8 Elite** 或 **8 Elite Gen 5** 的交互式会话，并安装你从源码构建的 demo APK。
从 [`qualcomm/ai-hub-apps`](https://github.com/qualcomm/ai-hub-apps/blob/release/geniex_chat_android/README.md) 在 Android Studio 中构建示例应用（**Build → Build APK(s)**）以生成 `.apk`。
登录 [Qualcomm Device Cloud](https://qdc.qualcomm.com/)，选择 **骁龙 8 Elite** 或 **骁龙 8 Elite Gen 5**，并选择 **Interactive session（交互式会话）**。
启用 **Wi-Fi**（让 demo 能下载模型）和 **Keep screen on**（避免下载中途锁屏）。**无需** SSH。
在会话设置页用 **Upload file** 把你构建的 `.apk` 推送到设备——该文件必须在会话开始**之前**上传。
启动会话。在镜像屏幕中点击已上传的 APK 进行安装，然后从应用抽屉打开 **GenieX Demo**。
通过 QDC 终端上传一张测试图片：
```bash theme={"dark"}
curl -L "https://s7d1.scene7.com/is/image/dmqualcommprod/Qualcomm_AIHub_image2-1?$QC_Responsive$&fmt=png-alpha" -o /data/local/tmp/qualcomm.png
cp /data/local/tmp/qualcomm.png /sdcard/Download/
```
该图片会出现在应用的图片选择器中。
## **Python**
GenieX 要求 **ARM64** Python，不支持 x86\_64 / AMD64（即使在模拟器下也不支持）。
QDC 设备（高通嵌入式 Linux / Yocto）已预装 ARM64 Python，用 `python3 --version` 验证即可。如设备未预装 Python，使用下列方法之一。
**方法 1 —— [Miniconda](https://docs.anaconda.com/miniconda/)（推荐；Yocto 与 Ubuntu ARM64 均可用）**
```bash theme={"dark"}
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh
# CONDA_OVERRIDE_GLIBC：Yocto 镜像通常不带 `ldd`，安装器会因此报
# "Installer requires GLIBC >=2.28, but system has ." 而退出。
# 该变量跳过探测；Qualcomm Linux 1.7+ 的实际 glibc 是 2.39，远超下限。
CONDA_OVERRIDE_GLIBC=2.39 bash Miniconda3-latest-Linux-aarch64.sh -b -p $HOME/miniconda
eval "$($HOME/miniconda/bin/conda shell.bash hook)"
# 新版 conda 在非交互模式下强制要求接受默认 channel 的 ToS，
# 否则下面的 `conda create` 会直接报错。
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r
conda create -n geniex python=3.13 -y
conda activate geniex
python --version
```
**方法 2 —— apt（仅 Ubuntu ARM64）**
```bash theme={"dark"}
sudo apt update && sudo apt install -y python3 python3-pip python3-venv
python3 --version
```
QDC Yocto 镜像不带 `apt`，请使用上面的 Miniconda 方法。
不支持。目前 Miniconda 没有原生的 Windows ARM64 安装程序。请直接从 python.org 下载官方 [Python 3.13.3 ARM64 安装程序](https://www.python.org/ftp/python/3.13.3/python-3.13.3-arm64.exe)——详见 [Python 安装](/cn/run/python/install)。不要安装 x86 / AMD64 版本：GenieX wheel 只支持 ARM64。
## **服务器 / API**
是——详见[本地服务器](/cn/run/cli/local-server)。可将官方 `openai` Python 客户端指向 `http://127.0.0.1:18181/v1`，OpenAI 代码无需修改即可复用。
不会。请先用 `geniex pull` 拉取模型再启动服务器。