在本地构建 llama.cpp

本项目的主要产物是 llama 库，其 C 风格接口见 include/llama.h。项目还提供了许多使用这个库的示例程序和工具，从简短的最小代码片段，到兼容 OpenAI 接口的 HTTP 服务器这样的复杂子项目都有。

获取代码：

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

下面依次介绍不同后端与选项的构建方式：CPU、BLAS、Metal、SYCL、CUDA、MUSA、HIP、Vulkan、CANN、ZenDNN、Arm KleidiAI、OpenCL、Android、WebGPU、IBM Z 与 LinuxONE、OpenVINO、Hexagon，以及 GPU 加速后端的补充说明。

CPU 构建

使用 CMake 构建 llama.cpp：

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

为了加快编译，可以添加 -j 并行运行多个任务，或者使用 Ninja 等自动并行的生成器。例如，cmake --build build --config Release -j 8 会并行运行 8 个任务。重复编译时，安装 ccache 可以加快速度。

调试构建分两种情况。单配置生成器，例如默认的 Unix Makefiles，会忽略 --config 标志，应这样构建：

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

多配置生成器，也就是通过 -G 指定 Visual Studio、Xcode 等生成器时，使用：

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

更多细节和支持的生成器列表见 CMake 文档。静态构建添加 -DBUILD_SHARED_LIBS=OFF：

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

在 Windows 上，使用 MSVC 或 clang 构建 x86、x64、arm64 版本时，先安装 Visual Studio 2022，例如社区版。安装器至少选择“使用 C++ 的桌面开发”工作负载，以及组件页中的 C++ CMake Tools for Windows、Git for Windows、C++ Clang Compiler for Windows、MS-Build Support for LLVM-Toolset (clang)。这也会自动安装 CMake 等必需工具。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 复制到运行时输出目录，并一同安装。省略这个选项即可使用 CMake 的常规 OpenMP 检测；传入 -D GGML_OPENMP=OFF 则禁用 OpenMP。

使用 Ninja 生成器并以 clang 为默认编译器时，先设置路径：

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

需要 HTTPS/TLS 功能时，可以安装 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。

BLAS 构建

启用 BLAS 后，当批大小超过 32（默认是 512）时，提示词处理可能有所提速。BLAS 不影响生成阶段的性能。当前可选择多种实现。

Accelerate Framework

仅适用于 Mac，默认启用，按照普通构建步骤即可。

OpenBLAS

这提供纯 CPU 的 BLAS 加速。确保机器已安装 OpenBLAS。Linux 上使用 CMake：

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

BLIS

更多信息见 BLIS.md。

Intel oneMKL

通过 oneAPI 编译器构建，可以在不支持 avx512 和 avx512_vnni 的 Intel 处理器上使用 avx_vnni 指令集。这个构建配置不支持 Intel GPU；Intel GPU 支持见 llama.cpp for SYCL。

手动安装 oneAPI 时，GGML_BLAS_VENDOR 默认是 Generic。如果已经加载 Intel 环境脚本，并在 CMake 中设置 -DGGML_BLAS=ON，会自动选择 MKL 版 BLAS。否则，安装 oneAPI 后执行：

source /opt/intel/oneapi/setvars.sh # You can skip this step if  in oneapi-basekit docker image, only required for manual installation
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

不想手动安装 oneAPI 和加载环境变量，也可以使用 Intel 的 oneAPI-basekit Docker 容器，再使用上面的命令。更多信息见 Optimizing and Running LLaMA2 on Intel CPU。

其他 BLAS 库

设置 GGML_BLAS_VENDOR 可以选择其他 BLAS 库。支持的供应商列表见 CMake 文档。

Metal 构建

macOS 默认启用 Metal，让计算在 GPU 上进行。编译时使用 -DGGML_METAL=OFF 可以禁用 Metal 构建。构建时支持 Metal 的情况下，也可以通过命令行参数 --n-gpu-layers 0 显式禁用 GPU 推理。

SYCL

SYCL 是面向各种硬件加速器的高级编程模型，可以提高开发效率。基于 SYCL 的 llama.cpp 用于支持 Intel GPU，包括 Data Center Max、Flex、Arc 系列，以及内置 GPU 和 iGPU。详细信息见 llama.cpp for SYCL。

CUDA

CUDA 后端使用 NVIDIA GPU 提供加速。确保安装了 CUDA toolkit。

从 NVIDIA 直接下载

官方安装包见 NVIDIA 开发者网站。

在 Fedora Toolbox 容器中编译和运行

项目还提供在 Fedora toolbox 容器中配置 CUDA toolkit 的指南。原文推荐以下使用场景：

• Fedora Atomic Desktops 用户必须使用，例如 Silverblue 和 Kinoite，因为没有支持这些系统的 CUDA 软件包。
• 主机系统不属于 NVIDIA CUDA 支持平台时必须使用，例如主机运行 Fedora 42 Beta。
• Fedora Workstation 或 Fedora KDE Plasma Desktop 用户希望保持主机整洁时，使用容器很方便。
• Arch Linux、Red Hat Enterprise Linux 8.5 及以上，以及 Ubuntu 也有可选的 toolbox 软件包。

编译

请先阅读 CPU 构建的通用说明，例如如何加快编译。

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

非本机构建

默认情况下，llama.cpp 针对构建时系统连接的硬件编译。若要覆盖全部 CUDA GPU，应禁用 GGML_NATIVE：

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

原文指出，得到的二进制应能在所有 CUDA GPU 上以最佳性能运行，不过可能需要一些即时编译。

覆盖计算能力配置

如果 nvcc 检测不到 GPU，可能出现以下编译警告：

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

可以采用上面的非本机构建，但会产生较大的二进制，编译耗时也更长。另一种办法是明确指定 CUDA 架构。非本机构建也可能适合这样做，可以先查看 ggml/src/ggml-cuda/CMakeLists.txt 中的逻辑。

第一步，记录 NVIDIA 设备的 Compute Capability，见 CUDA GPU 计算能力列表：

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

第二步，把不同的计算能力逐一列入 CMAKE_CUDA_ARCHITECTURES：

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

覆盖 CUDA 版本

系统安装多个 CUDA 版本时，可以指定构建所用版本。例如 CUDA 11.7 位于 /opt/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（例如 v11.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 环境变量：

# Use `CUDA_VISIBLE_DEVICES` to hide the first compute device.
CUDA_VISIBLE_DEVICES="-0" ./build/bin/llama-server --model /srv/models/llama.gguf

CUDA_SCALE_LAUNCH_QUEUES

CUDA_SCALE_LAUNCH_QUEUES 控制 CUDA 命令缓冲区大小，决定 CPU 必须等待 GPU 跟上之前能够排队多少 GPU 操作。更大的缓冲区能减少 CPU 端停顿，让 GPU 上排队更多工作。可以考虑设置 CUDA_SCALE_LAUNCH_QUEUES=4x，将缓冲区增大到默认值的四倍。原文指出，这对使用流水线并行的多 GPU 配置尤其有益，因为它能让跨 GPU 排队的操作更多，从而显著提高提示词处理吞吐量。

GGML_CUDA_CUBLAS_COMPUTE_TYPE

覆盖 cuBLAS 矩阵乘法默认的、以速度优化为目标的计算类型。合法值为 auto、f16、fp16、bf16、f32、fp32。

统一内存

Linux 中，GGML_CUDA_ENABLE_UNIFIED_MEMORY=1 可以启用统一内存。GPU 显存耗尽时，可以换用系统 RAM，而不是崩溃。Windows 在 NVIDIA 控制面板中以 System Memory Fallback 提供此设置。

点对点访问

GGML_CUDA_P2P 可以启用多 GPU 间的点对点访问，使数据直接传输，无需经过系统内存。这需要驱动支持，通常限于工作站或数据中心 GPU。某些主板及 BIOS 设置（例如 IOMMU）下，它可能造成崩溃或输出损坏。

性能调优

还可以通过以下编译选项调整性能：

选项	合法值	默认值	说明
GGML_CUDA_FORCE_MMQ	Boolean	false	对量化模型强制使用自定义矩阵乘法内核，而非 FP16 cuBLAS，即使没有 int8 tensor core 实现也如此，涉及 V100、CDNA 和 RDNA3+。支持 int8 tensor core 的 GPU 默认启用 MMQ。强制启用后，大批量速度会变慢，但显存消耗更低。
GGML_CUDA_FORCE_CUBLAS	Boolean	false	对量化模型强制使用 FP16 cuBLAS，而非自定义矩阵乘法内核。可能出现数值溢出，V100、CDNA 和 RDNA4 默认使用 FP32 计算类型，因此例外；内存使用也会增加。较新的数据中心 GPU 上，提示词处理可能更快，因为自定义内核主要针对 RTX 3000/4000 调优。
GGML_CUDA_FA_QUANTS	all 或 type_K-type_V 列表	q4_0-q4_0;q8_0-q8_0;f16-f16;bf16-bf16	指定 FlashAttention CUDA 内核要编译的 K/V 类型组合。all 编译全部组合，耗时明显更长；否则使用分号分隔的类型对列表。f16-f16 始终编译。未编译组合会退回 f16-f16 内核并警告。合法类型：f16、bf16、q4_0、q4_1、q5_0、q5_1、q8_0。
GGML_CUDA_FA_ALL_QUANTS	Boolean	false	已弃用，相当于 GGML_CUDA_FA_QUANTS=all。

MUSA

MUSA 使用摩尔线程 GPU 提供加速。确保安装 MUSA SDK。

从摩尔线程直接下载

官方安装包见摩尔线程开发者网站。

编译

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

覆盖计算能力配置

默认启用全部支持的计算能力。可以在 CMake 命令中指定 MUSA_ARCHITECTURES：

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

这只启用计算能力 2.1（MTT S80），有助于减少编译时间。

编译选项

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 运行时环境变量

运行时可以设置 MUSA 环境变量：

# Use `MUSA_VISIBLE_DEVICES` to hide the first compute device.
MUSA_VISIBLE_DEVICES="-0" ./build/bin/llama-server --model /srv/models/llama.gguf

统一内存

原文此处同样使用 GGML_CUDA_ENABLE_UNIFIED_MEMORY=1，在 Linux 启用统一内存，显存耗尽时改用系统 RAM，避免崩溃。

HIP

HIP 为支持 HIP 的 AMD GPU 提供加速。确保安装 ROCm，可通过 Linux 发行版包管理器或 ROCm Quick Start 获取。

Linux 上使用 CMake，假设 GPU 兼容 gfx1030：

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=<directory-you-just-found>，例如：

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 上使用 CMake，应打开 VS 的 x64 Native Tools Command Prompt，下面假设 GPU 兼容 gfx1100：

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_TARGETS。示例的 gfx1100 对应 Radeon RX 7900XTX/XT/GRE。目标列表见 LLVM 文档。将 rocminfo | grep gfx | head -1 | awk '{print $2}' 的主要版本信息与处理器列表匹配，即可确定 GPU 版本字符串，例如 gfx1035 映射到 gfx1030。

HIP_VISIBLE_DEVICES 可以指定要使用的 GPU。如果 GPU 未被官方支持，可以用 HSA_OVERRIDE_GFX_VERSION 指定相近 GPU，例如 RDNA2 的 10.3.0（gfx1030、gfx1031、gfx1035），或 RDNA3 的 11.0.0。该变量不支持 Windows。

统一内存

Linux 上设置 GGML_CUDA_ENABLE_UNIFIED_MEMORY=1，可以使用统一内存架构（UMA），在 CPU 与集成 GPU 之间共享主内存。但非集成 GPU 的性能会受损；它使集成 GPU 能够工作。

Vulkan

Windows

w64devkit：下载解压 w64devkit，按默认设置安装 Vulkan SDK。启动 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

切换到 llama.cpp 目录，使用 CMake 构建：

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

Git Bash MINGW64：按默认设置安装 Git-SCM、CMake 和 Vulkan SDK，安装 Visual Studio Community Edition 时勾选 C++。在 llama.cpp 目录右键选择 Open Git Bash Here，运行：

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

然后可以使用 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

切换到 llama.cpp 目录，使用 CMake 构建：

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

先按照 Getting Started with the Linux Tarball Vulkan SDK 的官方步骤安装配置。完成后，必须在当前终端会话中用 source 加载 SDK 内的 setup_env.sh，否则无法构建。关闭终端后，下次构建还要再次执行；持久化办法见上述 SDK 指南。

使用系统包

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 目录已包含这些头文件。

通用步骤

确认 SDK 安装配置完成后，先执行：

vulkaninfo

已进入 llama.cpp 目录且 vulkaninfo 无错误时，使用以下命令构建：

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

完成构建后，可以按照原文示例检查输出二进制：

# Test the output binary
# "-ngl 99" should offload all of the layers to GPU for most (if not all) models.
./build/bin/llama-cli -m "PATH_TO_MODEL" -p "Hi you how are you" -ngl 99
# You should see in the output, ggml_vulkan detected your GPU. For example:
# ggml_vulkan: Using Intel(R) Graphics (ADL GT2) | uma: 1 | fp16: 1 | warp size: 32

Mac

安装配置参见 LunarG 的 Getting Started with the MacOS Vulkan SDK。macOS 有两种 Vulkan 驱动，均通过转换层将 Vulkan 映射到 Metal。设置 VK_ICD_FILENAMES 指向相应 ICD JSON 文件即可切换。安装 SDK 时勾选 KosmicKrisp。安装后加载 SDK 环境，必要时加入 shell 配置以持久化：

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

MoltenVK

MoltenVK 是 LunarG SDK 在 macOS 上默认安装的 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

构建

这一步是与上面通用步骤唯一不同之处：

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

CANN

CANN 使用昇腾 NPU 的 AI 核心提供加速。CANN 是一组分层 API，帮助快速构建基于昇腾 NPU 的 AI 应用与服务。更多信息见昇腾社区。确保安装 CANN toolkit，进入 llama.cpp 目录并构建：

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 安装等详情见 llama.cpp for CANN。

ZenDNN

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

编译

Linux 上自动构建：

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

首次构建会自动下载并构建 ZenDNN，原文预计需要 5—10 分钟，后续构建会快得多。使用自定义安装：

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

硬件支持、配置和性能优化详情见 llama.cpp for ZenDNN。

Arm® KleidiAI™

KleidiAI 为 ggml CPU 后端提供优化的 Arm CPU 微内核。构建时启用只是使这些内核可用，不会强制全部操作都使用 KleidiAI。运行时，llama.cpp 根据检测到的 CPU 特性、张量类型、操作形状和当前后端优先级，选择最合适的兼容 CPU 内核。

平台	支持的 ABI/架构	说明
Linux	AArch64/arm64	自动检测运行时 CPU 特性。
Android	arm64-v8a	使用下面的 NDK 命令构建可移植版本。
Apple	arm64	自动检测 CPU 特性；非流式 SVE 向量长度视为不可用。
Windows	arm64	自动检测 CPU 特性；检测路径核实前，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 根目录，再从源码目录执行以下命令。它配置启用 KleidiAI 的可移植 Android arm64-v8a 构建，并避开 NDK 稳定原生 API 集之外的 Android 依赖：

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_OPENMP=OFF 避免增加 OpenMP 运行时依赖；GGML_LLAMAFILE=OFF 避免 Android 不支持的 llamafile 后端；LLAMA_OPENSSL=OFF 避免依赖不属于 NDK 稳定原生 API 集的 OpenSSL。

examples/llama.android 中的 Android Studio 项目自动为 arm64-v8a 启用 KleidiAI。Android 命令行 CMake 构建需要明确传入 -DGGML_CPU_KLEIDIAI=ON。可移植构建不需要 -march=armv8.7a 等全局标志：全局 -march 会提高通用代码的指令集基线。也不需要手动选择架构专属源码，运行时会选择兼容内核；KleidiAI 库内部的 CMake 会为各个内核处理 -march 标志。

验证构建

运行安装后的或构建树中的二进制：

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

启用 KleidiAI 时，原文指出输出包含类似以下行：

load_tensors: CPU_KLEIDIAI model buffer size =  3474.00 MiB

这只确认模型通过 KleidiAI CPU 缓冲区分配了张量，不证明每个操作或任何特定 SME 系列操作用了 KleidiAI 微内核。实际分派仍由 CPU 特性、张量类型、操作形状与后端优先级决定。根据构建目标，其他后端可能比 CPU 优先级高。要强制使用 CPU，可在构建时关闭优先级更高的后端，例如 -DGGML_METAL=OFF，或在支持时使用 --device none 等运行时设备选项。

运行时分派

KleidiAI 微内核使用 dotprod、i8mm、SVE、SME/SME2 等 Arm CPU 特性。构建配置使内核可用，运行时根据 CPU 和操作选择兼容内核；较旧或特性较少的 CPU 自动退回兼容实现。

它加速 F32 和常见量化格式的部分 GGML_OP_MUL_MAT 路径。具体覆盖范围取决于随附 KleidiAI 版本和 llama.cpp 运行时选择器。因此，即使 CPU 支持必要特性，不支持的张量类型、操作形状或优先级更高的后端仍可能绕过 KleidiAI。这也解释了为什么具备 SME 能力的硬件上，模型可能没有使用 SME 系列内核。

当前 SVE 选择器只在运行时 SVE 向量长度确认为 QK8_0 字节（目前 32 字节）时启用 SVE 内核。Linux 和 Android 在运行时查询。Apple 区分 SVE 能力与用户空间非流式 SVE 可用性，所以向量长度被视为未知。Windows 暴露 SVE 特性是否存在，却未暴露选择器所用的运行时向量长度，所以也视为未知。Windows arm64 的 SMCU 数量在检测机制核实前同样视为未知。

可用的 SME 系列内核取决于随附版本与 CPU 能力。生产配置不需要任何 KleidiAI 运行时环境变量。

诊断与调试覆盖

这些环境变量只用于诊断和调试覆盖，正常使用应保持未设置。GGML_KLEIDIAI_SME 控制 SME 系列内核选择，并覆盖选定量化 SME 内核可用的最大线程数：不设置则自动检测；0 禁用 SME 系列；<n> > 0 启用兼容内核，并允许量化 SME 内核最多使用 <n> 个线程。

Windows arm64 在自动 SMCU 数量检测核实前，可用 GGML_KLEIDIAI_SME=<n> 临时诊断、调试和校准线程上限。若 CPU 不支持某个内核所需的 SME 能力，无论环境变量如何设置，该内核都会禁用。

OpenCL

OpenCL 为较新的 Adreno GPU 提供 GPU 加速，详情见 OPENCL.md。

Android

假设 $ANDROID_NDK 指向 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 头文件与 ICD loader 库，先执行：

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 构建：

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 构建说明见 android.md。

WebGPU

WebGPU 后端依赖 Dawn。按照其 CMake 快速入门 在本地安装 Dawn，使 llama.cpp 能通过 CMake 找到它。原文中的实现与 Dawn 提交 94c3c9c 对齐。在 llama.cpp 目录构建：

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

浏览器支持

WebGPU 让支持它的浏览器能够跨平台访问 GPU。项目使用 Emscripten 将 ggml WebGPU 后端编译为 WebAssembly。原文指出，Emscripten 尚未正式支持 WebGPU 绑定，但 Dawn 维护自己的 emdawnwebgpu 绑定。按照 emdawnwebgpu 说明 下载或构建相应包。本地构建可能更稳妥，因为可以与前面安装的 Dawn 保持同步。CMake 构建时，通过 EMDAWNWEBGPU_DIR 指定 port 文件路径。

IBM Z 与 LinuxONE

构建说明见 build-s390x.md。

OpenVINO

OpenVINO 是优化和部署高性能 AI 推理的开源工具包，专门面向 Intel CPU、GPU 与 NPU。构建步骤和使用示例见 OPENVINO.md。

Hexagon

特定目标的构建运行说明见 README.md。

GPU 加速后端补充说明

即使使用 -ngl 0，GPU 仍可能加速部分计算。--device none 可以完全禁用 GPU 加速。

多数情况下，可以同时构建使用多个后端。例如 CMake 使用 -DGGML_CUDA=ON -DGGML_VULKAN=ON，就同时支持 CUDA 和 Vulkan。运行时通过 --device 指定后端设备；--list-devices 列出可用设备。

后端可以构建为运行时动态加载的动态库，让同一个 llama.cpp 二进制在不同 GPU 的机器上使用。构建时用 GGML_BACKEND_DL 启用。

---

原作：Build llama.cpp locally，v0.5.0，llama.cpp 文档贡献者。根据同版本 MIT 许可证 转为中文；代码保持原文，完整许可随稿附在 LICENSE-MIT.txt。本文没有编译程序、下载模型或执行推理；命令输出与性能描述均来自原文，不是本机测试结果。原文的默认 clone 命令未固定 tag，复现该文档版本应另行固定 v0.5.0；本稿保留原命令，不将它误称为版本固定命令。旧 CUDA 手改头文件的内容属于特定兼容问题的原文方案，实际使用需结合匹配的工具链评估。