使用 GenieX 运行 LLM/VLM - Qualcomm Dragonwing Documentation

GenieX 是 Qualcomm AI Hub 面向生成式模型的命令行和服务层。在 Dragonwing ARM64 Linux 主机上,它通过 Qualcomm 驱动程序库直接在设备 NPU 上原生运行模型。本页将带您从刚刷好镜像的 IQ9 开发板开始,直到 Gemma 4 E4B 在 NPU 上响应提示词。预计需要约 15 分钟完成设置,其中大部分时间用于下载约 5 GB 的模型包。您将:

从 AI Hub 拉取 Gemma 4 E4B 模型包。
运行文本、图像和音频推理,并可选择提供兼容 OpenAI 的 API 服务。

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

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

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`

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

uname -m      # expected: aarch64
df -h /       # confirm at least 12 GB available

如果开发板尚未完成启动配置,请先完成设备设置 — 请参阅 IQ-9075 EVK 设置指南。这仅适用于 IQ9;对于其他平台,请参阅 GenieX 页面并选择受支持的模型。

安装 GenieX

运行安装程序

如果未设置 HOME(在精简容器中很常见),请先将其导出:

export HOME=/root

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

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

验证 GenieX

geniex --help

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

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

下载模型

geniex pull google/gemma-4-E4B-it-qat-q4_0-gguf

这将传输约 5 GB 数据,在一般网络条件下需要几分钟。如果传输中断, 重新运行同一命令即可 — 它会继续下载,而不是从头开始。通用语法为:

geniex pull <model-name>[:<precision>]

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

对于 GGUF 模型,当发布了多个精度时,CLI 会提示您选择精度。对于 IQ9,请选择 Q4_0 — 这是经过量化感知训练的版本,在 NPU 上能提供最佳的单位字节精度。在脚本中可以内联固定该精度以跳过提示:

geniex pull google/gemma-4-E4B-it-qat-q4_0-gguf:Q4_0

确认结果:

geniex list

pull 会将文件复制到 GenieX 缓存中。使用 --local-path 成功拉取后,您可以删除源目录,而无需保留约 5 GB 模型的两份副本。

模型包内容

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 生成器上下文二进制文件

示例 Genie 配置发布在 AI Hub Apps 代码仓库中; 有关字段定义,请参阅 Genie dialog JSON 参考。

运行推理

启动交互式聊天会话:

geniex infer google/gemma-4-E4B-it-qat-q4_0-gguf

模型加载到 NPU 后,您会看到一个提示符。输入消息并按 Enter 键。也可以传入单个提示词后退出 — 这对于脚本和冒烟测试很有用:

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

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"

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

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.

图像和音频输入请始终使用绝对路径。相对路径会相对于进程工作目录进行解析, 是“file not found”错误的常见原因。

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

QAIRT 模型报告 audio: false。向其传入音频文件会失败并显示 GenieXError(-201201): Multimodal generation failed。请使用 GGUF 版本处理音频。

提供兼容 OpenAI 的端点

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

geniex serve

服务器启动时会打印其监听的地址和端口。请在下方命令中替换为这些值:

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,从而在保持呈现的答案简洁的同时, 保留推理过程用于日志记录。

请先在设备本机上使用 curl 进行测试。如果端点在本地可用但远程不可用, 则说明服务器绑定到了回环地址,或者防火墙阻止了该端口。

性能和最佳实践

在 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 路径。否则,请前往故障排除和后续步骤。

​先决条件

​安装 GenieX

​验证 GenieX

​下载模型

​模型包内容

​运行推理

​常用标志

​多模态提示词

​提供兼容 OpenAI 的端点

​性能和最佳实践

​验证结果

​下一步

先决条件

安装 GenieX

验证 GenieX

下载模型

模型包内容

运行推理

常用标志

多模态提示词

提供兼容 OpenAI 的端点

性能和最佳实践

验证结果

下一步