跳转到主要内容

​
通用

面向高通骁龙的多平台 AI 推理 SDK。GenieX 在 Hexagon NPU、Adreno GPU 或 CPU 计算单元上端侧运行前沿 LLM 与 VLM，覆盖 Windows ARM64、Android 与 Linux ARM64。详见 GenieX 是什么。
  • 试用、写脚本 —— Windows ARM64 或 Linux ARM64 上的 CLI。
  • 构建应用 —— 本地服务器（兼容 OpenAI 协议的 HTTP）或 Python SDK。
  • 移动端 —— Android SDK（Kotlin，Maven Central）。
  • 可复现的 IoT 部署 —— Linux ARM64 EVK 上的 Docker 镜像，锁定到指定 release tag。
快速入门是这四条路径的统一入口。
支持的平台 —— Windows ARM64 上的 骁龙 X、Android 上的骁龙 8 至尊版、Linux ARM64 上的跃龙 QCS9075。

​
运行环境

  • llama.cpp —— 运行任意 GGUF 模型，支持 NPU/GPU/CPU 计算单元。最适合试用社区模型。
  • Qualcomm® AI Engine Direct（qairt）—— 运行 Qualcomm AI Hub 预编译模型，仅 NPU。当模型在 Qualcomm AI Hub 可用时，通常是最快路径。
详见平台与运行环境。
如果不传计算单元：
  • llama_cpp 默认 hybrid（HTP + CPU 按张量调度——骁龙上的快速路径）。
  • qairt 默认 npu。
部分模型会覆盖默认值——例如 gpt-oss 在 llama_cpp 下回退到 npu。
llama.cpp 在骁龙 NPU 上请用 Q4_0——它在 Hexagon NPU 上支持最佳。Qualcomm AI Hub 模型已预量化——无需选择。详见支持的精度（量化）。

​
模型

llama.cpp 运行环境可执行任意 GGUF 模型。详见运行 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 获取令牌。完整设置步骤见设置 Hugging Face 令牌。
模型 —— 按运行环境拆分（Qualcomm AI Engine Direct、llama.cpp）。

​
芯片与设备

是。GenieX 面向高通骁龙芯片——Hexagon NPU、Adreno GPU 与骁龙 ARM CPU 计算单元。不支持 x86 或非骁龙 ARM 设备。如手头无设备，可使用 Qualcomm Developer Cloud / Device Cloud。
不能。Qualcomm AI Engine Direct 设计上仅支持 NPU。cpu 与 gpu 别名会被自动转为 NPU 并打印告警。如需 CPU/GPU 回退，请改用 llama.cpp 运行环境（GGUF 模型）。

​
QDC（Qualcomm Device Cloud）

不需要。登录 Qualcomm Developer Cloud，选择一台骁龙设备，启动交互式会话——整个流程就是这样。关于哪些芯片在支持范围内，详见支持的平台。
1

建立 SSH 隧道

在 QDC 控制台中前往 Interactive Sessions 页面，点击 Connect 查看 SSH 连接说明。QDC 门户中用于查看 SSH 连接说明的 Connect 按钮打开终端，运行 QDC 提供的 SSH 隧道命令，把 <PRIVATE_KEY_FILE_PATH> 替换为你的私钥路径。使用私钥和端口转发配置 SSH 隧道
WARNING: UNPROTECTED PRIVATE KEY FILE! —— 你的 .pem 文件权限过宽。SSH 要求私钥仅文件所有者可读：
chmod 600 /path/to/your-key.pem
2

连接到设备

在新终端中通过转发端口 SSH 进入设备。默认密码为 oelinux123：
ssh -o StrictHostKeychecking=no -o UserKnownHostsFile=/dev/null -p 2222 root@localhost
已成功通过 SSH 连接到 QDC 设备
在 QDC 上使用 骁龙 8 Elite 或 8 Elite Gen 5 的交互式会话，并安装你从源码构建的 demo APK。从 qualcomm/ai-hub-apps 在 Android Studio 中构建示例应用（Build → Build APK(s)）以生成 .apk。
1

选择设备

登录 Qualcomm Device Cloud，选择 骁龙 8 Elite 或 骁龙 8 Elite Gen 5，并选择 Interactive session（交互式会话）。
2

配置会话

启用 Wi-Fi（让 demo 能下载模型）和 Keep screen on（避免下载中途锁屏）。无需 SSH。
3

上传 APK

在会话设置页用 Upload file 把你构建的 .apk 推送到设备——该文件必须在会话开始之前上传。
4

启动并测试

启动会话。在镜像屏幕中点击已上传的 APK 进行安装，然后从应用抽屉打开 GenieX Demo。
5

（可选）用图片测试 VLM

通过 QDC 终端上传一张测试图片：
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（推荐；Yocto 与 Ubuntu ARM64 均可用）
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）
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 安装程序——详见 Python 安装。不要安装 x86 / AMD64 版本：GenieX wheel 只支持 ARM64。

​
服务器 / API

是——详见本地服务器。可将官方 openai Python 客户端指向 http://127.0.0.1:18181/v1，OpenAI 代码无需修改即可复用。
不会。请先用 geniex pull 拉取模型再启动服务器。