平台与运行环境

import Feedback from "/snippets/page-feedback.mdx";

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

骁龙平台

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

操作系统	接入方式
Windows ARM64 （桌面端 / Copilot+ PC）	<ul><li>CLI</li><li>Python SDK</li><li>本地服务器</li></ul>
Android （移动端）	<ul><li>Android SDK（Kotlin，Maven Central）</li></ul>
Linux ARM64 （跃龙 IoT —— 摄像头、机器人、工业）	<ul><li>原生安装</li><li>Docker</li></ul>

完整的支持芯片列表详见 Qualcomm AI Hub 设备列表。

<Tip>手头无设备？ 登录 Qualcomm Developer Cloud (QDC) 即可远程访问骁龙X、骁龙8至尊版与跃龙QCS9075。详见 FAQ 中的 QDC 操作步骤。</Tip>

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 官方时，这是最高效的运行环境。

<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	npu（固定到 HTP0）
qairt	npu

如需 llama.cpp 的 HTP + CPU 按张量调度（骁龙上更快的路径），显式传入 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=-1（全部层）——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 获取另一个模型包。

<Feedback/>