> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.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. 从 AI Hub 拉取 Gemma 4 E4B 模型包。
2. 运行文本、图像和音频推理,并可选择提供兼容 OpenAI 的 API 服务。

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

在开发板上打开一个会话:

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

## 先决条件

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

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

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

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

### 安装 GenieX

<Steps>
  <Step title="运行安装程序">
    如果未设置 `HOME`(在精简容器中很常见),请先将其导出:

    ```bash theme={null}
    export HOME=/root
    ```

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

    该脚本会下载最新的稳定版本并验证其 SHA256 校验和。
  </Step>
</Steps>

### 验证 GenieX

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

在任意命令中添加 `--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` | 提示词处理器和 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 后,您会看到一个提示符。输入消息并按 Enter 键。

也可以传入单个提示词后退出 — 这对于脚本和冒烟测试很有用:

```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>"` | 运行一个提示词后退出,而不是打开会话。 |
| `--think` | 在给出答案之前显示中间推理过程。 |
| `--think=false` | 直接回答。建议在生产环境中使用。 |
| `--compute npu` | 在 Hexagon NPU 上运行。这是默认设置。 |
| `--compute cpu` / `--compute gpu` | 在 CPU 或 GPU 上运行。仅对 GGUF 版本有效;可用于 A/B 对比或隔离 NPU 驱动问题。 |
| `--log <level>` | 提高日志级别以便诊断。 |

### 多模态提示词

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

```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"
```

在提示词中通过绝对路径引用它们:

```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>
  图像和音频输入请始终使用**绝对**路径。相对路径会相对于进程工作目录进行解析,
  是“file not found”错误的常见原因。
</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 的预填充速度,以及
约 17.9 tokens/s 的解码速度。由于解码速度比预填充慢约 37 倍,输出长度对响应时间的
影响远大于提示词长度。

* **复用已加载的模型。** 模型加载是最大的固定开销 — 请使用 `geniex serve`
  或长期运行的交互式会话,而不是每个请求都调用一次 `geniex infer`。
* **限制输出长度。** 当延迟很重要时,请要求“三个要点”,而不是“详细解释”。
* **保持提示词简短。** 预填充速度很快,但提示词 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 notebook 路径。否则,请前往故障排除和后续步骤。