> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 GenieX 运行 LLM/VLM

> 在 Qualcomm Dragonwing IQ9 设备上安装 GenieX CLI,拉取 Gemma 4 E4B 模型包,并在 Hexagon NPU 上运行文本、图像和音频推理。

GenieX 是 Qualcomm AI Hub 面向生成式模型的命令行和服务层。在 Dragonwing ARM64
Linux 主机上,它通过 Qualcomm 驱动库以原生方式在设备端 NPU 上运行模型。

本页将带您从新烧录的 IQ9 开发板出发,直到 Gemma 4 E4B 能够在 NPU 上响应提示。整个
搭建过程约需 15 分钟,大部分时间花在下载约 5 GB 的模型包上。

您将完成以下操作:

1. 安装系统和 Qualcomm 驱动包,然后安装 `geniex` CLI。
2. 从 AI Hub 拉取 Gemma 4 E4B 模型包。
3. 运行文本、图像和音频推理,并可选地对外提供兼容 OpenAI 的 API。

<Warning>
  本页的每一步都**直接在 IQ9 设备上运行**,而不是在开发主机上。
</Warning>

在开发板上打开会话:

```bash theme={null}
ssh ubuntu@<device-ip>
```

## 前置条件

| 要求   | 值                                                               |
| ---- | --------------------------------------------------------------- |
| 架构   | Linux ARM64(`aarch64`)                                          |
| 操作系统 | 适用于 Dragonwing IQ-9075 EVK 的 Ubuntu 镜像,或任何带有 Qualcomm BSP 的设备   |
| 芯片组  | Dragonwing IoT 芯片组 —— 本文使用 IQ-9075 / QCS9075                    |
| 可用存储 | ≥ 12 GB                                                         |
| 内存   | ≥ 12 GB                                                         |
| 网络   | 可访问 `qaihub-public-assets.s3.us-west-2.amazonaws.com` 的出站 HTTPS |

继续之前,先确认架构和可用空间:

```bash theme={null}
uname -m      # expected: aarch64
df -h /       # confirm at least 12 GB available
```

<Note>
  如果开发板尚未启动,请先完成设备设置 —— 参见
  [IQ-9075 EVK 设置指南](https://dragonwingdocs.qualcomm.com/Ubuntu/devices/iq9075-evk/set-up-the-device)。
  本文仅适用于 IQ9,其他平台请参考 [GenieX](https://aihub.qualcomm.com/geniex) 页面并选择受支持的模型。
</Note>

## 安装 GenieX

<Steps>
  <Step title="安装标准 APT 软件包">
    ```bash theme={null}
    sudo apt update
    sudo apt install -y libatomic1 libglib2.0-0 ocl-icd-libopencl1
    ```

    <Note>
      `ocl-icd-libopencl1` 会在下一步被 `qcom-adreno1` 取代;先安装它可以让最小镜像上
      的依赖解析器保持一致。
    </Note>
  </Step>

  <Step title="安装 Qualcomm 驱动包">
    `geniex` 通过 Qualcomm 专有驱动库访问 NPU,这些库由 `ubuntu-qcom-iot` PPA 提供。

    ```bash theme={null}
    sudo apt-get install -y qcom-adreno1 qcom-fastrpc1 libqnn1
    ```

    | 库                                                                         | 由以下软件包提供        |
    | ------------------------------------------------------------------------- | --------------- |
    | `libOpenCL_adreno.so.1`、`libCB.so.1`、`libadreno_utils.so.1`、`libgsl.so.1` | `qcom-adreno1`  |
    | `libcdsprpc.so.1.0.0`                                                     | `qcom-fastrpc1` |
    | QNN 后端库(`libQnnHtp.so`、`libQnnSystem.so`)                                 | `libqnn1`       |

    <Note>
      在 IQ9075 EVK 的 Ubuntu 镜像中已预先配置了 PPA(`ppa:ubuntu-qcom-iot/qcom-ppa`)。
      在自定义镜像上,可通过 `sudo add-apt-repository -y ppa:ubuntu-qcom-iot/qcom-ppa`
      添加,然后执行 `sudo apt update`。
    </Note>

    这三个软件包是安装失败最常见的原因。如果后续步骤报告缺少 `.so`,请回到这里检查。
  </Step>

  <Step title="运行安装脚本">
    如果 `HOME` 未设置 —— 在最小容器或 `sudo -s` 会话中常见 —— 请先导出它:

    ```bash theme={null}
    export HOME=/home/ubuntu
    ```

    ```bash theme={null}
    curl -fsSL https://qaihub-public-assets.s3.us-west-2.amazonaws.com/qai-hub-geniex/install.sh | sh
    ```

    该脚本会下载最新的稳定版本,验证其 SHA256 校验和,然后无需 `sudo` 完成安装。
  </Step>

  <Step title="将 GenieX 添加到 PATH">
    如果启动器目录尚不在 `PATH` 中,安装程序会输出确切的 export 语句。例如:

    ```bash theme={null}
    echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Step>

  <Step title="可选:为麦克风输入安装 SoX">
    仅当在交互式会话中使用 `/mic` 命令时才需要。从磁盘加载音频不需要它。

    ```bash theme={null}
    sudo apt install -y sox
    ```
  </Step>
</Steps>

### 验证安装

```bash theme={null}
geniex --help
```

如果找不到 `geniex`,请打开一个新的 shell,或应用安装程序输出的 `PATH` 语句。
如果命令因缺失共享库(如 `libCB.so.1` 或 `libcdsprpc.so.1.0.0`)而失败,说明未安装
Qualcomm 驱动包 —— 请参见步骤 2。

在任意命令后附加 `--log` 可提高日志级别。该标志等价于 `GENIEX_LOG` 环境变量,并且
优先级高于该环境变量。

| 级别      | 输出内容       |
| ------- | ---------- |
| `none`  | 无输出(默认)    |
| `error` | 仅错误        |
| `warn`  | 警告和错误      |
| `info`  | 信息级别及以上的消息 |
| `debug` | 调试级别及以上的消息 |
| `trace` | 全部         |

## 下载模型

```bash theme={null}
geniex pull google/gemma-4-E4B-it-qat-q4_0-gguf
```

传输大小约为 5 GB,因此在普通网络上需要数分钟。如果传输被中断,重新执行同一条命令
即可 —— 它会断点续传而不是重新下载。

通用语法为:

```bash theme={null}
geniex pull <model-name>[:<precision>]
```

| 标志             | 用途                                     |
| -------------- | -------------------------------------- |
| `--model-hub`  | 模型来源:`aihub`、`hf` 或 `localfs`。省略时自动检测。 |
| `--local-path` | 注册磁盘上已有的模型包。                           |

对于 GGUF 模型,如果发布了多种精度,CLI 会提示选择精度。请为 IQ9 选择 **`Q4_0`** ——
它是量化感知训练构建,能在 NPU 上以每字节最高的精度运行。可以内联指定以在脚本中跳过
提示:

```bash theme={null}
geniex pull google/gemma-4-E4B-it-qat-q4_0-gguf:Q4_0
```

确认结果:

```bash theme={null}
geniex list
```

<Note>
  `pull` 会将文件复制到 GenieX 缓存。成功执行 `--local-path` 拉取后,您可以删除源目录,
  而不必为约 5 GB 的模型保留两份副本。
</Note>

### 模型包内容

GenieX 会为您管理 GGUF 模型包。其中包含量化后的 `*.gguf` 权重、用于图像和音频输入的
`mmproj-*.gguf` 多模态投影器、嵌入在 GGUF 容器中的分词器元数据,以及一份记录精度、
运行时和默认计算单元的清单。

**Genie/QAIRT** 模型包 —— `w4a16` 构建,或 Jupyter 路径的输出 —— 则是显式的,必须
包含:

| 文件                            | 用途                               |
| ----------------------------- | -------------------------------- |
| `genie_config.json`           | 后端选择、模型和分词器路径、上下文和 token 限制      |
| `htp_backend_ext_config.json` | HTP/NPU 后端设置(SoC ID、DSP 架构、性能模式) |
| `tokenizer.json`              | 分词器词表和合并规则                       |
| `*.bin`                       | prompt 处理器和 token 生成器上下文二进制文件    |

<Note>
  Genie 示例配置发布在
  [AI Hub Apps 仓库](https://github.com/qualcomm/ai-hub-apps/tree/main/tutorials/llm_on_genie/configs/genie);
  字段定义参见
  [Genie dialog JSON 参考](https://docs.qualcomm.com/doc/80-63442-10/topic/json.html#genie-dialog-json-config-string)。
</Note>

## 运行推理

启动一个交互式聊天会话:

```bash theme={null}
geniex infer google/gemma-4-E4B-it-qat-q4_0-gguf
```

模型加载到 NPU 后会出现提示符。输入消息并按回车。

也可以传入单个 prompt 后退出 —— 适合脚本和冒烟测试:

```bash theme={null}
geniex infer google/gemma-4-E4B-it-qat-q4_0-gguf \
  -p "Summarize what a Hexagon NPU does in three sentences."
```

### 常用标志

| 标志                                | 效果                                                   |
| --------------------------------- | ---------------------------------------------------- |
| `-p "<prompt>"`                   | 执行一个 prompt 后退出,而不是打开会话。                             |
| `--think`                         | 在回答之前显示中间推理过程。                                       |
| `--think=false`                   | 直接回答。生产环境推荐。                                         |
| `--compute npu`                   | 在 Hexagon NPU 上运行。这是默认值。                             |
| `--compute cpu` / `--compute gpu` | 在 CPU 或 GPU 上运行。仅对 GGUF 构建有效;适用于 A/B 对比或排查 NPU 驱动问题。 |
| `--log <level>`                   | 提高日志级别以便诊断。                                          |

### 多模态 prompt

`q4_0` 模型包内置支持音频的投影器,因此一个 prompt 可以同时携带图像和音频片段。
将两个示例文件下载到您的主目录:

```bash theme={null}
cd ~
curl -L -o jfk.wav https://github.com/ggml-org/whisper.cpp/raw/master/samples/jfk.wav
curl -L -o landmark.jpg "https://images.pexels.com/photos/402028/pexels-photo-402028.jpeg?w=1024"
```

在 prompt 中通过绝对路径引用它们:

```bash theme={null}
geniex infer google/gemma-4-E4B-it-qat-q4_0-gguf \
  -p "Describe the image and transcribe the audio. Image: $HOME/landmark.jpg Audio: $HOME/jfk.wav"
```

预期输出:

```
**Image Description:**
This is a scenic, panoramic photograph that features a traditional Japanese temple ...

**Audio Transcription:**
And so my fellow Americans, ask not what your country can do for you, ask what you
can do for your country.
```

<Note>
  图像和音频输入始终使用**绝对**路径。相对路径会相对于进程的工作目录解析,是"文件未
  找到"错误的常见来源。
</Note>

在交互式会话中,`/mic` 用于录制片段,而不是从磁盘加载;`Ctrl-C` 停止录制并进行转写。
这需要 `PATH` 中有 SoX。

<Warning>
  QAIRT 模型报告 `audio: false`。向其传入音频文件会失败,提示
  `GenieXError(-201201): Multimodal generation failed`。音频请使用 GGUF 构建。
</Warning>

### 提供兼容 OpenAI 的端点

若要与应用集成,请运行本地服务器而不是交互式 CLI:

```bash theme={null}
geniex serve
```

服务器启动时会打印其监听的地址和端口。请将它们替换到下面的命令中:

```bash theme={null}
curl http://<device-ip>:<port>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemma-4-E4B-it-qat-q4_0-gguf",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of Italy?"}
    ],
    "stream": false
  }'
```

任何兼容 OpenAI 的客户端或框架都可以使用,包括 LangChain 和 Open WebUI。设置每次
请求的 `reasoning_format` 字段,可将思维模型的思维链从 `message.content` 中移到
`message.reasoning_content`,从而在保留推理供日志记录的同时,让呈现的回答保持简洁。

<Note>
  先在设备本地用 `curl` 测试。如果端点在本地可用但远程不可用,则可能是服务器绑定到
  了回环地址,或防火墙阻止了端口。
</Note>

## 性能和最佳实践

在 IQ9 上,参考数据为 4096 token 的上下文,约 660 tokens/s 的 prefill,以及
约 17.9 tokens/s 的 decode。由于 decode 大约比 prefill 慢 37 倍,输出长度对响应
时间的影响远大于 prompt 长度。

* **复用已加载的模型。** 模型加载是最大的固定成本 —— 请使用 `geniex serve` 或长期
  存在的交互式会话,而不是每次请求都调用 `geniex infer`。
* **限制输出长度。** 关心延迟时,应要求"三条要点",而不是"详细解释"。
* **保持 prompt 简短。** Prefill 很快,但 prompt token 仍然会占用生成所需的上下文。
* **关闭思维模式**(`--think=false`),除非您会使用推理轨迹;它可能会使生成的 token
  数成倍增加。
* **合理设置上下文大小。** KV 缓存内存随上下文长度增长,因此不要为一个永远用不到的
  任务配置大窗口。
* **关注温度。** 持续生成会提升 SoC 温度并触发降频;要衡量稳态吞吐,而不仅是第一次
  请求。
* **保留存储余量。** 大约按模型包 5 GB 的双倍容量预留空间,以便升级。

## 验证结果

| # | 检查项        | 命令                                                                     | 预期                     |
| - | ---------- | ---------------------------------------------------------------------- | ---------------------- |
| 1 | 架构正确       | `uname -m`                                                             | `aarch64`              |
| 2 | 驱动已安装      | `apt list --installed qcom-adreno1 qcom-fastrpc1 libqnn1`              | 三个包都在                  |
| 3 | CLI 可用     | `geniex --help`                                                        | 显示用法文本,无库错误            |
| 4 | 模型在缓存中     | `geniex list`                                                          | 列出 Gemma 4 E4B         |
| 5 | 推理返回文本     | `geniex infer google/gemma-4-E4B-it-qat-q4_0-gguf -p "Reply with OK."` | 模型加载后几秒内返回一段简短、连贯的回复   |
| 6 | 已选中 NPU 后端 | `geniex --log debug infer google/gemma-4-E4B-it-qat-q4_0-gguf -p "Hi"` | 日志中显示 NPU 后端,而非回退到 CPU |

如果任何检查失败,请参见"故障排查"。

## 下一步

发布的模型包现已在 NPU 上运行。如果它满足您对精度、上下文长度和许可的要求,那就
完成了 —— 可以开始将它集成到您的应用中。

如果您需要自定义量化方案、更长的上下文或您自己的检查点,请继续按 Jupyter 笔记本
路径操作。否则请前往"故障排查和后续步骤"。