使用 Llama.cpp 运行 LLM/VLM - Qualcomm Dragonwing Documentation

您可以使用 llama.cpp 在 Dragonwing 开发板上运行多种大语言模型(LLM)和视觉语言模型(VLM)。llama.cpp 在 Dragonwing 设备上支持三种后端:CPU、GPU(通过 OpenCL)和 NPU(通过 Hexagon HTP 后端)。您也可以通过 GENIE 在 NPU 上运行部分模型。

选择后端

CPU:无需特殊驱动或额外的构建标志。可作为与 GPU 或 NPU 性能对比的基准。
GPU(OpenCL):使用 OpenCL 后端构建 llama.cpp,将模型层卸载到 Adreno GPU。同一构建也可以通过跳过 GPU 卸载在 CPU 上运行。
NPU(Hexagon HTP):使用 Snapdragon 工具链容器构建 llama.cpp,将模型层卸载到 Hexagon HTP 设备(HTP0),在受支持的模型上获得最佳性能。

NPU(Hexagon HTP)
GPU(OpenCL)
CPU

概述

使用 Hexagon HTP 后端为 Dragonwing 设备构建 llama.cpp,然后在 HTP0 上运行 GGUF 大语言模型。

这些说明侧重于将 Hexagon HTP 设备公开为 HTP0 的 Snapdragon 和 Dragonwing llama.cpp 构建。这与 GPU 选项卡中的 OpenCL GPU 工作流不同。

前提条件

在开始之前,请确保您已:

完成 Dragonwing 设备的首次设置:
- Dragonwing IQ8 设置
- Dragonwing IQ9 设置
可以通过 SSH 或直接连接的显示器、键盘和鼠标访问设备。
- 上面链接的设置指南包含网络、串行控制台访问、显示设置和 SSH 访问的说明。
在设备上安装了所需的 Dragonwing 软件包:
- Dragonwing IQ8
- Dragonwing IQ9
在构建主机上安装了 Docker。
有足够的可用空间用于构建输出和模型。每个模型请预留数 GB 空间。

所需软件包的安装过程会安装 QNN 运行时和工具,包括 llama.cpp 加速推理所需的 libqnn-dev 和 qnn-tools。

准备构建主机

在构建主机上,克隆 llama.cpp 或更新现有的检出。

mkdir -p ~/src
cd ~/src

# Clone if this is your first build
git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp

# For repeat builds, update to the latest upstream changes
git fetch origin
git checkout master
git pull --ff-only

如果您需要可复现的构建,请记录所构建的提交:

git rev-parse HEAD

使用 Snapdragon 工具链容器构建 llama.cpp

为 Dragonwing 构建 llama.cpp 最简单的方法是使用 Snapdragon ARM64 Linux 工具链容器。该容器包含 Snapdragon 预设所需的 ARM64 交叉编译器、CMake、OpenCL SDK 和 Hexagon SDK 组件。下面的 Docker 命令显式请求 linux/amd64 镜像。从 llama.cpp 检出目录的根目录启动容器:

docker run -it \
  -u $(id -u):$(id -g) \
  --volume $(pwd):/workspace \
  --platform linux/amd64 \
  ghcr.io/snapdragon-toolchain/arm64-linux:v0.1

在容器内,配置并构建 llama.cpp:

cd /workspace
cp docs/backend/snapdragon/CMakeUserPresets.json .

cmake --preset arm64-linux-snapdragon-release -B build-snapdragon
cmake --build build-snapdragon -j $(nproc)

创建可安装的软件包:

cmake --install build-snapdragon --prefix pkg-snapdragon
zip -r pkg-snapdragon.zip pkg-snapdragon

软件包完成后退出容器:

exit

软件包归档文件现在位于主机上的以下位置:

~/src/llama.cpp/pkg-snapdragon.zip

当上游 llama.cpp 变更时重新构建

llama.cpp 变更频繁。要使用最新的上游代码重新构建,请从主机检出目录重复以下更新和构建流程:

cd ~/src/llama.cpp
git fetch origin
git checkout master
git pull --ff-only

docker run -it \
  -u $(id -u):$(id -g) \
  --volume $(pwd):/workspace \
  --platform linux/amd64 \
  ghcr.io/snapdragon-toolchain/arm64-linux:v0.1

然后,在容器内:

cd /workspace
cp docs/backend/snapdragon/CMakeUserPresets.json .

rm -rf build-snapdragon pkg-snapdragon pkg-snapdragon.zip
cmake --preset arm64-linux-snapdragon-release -B build-snapdragon
cmake --build build-snapdragon -j $(nproc)
cmake --install build-snapdragon --prefix pkg-snapdragon
zip -r pkg-snapdragon.zip pkg-snapdragon

如果您要测试某个分支、标签或本地 llama.cpp 改动,请在运行 Docker 构建命令之前先检出该源码。

将软件包复制到 Dragonwing 设备

请将 ubuntu@DEVICE_IP 替换为您的 SSH 用户和目标 IP 地址。

scp ~/src/llama.cpp/pkg-snapdragon.zip ubuntu@DEVICE_IP:/home/ubuntu/

登录目标设备:

ssh ubuntu@DEVICE_IP

解压软件包:

cd ~
unzip pkg-snapdragon.zip
cd pkg-snapdragon

为当前 shell 设置运行时库路径:

export LD_LIBRARY_PATH=$PWD/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
export ADSP_LIBRARY_PATH=$PWD/lib${ADSP_LIBRARY_PATH:+:$ADSP_LIBRARY_PATH}

验证软件包可以运行:

./bin/llama-cli --version

列出可用的 llama.cpp 设备:

./bin/llama-cli --list-devices

预期输出包括:

Available devices:
  HTP0: Hexagon

将其设为设备上的默认 llama.cpp 安装

打包的二进制文件需要 LD_LIBRARY_PATH 和 ADSP_LIBRARY_PATH 才能找到打包的 llama.cpp 和 Hexagon 后端库。将其设为默认安装的最安全方法是把软件包移动到 /opt 并在 /usr/local/bin 中创建包装命令。在 Dragonwing 设备上运行以下命令:

cd ~
sudo rm -rf /opt/llama.cpp-snapdragon
sudo mkdir -p /opt
sudo cp -a ~/pkg-snapdragon /opt/llama.cpp-snapdragon
sudo chown -R root:root /opt/llama.cpp-snapdragon

创建共享环境文件:

sudo tee /etc/llama.cpp-snapdragon.env >/dev/null <<'EOF'
LLAMA_CPP_SNAPDRAGON_HOME=/opt/llama.cpp-snapdragon
LD_LIBRARY_PATH=/opt/llama.cpp-snapdragon/lib
ADSP_LIBRARY_PATH=/opt/llama.cpp-snapdragon/lib
EOF

为 llama-cli 和 llama-server 创建包装命令:

sudo tee /usr/local/bin/llama-cli >/dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
source /etc/llama.cpp-snapdragon.env
exec "$LLAMA_CPP_SNAPDRAGON_HOME/bin/llama-cli" "$@"
EOF

sudo tee /usr/local/bin/llama-server >/dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
source /etc/llama.cpp-snapdragon.env
exec "$LLAMA_CPP_SNAPDRAGON_HOME/bin/llama-server" "$@"
EOF

sudo chmod +x /usr/local/bin/llama-cli /usr/local/bin/llama-server
hash -r

确认默认命令现在解析到这些包装脚本:

which llama-cli
which llama-server
llama-cli --version
llama-cli --list-devices

预期路径:

/usr/local/bin/llama-cli
/usr/local/bin/llama-server

在 PATH 中,/usr/local/bin 通常排在 /usr/bin 之前,因此这些包装脚本会成为默认命令,而无需替换系统软件包。

下载模型

llama.cpp 使用 GGUF 格式的模型。一个小型的 instruct 模型很适合作为首次测试。在 Dragonwing 设备上创建模型目录:

mkdir -p ~/models
cd ~/models

下载 Llama 3.2 3B instruct GGUF 模型:

wget https://huggingface.co/bartowski/Llama-3.2-3B-Instruct-GGUF/resolve/main/Llama-3.2-3B-Instruct-Q4_0.gguf

模型的支持情况和性能因架构、量化方式、上下文长度和 llama.cpp 提交而异。如果您发现某个模型或量化方式在 Dragonwing 设备上运行得特别好,请与社区分享。

在 HTP0 上运行您的第一个提示词

运行 llama-cli 并将模型层卸载到 Hexagon HTP 设备:

llama-cli \
  -m ~/models/Llama-3.2-3B-Instruct-Q4_0.gguf \
  --device HTP0 \
  -ngl 99 \
  -p "What is the most popular cookie in the world?"

常用选项:

--device HTP0 选择 Hexagon HTP 后端。
-ngl 99 要求 llama.cpp 将模型层卸载到所选设备。
-m 指向您的 GGUF 模型文件。
-p 传入用于单次提示词测试的提示词。

启动 llama-server

llama-server 提供一个本地 Web UI 和一个兼容 OpenAI 的 API。在 Dragonwing 设备上启动服务器:

llama-server \
  -m ~/models/Llama-3.2-3B-Instruct-Q4_0.gguf \
  --device HTP0 \
  -ngl 99 \
  --host 0.0.0.0 \
  --port 8080

查找设备 IP 地址:

hostname -I

在同一网络中的另一台机器上,打开:

http://DEVICE_IP:8080

您也可以使用 curl 测试 API:

curl http://DEVICE_IP:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain Dragonwing in one sentence."}
    ],
    "temperature": 0.7,
    "max_tokens": 128
  }'

重新构建后更新默认安装

在重新构建并将新的 pkg-snapdragon.zip 复制到设备后,更新 /opt/llama.cpp-snapdragon:

cd ~
rm -rf pkg-snapdragon
unzip pkg-snapdragon.zip

sudo rm -rf /opt/llama.cpp-snapdragon
sudo cp -a ~/pkg-snapdragon /opt/llama.cpp-snapdragon
sudo chown -R root:root /opt/llama.cpp-snapdragon

llama-cli --version
llama-cli --list-devices

除非您更改安装路径,否则无需重新创建 /usr/local/bin 中的包装命令。

故障排除

error while loading shared libraries如果直接从软件包目录运行二进制文件,请先设置库路径:

cd ~/pkg-snapdragon
export LD_LIBRARY_PATH=$PWD/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}
export ADSP_LIBRARY_PATH=$PWD/lib${ADSP_LIBRARY_PATH:+:$ADSP_LIBRARY_PATH}
./bin/llama-cli --version

如果您使用的是默认安装的包装脚本,请确认正在使用包装脚本:

which llama-cli

它应输出 /usr/local/bin/llama-cli。HTP0 未出现确认已安装所需的 Dragonwing 软件包,尤其是 libqnn-dev 和 qnn-tools。然后再次检查设备:

llama-cli --list-devices

还需确认软件包中包含 Hexagon 后端库:

ls /opt/llama.cpp-snapdragon/lib/libggml-hexagon.so*
ls /opt/llama.cpp-snapdragon/lib/libggml-htp-*.so

命令使用了错误的 llama.cpp 二进制文件检查命令解析:

type -a llama-cli
type -a llama-server

如果有其他路径排在 /usr/local/bin 之前,请更新您的 PATH,或显式调用 /usr/local/bin/llama-cli。

构建 llama.cpp

您需要为 llama.cpp 构建一些依赖项。在开发板上打开终端,或通过 SSH 会话连接到开发板,然后运行:

安装构建依赖项:

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

安装 OpenCL 头文件和 ICD 加载器库:

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
sudo rm -rf /usr/include/CL
sudo ln -s ~/dev/llm/opencl/include/CL/ /usr/include/CL

使用 OpenCL 后端构建 llama.cpp:

cd ~/dev/llm

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

# We've tested this commit explicitly, you can try master if you want bleeding edge
git checkout f6da8cb86a28f0319b40d9d2a957a26a7d875f8c
git rev-parse HEAD
# Expected: f6da8cb86a28f0319b40d9d2a957a26a7d875f8c

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

将 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

# To use the llama.cpp files in your current session
source ~/.bash_profile

您现在已经拥有了 llama.cpp:

llama-cli --version
# ggml_opencl: selected platform: 'QUALCOMM Snapdragon(TM)'
# ggml_opencl: device: 'QUALCOMM Adreno(TM) 663 (OpenCL 3.0 Adreno(TM) 663)'
# ggml_opencl: OpenCL driver: OpenCL 3.0 QUALCOMM build: 0808.0.7 Compiler E031.49.02.00
# ggml_opencl: vector subgroup broadcast support: true

下载并量化模型

要运行 GPU 加速的模型,您需要 GGUF 格式(llama.cpp 格式,转换指南)的纯 4 位量化(Q4_0)模型。您可以寻找预量化模型,也可以使用 llama-quantize 自行量化模型。例如,对于 Qwen2-1.5B-Instruct:

# Download fp16 model (https://huggingface.co/Qwen/Qwen2-1.5B-Instruct-GGUF)
wget https://huggingface.co/Qwen/Qwen2-1.5B-Instruct-GGUF/resolve/main/qwen2-1_5b-instruct-fp16.gguf

# Quantize (pure Q4_0)
llama-quantize --pure qwen2-1_5b-instruct-fp16.gguf qwen2-1_5b-instruct-q4_0-pure.gguf Q4_0

使用 llama-cli 运行您的第一个 LLM

现在您可以通过 llama-cli 运行 LLM。它会自动将模型层卸载到 GPU:

llama-cli -m ./qwen2-1_5b-instruct-q4_0-pure.gguf -no-cnv --no-warmup -b 128 -c 2048 -s 11 -n 128 -p "Knock knock, " -fa off

# ... You'll see:
# load_tensors: offloaded 29/29 layers to GPU
# ...
# Knock knock, 11:59 pm ... rest of the story

🚀 您现在已经在设备的 GPU 上运行了一个 LLM!

使用 llama-server 提供 LLM 服务

接下来,您可以使用 llama-server 启动一个带有聊天界面和兼容 OpenAI 的 chat completions API 的 Web 服务器。

首先,查找开发板的 IP 地址:

ifconfig | grep -Eo 'inet (addr:)?([0-9]*\.){3}[0-9]*' | grep -Eo '([0-9]*\.){3}[0-9]*' | grep -v '127.0.0.1'

# ... Example:
# 192.168.1.253

通过以下命令启动服务器:

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

在您的计算机上,打开 Web 浏览器并访问 http://192.168.1.253:9876(将 IP 地址替换为您在第 1 步中找到的地址):
使用 llama-server 提供 LLM 服务

您还可以使用 OpenAI Chat Completions API 以编程方式访问该服务器。例如,通过 Python:

创建一个新的 venv 并安装 requests:

python3 -m venv .venv-chat
source .venv-chat/bin/activate
pip3 install requests

创建一个新文件 chat.py:

import requests

# if running from your own computer, replace localhost with the IP address of your development board
url = "http://localhost:9876/v1/chat/completions"

payload = {
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain Qualcomm in one sentence."}
    ],
    "temperature": 0.7,
    "max_tokens": 200
}

response = requests.post(url, headers={ "Content-Type": "application/json" }, json=payload)
print(response.json())

运行 chat.py:

python3 chat.py

# ...
# {'choices': [{'finish_reason': 'stop', 'index': 0, 'message': {'role': 'assistant', 'content': 'Qualcomm is a leading global technology company that designs, develops, licenses, and markets semiconductor-based products and mobile platform technologies to major telecommunications and consumer electronics manufacturers worldwide.'}}], 'created': 1757073340, 'model': 'gpt-3.5-turbo', 'system_fingerprint': 'b6362-f6da8cb8', 'object': 'chat.completion', 'usage': {'completion_tokens': 34, 'prompt_tokens': 26, 'total_tokens': 60}, 'id': 'chatcmpl-3O7l005WG1DzN191FTNomJNweHMoH8Is', 'timings': {'prompt_n': 12, 'prompt_ms': 303.581, 'prompt_per_token_ms': 25.298416666666668, 'prompt_per_second': 39.52816546490064, 'predicted_n': 34, 'predicted_ms': 4052.23, 'predicted_per_token_ms': 119.18323529411765, 'predicted_per_second': 8.390441806116632}}

提供多模态 LLM 服务

您也可以使用多模态 LLM。例如 SmolVLM-500M-Instruct-GGUF。下载 Q4_0 量化权重(或自行量化),并下载 CLIP 编码器 mmproj-*.gguf 文件。例如:

# Download weights
wget https://huggingface.co/ggml-org/SmolVLM-500M-Instruct-GGUF/resolve/main/SmolVLM-500M-Instruct-f16.gguf
wget https://huggingface.co/ggml-org/SmolVLM-500M-Instruct-GGUF/resolve/main/mmproj-SmolVLM-500M-Instruct-f16.gguf

# Quantize model (mmproj- models are not quantizable via llama-quantize, see below)
llama-quantize --pure SmolVLM-500M-Instruct-f16.gguf SmolVLM-500M-Instruct-q4_0-pure.gguf Q4_0

# Serve the model
llama-server -m ./SmolVLM-500M-Instruct-q4_0-pure.gguf --mmproj ./mmproj-SmolVLM-500M-Instruct-f16.gguf --no-warmup -b 128 -c 2048 -s 11 -n 128 --host 0.0.0.0 --port 9876

CLIP 模型仍为 fp16: mmproj 模型仍然是 fp16,因此处理图像会比较慢。较早版本的 llama.cpp 中有量化 CLIP 编码器的代码,您可以进行探索。

在 CPU 上运行

尝试 CPU 推理无需单独构建。GPU 选项卡中启用 OpenCL 的同一构建也可以在 CPU 上运行。在任何 llama-* 命令中添加 -ngl 0 即可跳过将模型层卸载到 GPU,这是在同一模型和构建上快速比较 CPU 与 GPU 性能的方法。例如,Qwen2-1.5B-Instruct Q4_0 模型(下载和量化方法请参见 GPU 选项卡):GPU:

llama-cli -m ./qwen2-1_5b-instruct-q4_0-pure.gguf -no-cnv --no-warmup -b 128 -c 2048 -s 11 -n 128 -p "Knock knock, " -fa off

# llama_perf_sampler_print:    sampling time =      26.33 ms /   133 runs   (    0.20 ms per token,  5050.70 tokens per second)
# llama_perf_context_print:        load time =    3535.69 ms
# llama_perf_context_print: prompt eval time =     192.38 ms /     5 tokens (   38.48 ms per token,    25.99 tokens per second)
# llama_perf_context_print:        eval time =    5679.81 ms /   127 runs   (   44.72 ms per token,    22.36 tokens per second)
# llama_perf_context_print:       total time =    9276.10 ms /   132 tokens
# llama_perf_context_print:    graphs reused =        122

CPU:

llama-cli -m ./qwen2-1_5b-instruct-q4_0-pure.gguf -no-cnv --no-warmup -b 128 -ngl 0 -c 2048 -s 11 -n 128 -p "Knock knock, " -fa off

# llama_perf_sampler_print:    sampling time =      15.44 ms /   133 runs   (    0.12 ms per token,  8615.66 tokens per second)
# llama_perf_context_print:        load time =    1061.95 ms
# llama_perf_context_print: prompt eval time =      51.75 ms /     5 tokens (   10.35 ms per token,    96.62 tokens per second)
# llama_perf_context_print:        eval time =    2789.13 ms /   127 runs   (   21.96 ms per token,    45.53 tokens per second)
# llama_perf_context_print:       total time =    3885.55 ms /   132 tokens
# llama_perf_context_print:    graphs reused =        122

在这个小模型上,CPU 评估 token 的速度大约是 GPU 的两倍。较小的模型可能受内存带宽限制,使 CPU 的表现可以追平甚至超过 GPU,因此值得针对您的具体模型和量化方式对两者进行比较。llama-server 同样支持 -ngl 0,因此您可以使用 GPU 选项卡服务部分所示的相同命令在 CPU 上提供服务。

​选择后端

​概述

​前提条件

​准备构建主机

​使用 Snapdragon 工具链容器构建 llama.cpp

​当上游 llama.cpp 变更时重新构建

​将软件包复制到 Dragonwing 设备

​将其设为设备上的默认 llama.cpp 安装

​下载模型

​在 HTP0 上运行您的第一个提示词

​启动 llama-server

​重新构建后更新默认安装

​故障排除

​构建 llama.cpp

​下载并量化模型

​使用 llama-cli 运行您的第一个 LLM

​使用 llama-server 提供 LLM 服务

​提供多模态 LLM 服务

​在 CPU 上运行

选择后端

概述

前提条件

准备构建主机

使用 Snapdragon 工具链容器构建 llama.cpp

当上游 llama.cpp 变更时重新构建

将软件包复制到 Dragonwing 设备

将其设为设备上的默认 llama.cpp 安装

下载模型

在 HTP0 上运行您的第一个提示词

启动 llama-server

重新构建后更新默认安装

故障排除

构建 llama.cpp

下载并量化模型

使用 llama-cli 运行您的第一个 LLM

使用 llama-server 提供 LLM 服务

提供多模态 LLM 服务

在 CPU 上运行