llama.cpp 本地构建完全指南：从 CMake 工作流到 CPU、BLAS、Metal、CUDA、Vulkan 等全后端编译配置

llama.cpp 的核心产物是 llama 推理库，其 C 风格接口定义在 include/llama.h，而整个项目围绕它提供从极简示例到 OpenAI 兼容 HTTP 服务（tools/server）的大量可执行程序。本文基于仓库中的构建文档 docs/build.md，系统讲解如何用 CMake 完成本地构建：覆盖 CPU 基线构建、各 BLAS 实现、Metal/SYCL/CUDA/MUSA/HIP/Vulkan/CANN/ZenDNN/KleidiAI/OpenCL/WebGPU 等全部后端的开启方式，并给出编译参数、运行时环境变量与常见问题修复方案，帮助你针对自己的硬件得到一份可直接运行的构建。

获取代码与构建体系概览

git clone https://gitcode.com/GitHub_Trending/ll/llama.cpp
cd llama.cpp

构建入口是根目录的 CMakeLists.txt。各硬件后端对应的编译开关（如 GGML_CUDA、GGML_METAL、GGML_VULKAN）统一定义在 ggml 子项目的 ggml/CMakeLists.txt 中，而根 CMakeLists 负责 llama 库与工具层选项。值得注意的几点源码事实：

• 默认构建共享库：ggml/CMakeLists.txt 中 BUILD_SHARED_LIBS 在多数平台默认为 ON，但 MINGW 与 Emscripten 下默认为 OFF（见 ggml/CMakeLists.txt）；
• GGML_NATIVE（按本机 CPU/GPU 特性优化编译）默认为 ON，但检测到交叉编译时会自动置 OFF（ggml/CMakeLists.txt）；
• 旧选项名有废弃映射，例如 LLAMA_CUDA 会提示迁移到 GGML_CUDA（CMakeLists.txt），本文一律使用现行 GGML_* 选项名。

下面的章节按后端逐一给出完整的编译命令与配置说明。

CPU Build（基线构建）

使用 CMake 的标准两步构建：

cmake -B build
cmake --build build --config Release

编译加速与常用变体：

• 并行编译：cmake --build build --config Release -j 8 表示并行 8 个任务；也可以直接选用 Ninja 这类自动并行化的生成器。

• 重复编译加速：安装 ccache（仓库中也提供了配套的 scripts/ccache-clear.sh 脚本）。

• Debug 构建分两种情况：

  1. 单配置生成器（默认 Unix Makefiles，忽略 --config 参数）：

     cmake -B build -DCMAKE_BUILD_TYPE=Debug
     cmake --build build
     

  2. 多配置生成器（-G 指定 Visual Studio、Xcode 等）：

     cmake -B build -G "Xcode"
     cmake --build build --config Debug
     

• 静态库构建：追加 -DBUILD_SHARED_LIBS=OFF：

  cmake -B build -DBUILD_SHARED_LIBS=OFF
  cmake --build build --config Release
  

Windows（x86 / x64 / arm64，MSVC 或 clang）构建：

• 安装 Visual Studio 2022（Community 版即可），安装器中至少勾选：

  • Workloads 页：Desktop development with C++
  • Components 页（可用搜索快速定位）：C++ CMake Tools for Windows、Git for Windows、C++ Clang Compiler for Windows、MS-Build Support for LLVM-Toolset (clang)

• 注意：git、构建、测试操作请始终使用 VS2022 的 Developer Command Prompt / PowerShell。

• Windows on ARM（arm64、WoA）构建：

  cmake --preset arm64-windows-llvm-release -D GGML_OPENMP_FETCH=ON
  cmake --build build-arm64-windows-llvm-release
  

  • 若构建机本身是 ARM64，请使用 ARM64 Native Tools Command Prompt for VS 2022。
  • GGML_OPENMP_FETCH 会下载官方 LLVM OpenMP 运行时，需要 Clang、7-Zip 以及配置期网络访问。CMake 会按目标架构选择运行时，因此从 x64 交叉编译 WoA 也适用。解压出的头文件、导入库、DLL 与 OpenMP 许可证位于 build/_deps，构建过程会把 libomp.dll 和 LICENSE-LLVM-OpenMP 拷贝到运行时输出目录并随产物一起安装。若不想引入该选项，可省略；或传 -DGGML_OPENMP=OFF 彻底禁用 OpenMP。

• 使用 Ninja 生成器 + clang 作为默认编译器时，需先设置 LIB 环境变量（路径按本机 VS 版本调整）：

  set LIB=C:\Program Files (x86)\Windows Kits\10\Lib\10.0.22621.0\um\x64;C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.41.34120\lib\x64\uwp;C:\Program Files (x86)\Windows Kits\10\Lib\10.0.22621.0\ucrt\x64
  

  然后：

  cmake --preset x64-windows-llvm-release
  cmake --build build-x64-windows-llvm-release
  

  这两个 preset 均可在 CMakePresets.json 中查看其继承关系（如 x64-windows-llvm-release 继承 base + x64-windows-llvm + release，内部使用了 cmake/x64-windows-llvm.cmake 工具链）。

HTTPS/TLS 支持：如需 HTTPS 功能，安装 OpenSSL 开发库；未安装时项目仍可构建和运行，只是没有 SSL 支持。

• Debian / Ubuntu：sudo apt-get install libssl-dev
• Fedora / RHEL / Rocky / Alma：sudo dnf install openssl-devel
• Arch / Manjaro：sudo pacman -S openssl

对应地，根 CMakeLists.txt 中定义了 LLAMA_OPENSSL（"llama: use openssl to support HTTPS"，默认 ON），未找到 OpenSSL 时会自动降级而非报错。

BLAS Build

开启 BLAS 支持后，prompt 处理（预填充阶段，默认 batch size 为 512，通常大于 32）可能获得性能提升，但不影响逐 token 生成速度。当前支持多种 BLAS 实现：

Accelerate Framework

仅 macOS 可用，且默认启用——按上面的常规 CPU 构建步骤编译即可。从源码可印证这一点：ggml/CMakeLists.txt 中，APPLE 平台默认 GGML_METAL_DEFAULT ON、GGML_BLAS_DEFAULT ON 且 vendor 为 Apple，其他平台则默认关闭。

OpenBLAS

纯 CPU 的 BLAS 加速，前提是机器上已安装 OpenBLAS：

cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release

BLIS

详见 docs/backend/BLIS.md。

Intel oneMKL

通过 oneAPI 编译器构建，可以为不支持 avx512 / avx512_vnni 的 Intel 处理器启用 avx_vnni 指令集。注意该构建配置不支持 Intel GPU；Intel GPU 请走 SYCL 后端（见 docs/backend/SYCL.md）。

• 手动安装 oneAPI 的方式：由于 GGML_BLAS_VENDOR 默认为 Generic，只要已 source 过 Intel 环境脚本并指定 -DGGML_BLAS=ON，就会自动选中 MKL 版 BLAS；否则请安装 oneAPI 后执行：

  source /opt/intel/oneapi/setvars.sh # oneapi-basekit docker 镜像内可跳过此步
  cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=Intel10_64lp -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx -DGGML_NATIVE=ON
  cmake --build build --config Release
  

• 使用 Intel oneAPI 官方 Docker 镜像（oneAPI-basekit）时，可免去手动 source 环境，直接执行上面的 cmake 命令。

其他 BLAS 库

通过设置 GGML_BLAS_VENDOR 可接入 CMake FindBLAS 模块支持的其他厂商实现，具体 vendor 列表以 CMake 官方 FindBLAS 模块文档为准。

Metal Build

macOS 上 Metal 默认启用，启用后计算在 GPU 上运行。

• 编译期禁用：-DGGML_METAL=OFF
• 运行期禁用 GPU 推理：--n-gpu-layers 0

注意这与后文“GPU 后端注意事项”中的 --device none 不同：后者用于彻底禁用 GPU 加速（见文末章节）。

SYCL

SYCL 是面向多种硬件加速器的高级编程模型。llama.cpp 的 SYCL 后端用于支持 Intel GPU（Data Center Max 系列、Flex 系列、Arc 系列以及内置 GPU / iGPU）。详细构建与使用信息见 docs/backend/SYCL.md。

CUDA

用于 NVIDIA GPU 加速，前提是已安装 CUDA Toolkit（可从 NVIDIA 开发者官网获取）。

Fedora Toolbox 容器内编译

对于以下场景，仓库提供了在 Fedora toolbox 容器中配置 CUDA Toolkit 的指南 docs/backend/CUDA-FEDORA.md：

• 必须：Atomic Desktop（Silverblue、Kinoite 等）用户——这类系统没有可用的 CUDA 官方包；
• 必须：宿主系统不在 NVIDIA 受支持平台列表中的用户（例如较新的测试版发行版）；
• 方便：Fedora Workstation / KDE Plasma 用户希望保持宿主系统干净；
• toolbox 在 Arch Linux、RHEL >= 8.5、Ubuntu 上也可选用。

Compilation

（通用编译加速建议见“CPU Build”一节。）

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

非本机（Non-Native）构建

默认情况下 llama.cpp 按当前连接在系统上的硬件编译。若要覆盖所有 CUDA GPU，关闭 GGML_NATIVE：

cmake -B build -DGGML_CUDA=ON -DGGML_NATIVE=OFF

得到的二进制可在所有 CUDA GPU 上以最优性能运行（个别情况需要即时编译）。从源码结构看，具体架构选择逻辑集中在 ggml/src/ggml-cuda/CMakeLists.txt：native 模式下直接取构建机 GPU 架构；非 native 模式会按 CUDA 版本组合 50-virtual 61-virtual 70-virtual、75-virtual 80-virtual 86-real、89-real 90-virtual，并在检测到 Blackwell 时追加 120a-real / 121a-real，其中 -virtual 架构支持按需即时编译以减小二进制体积。

显式指定 Compute Capability

若 nvcc 检测不到 GPU，可能出现类似警告：

nvcc warning : Cannot find valid GPU for '-arch=native', default arch is used

选项一：做非本机构建（缺点：二进制大、编译慢）；选项二：显式指定 CUDA 架构，做法是：

1. 查清各 NVIDIA 设备的 Compute Capability（以 NVIDIA 官方 GPU 列表为准），例如：

   GeForce RTX 4090      8.9
   GeForce RTX 3080 Ti   8.6
   GeForce RTX 3070      8.6
   

2. 将每个不同的 Compute Capability 列入 CMAKE_CUDA_ARCHITECTURES：

   cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="86;89"
   

覆盖 CUDA 版本

系统中装有多个 CUDA 时，可指定特定版本，例如 /opt/cuda-11.7 下的 CUDA 11.7：

cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_COMPILER=/opt/cuda-11.7/bin/nvcc -DCMAKE_INSTALL_RPATH="/opt/cuda-11.7/lib64;\$ORIGIN" -DCMAKE_BUILD_WITH_INSTALL_RPATH=ON

老版本 CUDA 与新 glibc 的兼容性问题

用旧版 CUDA（如 11.7）搭配新 glibc 时可能出现：

/usr/include/bits/mathcalls.h(83): error: exception specification is
  incompatible with that of previous function "cospi"

  /opt/cuda-11.7/bin/../targets/x86_64-linux/include/crt/math_functions.h(5545):
  here

文档给出的“最不坏的”方案是给 CUDA 安装打补丁，修正函数签名声明。将 /path/to/your/cuda/installation/targets/x86_64-linux/include/crt/math_functions.h 中以下声明：

// original lines
extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ double                 cospi(double x);
extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ float                  cospif(float x);
extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ double                 sinpi(double x);
extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ float                  sinpif(float x);
extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ double                 rsqrt(double x);
extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ float                  rsqrtf(float x);

替换为：

// edited lines
extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ double                 cospi(double x) noexcept (true);
extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ float                  cospif(float x) noexcept (true);
extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ double                 sinpi(double x) noexcept (true);
extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ float                  sinpif(float x) noexcept (true);
extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ double                 rsqrt(double x) noexcept (true);
extern __DEVICE_FUNCTIONS_DECL__ __device_builtin__ float                  rsqrtf(float x) noexcept (true);

运行时 CUDA 环境变量

• CUDA_VISIBLE_DEVICES：控制可见设备，例如隐藏第一个计算设备：

  CUDA_VISIBLE_DEVICES="-0" ./build/bin/llama-server --model /srv/models/llama.gguf
  

• CUDA_SCALE_LAUNCH_QUEUES：控制 CUDA 命令缓冲区大小，即 CPU 必须等待 GPU 追上之前可以入队的 GPU 操作数量。调大该缓冲可减少 CPU 侧停顿、允许在 GPU 上排队更多工作。可考虑 CUDA_SCALE_LAUNCH_QUEUES=4x（把命令缓冲扩大 4 倍），对多 GPU 流水线并行场景的 prompt 处理吞吐提升尤为明显。

• GGML_CUDA_CUBLAS_COMPUTE_TYPE：覆盖 cuBLAS 矩阵乘法默认的按速度优化的计算类型。合法取值：auto、f16、fp16、bf16、f32、fp32。

统一内存（Unified Memory）

GGML_CUDA_ENABLE_UNIFIED_MEMORY=1 在 Linux 上启用统一内存：GPU 显存耗尽时会交换到系统内存而不是直接崩溃。Windows 上对应 NVIDIA 控制面板里的 System Memory Fallback 设置。

Peer Access（GPU 间点对点）

设置 GGML_CUDA_P2P 可启用多 GPU 之间的点对点访问，使数据直接在 GPU 间传输而不经过系统内存。需要驱动支持（通常限于工作站/数据中心 GPU）；在部分主板与 BIOS 设置（如 IOMMU）下可能导致崩溃或输出损坏。

性能调优编译选项

Option	Legal values	Default	Description
GGML_CUDA_FORCE_MMQ	Boolean	false	强制对量化模型使用自定义矩阵乘法核（MMQ），即使没有 int8 张量核实现（影响 V100、CDNA 与 RDNA3+）。在具备 int8 张量核的 GPU 上 MMQ 默认开启。强制启用后大 batch 速度变差，但显存占用更低。
GGML_CUDA_FORCE_CUBLAS	Boolean	false	强制量化模型使用 FP16 cuBLAS 而非自定义矩阵乘法核。可能出现数值溢出问题（V100、CDNA 与 RDNA4 默认用 FP32 计算类型除外），且内存占用更高。在较新的数据中心 GPU 上 prompt 处理可能更快（自定义核主要面向 RTX 3000/4000 调优）。
GGML_CUDA_PEER_MAX_BATCH_SIZE	Positive integer	128	启用多 GPU peer access 的最大 batch size。peer access 需要 Linux 或 NVLink；有 NVLink 时，对更大 batch 启用 peer access 可能有益。
GGML_CUDA_FA_ALL_QUANTS	Boolean	false	为 FlashAttention CUDA 核编译全部 KV cache 量化类型（组合），提供对 KV cache 大小更细粒度的控制，但编译时间大幅变长。

MUSA（摩尔线程）

提供基于 Moore Threads GPU 的加速，前提是安装 MUSA SDK（可从摩尔线程开发者站点下载）。

cmake -B build -DGGML_MUSA=ON
cmake --build build --config Release

指定 Compute Capability：默认启用所有受支持的 compute capability；可自定义以减少编译时间，例如只启用 2.1（MTT S80）：

cmake -B build -DGGML_MUSA=ON -DMUSA_ARCHITECTURES="21"
cmake --build build --config Release

静态构建（CUDA 的多数编译选项在 MUSA 下也应当可用，但官方提示尚未充分测试）：追加 -DBUILD_SHARED_LIBS=OFF 与 -DCMAKE_POSITION_INDEPENDENT_CODE=ON：

cmake -B build -DGGML_MUSA=ON \
  -DBUILD_SHARED_LIBS=OFF -DCMAKE_POSITION_INDEPENDENT_CODE=ON
cmake --build build --config Release

运行时环境变量：可用 MUSA_VISIBLE_DEVICES 控制可见设备，例如隐藏第一个计算设备：

MUSA_VISIBLE_DEVICES="-0" ./build/bin/llama-server --model /srv/models/llama.gguf

统一内存：GGML_CUDA_ENABLE_UNIFIED_MEMORY=1 同样可用（显存耗尽时交换到系统内存）。

HIP（AMD ROCm）

提供 HIP 支持的 AMD GPU 加速，前提是安装 ROCm（可从发行版包管理器或 AMD 官方安装指南获取）。

• Linux（以 gfx1030 兼容的 AMD GPU 为例）：

  HIPCXX="$(hipconfig -l)/clang" HIP_PATH="$(hipconfig -R)" \
      cmake -S . -B build -DGGML_HIP=ON -DGPU_TARGETS=gfx1030 -DCMAKE_BUILD_TYPE=Release \
      && cmake --build build --config Release -- -j 16
  

  注：GPU_TARGETS 可选，省略时为当前系统所有 GPU 编译。

  若遇到：

  clang: error: cannot find ROCm device library; provide its path via '--rocm-path' or '--rocm-device-lib-path', or pass '-nogpulib' to build without ROCm device library
  

  可在 HIP_PATH 下搜索包含 oclc_abi_version_400.bc 的目录，并在命令前追加 HIP_DEVICE_LIB_PATH=<该目录>：

  HIPCXX="$(hipconfig -l)/clang" HIP_PATH="$(hipconfig -p)" \
  HIP_DEVICE_LIB_PATH=<directory-you-just-found> \
      cmake -S . -B build -DGGML_HIP=ON -DGPU_TARGETS=gfx1030 -DCMAKE_BUILD_TYPE=Release \
      && cmake --build build -- -j 16
  

• Windows（x64 Native Tools Command Prompt for VS，以 gfx1100 兼容的 AMD GPU 为例）：

  set PATH=%HIP_PATH%\bin;%PATH%
  cmake -S . -B build -G Ninja -DGPU_TARGETS=gfx1100 -DGGML_HIP=ON -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Release
  cmake --build build
  

  按目标 GPU 架构调整 GPU_TARGETS（上例 gfx1100 对应 Radeon RX 7900XTX/XT/GRE）。可用 rocminfo | grep gfx | head -1 | awk '{print $2}' 取显卡版本串，再映射到 LLVM AMDGPU 处理器列表（例如 gfx1035 映射到 gfx1030）。

运行时：

• HIP_VISIBLE_DEVICES：指定使用哪些 GPU；
• 若 GPU 未获官方支持，可用 HSA_OVERRIDE_GFX_VERSION 设置为相近 GPU 的值，例如 RDNA2（gfx1030/1031/1035）用 10.3.0，RDNA3 用 11.0.0。注意该变量在 Windows 上不受支持。

统一内存：Linux 上可通过 GGML_CUDA_ENABLE_UNIFIED_MEMORY=1 让 CPU 与集成 GPU 共享主存（UMA）。注意：对独显这会让性能下降，但使集成 GPU 可用。

Vulkan

Windows 用户

方式一：w64devkit

1. 下载并解压 w64devkit（skeeto 发行版）；
2. 按默认设置安装 LunarG Vulkan SDK；
3. 运行 w64devkit.exe，执行以下命令拷贝 Vulkan 依赖：

SDK_VERSION=1.3.283.0
cp /VulkanSDK/$SDK_VERSION/Bin/glslc.exe $W64DEVKIT_HOME/bin/
cp /VulkanSDK/$SDK_VERSION/Lib/vulkan-1.lib $W64DEVKIT_HOME/x86_64-w64-mingw32/lib/
cp -r /VulkanSDK/$SDK_VERSION/Include/* $W64DEVKIT_HOME/x86_64-w64-mingw32/include/
cat > $W64DEVKIT_HOME/x86_64-w64-mingw32/lib/pkgconfig/vulkan.pc <<EOF
Name: Vulkan-Loader
Description: Vulkan Loader
Version: $SDK_VERSION
Libs: -lvulkan-1
EOF

4. 进入 llama.cpp 目录用 CMake 构建：

cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release

方式二：Git Bash (MINGW64)

1. 安装 Git for Windows、Visual Studio Community Edition（勾选 C++）、CMake 与 Vulkan SDK（均按默认设置）；
2. 在 llama.cpp 目录右键 Open Git Bash Here，执行：

cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release

3. 用 Vulkan 跑会话模式：

build/bin/Release/llama-cli -m "[PATH TO MODEL]" -ngl 100 -c 16384 -t 10 -n -2 -cnv

方式三：MSYS2

安装 MSYS2 后，在 UCRT 终端安装依赖：

pacman -S git \
    mingw-w64-ucrt-x86_64-gcc \
    mingw-w64-ucrt-x86_64-cmake \
    mingw-w64-ucrt-x86_64-vulkan-devel \
    mingw-w64-ucrt-x86_64-shaderc \
    mingw-w64-ucrt-x86_64-spirv-headers

然后构建：

cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release

Docker 用户

无需在宿主机安装 Vulkan SDK（容器内会安装）：

# Build the image
docker build -t llama-cpp-vulkan --target light -f .devops/vulkan.Dockerfile .

# Then, use it:
docker run -it --rm -v "$(pwd):/app:Z" --device /dev/dri/renderD128:/dev/dri/renderD128 --device /dev/dri/card1:/dev/dri/card1 llama-cpp-vulkan -m "/app/models/YOUR_MODEL_FILE" -p "Building a website can be done in 10 simple steps:" -n 400 -e -ngl 33

Linux 用户

使用 LunarG Vulkan SDK：按官方 Linux Tarball 安装指南完成后，务必在当前终端对 SDK 内的 setup_env.sh 执行 source，否则构建会失败；关闭终端后再次构建前需要重新执行。

使用系统包（Debian / Ubuntu）：

sudo apt-get install libvulkan-dev glslc spirv-headers

注意：Vulkan 后端依赖 SPIRV-Headers（spirv/unified1/spirv.hpp），它不一定会随 Vulkan loader 开发包一起装进来。其他发行版对应包名如 spirv-headers（Ubuntu/Debian/Arch）或 spirv-headers-devel（Fedora/openSUSE）；Windows 上 LunarG SDK 的 Include 目录已包含这些头文件。

通用步骤：先用 vulkaninfo 确认环境正常，然后：

cmake -B build -DGGML_VULKAN=1
cmake --build build --config Release

构建完成后验证：

# "-ngl 99" 应把几乎所有模型的全部层卸载到 GPU
./build/bin/llama-cli -m "PATH_TO_MODEL" -p "Hi you how are you" -ngl 99

# 正常时输出中应看到 ggml_vulkan 探测到你的 GPU，例如：
# ggml_vulkan: Using Intel(R) Graphics (ADL GT2) | uma: 1 | fp16: 1 | warp size: 32

macOS 用户

按 LunarG 的 macOS Vulkan SDK 指南安装（macOS 上有两个把 Vulkan 翻译为 Metal 的驱动层，可通过 VK_ICD_FILENAMES 热切换）。安装 SDK 时勾选 "KosmicKrisp"，然后设置环境：

source /path/to/vulkan-sdk/setup-env.sh

• MoltenVK：是 LunarG macOS SDK 默认安装的 Vulkan 驱动，上面的环境设置即可直接使用；
• KosmicKrisp：通过覆盖环境变量切换：

export VK_ICD_FILENAMES=$VULKAN_SDK/share/vulkan/icd.d/libkosmickrisp_icd.json
export VK_DRIVER_FILES=$VULKAN_SDK/share/vulkan/icd.d/libkosmickrisp_icd.json

构建时额外关闭 Metal（与上文通用步骤的唯一差异）：

cmake -B build -DGGML_VULKAN=1 -DGGML_METAL=OFF
cmake --build build --config Release

CANN（华为 Ascend NPU）

CANN 是面向 Ascend NPU 的分层 API，用于加速 AI 应用构建与部署。安装 CANN Toolkit 后：

cmake -B build -DGGML_CANN=on -DCMAKE_BUILD_TYPE=release
cmake --build build --config release

验证：

./build/bin/llama-cli -m PATH_TO_MODEL -p "Building a website can be done in 10 steps:" -ngl 32

看到如下输出即表示正在使用 CANN 后端：

llm_load_tensors:       CANN model buffer size = 13313.00 MiB
llama_new_context_with_model:       CANN compute buffer size =  1260.81 MiB

模型/设备支持矩阵与 CANN 安装细节见 docs/backend/CANN.md。

ZenDNN（AMD EPYC 优化）

ZenDNN 为 AMD EPYC CPU 提供优化的深度学习原语，主要加速推理负载中的矩阵乘法。

# 自动构建：首次构建会自动下载并编译 ZenDNN，可能耗时 5-10 分钟，之后会快很多
cmake -B build -DGGML_ZENDNN=ON
cmake --build build --config Release

# 使用自定义安装的 ZenDNN
cmake -B build -DGGML_ZENDNN=ON -DZENDNN_ROOT=/path/to/zendnn/install
cmake --build build --config Release

测试：

./build/bin/llama-cli -m PATH_TO_MODEL -p "Building a website can be done in 10 steps:" -n 50

硬件支持与调优细节见 docs/backend/ZenDNN.md。

Arm® KleidiAI™（Arm CPU 微内核）

KleidiAI 提供 ggml CPU 后端使用的 Arm CPU 优化微内核。构建期开启只是使这些内核可用，并不强制所有运算都走 KleidiAI——运行期由 llama.cpp 根据检测到的 CPU 特性、张量类型、算子形状和当前后端优先级，自动选择最优兼容内核。

支持目标：

Platform	Supported ABI / architecture	Notes
Linux	AArch64 / arm64	运行时 CPU 特性检测是自动的
Android	arm64-v8a	使用下文 NDK 命令做可移植构建
Apple	arm64	运行时检测自动；非流式 SVE 向量长度视为不可用
Windows	arm64	运行时检测自动；SMCU 数量在检测路径验证前视为未知

GGML_CPU_KLEIDIAI=ON 仅对 AArch64/arm64 构建有效；不要在 x86、32 位 Arm 或非 arm64-v8a 的 Android ABI 上启用。

原生 AArch64/arm64 构建：

cmake -S . -B build -DGGML_CPU_KLEIDIAI=ON
cmake --build build --config Release

Android arm64-v8a NDK 构建：设置 ANDROID_NDK 为 NDK 根目录后执行。该命令配置了一个可移植的 Android arm64-v8a 构建，开启 KleidiAI 并规避不属于 NDK 稳定原生 API 集的依赖：

cmake -S . -B build-android \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK/build/cmake/android.toolchain.cmake" \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-28 \
  -DGGML_CPU_KLEIDIAI=ON \
  -DGGML_NATIVE=OFF \
  -DGGML_OPENMP=OFF \
  -DGGML_LLAMAFILE=OFF \
  -DLLAMA_OPENSSL=OFF
cmake --build build-android --config Release --parallel
cmake --install build-android --prefix {install-dir} --config Release

关键选项说明：

• GGML_CPU_KLEIDIAI=ON：为 Android arm64-v8a 启用 KleidiAI；
• GGML_NATIVE=OFF：交叉编译必须关闭，因为构建机 CPU 不是 Android 目标 CPU（与 ggml/CMakeLists.txt 中交叉编译自动关闭 GGML_NATIVE 的逻辑一致，此处显式指定更保险）；
• GGML_OPENMP=OFF：避免向 NDK 命令行构建引入 OpenMP 运行时依赖；
• GGML_LLAMAFILE=OFF：规避 llamafile 后端（Android 不支持）；
• LLAMA_OPENSSL=OFF：规避 OpenSSL 依赖（不属于 NDK 稳定原生 API 集）。

仓库中的 Android Studio 工程 examples/llama.android 会对 arm64-v8a 自动启用 KleidiAI；命令行 CMake 构建则需要显式传 -DGGML_CPU_KLEIDIAI=ON。

可移植的 Android arm64-v8a 构建不需要全局 -march 标志（如 -march=armv8.7a）——全局 -march 会抬升高通代码的基线指令集，而这里无需手动选择架构相关源码：llama.cpp 在运行时选择兼容的 KleidiAI 内核，KleidiAI 库自身的 CMake 会为每个具体内核处理 -march 标志。

验证构建：

./build/bin/llama-cli -m PATH_TO_MODEL -p "What is a car?"

启用后输出应包含类似：

load_tensors: CPU_KLEIDIAI model buffer size =  3474.00 MiB

这确认模型张量通过 KleidiAI CPU 缓冲区分配，但不证明每个运算（或某个 SME 系运算）都走了 KleidiAI 微内核——运行期 CPU 特性、张量类型、运算形状与后端优先级仍决定分派。若其他后端优先级更高，可在构建期关闭（如 -DGGML_METAL=OFF）或使用运行时设备选项（如 --device none）强制 CPU 执行。

运行时分派：KleidiAI 微内核依赖 dotprod、i8mm、SVE、SME/SME2 等 Arm CPU 特性。KleidiAI 加速的是 F32 与常见量化格式的选定 GGML_OP_MUL_MAT 路径；具体覆盖取决于捆绑的 KleidiAI 版本与运行期选择器，不支持的张量类型、运算形状或更高优先级后端都可能绕过 KleidiAI——这也是 SME 硬件上未必用到 SME 系内核的原因。当前 SVE 选择器仅在运行期 SVE 向量长度确定为 32 字节（QK8_0）时才启用 SVE 内核：Linux/Android 会运行期查询；Apple 将 SVE 能力与用户态非流式 SVE 可用性分开报告，因此该值视为未知；Windows 暴露 SVE 特性但不暴露该选择器所用的运行期向量长度，同样视为未知（Windows arm64 的 SMCU 数量在检测机制验证前也视为未知）。可用的 SME 系内核集合取决于捆绑版本与检测到的 CPU 能力；生产环境不需要设置任何 KleidiAI 运行时环境变量。

诊断与调试覆盖：KleidiAI 运行时环境变量是诊断/调试用途，正常使用时保持不设置。GGML_KLEIDIAI_SME 控制 SME 系内核选择并覆盖量化 SME 系内核的最大线程数：

• 未设置：自动运行期检测；
• 0：禁用 SME 系内核；
• <n> > 0：启用兼容的 SME 系内核，并允许量化 SME 系内核最多使用 <n> 个线程。

Windows arm64 上，可在自动 SMCU 数量检测验证之前，用 GGML_KLEIDIAI_SME=<n> 作为临时诊断手段做 SME 线程上限标定。若 CPU 不支持某捆绑内核所需的能力，该内核无论如何设置环境变量都会被禁用。

OpenCL

为较新的 Adreno GPU 提供 OpenCL 加速，更多信息见 docs/backend/OPENCL.md。

Android（NDK）

假设 NDK 位于 $ANDROID_NDK。先安装 OpenCL 头文件与 ICD loader 库（如尚未安装）：

mkdir -p ~/dev/llm
cd ~/dev/llm

git clone https://github.com/KhronosGroup/OpenCL-Headers && \
cd OpenCL-Headers && \
cp -r CL $ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/include

cd ~/dev/llm

git clone https://github.com/KhronosGroup/OpenCL-ICD-Loader && \
cd OpenCL-ICD-Loader && \
mkdir build_ndk && cd build_ndk && \
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
  -DOPENCL_ICD_LOADER_HEADERS_DIR=$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/include \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=24 \
  -DANDROID_STL=c++_shared && \
ninja && \
cp libOpenCL.so $ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android

然后启用 OpenCL 构建 llama.cpp：

cd ~/dev/llm

git clone https://github.com/ggml-org/llama.cpp && \
cd llama.cpp && \
mkdir build-android && cd build-android

cmake .. -G Ninja \
  -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-28 \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_OPENCL=ON

ninja

Windows Arm64

同样先构建并安装 OpenCL-Headers 与 OpenCL-ICD-Loader（PowerShell）：

mkdir -p ~/dev/llm
cd ~/dev/llm
git clone https://github.com/KhronosGroup/OpenCL-Headers && cd OpenCL-Headers
mkdir 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

cd ~/dev/llm
git clone https://github.com/KhronosGroup/OpenCL-ICD-Loader && cd OpenCL-ICD-Loader
mkdir 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

再启用 OpenCL 构建 llama.cpp（使用仓库自带的 cmake/arm64-windows-llvm.cmake 工具链）：

cmake .. -G Ninja `
  -DCMAKE_TOOLCHAIN_FILE="$HOME/dev/llm/llama.cpp/cmake/arm64-windows-llvm.cmake" `
  -DCMAKE_BUILD_TYPE=Release `
  -DCMAKE_PREFIX_PATH="$HOME/dev/llm/opencl" `
  -DBUILD_SHARED_LIBS=OFF `
  -DGGML_OPENCL=ON
ninja

Android

完整的 Android 构建文档见 docs/android.md。

WebGPU

WebGPU 后端依赖 Dawn。按 Dawn 官方的 CMake 快速上手指南本地安装 Dawn，使 llama.cpp 能通过 CMake 找到它（当前实现与 Dawn 仓库中的特定提交保持同步）。随后：

cmake -B build -DGGML_WEBGPU=ON
cmake --build build --config Release

浏览器支持：借助 Emscripten 把 ggml 的 WebGPU 后端编译为 WebAssembly。由于 Emscripten 尚不官方支持 WebGPU 绑定，使用 Dawn 维护的 emdawnwebgpu 包（下载或自行构建；建议本地构建以保持与本机 Dawn 版本一致）。用 CMake 构建时，需要用 EMDAWNWEBGPU_DIR 标志指定 emdawnwebgpu port 文件的路径。

IBM Z & LinuxONE

构建文档见 docs/build-s390x.md。

OpenVINO

OpenVINO 是面向 Intel 硬件（CPU、GPU、NPU）优化的开源 AI 推理部署工具包。构建说明与使用示例见 docs/backend/OPENVINO.md。

GPU 加速后端的通用注意事项

1. -ngl 0 不等于完全关闭 GPU：即使使用 -ngl 0，GPU 仍可能加速部分计算；彻底禁用 GPU 加速请用 --device none。
2. 多后端可同时构建：例如同时启用 CUDA 与 Vulkan：-DGGML_CUDA=ON -DGGML_VULKAN=ON。运行期用 --device 选项指定使用哪些后端设备；用 --list-devices 查看可用设备列表。
3. 动态后端库：后端可以构建为运行期动态加载的动态库，使同一个 llama.cpp 二进制能在不同 GPU 的机器上使用。构建时启用 GGML_BACKEND_DL 选项。从源码看，该选项定义在 ggml/CMakeLists.txt，默认 OFF，且要求 BUILD_SHARED_LIBS；另有 GGML_BACKEND_DIR 变量可指定运行期查找动态后端的目录。

小结

llama.cpp 的构建体系以一套 GGML_* CMake 选项统一描述各硬件后端：CPU 基线只需两条 cmake 命令，各 GPU/NPU 后端（CUDA、Metal、Vulkan、HIP、MUSA、CANN 等）通过对应开关启用，并按“构建期选项（GGML_NATIVE、架构列表、BLAS vendor）+ 运行时环境变量（设备可见性、统一内存、P2P、队列缩放）”两个层面完成调优。遇到问题时，优先对照各后端章节中的典型报错（nvcc 架构警告、ROCm device library 缺失、Vulkan ICD 未 source 等）逐项排查，并结合上文列出的源码文件定位 CMake 层的具体行为。