Linux 环境下 llama.cpp 编译指南：从 CPU 到 CUDA 加速全流程

详细介绍如何在 Linux 系统中从源码编译 llama.cpp，涵盖基础 CPU 版本及 NVIDIA GPU (CUDA) 加速版本的配置步骤。包含完整编译指令合集。

对于想要在本地运行大语言模型（LLM）的开发者来说，llama.cpp 是目前最核心的开源推理框架。它通过极致的 C++ 优化和量化技术，让原本需要昂贵显卡才能运行的模型可以在普通电脑甚至笔记本上流畅运行。

本项目的主要产物是 llama 库，其 C 语言风格接口可以在 include/llama.h 文件中找到。项目还包括大量示例程序和工具，这些示例均基于 llama 库开发，既有简单的代码片段，也有较为复杂的子项目，例如与 OpenAI 兼容的 HTTP 服务器等。

本文将指导你如何在 Linux 环境下从源码编译 llama.cpp，以获得最佳的硬件适配性能，并在文末提供完整的编译指令合集。

🛠️ 编译前提条件

在开始编译之前，请确保你的系统已安装以下基础工具：

基础构建工具：Git（用于拉取源码）和 CMake（用于构建项目）。
驱动与工具链（仅 GPU 用户）：如果你使用 NVIDIA 显卡，必须预先安装好最新的 NVIDIA Driver 和 CUDA Toolkit。
环境准备：建议在独立的文件夹中进行操作。

📥 获取源码

首先，从 GitHub 官方仓库克隆最新的代码库：

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

🚀 快速编译指南

1. 编译 CPU 版本 (通用版)

如果你没有独立显卡，或者只需要在 CPU 上运行模型，可以使用最简单的编译方式。这种方式兼容性最强，适用于所有 x86/ARM 架构。

# 创建构建目录并配置
cmake -B build

# 执行编译（建议 -j 后接你的 CPU 线程数，例如 -j 8）
cmake --build build --config Release -j 8

2. 编译 GPU 版本 (NVIDIA CUDA 加速) ← 默认推荐

为了获得极快的推理速度，强烈建议开启 CUDA 支持。这允许模型在显存中运行，速度比 CPU 快数十倍。

注意：请确保 nvcc 命令可用（即 CUDA Toolkit 已正确安装）。

# 配置 CUDA 加速参数
# GGML_CUDA=ON: 开启 CUDA 支持
# GGML_CUDA_ENABLE_UNIFIED_MEMORY=1: 开启统一内存，允许在显存不足时使用部分系统内存
# GGML_CUDA_NCCL=ON: 启用 NCCL（NVIDIA 集合通信库），支持多 GPU 通信
cmake -B build -DGGML_CUDA=ON -DGGML_CUDA_ENABLE_UNIFIED_MEMORY=1 -DGGML_CUDA_NCCL=ON

# 执行编译
cmake --build build --config Release -j 8

📚 llama.cpp 编译指令合集

本章汇总了 llama.cpp 的所有编译方案，涵盖各种后端和平台。

CPU 版本构建

基础 CPU 构建

使用 CMake 构建 llama.cpp：

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

注意：

想提升编译速度，可以加上 -j 参数实现多线程并行编译，比如：cmake --build build --config Release -j 8 表示并发运行 8 个任务。或者直接使用默认并发的编译器（如 Ninja）。
推荐安装 ccache 工具，以加快重复编译速度。

调试版本 (Debug)

单配置生成器（如默认的 Unix Makefiles，此类生成器会忽略 --config 参数）：

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

多配置生成器（如使用 -G "Xcode" 或 Visual Studio）：

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 版本构建

请先安装 Visual Studio 2022（如 Community Edition），选择以下功能：

工作负载：C++ 桌面开发
组件：C++ CMake 工具、Windows 版 Git、C++ Clang 编译器、MS-Build 对 LLVM 工具集的支持（clang）

在 Windows on ARM（arm64, WoA）上编译：

cmake --preset arm64-windows-llvm-release -D GGML_OPENMP=OFF
cmake --build build-arm64-windows-llvm-release

若使用 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

默认启用了 Curl（libcurl 客户端库）功能，如不需要可通过 -DLLAMA_CURL=OFF 关闭。

BLAS 构建

启用 BLAS（基础线性代数子程序库）可提升处理大型批次数据时的推理速度（如批量大于 32，推荐使用 512）。BLAS 不影响文本生成阶段的性能。

Accelerate 框架

仅在 Mac 上可用，且默认启用。按照常规流程构建即可。

OpenBLAS

纯 CPU 的 BLAS 加速，需要在本机预先安装 OpenBLAS。

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

Intel oneMKL

使用 oneAPI 编译器编译，可让不支持 avx512 的英特尔处理器启用 avx_vnni 指令集。

手动安装 oneAPI 后：

source /opt/intel/oneapi/setvars.sh
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

默认 GGML_BLAS_VENDOR 参数为 Generic。如果已加载 Intel 环境脚本并设置了 -DGGML_BLAS=ON，则会自动选择 mkl 版 Blas。

如需使用其他 BLAS 库，请通过 GGML_BLAS_VENDOR 指定。受支持库详见 CMake 官方文档。

Metal 构建

在 macOS 上，Metal（苹果自研图形与计算 API）默认开启，利用 Metal 可将运算任务交由 GPU 执行。如果想在编译时关闭 Metal，可在 CMake 命令里加上 -DGGML_METAL=OFF。

如果已启用 Metal 支持（即默认情况），可通过启动参数 --n-gpu-layers 0 显式禁用 GPU 推理。

SYCL (Intel GPU)

SYCL 是一种高层次的异构计算编程模型，可以提升跨设备（如 CPU、GPU、FPGA 等）开发效率。

llama.cpp 基于 SYCL 的实现用于支持英特尔 GPU（如数据中心 Max 系列、Flex 系列、Arc 系列、集成显卡及 iGPU）。

详细使用说明见 llama.cpp for SYCL。

CUDA (NVIDIA GPU) ← 默认推荐

利用 NVIDIA GPU 实现加速。请确保已经安装 CUDA 工具包。

官方下载

请访问 NVIDIA 开发者网站获取 CUDA 安装包。

编译命令

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

覆盖 CUDA 架构能力（Compute Capability）设置

如果 nvcc 不能检测到你的 GPU，可能会出现如下警告：

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

此时可以手动指定 CUDA 计算能力：

确认你的 NVIDIA 设备的 Compute Capability，例如：

GPU 型号	Compute Capability
GeForce RTX 4090	8.9
GeForce RTX 3080 Ti	8.6
GeForce RTX 3070	8.6

在 CMake 命令中手动列出需要支持的 Compute Capability，用分号 ; 分隔：

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

CUDA 运行时环境变量

可在运行时设置 CUDA 环境变量：

# 用 CUDA_VISIBLE_DEVICES 隐藏第一个计算设备
CUDA_VISIBLE_DEVICES="-0" ./build/bin/llama-server --model /srv/models/llama.gguf

统一内存（Unified Memory）

在 Linux 下，设置环境变量 GGML_CUDA_ENABLE_UNIFIED_MEMORY=1 可启用 CUDA 统一内存，这意味着当显存耗尽时会自动用系统内存（而不会直接崩溃）。在 Windows 中，此设定可在 NVIDIA 控制面板中通过"系统内存回退"选项实现。

性能调优选项

选项	可选值	默认值	说明
`GGML_CUDA_FORCE_MMQ`	布尔值	`false`	强制为量化模型使用自定义矩阵乘法核心，即使没有 int8 张量核心。适用于 V100、CDNA 和 RDNA3+。启用后大批次速度下降，但显存占用更低。
`GGML_CUDA_FORCE_CUBLAS`	布尔值	`false`	强制对量化模型使用 FP16 cuBLAS 库，不用自定义矩阵核心
`GGML_CUDA_F16`	布尔值	`false`	启用后，CUDA 去量化与乘法、q4_1 和 q5_1 矩阵乘法核心均使用半精度浮点（FP16）运算，适合较新 GPU 提升性能
`GGML_CUDA_PEER_MAX_BATCH_SIZE`	正整数	`128`	多 GPU 下，启用 peer access（显存直连）时最大批大小。Peer access 仅限 Linux 或支持 NVLink。
`GGML_CUDA_FA_ALL_QUANTS`	布尔值	`false`	为 FlashAttention CUDA 核心编译所有 KV 缓存量化类型。可细粒度控制 KV 缓存，但编译需时更长

MUSA (摩尔线程 GPU)

MUSA 提供对摩尔线程（Moore Threads）GPU 的加速支持。请确保已安装 MUSA SDK。

官方下载

访问摩尔线程开发者中心下载 MUSA SDK。

编译命令

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

覆盖计算能力规格

默认启用了全部受支持的 MUSA 计算能力。如需自定义：

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

该配置只启用计算能力为 2.1（MTT S80）的设备，可以有效缩短编译时间。

静态库编译

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

运行时环境变量

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

统一内存

通过设置环境变量 GGML_CUDA_ENABLE_UNIFIED_MEMORY=1，可以在 Linux 系统下启用统一内存。

HIP (AMD GPU / ROCm)

HIP 提供基于 AMD GPU 的加速功能（仅支持安装了 ROCm 的设备）。

请先确保已安装 ROCm 驱动。

Linux 上编译（以支持 gfx1030 架构的 AMD GPU 为例）

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

如果你的硬件为 RDNA3+ 或 CDNA 架构，为了提升 Flash Attention 的性能，可以在编译时加入 -DGGML_HIP_ROCWMMA_FATTN=ON，需要确保系统已经安装了 rocWMMA 库。

解决 ROCm 设备库错误：

如果编译时出现以下错误提示：

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 文件的目录：

HIPCXX="$(hipconfig -l)/clang" HIP_PATH="$(hipconfig -p)" \
HIP_DEVICE_LIB_PATH=<你的目录路径> \
    cmake -S . -B build -DGGML_HIP=ON -DAMDGPU_TARGETS=gfx1030 -DCMAKE_BUILD_TYPE=Release \
    && cmake --build build -- -j 16

Windows 上编译

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

请确保 AMDGPU_TARGETS 设置为你希望支持的 GPU 架构。例如 gfx1100 适用于 Radeon RX 7900XTX/XT/GRE。

查询本机 GPU 型号：

rocminfo | grep gfx | head -1 | awk '{print $2}'

统一内存

在 Linux 系统下，可以通过设置环境变量 GGML_CUDA_ENABLE_UNIFIED_MEMORY=1 启用统一内存架构（UMA）。

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

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

使用 Vulkan 后端加载模型：

build/bin/Release/llama-cli -m "[模型路径]" -ngl 100 -c 16384 -t 10 -n -2 -cnv

MSYS2

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

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

使用 Docker

# 构建镜像
docker build -t llama-cpp-vulkan --target light -f .devops/vulkan.Dockerfile .

# 运行
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

非 Docker 环境 (Ubuntu 22.04)

wget -qO - https://packages.lunarg.com/lunarg-signing-key-pub.asc | apt-key add -
wget -qO /etc/apt/sources.list.d/lunarg-vulkan-jammy.list https://packages.lunarg.com/vulkan/lunarg-vulkan-jammy.list
apt update -y
apt-get install -y vulkan-sdk
vulkaninfo

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

# 测试命令
./bin/llama-cli -m "PATH_TO_MODEL" -p "Hi you how are you" -n 50 -e -ngl 33 -t 4

CANN (华为昇腾 NPU)

CANN 支持利用华为昇腾（Ascend NPU）AI 核进行加速。

请确保已经安装 CANN 工具包。可前往 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 安装等细节，请参阅 llama.cpp for CANN。

Arm KleidiAI

KleidiAI 是专门为 Arm CPU 优化的 AI 微内核库。它可以通过微内核提升 ARM 架构下的 AI 工作负载性能。

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

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

如果启用 KleidiAI，输出内容将类似：

load_tensors: CPU_KLEIDIAI model buffer size = 3474.00 MiB

如果平台支持 SME，需要手动设置环境变量 GGML_KLEIDIAI_SME=1 以启用相应功能。

注意： 某些编译目标下，其他高优先级后端可能会默认启用。若需要强制使用 CPU 后端，请在编译时关闭高优先级后端（如 -DGGML_METAL=OFF），或运行时使用 --device none。

OpenCL

OpenCL 后端可通过近代 Adreno GPU（高通芯片）实现 GPU 加速。

Android 平台

假设 NDK 路径设置为 $ANDROID_NDK：

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

# 安装 OpenCL 头文件和 ICD loader
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

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

# 安装 OpenCL 头文件
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

# 安装 OpenCL ICD Loader
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

⚙️ GPU 加速后端说明

多后端同时编译

在大多数情况下，您可以同时编译并使用多个后端（例如，CUDA 和 Vulkan）：

cmake .. -DGGML_CUDA=ON -DGGML_VULKAN=ON

运行时可以通过 --device 参数指定使用的后端设备。要查看所有可用设备：

./main --list-devices

动态库加载

后端也可以构建为动态库（动态链接库），实现运行时按需加载。这意味着同一个 llama.cpp 可执行文件可以在不同 GPU 设备的机器上运行，自动适配相应环境。要启用该功能，请在构建时使用 GGML_BACKEND_DL 选项。

完全禁用 GPU

即使使用 -ngl 0 选项，某些计算过程仍可能使用 GPU。如果你希望完全禁用 GPU 加速，请添加参数 --device none。

📁 结果验证与运行

编译完成后，所有的可执行文件（例如 main, server 等）和相关库文件都会存放在以下路径：

build/bin/

你可以通过以下命令验证是否编译成功：

./build/bin/llama-cli --version

💡 进阶提示

性能调优：在运行模型时，可以通过 -t 参数指定 CPU 线程数，通过 -ngl (GPU Layers) 指定将多少层模型加载到显存中。
内存建议：如果你在编译 GPU 版本时遇到内存不足（OOM）错误，请尝试减小 cmake --build 时的 -j 线程数（例如改为 -j 2 或 -j 1）。
构建和运行时选择适合自己硬件的后端，可大幅提升推理速度和运行效率。对于初学者，建议先尝试单一后端，确认环境配置无误后再尝试多后端或动态库加载等高级功能。

现在，你可以开始下载 GGUF 格式的模型文件，体验本地 AI 的强大能力了！