2. 环境搭建：在 Windows / Linux / macOS 上编译与安装 llama.cpp

说实话，环境搭建往往是入坑的第一个坎，也是劝退最多人的地方。我之前带过几个新人，光是在编译器版本上就卡了一整天。其实 llama.cpp 的设计已经很良心了——纯 C++17，依赖极少，跨平台思路也很统一。你只要把「获取源码 → 安装依赖 → CMake 配置 → 编译 → 验证」这条线捋清楚，基本半小时内就能跑起来。

核心原则：不管哪个平台，都走 CMake 构建路线。llama.cpp 官方已经放弃直接 Makefile 的维护，所有新特性、GPU 加速、量化库绑定都优先在 CMake 里支持。

2.1 前置依赖

先别急着敲命令，把工具链准备好。我个人习惯在开始前统一检查一遍，免得编译到一半报错还要回头装东西。

平台 编译器 CMake 版本 额外工具
Linux GCC ≥ 10 或 Clang ≥ 12 ≥ 3.20 make / ninja, git
macOS Apple Clang (Xcode 14+) ≥ 3.20 Xcode Command Line Tools
Windows MSVC 2022 或 MinGW-w64 (GCC 12+) ≥ 3.22 Git for Windows, PowerShell
避坑小经验：如果你用 Ubuntu 20.04，默认 GCC 是 9.x，编译时会报一些 C++17 特性不支持。我曾经在这上面浪费过一下午，后来升级到 GCC-10 就顺畅了。macOS 用户记得先跑 xcode-select --install，不然连 clang 都找不到。

2.2 获取源码

源码直接从 GitHub 拉，没什么花头。我建议用 --depth 1 浅克隆，省时间省磁盘，毕竟我们目前只需要编译，不需要看完整历史。

git clone --depth 1 https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

如果你网络不好，也可以去 Releases 页面下载源码压缩包。但后续更新时还得手动下，不如 Git 方便。

2.3 Linux 编译——最省心的平台

Linux 下编译基本是「一条龙」体验。我个人最常用的是这种基础配置：

mkdir build && cd build
cmake ..
make -j$(nproc)

完事。编译完成后，./bin/main 就是推理入口。如果你想用 BLAS 加速 CPU 推理（说白了就是把矩阵乘法交给优化库），可以这样：

cmake .. -DLLAMA_BLAS=ON -DLLAMA_BLAS_VENDOR=OpenBLAS
make -j$(nproc)

为什么推荐 OpenBLAS？因为它 apt 就能装，不需要折腾。我有个项目在至强服务器上测过，开启 BLAS 后推理速度提升了大约 40%，还是挺香的。

注意：如果你装了 Intel oneAPI 或者 AMD ROCm，也可以设置 -DLLAMA_BLAS_VENDOR=MKL 或 -DLLAMA_HIPBLAS=ON。但初次搭建建议先用 OpenBLAS 跑通，后续再折腾更高级的加速。

2.4 macOS 编译——为 Apple Silicon 量身定制

macOS 用户最关心的肯定是 Metal 加速。苹果的 M 系列芯片用统一内存，llama.cpp 对 Metal 的支持已经非常成熟了。我第一版在 M1 Max 上跑 7B 模型，开启 Metal 后首 token 延迟直接压到 80ms 左右，当时还是很惊喜的。

mkdir build && cd build
cmake .. -DLLAMA_METAL=ON
make -j$(sysctl -n hw.logicalcpu)

这里注意两点：

  • 一定要安装 Xcode Command Line Tools，否则找不到 Metal 框架。
  • -j 后面的核数可以用 sysctl -n hw.logicalcpu 动态获取，别写死。

如果你用的是 Intel Mac，Metal 也能用，但效果不如 Apple Silicon 明显。这时候我更推荐直接用 CPU 模式，或者试试 Vulkan 后端（需要自己编译 MoltenVK，稍微麻烦些）。

2.5 Windows 编译——两种路径，任你选择

Windows 稍微复杂点，但有两条成熟的路子。我两种都试过，给你对比一下：

方式 工具链 优点 缺点
MSVC + CMake Visual Studio 2022 官方支持最完整，CUDA 绑定方便 安装包大，首次配置稍慢
MinGW-w64 + CMake GCC 13 / Clang 16 轻量，与 Linux 命令习惯一致 部分 GPU 后端需要额外 patch

MSVC 路径（推荐新手）

打开「Developer PowerShell for VS 2022」，然后：

mkdir build; cd build
cmake .. -DLLAMA_BUILD_TESTS=OFF
cmake --build . --config Release

注意这里用了 cmake --build 而不是 make，因为 Windows 下默认生成的是 Visual Studio 解决方案。你加 --config Release 确保编译优化版本，否则默认 Debug 跑起来慢不少。

MinGW 路径（适合 Linux 老手）

用 MSYS2 或者直接装 Git Bash 自带的 MinGW-w64：

mkdir build && cd build
cmake .. -G "MinGW Makefiles" -DLLAMA_BUILD_TESTS=OFF
mingw32-make -j$(nproc)

个人习惯：如果只做 CPU 推理，我更喜欢 MinGW，因为命令行操作和 Linux 完全一致，脚本可以复用。但如果要用 CUDA 或者 cuBLAS，乖乖走 MSVC，兼容性最好。

Windows 特别提醒：路径不要带中文或空格！我曾经把项目放在 D:\项目\llama.cpp 下，CMake 配置阶段各种诡异报错，最后发现是中文路径惹的祸。llama.cpp 的构建脚本对 Unicode 路径支持不够好，尽量用纯英文路径。

2.6 编译选项详解——按需定制

llama.cpp 的 CMake 选项大概有二十多个，但真正常用的就这几个。我整理了一张表，你可以对照自己的硬件来选择：

选项 作用 适用场景
-DLLAMA_METAL=ON 启用 Apple Metal GPU 加速 macOS (尤其 Apple Silicon)
-DLLAMA_CUBLAS=ON 启用 NVIDIA CUDA + cuBLAS Windows/Linux 有 N 卡的用户
-DLLAMA_CLBLAST=ON 启用 OpenCL 通用 GPU 加速 AMD / Intel 显卡或移动 GPU
-DLLAMA_BLAS=ON 启用 BLAS 库加速 CPU 推理 所有 CPU，尤其服务器场景
-DLLAMA_AVX2=ON/OFF 手动控制 AVX2 指令集 老旧 CPU 需要关闭
-DCMAKE_BUILD_TYPE=Release 编译优化版本 默认就是 Release，Debug 仅供调试

嗯，这里有个小坑你要注意：-DLLAMA_CUBLAS=ON 在 Windows 上必须搭配 MSVC，MinGW 目前支持不完整。我之前用 MinGW 试过，链接阶段报一堆符号错误，换成 MSVC 一次过。

2.7 验证安装——“hello world”阶段

编译完别急着跑大模型。先确认可执行文件是好的：

# Linux / macOS
./bin/main --help

# Windows (MSVC)
.\bin\Release\main.exe --help

如果能正常打印帮助信息，说明环境搭建成功了。这时候你可以找一个很小的 GGUF 模型来跑跑看（比如 TinyLlama 的 1.1B 版本），确认推理流程没问题。

快速验证命令：
./bin/main -m ../models/tinyllama-1.1b.Q4_K_M.gguf -p "Hello, world" -n 32
这条命令会加载模型，基于 "Hello, world" 续写 32 个 token。如果能看到输出，恭喜你，llama.cpp 已经跑起来了。

2.8 全平台编译流程总览

为了让你对整个过程有个整体观感，我把各平台的共同路径整理成了一张流程图。核心逻辑完全一样，只是工具链和加速选项有差异。

llama.cpp 跨平台编译安装流程 获取源码 git clone 安装依赖 编译器 + CMake CMake 配置 按需开启加速选项 编译 make / cmake --build 验证 --help 测试 各平台关键差异 🐧 Linux GCC/Clang + make -j$(nproc) 🍎 macOS Xcode CLT + -DLLAMA_METAL=ON 🪟 Windows MSVC / MinGW + cmake --build 编译产物都在 build/bin/ 目录下，跨平台一致

这张图把整个流程串起来了。你看，不管用什么平台，前两步完全一样，只在 CMake 配置环节根据硬件选择不同的加速选项。这就是 llama.cpp 的设计哲学——核心统一，硬件适配留给编译开关。

2.9 常见编译问题速查

最后，我把之前带新人时最常遇到的几个问题列出来，你如果遇到类似现象可以对照着解决：

  • "找不到 " 或 "未定义的引用"：通常是子模块没拉全。试试 git submodule update --init --recursive。
  • "CMake Error: No CUDA toolset found"：装了 CUDA 但没装 VS 的 CUDA 扩展。Windows 下必须用 -DLLAMA_CUBLAS=ON 配合 MSVC。
  • "线程报错 / 段错误"：大部分是编译时用了 -DLLAMA_AVX2=ON 但 CPU 不支持。保守做法是关掉它，或者用 -DLLAMA_AVX=ON 降级。
  • "Metal 编译报错"：macOS 用户检查 Xcode 版本，至少 14.3 以上。我曾用 13.x 编译，Metal 后端死活过不了。
我的调试习惯：第一次编译尽量不加任何 -D 选项，用纯 CPU 模式跑通。确认环境没问题后再开 BLAS 或 GPU 加速。这样万一出问题，你能快速定位是硬件加速的锅，还是环境本身的问题。

好了，到这一步，你的 llama.cpp 应该已经能编译通过了。接下来就可以真正开始玩模型了。记住：环境搭建只是手段，不是目的。跑通之后多试试不同的编译选项组合，找到最适合你硬件的那一套。

← 上一章 📖 返回目录 下一章 →