> ## 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 支持的骁龙平台，以及在每类平台上应选哪种运行环境。

GenieX 仅运行在高通骁龙平台上——不适用于 x86 或非骁龙 ARM 产品。开始之前，先选择你要运行的**骁龙平台**，再根据你想运行的模型选择对应的**运行环境**。

## **骁龙平台**

GenieX 覆盖三类骁龙平台——计算、移动与 IoT端，分别对应 Windows ARM64、Android 与 Linux ARM64。

| 操作系统                                     | 接入方式                                                                                                                                      |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Windows ARM64** *（桌面端 / Copilot+ PC）*  | <ul><li>[CLI](/cn/run/cli/quickstart)</li><li>[Python SDK](/cn/run/python/quickstart)</li><li>[本地服务器](/cn/run/cli/local-server)</li></ul> |
| **Android** *（移动端）*                      | <ul><li>[Android SDK](/cn/run/android/quickstart)（Kotlin，Maven Central）</li></ul>                                                         |
| **Linux ARM64** *（跃龙 IoT —— 摄像头、机器人、工业）* | <ul><li>[原生安装](/cn/run/cli/install)</li><li>[Docker](/cn/run/linux/install)</li></ul>                                                     |

完整的支持芯片列表详见 [Qualcomm AI Hub 设备列表](https://workbench.aihub.qualcomm.com/docs/hub/devices.html)。

<Tip>**手头无设备？** 登录 [Qualcomm Developer Cloud (QDC)](https://qdc.qualcomm.com/) 即可远程访问骁龙X、骁龙8至尊版与跃龙QCS9075。详见 [FAQ 中的 QDC 操作步骤](/cn/resources/faq#qdcqualcomm-device-cloud)。</Tip>

## **GenieX 运行环境**

GenieX 内置两种运行环境，让你在同一套 SDK 中同时获得**广泛的模型支持**与**骁龙芯片上的最佳性能**：

* **`llama_cpp`** —— Hugging Face 上的任意 GGUF 模型，可通过 Qualcomm 的 GGML Hexagon 后端在 Hexagon NPU、Adreno GPU 或 CPU 上运行，模型选择面最广。
* **`qairt`**（[Qualcomm® AI Engine Direct](https://www.qualcomm.com/developer/software/qualcomm-ai-engine-direct-sdk)）—— 来自 [Qualcomm AI Hub](https://aihub.qualcomm.com/models/) 的预编译模型包，按芯片编译并量化，固定运行在 Hexagon NPU 上。当你使用的模型来自 Qualcomm AI Hub 官方时，这是最高效的运行环境。

<Note>**Qualcomm AI Engine Direct**（也称为 *Qualcomm AI Engine Direct SDK*、*Qualcomm AI Runtime*，以及历史上的 *QAIRT*）是官方名称。本文档中我们统一使用该官方名称。</Note>

|                | **llama.cpp**              | **Qualcomm AI Engine Direct**     |
| -------------- | -------------------------- | --------------------------------- |
| **模型格式**       | GGUF（任意社区模型）               | Qualcomm AI Hub 预编译模型包            |
| **计算单元**       | NPU / GPU / CPU            | 仅 NPU                             |
| **精度（量化）由谁决定** | 你来选（`Q4_0`、`Q8_0`、`F16` 等） | 模型包内已预量化                          |
| **最适合场景**      | 从 Hugging Face 自带 GGUF 模型  | 在 Qualcomm® AI Hub 模型上获得最高 NPU 性能 |

希望运行 Hugging Face 上任意 GGUF 模型，或需要 CPU/GPU 回退（例如没有 HTP 的 IoT 设备），选 **`llama_cpp`**。希望在 Qualcomm AI Hub 已发布的模型上获得最快 NPU 路径，选 **`qairt`**。

### 默认值

如果不传入计算单元：

| 运行环境        | 默认计算单元                              |
| ----------- | ----------------------------------- |
| `llama_cpp` | `hybrid`（HTP + CPU 按张量调度——骁龙上的快速路径） |
| `qairt`     | `npu`                               |

部分模型系列会覆盖该默认值——例如 `gpt-oss` 在 `llama_cpp` 下会回退到 `npu`，因为它无法在 hybrid 路径上运行。

***

## **llama.cpp**

`llama_cpp` 运行环境通过 llama.cpp + Qualcomm 的 GGML Hexagon 后端执行**任意 GGUF 模型**。可从 Hugging Face 拉取任意社区 GGUF 模型，并在骁龙 NPU、Adreno GPU 或纯 CPU 上运行。

### 计算单元

`--compute` 与底层硬件的映射关系如下：

| 别名              | 行为                                                                      |
| --------------- | ----------------------------------------------------------------------- |
| `npu`           | 固定到 Hexagon NPU（`HTP0`）。最佳 NPU 独占路径。                                    |
| `gpu`           | 通过 OpenCL 使用 Adreno GPU。                                                |
| `cpu`           | 纯 CPU。强制 `nGpuLayers = 0`。                                              |
| `hybrid` *(默认)* | 空 `device_id` + `n_gpu_layers=999`——llama.cpp 的 HTP+CPU 按张量调度。**快捷使用。** |

`geniex pull` 时选择的精度也会决定模型最终落到哪里运行——详见[支持的精度（量化）](/cn/models/supported#支持的精度量化)。

***

## **Qualcomm AI Engine Direct**

`qairt` 运行环境通过 [Qualcomm® AI Engine Direct](https://www.qualcomm.com/developer/software/qualcomm-ai-engine-direct-sdk) 执行 **Qualcomm AI Hub** 上的预编译模型包。仅支持 NPU，模型包针对特定骁龙芯片编译并量化——当模型在 Qualcomm AI Hub 可用时，通常是最快的 NPU 部署方式。

### 计算单元

Qualcomm AI Engine Direct **仅支持 NPU**。

| 别名            | 行为                     |
| ------------- | ---------------------- |
| `npu` *(默认)*  | 固定 `HTP0`——唯一支持的路径。    |
| `cpu` / `gpu` | 自动转为 `npu` 并打印告警，绝不报错。 |

### 运行环境限制

模型包内已固化其**精度、上下文长度与 KV 缓存大小**——三者均无法在运行时修改。在 Android 上，`nGpuLayers != 0` 与 `nCtx != 0` 会被拒绝并返回 `PARAM_NOT_SUPPORTED`，请保持两者为默认值，仅调整 `max_tokens` / `enable_thinking`。如需改变精度或上下文长度，请从 [Qualcomm AI Hub](https://aihub.qualcomm.com/models/) 获取另一个模型包。

### Android 上的芯片

在 Android 上拉取 Qualcomm AI Hub 模型时**必须显式传入芯片类型**——自动识别仅在骁龙 Windows 上生效。可选值：

| 芯片 ID    | 芯片             |
| -------- | -------------- |
| `SM8750` | 骁龙 8 至尊版       |
| `SM8850` | 骁龙 8 至尊版 Gen 5 |

详见 [Android API 参考](/cn/run/android/api-reference#模型管理器) 中的 `ModelPullInput.chipset`。

### 限制

* 仅 NPU——无 CPU/GPU 回退。
* 上下文长度与 KV 缓存由模型包固定。
* 新增 Qualcomm AI Hub 模型需先在 C++ 侧注册（`third-party/geniex-qairt/models/{llm,vlm}_model_registry.h`）。

<br />

<div class="feedback-wrapper">
  <span class="feedback-label">Was this page helpful?</span>

  <div class="feedback-toggle">
    <input type="radio" name="feedback" id="feedback-yes" class="feedback-input" />

    <label for="feedback-yes" class="feedback-button">
      <img src="https://mintcdn.com/qualcomm-0801e48b/VijZ6eXFSGIGNc9Z/Images/FeedBack/thumbs-up.svg?fit=max&auto=format&n=VijZ6eXFSGIGNc9Z&q=85&s=9fa1e132909ee8667d02f775cd8bc108" alt="Thumbs up" class="feedback-icon" noZoom width="14" height="14" data-path="Images/FeedBack/thumbs-up.svg" />

      Yes
    </label>

    <input type="radio" name="feedback" id="feedback-no" class="feedback-input" />

    <label for="feedback-no" class="feedback-button">
      <img src="https://mintcdn.com/qualcomm-0801e48b/VijZ6eXFSGIGNc9Z/Images/FeedBack/thumbs-down.svg?fit=max&auto=format&n=VijZ6eXFSGIGNc9Z&q=85&s=7f5f8865b502b5262849a700e6989278" alt="Thumbs down" class="feedback-icon" noZoom width="14" height="14" data-path="Images/FeedBack/thumbs-down.svg" />

      No
    </label>
  </div>
</div>