> ## Documentation Index
> Fetch the complete documentation index at: https://qualcomm-0801e48b-fix-serve-reasoning-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 快速入门
> 使用 Kotlin 运行 GenieX Android SDK 中的第一个模型。
本页将指导你在 Kotlin 应用中运行第一个模型，然后再换用另一个模型。如需一个完整的参考应用——包含聊天 UI、模型选择器和 VLM 支持——请参阅[示例应用](https://github.com/qualcomm/ai-hub-apps/blob/release/geniex_chat_android/README.md)。
## **前置条件**
* 已将 SDK 添加到你的 Gradle 项目——参阅[安装](/cn/run/android/install)。
* 一台搭载 **骁龙 8 至尊版** 或 **骁龙 8 至尊版 Gen 5** 的手机。
* 在 `AndroidManifest.xml` 中声明 `INTERNET` 权限（SDK 会在首次使用时从 Hugging Face / Qualcomm AI Hub 拉取权重）。
## **运行你的第一个模型**
无论使用哪个模型，流程都是相同的：**初始化 SDK → 拉取权重 → 加载 → 生成**。下面是一个使用 `unsloth/Qwen3-0.6B-GGUF` 的最小端到端示例——这是一个小型的 Qwen3 0.6B 对话模型，可以在任何受支持的芯片组上运行。
在应用启动时调用一次（幂等——可安全地放在 `Activity.onCreate` 中）：
```kotlin theme={null}
GenieXSdk.getInstance().init(context)
```
`pullFlow` 会流式推送进度事件。在 `Dispatchers.IO` 上的协程中运行：
```kotlin theme={null}
ModelManagerWrapper.pullFlow(
ModelPullInput(
model_name = "unsloth/Qwen3-0.6B-GGUF",
precision = "Q4_0",
hub = HubSource.HUGGINGFACE,
)
).collect { event ->
when (event) {
is ModelManagerWrapper.PullEvent.Progress -> /* update UI */
ModelManagerWrapper.PullEvent.Completed -> /* done */
is ModelManagerWrapper.PullEvent.Error -> /* show error */
}
}
```
下载支持断点续传——在拉取过程中杀掉应用并重新运行，会从上次中断处继续。
解析磁盘上的路径并构建一个 `LlmWrapper`：
```kotlin theme={null}
val paths = ModelManagerWrapper.getPaths("unsloth/Qwen3-0.6B-GGUF")
?: error("Model not downloaded")
val llm = LlmWrapper.builder()
.llmCreateInput(
LlmCreateInput(
model_name = paths.model_name,
model_path = paths.model_path,
config = ModelConfig(nCtx = 4096),
runtime_id = "llama_cpp",
compute_unit = null, // null → NPU on Snapdragon (recommended)
)
)
.build()
.getOrThrow()
```
应用 chat template，然后从流式 flow 中收集 token：
```kotlin theme={null}
val chat = arrayListOf(ChatMessage("user", "What is AI?"))
val templated = llm.applyChatTemplate(chat.toTypedArray(), null, false).getOrThrow()
llm.generateStreamFlow(
templated.formattedText,
GenerationConfig(maxTokens = 2048),
).collect { result ->
when (result) {
is LlmStreamResult.Token -> print(result.text)
is LlmStreamResult.Completed -> println("\nDone")
is LlmStreamResult.Error -> println("Error: ${result.throwable}")
}
}
```
始终将 `templated.formattedText`（经过 chat template 处理的 prompt）传入 `generateStreamFlow`，而 **不是** 原始用户文本。原生工作流期望接收一个已经过 template 处理的 prompt。
## **切换模型**
切换模型主要就是更改 `model_name` 和 `runtime_id`。这里有两种运行环境：
* **`llama_cpp`** —— 运行任意 GGUF 模型。通过 `compute_unit` 支持 NPU / GPU / CPU 计算单元。
* **`qairt`**（Qualcomm AI Engine Direct）—— 运行 Qualcomm AI Hub 模型。仅支持 NPU，在 Android 上需要显式指定 `chipset`。
### 另一个 GGUF 模型 (llama.cpp)
只需更改 `model_name`（如果想要不同精度，再更改 `precision`）——其余流程完全相同：
```kotlin theme={null}
ModelPullInput(
model_name = "unsloth/Qwen3-VL-2B-Instruct-GGUF",
precision = "Q4_0",
hub = HubSource.HUGGINGFACE,
)
```
对于 VLM，还需将 `paths.mmproj_path` 传入 `VlmCreateInput`——参阅 [API 参考 → VLM](/cn/run/android/api-reference#vlm)。
### Qualcomm AI Hub 模型（通过 Qualcomm AI Engine Direct 使用 NPU）
Qualcomm AI Hub 模型会按芯片组预编译，且仅在 NPU 上运行。在 Android 上你 **必须** 传入 `chipset`：
```kotlin theme={null}
ModelManagerWrapper.pullFlow(
ModelPullInput(
model_name = "ai-hub-models/Qwen3-4B-Instruct-2507",
hub = HubSource.AUTO, // routes ai-hub-models/* to Qualcomm AI Hub
chipset = "SM8750", // SM8750 = 8 Elite, SM8850 = 8 Elite Gen 5
)
).collect { /* … */ }
```
然后在 `LlmCreateInput` 中切换为 `runtime_id = "qairt"`。受支持的 Qualcomm AI Hub 仓库参阅 [API 参考](/cn/run/android/api-reference#已支持模型)。
### 切换计算单元 (NPU / GPU / CPU)
仅适用于 `llama_cpp`——在 `LlmCreateInput` 上设置 `compute_unit`：
| `compute_unit` | 计算单元 |
| ----------------- | ------------------------ |
| `null` or `"npu"` | Hexagon NPU（骁龙上推荐）。 |
| `"gpu"` | 通过 OpenCL 使用 Adreno GPU。 |
| `"cpu"` | 纯 CPU。可在任意 ARM64 芯片组上运行。 |
Qualcomm AI Engine Direct 会忽略此设置——`cpu`/`gpu` 会带警告地被强制转换为 NPU。
## **使用本地模型**
如果权重已经在设备上——通过 `adb push` 侧载、打包进应用的 files 目录，或由其他工具生成——只需让模型管理器指向该目录，而不是某个 hub。设置 `hub = HubSource.LOCALFS`，并将 `local_path` 指向磁盘上的位置。`pullFlow` 会将其导入到 SDK 缓存中（不联网），之后 `getPaths` / `LlmWrapper` 的用法与下载的模型完全一致。
导入本地 GGUF 模型和本地 Qualcomm AI Engine Direct bundle 的完整 Android 代码片段位于“模型”页：
* [运行本地 Qualcomm AI Engine Direct bundle → Android](/cn/models/supported#run-a-local-qualcomm-ai-engine-direct-bundle)
* [运行本地 GGUF 模型 → Android](/cn/models/supported#run-a-local-gguf-model)
## **使用示例应用**
[示例应用](https://github.com/qualcomm/ai-hub-apps/blob/release/geniex_chat_android/README.md)是一个完整连通的聊天客户端，构建在上述代码片段之上。当你构建自己的 UI 时，有几个值得借鉴的模式：
* **模型选择器 UI** —— 下拉菜单由 `app/src/main/assets/model_list.json` 驱动。每个条目固定了一个 `model_name`、`hub`，以及一个 `chipset`（对于 Qualcomm AI Engine Direct）。编辑此文件即可添加新模型而无需改动代码。
* **带进度的断点续传下载** —— 来自 `pullFlow` 的 `Progress` 事件携带每个文件的字节计数；示例将它们直接接入 `LinearProgressIndicator`。
* **运行环境感知的计算单元选择器** —— 当所选模型使用 Qualcomm AI Engine Direct 时，选择器会隐藏 GPU/CPU 选项。参阅 `LoadDialog.kt`。
* **VLM 图片选择器** —— 对于 VLM，示例会将绝对文件路径传入 `VlmContent("image", path)`。不要传入 content URI——原生侧会直接读取文件。
克隆 [`qualcomm/ai-hub-apps`](https://github.com/qualcomm/ai-hub-apps/blob/release/geniex_chat_android/README.md)，在 Android Studio 中打开并点击 **Run ▶**。
## **下一步**
Wrapper 类、运行环境 / 计算单元选择与数据结构。
骁龙平台，以及何时选择 llama.cpp 或 Qualcomm AI Engine Direct。