> ## Documentation Index > Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt > Use this file to discover all available pages before exploring further. # 使用 Llama.cpp 运行 LLM/VLM > 使用 llama.cpp 在 Dragonwing 设备上本地运行大语言模型和视觉语言模型,支持 CPU、GPU(OpenCL)或 NPU(Hexagon HTP)后端。 您可以使用 [llama.cpp](https://github.com/ggml-org/llama.cpp) 在 Dragonwing 开发板上运行多种大语言模型(LLM)和视觉语言模型(VLM)。llama.cpp 在 Dragonwing 设备上支持三种后端:CPU、GPU(通过 OpenCL)和 NPU(通过 Hexagon HTP 后端)。您也可以通过 [GENIE](/zh/ai-workflows/genie) 在 NPU 上运行部分模型。 ## 选择后端 * **CPU**:无需特殊驱动或额外的构建标志。可作为与 GPU 或 NPU 性能对比的基准。 * **GPU(OpenCL)**:使用 OpenCL 后端构建 llama.cpp,将模型层卸载到 Adreno GPU。同一构建也可以通过跳过 GPU 卸载在 CPU 上运行。 * **NPU(Hexagon HTP)**:使用 Snapdragon 工具链容器构建 llama.cpp,将模型层卸载到 Hexagon HTP 设备(`HTP0`),在受支持的模型上获得最佳性能。 ### 概述 使用 Hexagon HTP 后端为 Dragonwing 设备构建 llama.cpp,然后在 `HTP0` 上运行 GGUF 大语言模型。 这些说明侧重于将 Hexagon HTP 设备公开为 `HTP0` 的 Snapdragon 和 Dragonwing llama.cpp 构建。这与 GPU 选项卡中的 OpenCL GPU 工作流不同。 ### 前提条件 在开始之前,请确保您已: * 完成 Dragonwing 设备的首次设置: * [Dragonwing IQ8 设置](/zh/devices/iq8275-evk/setup) * [Dragonwing IQ9 设置](/zh/devices/iq9075-evk/setup) * 可以通过 SSH 或直接连接的显示器、键盘和鼠标访问设备。 * 上面链接的设置指南包含网络、串行控制台访问、显示设置和 SSH 访问的说明。 * 在设备上安装了所需的 Dragonwing 软件包: * [Dragonwing IQ8](/zh/devices/iq8275-evk/Install_required_software_packages) * [Dragonwing IQ9](/zh/devices/iq9075-evk/Install_required_software_packages) * 在构建主机上安装了 Docker。 * 有足够的可用空间用于构建输出和模型。每个模型请预留数 GB 空间。 所需软件包的安装过程会安装 QNN 运行时和工具,包括 llama.cpp 加速推理所需的 `libqnn-dev` 和 `qnn-tools`。 ### 准备构建主机 在构建主机上,克隆 llama.cpp 或更新现有的检出。 ```shell theme={null} 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 ``` 如果您需要可复现的构建,请记录所构建的提交: ```shell theme={null} 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 检出目录的根目录启动容器: ```shell theme={null} docker run -it \ -u $(id -u):$(id -g) \ --volume $(pwd):/workspace \ --platform linux/amd64 \ ghcr.io/snapdragon-toolchain/arm64-linux:v0.1 ``` 在容器内,配置并构建 llama.cpp: ```shell theme={null} cd /workspace cp docs/backend/snapdragon/CMakeUserPresets.json . cmake --preset arm64-linux-snapdragon-release -B build-snapdragon cmake --build build-snapdragon -j $(nproc) ``` 创建可安装的软件包: ```shell theme={null} cmake --install build-snapdragon --prefix pkg-snapdragon zip -r pkg-snapdragon.zip pkg-snapdragon ``` 软件包完成后退出容器: ```shell theme={null} exit ``` 软件包归档文件现在位于主机上的以下位置: ```text theme={null} ~/src/llama.cpp/pkg-snapdragon.zip ``` ### 当上游 llama.cpp 变更时重新构建 llama.cpp 变更频繁。要使用最新的上游代码重新构建,请从主机检出目录重复以下更新和构建流程: ```shell theme={null} 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 ``` 然后,在容器内: ```shell theme={null} 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 地址。 ```shell theme={null} scp ~/src/llama.cpp/pkg-snapdragon.zip ubuntu@DEVICE_IP:/home/ubuntu/ ``` 登录目标设备: ```shell theme={null} ssh ubuntu@DEVICE_IP ``` 解压软件包: ```shell theme={null} cd ~ unzip pkg-snapdragon.zip cd pkg-snapdragon ``` 为当前 shell 设置运行时库路径: ```shell theme={null} export LD_LIBRARY_PATH=$PWD/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} export ADSP_LIBRARY_PATH=$PWD/lib${ADSP_LIBRARY_PATH:+:$ADSP_LIBRARY_PATH} ``` 验证软件包可以运行: ```shell theme={null} ./bin/llama-cli --version ``` 列出可用的 llama.cpp 设备: ```shell theme={null} ./bin/llama-cli --list-devices ``` 预期输出包括: ```text theme={null} Available devices: HTP0: Hexagon ``` ### 将其设为设备上的默认 llama.cpp 安装 打包的二进制文件需要 `LD_LIBRARY_PATH` 和 `ADSP_LIBRARY_PATH` 才能找到打包的 llama.cpp 和 Hexagon 后端库。将其设为默认安装的最安全方法是把软件包移动到 `/opt` 并在 `/usr/local/bin` 中创建包装命令。 在 Dragonwing 设备上运行以下命令: ```shell theme={null} 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 ``` 创建共享环境文件: ```shell theme={null} 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` 创建包装命令: ```shell theme={null} 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 ``` 确认默认命令现在解析到这些包装脚本: ```shell theme={null} which llama-cli which llama-server llama-cli --version llama-cli --list-devices ``` 预期路径: ```text theme={null} /usr/local/bin/llama-cli /usr/local/bin/llama-server ``` 在 `PATH` 中,`/usr/local/bin` 通常排在 `/usr/bin` 之前,因此这些包装脚本会成为默认命令,而无需替换系统软件包。 ### 下载模型 llama.cpp 使用 GGUF 格式的模型。一个小型的 instruct 模型很适合作为首次测试。 在 Dragonwing 设备上创建模型目录: ```shell theme={null} mkdir -p ~/models cd ~/models ``` 下载 Llama 3.2 3B instruct GGUF 模型: ```shell theme={null} 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 设备: ```shell theme={null} 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 设备上启动服务器: ```shell theme={null} llama-server \ -m ~/models/Llama-3.2-3B-Instruct-Q4_0.gguf \ --device HTP0 \ -ngl 99 \ --host 0.0.0.0 \ --port 8080 ``` 查找设备 IP 地址: ```shell theme={null} hostname -I ``` 在同一网络中的另一台机器上,打开: ```text theme={null} http://DEVICE_IP:8080 ``` 您也可以使用 `curl` 测试 API: ```shell theme={null} 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`: ```shell theme={null} 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`** 如果直接从软件包目录运行二进制文件,请先设置库路径: ```shell theme={null} 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 ``` 如果您使用的是默认安装的包装脚本,请确认正在使用包装脚本: ```shell theme={null} which llama-cli ``` 它应输出 `/usr/local/bin/llama-cli`。 **`HTP0` 未出现** 确认已安装所需的 Dragonwing 软件包,尤其是 `libqnn-dev` 和 `qnn-tools`。然后再次检查设备: ```shell theme={null} llama-cli --list-devices ``` 还需确认软件包中包含 Hexagon 后端库: ```shell theme={null} ls /opt/llama.cpp-snapdragon/lib/libggml-hexagon.so* ls /opt/llama.cpp-snapdragon/lib/libggml-htp-*.so ``` **命令使用了错误的 llama.cpp 二进制文件** 检查命令解析: ```shell theme={null} type -a llama-cli type -a llama-server ``` 如果有其他路径排在 `/usr/local/bin` 之前,请更新您的 `PATH`,或显式调用 `/usr/local/bin/llama-cli`。 ### 构建 llama.cpp 您需要为 llama.cpp 构建一些依赖项。在开发板上打开终端,或通过 SSH 会话连接到开发板,然后运行: 1. 安装构建依赖项: ``` sudo apt update sudo apt install -y cmake ninja-build curl libcurl4-openssl-dev build-essential ``` 2. 安装 OpenCL 头文件和 ICD 加载器库: ```shell theme={null} 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 ``` 3. 使用 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` ``` 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 # To use the llama.cpp files in your current session source ~/.bash_profile ``` 5. 您现在已经拥有了 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 格式,[转换指南](https://github.com/ggml-org/llama.cpp/discussions/2948))的纯 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 服务器。 1. 首先,查找开发板的 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 ``` 2. 通过以下命令启动服务器: ``` 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 ``` 3. 在您的计算机上,打开 Web 浏览器并访问 `http://192.168.1.253:9876`(将 IP 地址替换为您在第 1 步中找到的地址): 4. 您还可以使用 OpenAI Chat Completions API 以编程方式访问该服务器。例如,通过 Python: 1. 创建一个新的 venv 并安装 `requests`: ``` python3 -m venv .venv-chat source .venv-chat/bin/activate pip3 install requests ``` 2. 创建一个新文件 `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()) ``` 3. 运行 `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](https://huggingface.co/ggml-org/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](https://github.com/ggml-org/llama.cpp/pull/11644) 中有量化 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 上提供服务。