llama.cpp 在骁龙 Windows 设备上的原生构建指南：OpenCL 与 Hexagon NPU 双后端安装、签名与编译全流程

本文基于 llama.cpp 仓库中 docs/backend/snapdragon/windows.md 的官方文档整理，面向在 Windows on Snapdragon（WoS，arm64 原生环境）上部署本地大模型推理的开发者。读完本文，你将掌握从工具链依赖、Adreno GPU / Qualcomm NPU 驱动安装，到 OpenCL 与 Hexagon SDK 配置、NPU 驱动 test-signing 证书制作，直至最终产出带数字签名的 HTP Ops 库并完成整体验证的完整实战流程。

一、工具依赖总览

在 Windows 11 arm64 原生环境下构建 llama.cpp 的骁龙后端，需要以下工具链（引自 windows.md）：

• MS Visual Studio 2026（Community 或 Pro 版）
  • MSVC arm64 标准库与运行时
  • UCRT 与 Driver Kit
• LLVM 核心库与 Clang 编译器（通过 winget 安装）
• CMake、Git、Python（通过 winget 安装）
• Hexagon SDK Community Edition 6.6 或更高版本（用于 Hexagon NPU 后端，详见下文）
• OpenCL SDK 2.3 或更高版本（用于 Adreno GPU 后端，详见下文）

需要特别注意的前提：文档中 Windows 的构建流程假设你在 PowerShell 中原生（native arm64） 运行，而不是 x64 模拟环境。这一点决定了后面 CMake preset 的选择和 SDK 路径的架构匹配。

llama.cpp 在骁龙设备上共支持三种后端：CPU、Adreno GPU（OpenCL）和 Hexagon NPU（HTP）。本文聚焦于后两者的原生构建，CPU 后端则无需额外配置。

二、安装 Windows SDK（推荐 setup-sdk.py）

仓库提供了自动化安装脚本 setup-sdk.py，这是官方推荐的安装方式：

> python scripts\snapdragon\setup-sdk.py --list-sdk-releases
> python scripts\snapdragon\setup-sdk.py --hexagon --opencl

从脚本源码看，它的工作机制包括：

1. 拉取版本清单：脚本查询 snapdragon-toolchain 组织的 GitHub releases（hexagon-sdk 与 opencl-sdk 两个仓库），列出所有可用的 arm64-wos 精简版（面向 CI 优化）归档，见 sdk.py 中的 SDK_CONFIGS 配置；
2. 下载与校验：下载归档并做 SHA-256 校验，支持断点续传；
3. 解压安装：默认安装到 C:\Qualcomm（--sdk-base-dir 可修改），版本目录并列存放，例如：
   • C:\Qualcomm\Hexagon_SDK\6.6.0.0
   • C:\Qualcomm\OpenCL_SDK\2.3.2
4. 写入环境变量：把 HEXAGON_SDK_ROOT、HEXAGON_TOOLS_ROOT、OPENCL_SDK_ROOT 写入当前用户注册表环境（set_user_environment），完成后必须打开新终端才生效。

脚本常用选项：

选项	说明
--list-sdk-releases	列出两个 SDK 当前所有可用版本
--hexagon [VERSION]	安装 Hexagon SDK，可指定版本，如 --hexagon 6.4.0.2；缺省版本为 6.6.0.0
--opencl [VERSION]	安装 OpenCL SDK，缺省版本为 2.3.2
--sdk-base-dir DIR	修改安装根目录，默认 C:\Qualcomm
--force	即使已存在也强制重装

因为各版本目录并列安装，切换版本无需删除旧版本，但 CMake 会缓存 SDK 路径，切换版本后务必使用新的构建目录。

如果你不想用脚本，也可以手动安装：

• OpenCL SDK：从 snapdragon-toolchain/opencl-sdk 的 releases 页面下载 v2.3.2 的 adreno-opencl-sdk-v2.3.2-arm64-wos.tar.xz 精简版（或从 Qualcomm Software Center 下载完整官方版），解压到 c:\Qualcomm\OpenCL_SDK\2.3.2；
• Hexagon SDK：下载 v6.6.0.0 的 hexagon-sdk-v6.6.0.0-arm64-wos.tar.xz 精简版（或完整官方版），解压到 c:\Qualcomm\Hexagon_SDK\6.6.0.0。

安装完成后，validate_windows_sdks()（见 sdk.py）会在原生 Windows 构建流程中校验这三个环境变量与目录结构是否有效，缺失时会提示“先运行 setup-sdk.py”。

三、安装 Adreno GPU 驱动与 Qualcomm NPU 驱动

3.1 Adreno GPU 驱动

从 Qualcomm Software Center 的 Windows_Graphics_Driver 条目下载最新驱动。自动安装并重启后，请在设备管理器的“显示适配器”（Display Adapters）下确认 GPU 设备正常出现。

3.2 Qualcomm NPU（Hexagon）驱动

从 Qualcomm Software Center 的 Qualcomm_HND 条目下载最新驱动。安装重启后，在设备管理器的 “Neural Processors”（神经网络处理器） 分类下应能看到 Hexagon NPU 设备。

如果设备没有正常出现，可以手动安装全部组件（qcnspmcdm8380、qcnspmcdm8380_ext），这些组件会解压到：

c:\QCDrivers\qcnspmcdm...

四、启用 NPU 驱动的 Test-Signing（仅 Hexagon NPU 需要）

重点：只有 Hexagon NPU 后端需要 test-signing。Adreno GPU（OpenCL）后端不需要任何测试签名。

为什么 NPU 需要签名？因为要在骁龙 Windows 设备上使用 Hexagon NPU，底层的 HTP Ops 库（如 libggml-htp-v73.so）必须被包含在 .cat 目录文件中，并用受信任的证书进行数字签名。Windows 通过 test-signing 机制允许本地自签证书通过内核级校验。

4.1 开启 test-signing 启动项

> bcdedit /set TESTSIGNING ON

（Secure Boot 可能需要先禁用，否则该设置无法生效。）

重启后用 bcdedit /enum 确认：

...
testsigning             Yes
...

4.2 创建个人自签证书

所需工具 makecert 与 pvk2pfx 属于 Windows SDK 和 Windows Driver Kit，应随 MS Visual Studio 的 Driver Kit 组件安装，典型位置：

c:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0

（把 10.0.26100.0 替换为你实际安装的版本号。）

创建自签证书并打包为 PFX（cmd 或 PowerShell 均可）：

> cd c:\Users\MyUser
> mkdir Certs
> cd Certs
> makecert -r -pe -ss PrivateCertStore -n CN=GGML.HTP.v1 -eku 1.3.6.1.5.5.7.3.3 -sv ggml-htp-v1.pvk ggml-htp-v1.cer
> pvk2pfx.exe -pvk ggml-htp-v1.pvk -spc ggml-htp-v1.cer -pfx ggml-htp-v1.pfx

（把 MyUser 替换为你的用户名。）参数说明：-r -pe 生成私钥可导出的自签证书，-eku 1.3.6.1.5.5.7.3.3 是代码签名（Code Signing）增强密钥用途，-sv 导出私钥为 PVK，再经 pvk2pfx 转为可跨工具使用的 PFX 格式。

随后用 certlm 证书管理器，把生成的 PFX 证书同时导入两个存储区：

• Trusted Root Certification Authorities（受信任的根证书颁发机构）
• Trusted Publishers（受信任的发布者）

操作方式：右键对应存储区 → All Tasks -> Import → 按向导从 PFX 导入。

两个要点：

• 妥善保管 PFX 文件，后续构建流程需要用到它；
• 同一张证书可以给任意多次构建签名，无需每次重建。

五、构建带签名 HTP Ops 库的 Hexagon 后端

Windows 上骁龙设备的 Hexagon 后端整体构建流程与其他平台一致，只是多了 HTP Ops 库的生成与签名环节。

5.1 设置环境变量并执行 CMake

> $env:OPENCL_SDK_ROOT="C:\Qualcomm\OpenCL_SDK\2.3.2"
> $env:HEXAGON_SDK_ROOT="C:\Qualcomm\Hexagon_SDK\6.6.0.0"
> $env:HEXAGON_TOOLS_ROOT="C:\Qualcomm\Hexagon_SDK\6.6.0.0\tools\HEXAGON_Tools\19.0.07"
> $env:HEXAGON_HTP_CERT="c:\Users\MyUsers\Certs\ggml-htp-v1.pfx"
> $env:WINDOWS_SDK_BIN="C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0"

> cmake --preset arm64-windows-snapdragon-release -B build-wos
...
> cmake --install build-wos --prefix pkg-wos

这里用到了 CMakeUserPresets.json 中的 arm64-windows-snapdragon-release preset。把该文件复制到仓库根目录后即可使用（README 中建议 cp docs/backend/snapdragon/CMakeUserPresets.json .）。该 preset 继承自 arm64-windows-llvm（基于 CMakePresets.json 与 cmake/arm64-windows-llvm.cmake），核心配置为：

• GGML_OPENCL=ON、GGML_HEXAGON=ON、GGML_OPENMP=OFF、LLAMA_OPENSSL=OFF：双后端同时开启；
• CMAKE_C_FLAGS/CMAKE_CXX_FLAGS 使用 -march=armv8.7a+fp16+dotprod+i8mm -fvectorize -ffp-model=fast -flto：针对 ARMv8.7 的 FP16、dotprod、i8mm 指令做向量化优化；
• CMAKE_PREFIX_PATH=$env{OPENCL_SDK_ROOT}：让 CMake 找到 OpenCL 头文件与库；
• HEXAGON_SDK_ROOT/HEXAGON_TOOLS_ROOT 从环境变量读取，指向 Hexagon SDK 与工具链。

5.2 签名产物验证

构建完成后，cmake --install 会在 pkg-wos/lib 中安装四个 HTP Ops 库和一个 .cat 目录文件：

> dir pkg-wos/lib
...
-a----         1/22/2026   6:01 PM         187656 libggml-htp-v73.so
-a----         1/22/2026   6:01 PM         191752 libggml-htp-v75.so
-a----         1/22/2026   6:01 PM         187656 libggml-htp-v79.so
-a----         1/22/2026   6:01 PM         187656 libggml-htp-v81.so
-a----         1/22/2026   6:01 PM           4139 libggml-htp.cat

从源码 ggml/src/ggml-hexagon/CMakeLists.txt 可以看到，v73/v75/v79/v81 四个 skel（skeld）库是通过 build_htp_skel() 函数为不同 Hexagon DSP 架构版本分别交叉编译出来的；而 .cat 文件则来自 libggml-htp.inf——该 INF 声明了 ComputeAccelerator 设备类，并把四个 .so 文件列入 SourceDisksFiles，用于 Windows 驱动框架校验。

可以用 signtool 验证 .cat 文件、签名与证书安装是否正确：

> signtool.exe verify /v /pa .\pkg-wos\lib\libggml-htp.cat
Verifying: .\pkg-wos\lib\libggml-htp.cat

Signature Index: 0 (Primary Signature)
Hash of file (sha256): 9820C664DA59D5EAE31DBB664127FCDAEF59CDC31502496BC567544EC2F401CF

Signing Certificate Chain:
        Issued to: GGML.HTP.v1
...
Successfully verified: .\pkg-wos\lib\libggml-htp.cat
...

“Successfully verified” 即表示签名链完整、根证书已在受信任存储区中。

六、签名流程的源码级拆解

上面 CMake 命令中“幕后发生什么”，可以从 ggml/src/ggml-hexagon/CMakeLists.txt 精确还原：

1. 证书来源：GGML_HEXAGON_HTP_CERT 缓存变量直接读取环境变量 HEXAGON_HTP_CERT（CMakeLists.txt 第 26 行），这就是第五节中 PFX 文件的作用位置；
2. 工具定位：当系统为 Windows 且设置了证书时，CMake 在 WINDOWS_SDK_BIN/arm64、WINDOWS_SDK_BIN/x86、WindowsSdkVerBinPath/arm64、WindowsSdkVerBinPath/x86 四个候选路径中 find_program 定位 inf2cat.exe 与 signtool.exe，找不到直接报错；
3. 构建动作：自定义目标 libggml-htp-cat 依次执行——拷贝 libggml-htp.inf 到构建目录 → inf2cat /driver:... /os:10_25H2_ARM64 生成 libggml-htp.cat → signtool sign /fd sha256 /f <PFX> libggml-htp.cat 完成 SHA-256 签名；
4. 依赖与安装：ggml-hexagon 后端目标依赖 libggml-htp-cat，.cat 文件随四个 skel 一起 install(FILES ... TYPE LIB) 进 pkg-wos/lib，保证运行时设备驱动框架能校验到。

另外两点从源码结构可以确认的实现细节：

• HEXAGON_TOOLS_ROOT 若未显式指定，CMake 会尝试从 hexagon_sdk.json 的 tools.info[0].path 自动推导（CMakeLists.txt 第 8-18 行），但手动脚本安装路径下显式设置更稳妥；
• Windows 分支还为 htp_iface 目标额外预编译了 <sal.h> 头（CMakeLists.txt 第 43-44 行），这是 clang-cl 在 Windows SDK 下的 SAL 注解兼容处理。

七、构建产物如何运行

所有产物都已安装到 pkg-wos 目录。llama.cpp 为骁龙设备提供了统一运行脚本 run.py，它会自动把 CLI 选项映射为环境变量、解析可执行文件路径，并在本地（或 ADB/SSH 远程目标）执行命令（详见 docs/backend/snapdragon/README.md）。

在 WoS 本机运行时，用工具自身的 --device（run.py 中为 --devices）选择后端，例如把模型放到 Hexagon NPU 上的 HTP0:0 会话：

> python scripts\snapdragon\run.py --devices HTP0:0 -- llama-cli -m models\your-model-Q4_0.gguf -p "hello"

从 README 的示例输出可见，Hexagon NPU 在 -ngl 等 offload 选项中表现得如同一个“GPU”设备（日志会打印 load_tensors: offloaded N/N layers to GPU 与 HTP0:0 model buffer size 等行）。常用调试环境变量包括：

• GGML_HEXAGON_DEVICES：控制分配哪些 NPU 设备/会话，支持整数（如 2 表示 HTP0,HTP1）或 HTP<物理idx>:<虚拟idx> 列表（如 HTP0:0,HTP0:1 在同一物理 NPU 上开两个虚拟会话以限制内存）；
• GGML_HEXAGON_NHVX=0：控制 HVX 硬件线程数，默认全部；
• GGML_HEXAGON_HOSTBUF=1：控制是否分配 host 缓冲区，测试需要 REPACK 缓冲区的算子（MUL_MAT、MUL_MAT_ID）时必须开启；
• GGML_HEXAGON_VERBOSE=1：输出每个算子的详细日志（张量形状、量化类型、所在设备等）；
• GGML_HEXAGON_PROFILE=1|2|0x1..0x8：算子级 profiling，可配合 ggml-hexagon-profile.py 生成报告；
• GGML_HEXAGON_OPFILTER=regex：按正则禁用匹配的算子，让其回落到 CPU/GPU，例如 GGML_HEXAGON_OPFILTER="FLASH_ATTN_EXT" 可在 NPU 上关闭 Flash Attention 以便排查。

八、流程小结与常见检查点

整个 WoS 原生构建可以归纳为一条检查链：

1. 工具链：VS2026（arm64 + Driver Kit）、Clang、CMake/Git/Python、Hexagon SDK ≥ 6.6、OpenCL SDK ≥ 2.3（python scripts\snapdragon\setup-sdk.py --hexagon --opencl 一条命令搞定后两者，装完开新终端）；
2. 驱动：Adreno GPU 出现在设备管理器“显示适配器”，Hexagon NPU 出现在“Neural Processors”，缺失时手动装 qcnspmcdm* 组件；
3. test-signing：bcdedit /set TESTSIGNING ON（可能需关 Secure Boot），重启后 bcdedit /enum 确认 testsigning Yes；
4. 证书：makecert + pvk2pfx 生成 PFX，导入“受信任的根证书颁发机构”和“受信任的发布者”，妥善保存 PFX；
5. 构建：设置 OPENCL_SDK_ROOT、HEXAGON_SDK_ROOT、HEXAGON_TOOLS_ROOT、HEXAGON_HTP_CERT、WINDOWS_SDK_BIN 后，cmake --preset arm64-windows-snapdragon-release -B build-wos 并 cmake --install build-wos --prefix pkg-wos；
6. 验证：pkg-wos/lib 下应出现 libggml-htp-v73/v75/v79/v81.so 与 libggml-htp.cat，signtool verify /v /pa 输出 “Successfully verified”；
7. 运行：python scripts\snapdragon\run.py --devices HTP0:0 -- <tool>，用 GGML_HEXAGON_VERBOSE/OPFILTER/PROFILE 等变量做算子级调优与排障。

适用前提提醒：本文所有步骤以当前仓库文档与源码为准，对应 Hexagon SDK 6.6.0.0 / OpenCL SDK 2.3.2 的默认版本组合；若使用其他 SDK 版本，请确认 HTP 工具链目录名（HEXAGON_TOOLS 下的版本号目录）与 inf2cat /os:10_25H2_ARM64 参数是否仍然匹配你的 Windows SDK 版本。