教程:VENTUNO Q/llama.cpp

概述

Arduino® VENTUNO™ Q 由 Qualcomm® Dragonwing™ QCS8275 驱动，该芯片具有支持 OpenCL 3.0 的 Adreno™ GPU。这使得可以使用 llama.cpp 直接在开发板上运行大语言模型（LLM）。

在 llama.cpp 下运行的模型在 GPU 上执行。开发板的 Hexagon™ NPU 也可以通过 Qualcomm 的 GenieX 运行时运行相同模型，并且大约快三倍——两条路径此处都有介绍。差异见 在 GPU 与 NPU 之间选择。

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

1. 在 VENTUNO Q 上安装 OpenCL 依赖。
2. 使用 OpenCL 后端构建 llama.cpp。
3. 下载并量化 LLM。
4. 提供模型服务，并从本地网络上的浏览器访问它。
5. 使用 GenieX 在 Hexagon™ NPU 上运行相同模型，并对比两者。

说明：

说明： 本教程使用的 Qwen2.5-1.5B 模型 约 3.6 GB，你从它创建的量化副本还需要额外空间。开始本教程前请确保有足够可用磁盘空间。

在 GPU 与 NPU 之间选择

在此开发板上运行 LLM 有三种方式。其中两种今天可用，并且到达不同的处理器。

路径	运行于	在 VENTUNO Q 上的状态
带 OpenCL 后端的 llama.cpp	Adreno™ GPU	受支持。这是下文从源码构建的路径。
GenieX	Hexagon™ NPU	受支持，且明显更快。见 Running LLMs and VLMs on the NPU with GenieX。
带 ggml-hexagon 后端的 llama.cpp	Hexagon™ NPU	实验性，且比此处固定的 llama.cpp 修订版更新。构建需要 Hexagon™ SDK。

本教程从源码针对 GPU 构建 llama.cpp，因为这样做能展示各组件如何配合，也因为生成的二进制文件（llama-cli、llama-quantize、llama-server）本身就很有用——尤其是 llama-quantize，它生成两条路径都使用的模型文件。

如果你的目标只是在此开发板上获得最快的本地 LLM，通过 GenieX 的 NPU 路径是更好的选择，本教程末尾使用完全相同的模型文件介绍了它。

NPU 上的 llama.cpp

llama.cpp 有自己的 Hexagon™ NPU 后端 ggml-hexagon，可为架构 v73、v75、v79 与 v81 构建 HTP skeleton。VENTUNO Q 的 DSP 是 HTP v75（在开发板上可见为 /usr/lib/dsp/cdsp/libQnnHtpV75Skel.so），因此硬件受支持，以此方式提供的模型约以每秒 25 个 token 运行。

该后端不是本指南固定的 llama.cpp 修订版的一部分，其作者将其标记为实验性。构建它除了下文安装的工具外，还需要 Qualcomm® Hexagon™ SDK。若要尝试，请参阅 llama.cpp 的 Snapdragon 后端文档 及其 Linux 构建说明。它目前支持 Q4_0 模型，这正是本指南生成的量化，因此模型文件可沿用。

若要在没有 SDK 的情况下使用 NPU，GenieX 用一条安装命令即可到达相同硬件并以相同速度运行。

硬件与软件要求

硬件要求

• Arduino® VENTUNO™ Q（1 块）
• Arduino® USB-C® Power Supply (65W)，或在圆口插孔上使用 7–24 V 直流电源
• Arduino® USB Type-C® Cable (2in1)（1 根）

警告：

重要： 请始终 先 将电源连接到圆口插孔，再 连接 USB-C® 线缆。在开发板未供电时先连接 USB-C® 可能导致开发板崩溃。

访问开发板 Shell

要访问 VENTUNO Q 上的 Ubuntu® shell，请使用 adb 或 ssh。

通过 adb — 在 VENTUNO Q 与电脑之间连接 USB-C® 线缆，然后运行：

adb shell

通过 ssh — 确保 VENTUNO Q 与电脑连接到同一网络，然后运行：

ssh arduino@<ip-address>

说明：

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

构建 llama.cpp

步骤 1：安装构建依赖

安装基本构建工具：

sudo apt update
sudo apt install -y cmake ninja-build curl libcurl4-openssl-dev build-essential

步骤 2：安装 OpenCL 依赖

在 VENTUNO Q 上获取 OpenCL 头文件与 ICD 加载器有两种方式。

选项 A — 包管理器（推荐）：

安装 OpenCL 头文件与 ICD 加载器，以及 Qualcomm 的 Adreno™ OpenCL 驱动：

sudo apt update
sudo apt install ocl-icd-opencl-dev opencl-headers qcom-adreno-cl1

注意：

重要： qcom-adreno-cl1 是 Qualcomm® Adreno™ OpenCL 用户态驱动，没有它 llama.cpp 将无法使用 GPU。开源 Mesa 驱动（mesa-opencl-icd，也称为 rusticl）确实能检测到 Adreno™ 623 并会出现在 clinfo 中，但它不暴露 llama.cpp 的 OpenCL 后端所需的 OpenCL subgroups 扩展。仅安装 Mesa 时，llama.cpp 会打印 drop unsupported device 并静默回退到 CPU。

要验证 OpenCL 是否被检测到，安装 clinfo：

sudo apt install -y clinfo
clinfo | grep -E "Platform Name|Device Name"

安装 Qualcomm® 驱动后，你应看到 QUALCOMM Snapdragon(TM) 平台，而不仅仅是 rusticl。

选项 B — 从源码构建（以便完全控制版本）：

警告：

注意： 选项 B 会替换属于系统的文件。它会在符号链接自己的副本之前删除 /usr/lib/libOpenCL.so 与整个 /usr/include/CL 目录，这会影响开发板上所有其他使用 OpenCL 的程序。仅当你特别需要与打包版本不同的头文件或加载器版本时才使用它——选项 A 足以构建 llama.cpp，并保持系统包完好。

mkdir -p ~/dev/llm

# Symlink the OpenCL shared library
sudo rm -f /usr/lib/libOpenCL.so
sudo ln -s /lib/aarch64-linux-gnu/libOpenCL.so.1.0.0 /usr/lib/libOpenCL.so

# OpenCL headers
cd ~/dev/llm
git clone https://github.com/KhronosGroup/OpenCL-Headers
cd OpenCL-Headers
git checkout 5d52989617e7ca7b8bb83d7306525dc9f58cdd46
mkdir -p build && cd build
cmake .. -G Ninja \
    -DBUILD_TESTING=OFF \
    -DOPENCL_HEADERS_BUILD_TESTING=OFF \
    -DOPENCL_HEADERS_BUILD_CXX_TESTS=OFF \
    -DCMAKE_INSTALL_PREFIX="$HOME/dev/llm/opencl"
cmake --build . --target install

# ICD Loader
cd ~/dev/llm
git clone https://github.com/KhronosGroup/OpenCL-ICD-Loader
cd OpenCL-ICD-Loader
git checkout 02134b05bdff750217bf0c4c11a9b13b63957b04
mkdir -p build && cd build
cmake .. -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH="$HOME/dev/llm/opencl" \
    -DCMAKE_INSTALL_PREFIX="$HOME/dev/llm/opencl"
cmake --build . --target install

# Symlink OpenCL headers for the compiler to find them
sudo rm -rf /usr/include/CL
sudo ln -s ~/dev/llm/opencl/include/CL/ /usr/include/CL

步骤 3：构建 llama.cpp

克隆并启用 OpenCL 后端构建 llama.cpp：

cd ~/dev/llm

# Clone the repository
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

# This commit has been explicitly tested; use main for the latest changes
git checkout f6da8cb86a28f0319b40d9d2a957a26a7d875f8c

# Build
mkdir -p build && cd build
cmake .. -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_SHARED_LIBS=OFF \
    -DGGML_OPENCL=ON
ninja -j$(nproc)

步骤 4：将 llama.cpp 添加到 PATH

cd ~/dev/llm/llama.cpp/build/bin

echo "" >> ~/.bash_profile
echo "# Begin llama.cpp" >> ~/.bash_profile
echo "export PATH=\$PATH:$PWD" >> ~/.bash_profile
echo "# End llama.cpp" >> ~/.bash_profile
echo "" >> ~/.bash_profile

# Apply changes to the current session
source ~/.bash_profile

验证安装：

llama-cli --version

然后确认 llama.cpp 确实可以使用 GPU：

llama-cli --list-devices

正常工作的设置会报告 Qualcomm® 平台并保留设备：

ggml_opencl: selected platform: 'QUALCOMM Snapdragon(TM)'
ggml_opencl: device: 'QUALCOMM Adreno(TM) 623 (OpenCL 3.0 Adreno(TM) 623)'
ggml_opencl: vector subgroup broadcast support: true

如果你看到平台为 rusticl，随后是 drop unsupported device 以及空的设备列表，则缺少 Qualcomm® Adreno™ 驱动——请回到步骤 2 并安装 qcom-adreno-cl1。

下载并量化模型

要获得 GPU 加速性能，你需要 GGUF 格式 的 纯 Q4_0 量化 模型。你可以下载预量化模型，或使用 llama-quantize 自行量化。

以下示例使用 Qwen2.5-1.5B-Instruct：

# Download the fp16 base model
wget https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct-GGUF/resolve/main/qwen2.5-1.5b-instruct-fp16.gguf

# Quantize to pure Q4_0
llama-quantize --pure qwen2.5-1.5b-instruct-fp16.gguf qwen2.5-1.5b-instruct-q4_0-pure.gguf Q4_0

说明：

说明： 同一仓库也发布了现成的 qwen2.5-1.5b-instruct-q4_0.gguf，但此处不要把它当作捷径使用。标准 Q4_0 文件会将某些张量保持在更高精度，而 --pure 标志强制每个张量都为 Q4_0，这正是 OpenCL 后端将整个模型跑在 GPU 上所需的。下载 fp16 模型并自行量化，是获得真正纯净文件的可靠方式。

在本地网络上提供 LLM 服务

llama-server 会启动带有内置聊天界面的 Web 服务器，同一网络上的任何浏览器都可访问。

1. 首先我们需要定位 VENTUNO Q 的 IP 地址：

hostname -I

<img src="" alt="查找正确的 IP 地址" />

说明：

运行 hostname -I 应能显示开发板的 IP 地址。请确保它已连接到 Wi-Fi® 网络。

2. 在端口 9876 上启动服务器：

llama-server -m ./qwen2.5-1.5b-instruct-q4_0-pure.gguf \
    --no-warmup -b 128 -c 2048 -s 11 -n 128 \
    --host 0.0.0.0 --port 9876

你应看到确认服务器正在运行的输出：

llama server listening at http://0.0.0.0:9876

加载模型时，llama.cpp 会报告有多少层卸载到了 GPU。所有层都应被卸载：

load_tensors: offloading 28 repeating layers to GPU
load_tensors: offloading output layer to GPU
load_tensors: offloaded 29/29 layers to GPU
load_tensors:       OpenCL model buffer size =   828.59 MiB

无需额外标志——一旦使用 OpenCL 后端构建，llama.cpp 默认会将整个模型卸载到 Adreno™ GPU。在运行 Ubuntu 24.04 的 VENTUNO Q 上，此模型大约以 每秒 7.4 个 token 生成。

说明：

说明： 启动时你可能多次看到 libOpenCL.so.1: no version information available。这来自 Qualcomm® 驱动的符号版本控制，无害——请改为检查 offloaded 29/29 layers to GPU 这一行以确认正在使用 GPU。

3. 在同一网络上的任何设备上，打开浏览器并导航到：

http://<ip-address>:9876

说明：

说明： 将 <ip-address> 替换为步骤 1 中找到的地址。

4. 内置聊天界面可让你直接向模型发送提示：

<img src="" alt="llama-server 聊天界面" />

通过代码访问服务器（Python 示例）

我们也可以使用脚本查询 LLM。在下面的示例中，我们使用 Python 进行测试。请注意，你需要安装 requests 模块（pip install requests）。

import requests

# Replace with the IP address of your VENTUNO Q, from step 1 (`hostname -I`)
VENTUNO_Q_IP = "192.168.1.100"

url = f"http://{VENTUNO_Q_IP}:9876/v1/chat/completions"

payload = {
    "messages": [
        {"role": "user", "content": "Tell me a poem about microcontrollers in 10 words."}
    ],
}

response = requests.post(url, headers={ "Content-Type": "application/json" }, json=payload)
print(response.json().get("choices", [{}])[0].get("message", {}).get("content", "No response"))

响应应类似：

Microcontrollers, tiny and strong, guide the world, in every form, power and design they hold.

<img src="" alt="LLM 查询" />

在 NPU 上运行相同模型

你刚刚生成的 Q4_0 文件并不绑定到 llama.cpp。GenieX（Qualcomm 的端侧生成式 AI 运行时）可以加载相同文件，并在 Hexagon™ NPU 而非 GPU 上运行它——大约快三倍，且无需编译任何内容。

注册你构建的文件并运行：

mkdir -p ~/dev/llm/qwen25pure
cp ~/dev/llm/qwen2.5-1.5b-instruct-q4_0-pure.gguf ~/dev/llm/qwen25pure/

geniex pull qwen25-pure --model-hub localfs --local-path ~/dev/llm/qwen25pure
geniex infer qualcomm/qwen25-pure:Q4_0 --compute npu --prompt "Say hello in 5 words."

在运行 Ubuntu 24.04 的 VENTUNO Q 上测得，全程使用相同的 Q4_0 模型文件：

运行时	计算单元	生成速度
llama.cpp（本指南的 OpenCL 构建）	Adreno™ GPU	7.4 tok/s
GenieX	Adreno™ GPU	9.2 tok/s
GenieX	CPU	11.4 tok/s
GenieX	Hybrid	13.9 tok/s
GenieX	Hexagon™ NPU	~25 tok/s

有关安装 GenieX、从 Hugging Face 或 Qualcomm® AI Hub 下载模型，以及提供兼容 OpenAI 的 API，请参阅 Running LLMs and VLMs on the NPU with GenieX。

结论

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

• 使用包管理器或从源码构建，在 VENTUNO Q 上安装 OpenCL 依赖。
• 使用 Adreno™ GPU OpenCL 后端构建 llama.cpp。
• 将 LLM 下载并量化为 Q4_0 GGUF 格式。
• 使用 llama-server 提供模型服务，并从本地网络上的浏览器访问聊天界面。
• 使用 GenieX 在 Hexagon™ NPU 上运行相同的量化模型，速度约为 GPU 路径的 3 倍——见 Running LLMs and VLMs on the NPU with GenieX。

---

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