📚 课程目录第3章编译与安装

编译与安装：Linux/macOS/Windows 下源码编译、预编译包使用、CMake 选项详解

编译安装 llama.cpp，说难不难，说简单也真有不少坑。我前后在三个平台都折腾过一遍，踩过的雷比写过的代码还多。今天把经验和教训一并倒出来，希望能帮你少走弯路。

  核心要点：编译安装的最终目标只有一个——让 llama.cpp 在你的硬件上跑出最佳性能。不同的操作系统、不同的硬件，编译选项天差地别。

一、Linux 下的编译：最省心也最容易踩坑

Linux 是 llama.cpp 的"亲爹"平台，编译最顺畅。但我见过很多人一上来就用默认配置，结果 CPU 推理慢得令人发指。

1.1 基础编译

先拉代码，这是最基本的操作：

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
mkdir build && cd build
cmake ..
make -j$(nproc)

简单吧？但问题来了——这样编译出来的是纯 CPU 版本。你想想看，如果你的机器有 NVIDIA 显卡，这简直是暴殄天物。

个人经验：我习惯先用 lscpu 和 nvidia-smi 确认硬件信息，再决定编译选项。别一上来就跑默认，回头还得重新编译。

1.2 开启 CUDA 加速

有 NVIDIA 显卡的，必须把 CUDA 带上：

cmake .. -DGGML_CUDA=ON -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

这里有个坑——CUDA 版本要匹配。我曾经在一个项目里，系统自带的 CUDA 11.7 和 llama.cpp 要求的 11.8 差了 0.1，编译通过但跑起来直接崩。后来老老实实装了 CUDA 12.1 才搞定。

1.3 启用 BLAS 优化

如果不用 GPU，那至少把 BLAS 打开：

cmake .. -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS

我个人推荐 OpenBLAS，安装简单，性能稳定。记得先 sudo apt install libopenblas-dev 装上库文件。

注意：不要同时开启 CUDA 和 BLAS。官方明确说过，两者冲突，推理结果会出错。我亲眼看到同事两个都开了，跑出来的回答驴唇不对马嘴。

二、macOS 编译：M 系列芯片的专属优化

macOS 这边，Apple Silicon 是主角。Intel Mac 用户就别折腾了，老老实实用 CPU 模式吧。

2.1 安装依赖

先装 Xcode Command Line Tools：

xcode-select --install

然后用 Homebrew 装 CMake：

brew install cmake

2.2 开启 Metal 加速

cmake .. -DGGML_METAL=ON -DCMAKE_BUILD_TYPE=Release
make -j$(sysctl -n hw.logicalcpu)

嗯，这里要注意。Metal 只支持 M1/M2/M3/M4 系列芯片。Intel 的 Mac 开了 Metal 也没用，反而会拖慢速度。我测试过，M2 Max 上开启 Metal 后，推理速度提升了 5 倍以上，差距非常明显。

小技巧：编译完成后，试试 ./bin/main --help 看看有没有 "ggml_metal_init: using Metal" 的日志输出，有就说明 Metal 生效了。

2.3 关于预编译包

macOS 用户可以去 GitHub Releases 页面下载 llama.cpp-macos-xxx.zip。但我建议还是自己编译——Apple 每次系统更新都会调整 Metal 性能，自己编译能吃到最新优化。

三、Windows 编译：最折腾但也最全面

Windows 是三个平台里最麻烦的。我自己前前后后重装了 3 次环境才搞明白。

3.1 环境准备

需要装好这些东西：

Visual Studio 2022（社区版免费，装的时候选"使用 C++ 的桌面开发"）
CUDA Toolkit（如果要用 NVIDIA 显卡）
CMake（从官网下载安装，记得勾选"Add to PATH"）
Git

3.2 编译命令

打开"Developer Command Prompt for VS 2022"：

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
mkdir build && cd build
cmake .. -G "Visual Studio 17 2022" -A x64 -DGGML_CUDA=ON
cmake --build . --config Release

为什么要指定 Generator？因为 Windows 下默认用的是 MSBuild，不指定的话 CMake 会选 Ninja，但 Ninja 在 Windows 上经常找不到 Visual Studio 工具链。我吃过这个亏，编译报错一堆，排查了半天才发现是 Generator 的问题。

避坑指南：Windows 下路径不要有中文和空格！我之前把项目放在 "D:/我的项目/llama.cpp" 下，编译到一半报错：找不到文件路径。改成纯英文路径后一次过。

3.3 使用预编译包

如果实在不想折腾，去 GitHub Releases 页面下载 llama.cpp-windows-xxx.zip。解压后直接运行 main.exe 就行。

但有个限制——预编译包只支持 CUDA 12.x。如果你用的是 CUDA 11.x 或者 10.x，不好意思，只能自己编译。

四、CMake 选项详解

这是我最想展开讲的部分。很多人觉得 CMake 选项就是抄几个参数，其实每个选项背后都有性能逻辑。

选项	说明	推荐场景
`-DGGML_CUDA=ON`	开启 NVIDIA GPU 加速	有 NVIDIA 显卡，且显存 ≥ 4GB
`-DGGML_METAL=ON`	开启 Apple Silicon GPU 加速	M1/M2/M3/M4 Mac
`-DGGML_BLAS=ON`	开启 CPU BLAS 加速	无 GPU，但有高性能 CPU
`-DCMAKE_BUILD_TYPE=Release`	编译优化（必须加）	所有场景（不加的话性能直接打对折）
`-DLLAMA_CUDA_F16=ON`	允许 GPU 使用 FP16 计算	CUDA 计算能力 ≥ 7.0（RTX 20 系列及以上）
`-DLLAMA_AVX2=ON`	启用 AVX2 指令集	Intel Haswell 及以上，AMD Zen 及以上
`-DLLAMA_AVX512=ON`	启用 AVX-512 指令集	Intel Skylake-X 及以上（AMD 暂不支持）

个人建议：如果你是首次编译，先把 CMAKE_BUILD_TYPE=Release 和对应平台的 GPU 选项打开就够了。别的锦上添花的选项，后面慢慢加。我一开始想一步到位全打开，结果编译了 40 分钟，还报了两个链接错误。

五、避坑总结

最后列几个我亲身踩过的大坑，希望能帮你躲过去：

不要混用 CUDA 和 BLAS——两者会打架，推理结果不可靠。
Windows 下路径别有中文——CMake 对中文路径的支持一塌糊涂。
macOS 一定要开 Metal——不开的话，M 芯片的算力浪费了 80%。
Release 模式是必须的——Debug 模式的速度，我测试过慢 3 倍以上。
预编译包不是万能的——它只适合快速体验。想做生产环境，自己编译更靠谱。