README Zh CN

在高通设备上本地运行前沿 LLM 与 VLM 的最简方式

文档 · 快速入门 · 模型 · 社区与联系方式

English · 简体中文

GenieX 是一款面向高通设备的端侧生成式 AI 推理运行时。你几乎可以引入任意来自 Hugging Face 的 GGUF 模型——或来自 Qualcomm AI Hub 的预编译模型包——只需几行代码即可在 Hexagon NPU、Adreno GPU 或 CPU 上本地运行。底层是同一套 C SDK，并通过 CLI、Python、Kotlin/Java、Docker 以及一个 OpenAI 兼容服务器交互。它是 Qualcomm GENIE 的社区版本。

支持的平台

GenieX 仅在高通骁龙（Qualcomm Snapdragon）上运行。找到你的平台，然后直接跳转到你想使用的接口。

手边没有设备？在 Qualcomm Device Cloud 上开启一个远程会话。

快速入门

从下方选择你的接口。每个接口都遵循相同的三个步骤——安装（Install）、运行（Run） 和 文档（Docs）——并同时展示两种运行时：来自 Hugging Face 的 GGUF 模型（llama_cpp）和来自 Qualcomm AI Hub 的预编译模型包（qairt，NPU）。

CLI

安装

• Windows ARM64 —— 下载安装程序，运行它，然后打开一个新终端。
• Linux ARM64 —— 一行命令，无需 sudo：
  bashCopy

  curl -fsSL https://qaihub-public-assets.s3.us-west-2.amazonaws.com/qai-hub-geniex/install.sh | sh
  

运行 —— 一行命令即可与任意模型对话（对于 VLM，拖入一张图片即可）：

# 来自 Hugging Face 的 GGUF → llama.cpp（NPU / GPU / CPU）
geniex infer google/gemma-4-E4B-it-qat-q4_0-gguf

# 来自 Qualcomm AI Hub 的预编译模型包 → Qualcomm AI Engine Direct（NPU）
geniex infer ai-hub-models/Qwen2.5-VL-7B-Instruct

📖 文档 —— 安装 · 快速入门 · 命令参考

Python

安装

pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple geniex

运行 —— 与 Hugging Face transformers 保持一致（from_pretrained() → .generate()）：

# 来自 Hugging Face 的 GGUF → llama.cpp
from geniex import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("unsloth/Qwen3.5-2B-GGUF", precision="Q4_0")

messages = [{"role": "user", "content": "What is 2+2?"}]
prompt = model.tokenizer.apply_chat_template(messages, add_generation_prompt=True)

for chunk in model.generate(prompt, max_new_tokens=256, stream=True):
    print(chunk, end="", flush=True)

model.close()

# 来自 Qualcomm AI Hub 的预编译模型包 → Qualcomm AI Engine Direct（NPU）
from geniex import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("ai-hub-models/Qwen3-4B")

messages = [{"role": "user", "content": "What is 2+2?"}]
prompt = model.tokenizer.apply_chat_template(messages, add_generation_prompt=True)

for chunk in model.generate(prompt, max_new_tokens=256, stream=True):
    print(chunk, end="", flush=True)

model.close()

📖 文档 —— 安装 · 快速入门 · API 参考

OpenAI 兼容服务器

安装 —— 随 CLI 一同提供（见上文安装）。

运行 —— 拉取任意模型（GGUF 或 Qualcomm AI Hub 模型包），然后提供一个 OpenAI 兼容的 API：

geniex pull ai-hub-models/Qwen3-4B-Instruct-2507
geniex serve   # 服务于 http://127.0.0.1:18181/v1

curl http://127.0.0.1:18181/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai-hub-models/Qwen3-4B-Instruct-2507",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

将任意 OpenAI 客户端指向 http://127.0.0.1:18181/v1 即可——无需改动代码。

📖 文档 —— 本地服务器指南

Android（Kotlin / Java）

安装 —— 将 SDK 添加到应用模块的 build.gradle.kts：

dependencies {
    implementation("com.qualcomm.qti:geniex-android:0.3.1")
}

运行 —— 最快的上手路径是示例应用（含聊天 UI、支持 GGUF + Qualcomm AI Hub 模型包的模型选择器、VLM 支持）：

Android 演示应用位于 qualcomm/ai-hub-apps。克隆它，在 Android Studio 中打开示例应用，然后点击 Run。

📖 文档 —— 安装 · 快速入门 · API 参考

Docker

安装

docker pull docker.io/qualcomm/geniex:latest

运行 —— 容器封装了 CLI，因此 geniex infer … 的用法与上文完全一致。

📖 文档 —— Docker 指南

C / C++ SDK

安装 —— 链接单一的 C 头文件 sdk/include/geniex.h；其他所有接口都只是它之上的一层薄封装。

📖 文档 —— sdk/README.md · notes/build.md

模型

GenieX 拥有两套运行时，让你在同一技术栈中既能获得广泛的模型覆盖，又能获得骁龙上的峰值性能。LLM 与 VLM 均受支持。

对于 llama.cpp，在提示时请选择 Q4_0 精度——它对 Hexagon NPU 的支持最佳。完整的模型列表、精度以及如何运行本地模型，请参阅模型指南 →。

🤝 贡献

欢迎贡献！在提交 PR 之前，请阅读 CONTRIBUTING.md，了解分支命名、提交 / PR 标题格式、预提交检查，以及针对公共 SDK 头文件的 FFI 更新规则。

💬 社区与联系方式

有问题、想法，或想展示你的作品？欢迎来打个招呼。

• 💬 Slack —— 提问并与社区实时交流。
• 🐛 GitHub Issues —— 报告缺陷或提出功能请求。
• 🔗 LinkedIn —— 关注 Qualcomm AI Hub 获取新闻与更新。

贡献者

感谢每一位共建 GenieX 的伙伴 💙

📄 许可证

BSD 3-Clause —— 参阅 LICENSE 与 NOTICE。

本项目的使用还须遵守高通的使用条款。