第 2 章 环境搭建：编译 llama.cpp 与安装 Python 绑定库
说实话，我第一次搞 llama.cpp 编译的时候，也以为直接 pip install 就完事了。结果跑起来慢得离谱，还老崩。后来才发现，自己编译是绕不开的坎。这一章我就带你走一遍流程，把三个主流平台都讲透。
我会尽量把坑都指出来。你跟着走，基本不会出问题。
2.1 为什么非要自己编译？
官方虽然提供了一些预编译包，但有几个硬伤：
- 没有针对你 CPU 的指令集优化（比如 AVX2、AVX512）
- CUDA / Metal / Vulkan 支持要手动开
- 有些新特性（比如 Q4_K_M 量化）预编译版可能落后
自己编译，说白了就是让 llama.cpp 跑在你的硬件上，而不是跑在通用模板上。性能差距可以到 2-3 倍，值得花这十几分钟。
2.2 编译前的准备工作
不同平台依赖不一样。我整理了一张表，你对着准备就行。
| 平台 | 必需工具 | 可选（加速） |
|---|---|---|
| Linux | gcc / clang, cmake, make, git | CUDA Toolkit (NVIDIA), ROCm (AMD) |
| macOS | Xcode Command Line Tools, cmake | Metal (M1/M2/M3 自动启用) |
| Windows | Visual Studio 2022 Build Tools, cmake, git | CUDA Toolkit, OpenCL SDK |
我的小习惯：Linux 上我固定用 clang 编译，比 gcc 快 5-10%。macOS 什么也不用配，Xcode 装好就行。Windows 记得把 cmake 加到 PATH 里，不然会报“找不到命令”。
2.3 编译 llama.cpp
2.3.1 Linux / macOS
过程几乎一样，我就放一块儿说了。
# 克隆仓库
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
# 创建构建目录
mkdir build && cd build
# 配置（纯 CPU 版）
cmake .. -DCMAKE_BUILD_TYPE=Release
# 如果你有 NVIDIA 显卡，加 CUDA 支持
cmake .. -DCMAKE_BUILD_TYPE=Release -DLLAMA_CUBLAS=ON
# 如果是 macOS M 系列，Metal 自动检测，也可以显式指定
cmake .. -DCMAKE_BUILD_TYPE=Release -DLLAMA_METAL=ON
# 编译
cmake --build . --config Release -j$(nproc) # Linux
cmake --build . --config Release -j$(sysctl -n hw.logicalcpu) # macOS-j 后面的参数是并行编译线程数。我一般设成 CPU 核心数，编译会快很多。
2.3.2 Windows
Windows 稍微麻烦点，我建议用 VS 2022 开发者命令提示符（或者在 PowerShell 里加载环境变量）。
# 打开 "x64 Native Tools Command Prompt for VS 2022"
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
mkdir build
cd build
# 纯 CPU
cmake .. -DCMAKE_BUILD_TYPE=Release -G "Ninja"
# 带 CUDA
cmake .. -DCMAKE_BUILD_TYPE=Release -DLLAMA_CUBLAS=ON -G "Ninja"
# 编译
cmake --build . --config Release注意：不要用默认的 “Visual Studio 17 2022” 生成器，Ninja 更稳定。另外 Windows 路径不要有中文和空格，否则 cmake 解析会出错。我曾经被这个坑了半小时，后来全改成英文目录才过。
编译完成后，build/bin/Release/ 下会生成 main.exe、server.exe 等可执行文件。Linux/macOS 则在 build/bin/ 下。
2.4 安装 Python 绑定库
llama.cpp 最方便的 Python 接口是 llama-cpp-python。但如果你直接 pip install，它下载的是预编译包，跟你刚编译的 C++ 版本不对应。所以我们要用 本地编译版。
# 回到 llama.cpp 根目录
cd ..
# 安装 Python 绑定（会自动用刚才编译好的库）
pip install . --config-settings=cmake.args="-DLLAMA_CUBLAS=ON" # 带 CUDA
# 或者纯 CPU
pip install . --config-settings=cmake.args="-DCMAKE_BUILD_TYPE=Release"
# macOS M 系列
CMAKE_ARGS="-DLLAMA_METAL=ON" pip install .如果你不想重新编译，也可以直接 pip install llama-cpp-python 然后用环境变量指向已有的动态库。但那样容易版本不匹配。我个人更推荐 源码安装，一劳永逸。
2.5 验证安装是否成功
写个简单脚本来确认一切正常。
from llama_cpp import Llama
# 加载一个 tiny 模型测试（没有模型的话，先随便找个 gguf 文件）
llm = Llama(model_path="./models/some-model.gguf", n_gpu_layers=-1) # -1 表示全部 GPU 层
output = llm("Hello, world!", max_tokens=20)
print(output["choices"][0]["text"])
如果不报错，且能正常输出文字，那就说明环境搭好了。如果报 RuntimeError: model file not found，那是你没放模型，不是环境问题。如果报 ImportError，请检查 Python 绑定是否安装成功。
2.6 常见问题与避坑
我曾遇到过的问题，你很可能也会遇到：
- 编译时找不到 CUDA：检查
nvcc --version，确保 CUDA Toolkit 安装了且PATH里包含nvcc。Linux 上还要装cuda-driver。 - 编译极慢：去掉
-j高并发，或者减少线程数。内存小于 8GB 时，-j4就够了，否则 swap 狂写反而更慢。 - Windows 上 Ninja 报错找不到：在 VS 命令提示符里输入
where ninja，如果没有，用choco install ninja或者去 GitHub 下载。 - Python 绑定装完还是旧版本：先卸载
pip uninstall llama-cpp-python，然后重新用pip install .安装。 - macOS 上 Metal 编译成功但运行时崩溃：检查 Xcode 版本，至少 14.3 以上。如果还崩，试试
-DLLAMA_METAL=OFF先跑 CPU 版。
一个实用技巧：编译完成后，把 build/bin 加到系统 PATH 里，这样以后在任意目录都能直接用 main、server 命令。
环境搭建搞定，你就可以愉快地开始玩 llama.cpp 了。后面的章节咱们会用它来跑推理、调参、甚至自己写 API 服务。