环境准备：安装 llama.cpp、编译环境踩坑（Windows/Linux/Mac）、Python 绑定安装

好，咱们正式开始动手了。

这一章，说白了就是搭积木前的准备工作。你想想看，如果地基没打好，后面模型量化、推理加速全是空中楼阁。我见过太多人卡在编译这一步，一卡就是半天，最后心态崩了。

别急，我带你一步步走。我会把 Windows、Linux、Mac 三个平台都讲透，顺便把我踩过的坑也抖出来。

1. 获取 llama.cpp 源码

首先，你得把代码拉下来。这个没什么技术含量，但有个小细节——版本选择。

我个人习惯用 git tag 查看版本号，然后 checkout 到指定版本。比如：

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
git tag -l  # 看看有哪些版本
git checkout bXXXX  # 选一个你信任的版本

为什么要这么做？因为 llama.cpp 迭代太快了，有时候新版本会改掉一些 API 或者量化格式。你如果直接拉最新版，可能跟你的模型不兼容。嗯，这里要注意。

2. 编译环境：三大平台的踩坑实录

编译这一步，是坑最多的地方。我分平台来讲，你根据自己的系统对号入座。

2.1 Linux 环境

Linux 是最省心的，但也不是完全没坑。

你需要装的基础依赖：

• gcc / g++（版本 >= 11）
• cmake（版本 >= 3.22）
• make
• CUDA Toolkit（如果你要用 GPU 加速）

安装命令（Ubuntu/Debian 为例）：

sudo apt update
sudo apt install build-essential cmake
# 如果需要 GPU 支持
sudo apt install nvidia-cuda-toolkit

我踩过的坑： 有一次我忘了装 cmake 的新版本，结果编译到一半报错，说找不到某个模块。查了半天才发现是 cmake 版本太旧。所以，装之前先检查版本：

cmake --version
gcc --version

如果版本不够，建议用 pip 装 cmake：

pip install cmake

然后编译：

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

这里有个小技巧：-j$(nproc) 是让编译用满所有 CPU 核心，速度能快不少。

2.2 Windows 环境

Windows 是重灾区。我建议你直接用 Visual Studio 2022 或者 MSYS2。

方案一：Visual Studio 2022

1. 安装 VS2022，勾选「使用 C++ 的桌面开发」工作负载。
2. 打开「x64 Native Tools Command Prompt」。
3. 进入 llama.cpp 目录，执行：

mkdir build
cd build
cmake .. -G "Visual Studio 17 2022" -A x64
cmake --build . --config Release

方案二：MSYS2（我更喜欢这个）

MSYS2 能给你一个类 Linux 的环境，编译命令跟 Linux 几乎一样。

1. 下载安装 MSYS2。
2. 打开 MSYS2 UCRT64 终端。
3. 安装依赖：

pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-cmake make

1. 然后跟 Linux 一样编译：

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

2.3 Mac 环境

Mac 用户相对幸福，但也要注意芯片类型。

Intel Mac：

brew install cmake
mkdir build && cd build
cmake ..
make -j$(sysctl -n hw.logicalcpu)

Apple Silicon（M1/M2/M3）：

这里有个大坑——你要启用 Metal 加速，否则性能会差很多。

cmake .. -DLLAMA_METAL=ON
make -j$(sysctl -n hw.logicalcpu)

我曾经在 M1 上忘了加 -DLLAMA_METAL=ON，结果推理速度比 CPU 还慢。加了之后，速度直接翻了好几倍。

3. Python 绑定安装

编译完 C++ 部分，我们还需要 Python 绑定。这样你就能在 Python 里直接调用 llama.cpp 了。

安装方式很简单：

pip install llama-cpp-python

但如果你要 GPU 加速，就得指定编译参数：

Linux/Windows 带 CUDA：

CMAKE_ARGS="-DLLAMA_CUBLAS=on" pip install llama-cpp-python

Mac 带 Metal：

CMAKE_ARGS="-DLLAMA_METAL=on" pip install llama-cpp-python

我踩过的坑： 有一次我直接 pip install，没加任何参数。结果装的是 CPU 版本，跑起来慢得让人抓狂。后来卸载重装，加上 CMAKE_ARGS，才恢复正常。

验证安装是否成功：

python -c "from llama_cpp import Llama; print('OK')"

如果没有报错，恭喜你，环境准备好了。

4. 知识体系总览

为了让你对整个流程有个直观印象，我画了一张图：

好了，环境准备就到这里。你按照上面的步骤走，应该不会出大问题。如果卡住了，回头看看我标出来的那些坑——尤其是 Windows 的路径问题和 Mac 的 Metal 参数。

下一章，我们就要开始真正的模型量化了。到时候你会看到，前面这些折腾都是值得的。

---