教程:VENTUNO Q/GenieX

来自WindwizPi wiki
< 教程:VENTUNO Q
Windwiz​（留言 | 贡献）2026年9月28日 (一) 05:58的版本 （导入 VENTUNO Q 中文教程）
(差异) ←上一版本 | 最后版本 (差异) | 下一版本→ (差异)

概述

GenieX 是 Qualcomm® 的端侧生成式 AI 运行时，也是 Qualcomm GENIE 的社区版。它可以从 Hugging Face 获取 GGUF 模型，或从 Qualcomm® AI Hub 获取预编译包，并在 Arduino® VENTUNO™ Q 的 Hexagon™ NPU、Adreno™ GPU 或 CPU 上本地运行。

在 VENTUNO Q 上运行语言与视觉语言模型有多种方式，其中 GenieX 既是最快也是最容易设置的：一条命令即可安装，无需管理员权限，也无需编译任何内容。

在本教程中，你将学习如何：

  1. 在 VENTUNO Q 上安装 GenieX。
  2. 下载模型。
  3. 在 NPU 上运行推理，并与 GPU、CPU 进行对比。
  4. 使用图像运行视觉语言模型（VLM）。
  5. 通过兼容 OpenAI 的 API 提供模型服务。

说明：

说明： GenieX 以 Developer Preview 形式发布。以下命令已在运行 Ubuntu® 24.04 与 GenieX v0.4.0 的 VENTUNO Q 上验证，但请预期接口会在版本之间持续变化。

硬件与软件要求

硬件

软件

  • 主机上可用的 adb 或 ssh
  • 至少 5 GB 可用磁盘空间，用于本教程所用模型

注意：

重要： 在将 USB-C® 线缆连接到主机电脑之前，必须先用电源为 VENTUNO Q 供电，否则开发板可能会崩溃。

访问开发板 Shell

本指南中的所有命令都在 VENTUNO Q 上 运行。使用以下任一方法连接： 

# Using adb (Android Debug Bridge)
adb shell

# Using ssh (Secure Shell)
ssh arduino@<ip-address>

说明：

有关远程访问开发板的更多替代方案，请参阅 Remote Access 教程。

安装 GenieX

GenieX 安装到你的主目录，因此不需要 sudo： 

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

安装程序将二进制文件放在 ~/.local/share/geniex，在 ~/.local/bin/geniex 添加启动器，并链接开发板的 DSP 库，以便运行时可以访问 NPU。将启动器目录添加到你的 PATH： 

export PATH="$HOME/.local/bin:$PATH"

将该行添加到 ~/.bashrc 以使其永久生效，然后检查安装： 

geniex --version

这将报告 CLI 版本以及其后的运行时： 

GenieX CLI Version:     v0.4.0
QAIRT Runtime Version:  v2.45.0.260326
LlamaCPP Runtime Hash:  6ba5ef2

这两个运行时是 GenieX 访问硬件的方式：llama.cpp 用于 GGUF 模型，Qualcomm® AI Runtime (QAIRT) 用于预编译的 AI Hub 包。

下载模型

GenieX 使用 geniex pull 在本地缓存模型。它可以从 Hugging Face、Qualcomm® AI Hub、Docker Hub，或开发板上的目录获取模型。

拉取本教程通篇使用的 Q4_0 Gemma 4 E2B 模型。它由 Google 发布，并用于 Qualcomm 的 GenieX 示例： 

geniex pull google/gemma-4-E2B-it-qat-q4_0-gguf --model-hub hf

此仓库提供 Q4_0 语言模型及其视觉投影器。GenieX 会下载两者，并将缓存的精度记录为 Q4_0。

说明：

说明： 包含多种精度的仓库会打开交互式提示。通过 ssh 或 adb 脚本化拉取此类模型时，请将精度追加到模型名称，例如 :Q4_0。

说明：

说明： 对于 NPU 执行，优先使用 Q4_0 量化。这是 Hexagon™ 内核所优化的格式。

如果你已在开发板上有一个 .gguf 文件——例如在跟随 llama.cpp 教程 时用 llama-quantize 生成的文件——可改为从本地目录注册它： 

mkdir -p ~/models/my-model
cp ~/path/to/model.gguf ~/models/my-model/

geniex pull my-model --model-hub localfs --local-path ~/models/my-model

说明：

说明： --local-path 需要一个目录或 AI Hub .zip 归档，而不是单独的 .gguf 文件。直接指向文件会失败，并提示 local path ... is a file but not a .zip。

随时列出已缓存的内容： 

geniex list
NAME SIZE PRECISIONS
google/gemma-4-E2B-it-qat-q4_0-gguf 4.0 GiB Q4_0

在 NPU 上运行推理

使用 geniex infer 运行模型。--compute 标志选择处理器，默认值为 npu： 

geniex infer google/gemma-4-E2B-it-qat-q4_0-gguf:Q4_0 \
  --compute npu --max-tokens 32 --think=false \
  --prompt "Reply with exactly: NPU OK"

GenieX 会打印回复，随后是一行包含生成速度、token 数量和首 token 时间的摘要： 

NPU OK

— 12.8 tok/s • 3 tok • 0.2 s first token —

对比各处理器

GPU 路径需要 Qualcomm 的 OpenCL 驱动。在运行对比之前请先安装： 

sudo apt update
sudo apt install -y qcom-adreno-cl1

同一命令使用不同的 --compute 值会在芯片的其他位置运行相同模型，从而便于看清取舍。以下结果在运行 Ubuntu® 24.04 的 VENTUNO Q 上、使用 Gemma 4 E2B 模型测得，每次运行使用相同的 128-token 提示：

--compute 运行于 生成速度
cpu Kryo™ CPU 4.7 tok/s
gpu Adreno™ 623 4.6 tok/s
hybrid CPU 与 NPU 一起 6.5 tok/s
npu Hexagon™ NPU 12.7 tok/s

在此模型上，NPU 比 CPU 快两倍以上，并且大约在 0.2 秒内到达首 token，这使得聊天界面感觉响应迅速。

有关直接设置 llama.cpp 与 Ollama 的对比，请参阅 在 Ventuno Q 上运行本地 LLM。

常用标志

  • --max-tokens <n> — 限制回复长度。
  • --system-prompt "<text>" — 设置系统提示。
  • --think=false — 对支持思考模式的模型禁用思考模式。
  • --nctx <n> — 上下文窗口大小，用于 llama.cpp 运行时。
  • --temperature、--top-p、--top-k — 常见采样控制。

运行视觉语言模型

VLM 同时接受图像与文本。本教程中已下载的 Gemma 4 E2B 模型已包含视觉支持，因此不需要第二个模型。

通过在提示中将图像的绝对路径放在尖括号内来传入图像： 

geniex infer google/gemma-4-E2B-it-qat-q4_0-gguf:Q4_0 \
  --compute npu \
  --prompt "Describe this image </home/arduino/photos/example.png>"

图像必须在 VENTUNO Q 上可用。GenieX 在设备上对其进行编码，并在终端中返回模型的描述。交互使用前请先缩小大尺寸照片：256 × 384 的图像大约需要 32 秒到达首 token，而 1200 × 1800 的图像大约需要 194 秒。

提供兼容 OpenAI 的 API

要从另一台设备或你自己的代码使用模型，请启动内置服务器： 

geniex serve

默认监听 127.0.0.1:18181，并暴露兼容 OpenAI 的 API。要从网络上的其他位置访问，请绑定到所有接口： 

geniex serve --host 0.0.0.0:18181 --compute npu

警告：

警告： 该服务器不要求身份验证。除非确实需要远程访问，否则请保持默认的回环绑定，并且仅在受信任网络上暴露它。

使用 hostname -I 查找开发板的网络地址。在同一网络上的受信任设备中，打开 http://<board-ip>:18181。如果两台设备都使用 Tailscale，请在开发板上运行 tailscale ip -4 并使用该地址。这将打开交互式 Swagger API 浏览器，而不是聊天界面。

列出服务器可以看到的模型： 

curl http://127.0.0.1:18181/v1/models

{"data":[{"id":"google/gemma-4-E2B-it-qat-q4_0-gguf:Q4_0","created":0,"object":"model","owned_by":"google"}],"object":"list"}

并发送聊天补全请求： 

curl http://127.0.0.1:18181/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemma-4-E2B-it-qat-q4_0-gguf:Q4_0",
    "messages": [{"role": "user", "content": "Say hi in 3 words."}]
  }'

在请求体中添加 "stream": true，可在生成 token 时接收 Server-Sent Events。

VLM 使用相同的端点。使用 OpenAI 的多模态消息格式提供文本与绝对图像路径： 

curl http://127.0.0.1:18181/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemma-4-E2B-it-qat-q4_0-gguf:Q4_0",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image in one sentence."},
        {"type": "image_url", "image_url": {"url": "/home/arduino/photos/example.png"}}
      ]
    }]
  }'

由于 API 遵循 OpenAI schema，接受自定义 base URL 的客户端可以与开发板通信。创建虚拟环境并安装 OpenAI Python 包： 

python3 -m venv .venv
source .venv/bin/activate
python -m pip install openai

然后运行： 

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:18181/v1",
    api_key="geniex",
)

response = client.chat.completions.create(
    model="google/gemma-4-E2B-it-qat-q4_0-gguf:Q4_0",
    messages=[{"role": "user", "content": "Say hi in 3 words."}],
)
print(response.choices[0].message.content)

本地服务器会忽略 API 密钥，但客户端需要非空值。完整 API 参考请参阅 GenieX 本地服务器文档。

结论

在本教程中，你在 VENTUNO Q 上安装了 GenieX，下载了一个可用于语言与视觉任务的模型，在 Hexagon™ NPU 上运行了它，将 NPU 与 GPU、CPU 进行了对比，并通过兼容 OpenAI 的 API 使用了该模型。

NPU 路径是在此开发板上运行这些模型的最快方式，也是设置工作量最少的方式。从这里开始，你可以将现有的兼容 OpenAI 的应用指向开发板，或构建完全在 Dragonwing™ QCS8275 处理器上离线运行的多模态应用。

原文：https://docs.arduino.cc/tutorials/ventuno-q/geniex/ 本页为 Arduino 官方教程的中文翻译，供内部查阅。命令与代码保持原文。

检索自“https://windwiz-pi.com/index.php?title=教程:VENTUNO_Q/GenieX&oldid=2017”