GenieX 仅运行在高通骁龙平台上——不适用于 x86 或非骁龙 ARM 产品。开始之前，先选择你要运行的骁龙平台，再根据你想运行的模型选择对应的运行环境。
骁龙平台
GenieX 覆盖三类骁龙平台——计算、移动与 IoT端，分别对应 Windows ARM64、Android 与 Linux ARM64。
| 操作系统 | 接入方式 |
|---|
| Windows ARM64 （桌面端 / Copilot+ PC） | |
| Android （移动端） | |
| Linux ARM64 （跃龙 IoT —— 摄像头、机器人、工业） | |
GenieX 运行环境
GenieX 内置两种运行环境，让你在同一套 SDK 中同时获得广泛的模型支持与骁龙芯片上的最佳性能：
llama_cpp —— Hugging Face 上的任意 GGUF 模型，可通过 Qualcomm 的 GGML Hexagon 后端在 Hexagon NPU、Adreno GPU 或 CPU 上运行，模型选择面最广。qairt（Qualcomm® AI Engine Direct）—— 来自 Qualcomm AI Hub 的预编译模型包，按芯片编译并量化，固定运行在 Hexagon NPU 上。当你使用的模型来自 Qualcomm AI Hub 官方时，这是最高效的运行环境。
Qualcomm AI Engine Direct（也称为 Qualcomm AI Engine Direct SDK、Qualcomm AI Runtime，以及历史上的 QAIRT）是官方名称。本文档中我们统一使用该官方名称。
| 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 性能 |
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 时选择的精度也会决定模型最终落到哪里运行——详见支持的精度（量化）。
Qualcomm AI Engine Direct
qairt 运行环境通过 Qualcomm® AI Engine Direct 执行 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 获取另一个模型包。
Android 上的芯片
在 Android 上拉取 Qualcomm AI Hub 模型时必须显式传入芯片类型——自动识别仅在骁龙 Windows 上生效。可选值：
| 芯片 ID | 芯片 |
|---|
SM8750 | 骁龙 8 至尊版 |
SM8850 | 骁龙 8 至尊版 Gen 5 |
ModelPullInput.chipset。
- 仅 NPU——无 CPU/GPU 回退。
- 上下文长度与 KV 缓存由模型包固定。
- 新增 Qualcomm AI Hub 模型需先在 C++ 侧注册（
third-party/geniex-qairt/models/{llm,vlm}_model_registry.h）。