llama.cpp 入门：编译、运行 GGUF 模型

llama.cpp 的定位和其他推理框架都不一样：纯 C/C++ 实现、零依赖、以 MIT 许可证开源，目标是在尽可能广泛的硬件上以最小配置跑出顶尖性能——从本地笔记本到云端服务器都在射程内 ^[1]。这篇从安装、编译讲到拉起模型和开服务，把最短路径走一遍。

为什么是 C/C++

零依赖是 llama.cpp 的立身之本：不需要 Python 环境，不需要 CUDA 全家桶，编译产物就是可执行文件。硬件覆盖从清单可见一斑 ^[1]：x86 走 AVX、AVX2、AVX512 和 AMX，RISC-V 走 RVV 一族，Apple Silicon 经 ARM NEON、Accelerate 和 Metal 被当作一等公民优化。GPU 侧是自研 CUDA 内核，AMD 卡走 HIP，摩尔线程卡走 MUSA，另外还有 Vulkan 和 SYCL 两套通用后端。后端矩阵从 Nvidia、Apple、AMD、Intel 一直排到华为昇腾 NPU、骁龙和 IBM 主机 ^[1]。

另一个杀手锏是量化：1.5-bit 到 8-bit 的整数量化全家桶，推理更快、内存更省 ^[1]。显存装不下整个模型也没关系，CPU+GPU 混合推理能把超出显存的部分放到内存里算 ^[1]。整个项目构建在 ggml 库之上 ^[1]。

安装与第一条命令

装法有五条路：一行安装脚本、llama.app 网站指引、Docker、发布页下载预编译二进制、克隆仓库自己编译 ^[1]。脚本安装最省事 ^[1]：

# curl
curl -LsSf https://llama.app/install.sh | sh

# powershell
irm https://llama.app/install.ps1 | iex

装完之后，从 Hugging Face 拉一个 GGUF 模型并直接进入对话，一条命令 ^[1]：

# Download and run a model directly from Hugging Face
llama cli -hf ggml-org/Qwen3.5-0.8B-GGUF

# Launch OpenAI-compatible API server
llama serve -hf ggml-org/Qwen3.5-0.8B-GGUF

cli 子命令负责交互式对话，serve 子命令直接起一个 OpenAI 协议兼容的 API 服务——后者还带内置 WebUI，浏览器打开就能聊天。GGUF 的 -hf 用法把「找模型、下权重、加载运行」压缩成一步，模型名就是 Hugging Face 上的仓库 ID。工具箱里还有 completion 和 GBNF 语法约束等组件 ^[1]。

从源码编译

要定制后端就得自己编译。主产物是 llama 库，C 风格接口在 include/llama.h，仓库里从最小示例到 OpenAI 兼容 HTTP 服务器的完整子项目都有 ^[2]。先拿代码 ^[2]：

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

CPU 版就是标准 CMake 流程 ^[2]：

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

加速编译有三种手段：-j 参数并行跑任务（如 -j 8）、换 Ninja 这类自动并行的生成器、装 ccache 缓存重复编译 ^[2]。调试版按生成器类型分两种写法，单配置生成器忽略 --config，要用 -DCMAKE_BUILD_TYPE=Debug ^[2]：

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

静态链接加 -DBUILD_SHARED_LIBS=OFF ^[2]：

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

Windows 上用 MSVC 或 clang，装 Visual Studio 2022 时至少勾选 C++ 桌面开发工作负载和 CMake 工具；Windows on ARM 走 arm64-windows-llvm-release 预设并加 GGML_OPENMP_FETCH，从 x64 交叉编译到 WoA 也能用 ^[2]。需要 HTTPS 功能就装 OpenSSL 开发库——Debian/Ubuntu 是 libssl-dev，Fedora 系是 openssl-devel，不装也能跑，只是没有 SSL 支持 ^[2]。

后端编译开关

BLAS 后端只在批大于 32 的提示词处理上有提速（默认 512），对生成速度没有影响；Mac 上 Accelerate 默认启用，OpenBLAS 提供纯 CPU 加速 ^[2]。macOS 上 Metal 默认开启，计算直接跑在 GPU 上；编译期想关掉用 -DGGML_METAL=OFF，运行期想强制回 CPU 用 --n-gpu-layers 0 ^[2]。SYCL 后端面向 Intel GPU，覆盖 Data Center Max、Flex、Arc 系列和集成显卡 ^[2]。

NVIDIA 显卡是重头戏，前提是装好 CUDA toolkit ^[2]：

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

CCCL 版本可以用 -DGGML_CUDA_CCCL_VERSION 显式指定；CUB DeviceTopK 需要 CCCL 3.4.3 以上，旧版本自动退回排序实现 ^[2]。

选型参考

最后把 llama.cpp 在推理工具链里的位置说清楚：它不追求集群级吞吐，而是把「在任何设备上跑模型」这件事做到极致——CPU-only 的服务器、旧款 Mac、国产显卡、甚至手机端都有对应后端。GGUF 量化让模型体积可以按硬件预算裁剪，7B 模型压到 4-bit 后几张 GB 的内存就能承载。需要高并发生产服务时 vLLM 更合适；需要在资源受限设备上本地跑、或想深入理解推理引擎内部时，llama.cpp 是那个最合适的选择。官方文档里还备有 Docker、多卡、性能排查等专题 ^[1]，需要时按图索骥即可。

本文改编自 llama.cpp 项目仓库的 README 与构建文档^[1][2]，原文以 MIT 许可证发布。