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

GenieX 是 Qualcomm AI Hub 面向生成式模型的命令行和服务层。在 Dragonwing ARM64 Linux 主机上,它通过 Qualcomm 驱动库以原生方式在设备端 NPU 上运行模型。本页将带您从新烧录的 IQ9 开发板出发,直到 Gemma 4 E4B 能够在 NPU 上响应提示。整个搭建过程约需 15 分钟,大部分时间花在下载约 5 GB 的模型包上。您将完成以下操作:

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

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

在开发板上打开会话:

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

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

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

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

安装 GenieX

安装标准 APT 软件包

sudo apt update
sudo apt install -y libatomic1 libglib2.0-0 ocl-icd-libopencl1

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

安装 Qualcomm 驱动包

geniex 通过 Qualcomm 专有驱动库访问 NPU,这些库由 ubuntu-qcom-iot PPA 提供。

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`

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

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

运行安装脚本

如果 HOME 未设置 —— 在最小容器或 sudo -s 会话中常见 —— 请先导出它:

export HOME=/home/ubuntu

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

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

将 GenieX 添加到 PATH

如果启动器目录尚不在 PATH 中,安装程序会输出确切的 export 语句。例如:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

可选:为麦克风输入安装 SoX

仅当在交互式会话中使用 /mic 命令时才需要。从磁盘加载音频不需要它。

sudo apt install -y sox

验证安装

geniex --help

如果找不到 geniex,请打开一个新的 shell,或应用安装程序输出的 PATH 语句。如果命令因缺失共享库(如 libCB.so.1 或 libcdsprpc.so.1.0.0)而失败,说明未安装 Qualcomm 驱动包 —— 请参见步骤 2。在任意命令后附加 --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`	prompt 处理器和 token 生成器上下文二进制文件

Genie 示例配置发布在 AI Hub Apps 仓库; 字段定义参见 Genie dialog JSON 参考。

运行推理

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

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

模型加载到 NPU 后会出现提示符。输入消息并按回车。也可以传入单个 prompt 后退出 —— 适合脚本和冒烟测试:

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 可以同时携带图像和音频片段。将两个示例文件下载到您的主目录:

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 中通过绝对路径引用它们:

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.

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

在交互式会话中,/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 的 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 笔记本路径操作。否则请前往”故障排查和后续步骤”。

​前置条件

​安装 GenieX

​验证安装

​下载模型

​模型包内容

​运行推理

​常用标志

​多模态 prompt

​提供兼容 OpenAI 的端点

​性能和最佳实践

​验证结果

​下一步

前置条件

安装 GenieX

验证安装

下载模型

模型包内容

运行推理

常用标志

多模态 prompt

提供兼容 OpenAI 的端点

性能和最佳实践

验证结果

下一步