环境搭建：从零开始准备好你的工具箱

说实话，很多人在跑视觉语言模型时，卡得最久的不是模型本身，而是环境搭建这一步。

我见过太多朋友，明明代码写得不错，结果卡在编译错误上摔跟头。所以这一章，咱们踏踏实实把环境搞定。你想想看，如果连工具都没装对，后面再牛的模型也只能干瞪眼。

核心目标：在本章结束时，你手上应该有一套完整的 Llama.cpp 编译环境，能直接克隆仓库并生成可执行文件。

你需要哪些东西？

其实就四样：C++ 编译器、CMake、Git，外加一个能上网的终端。咱们一个一个来。

工具 最低版本 我踩过的坑
C++ 编译器（GCC/Clang/MSVC） GCC ≥ 11 / Clang ≥ 14 老版本不支持 C++17，编译会报一堆让你看不懂的模板错误。
CMake ≥ 3.22 太老的 CMake 找不到 CUDA，白折腾半天。
Git 任意现代版本 这个倒没啥，就是记得配好 SSH 密钥，不然每次克隆都要输密码。
Python（可选但建议） ≥ 3.9 后面跑转换脚本需要，提前装好省事。

Linux / macOS 环境

我个人习惯用 Ubuntu 22.04，但 macOS 也完全没问题。一条命令装全家桶：

# Ubuntu / Debian
sudo apt update
sudo apt install build-essential cmake git

# macOS（用 Homebrew）
brew install cmake git
xcode-select --install  # 装命令行工具，自带 Clang
如果你用 macOS 且机器是 Apple Silicon（M1/M2/M3），装好 Xcode Command Line Tools 就行，编译器默认是 Apple Clang，性能很好。

Windows 环境

Windows 稍微麻烦点。我建议直接用 MSYS2 或者 Visual Studio 2022 的开发者命令行。

步骤很简单：

  1. 下载并安装 Visual Studio 2022 Community，勾选「使用 C++ 的桌面开发」。
  2. 安装 CMake（官网下载 .msi，一路下一步）。
  3. 安装 Git for Windows，装完记得把 Git Bash 加到 PATH 里。
千万不要手贱去装 VS 2017 或更老版本，Llama.cpp 需要 C++17 特性，老编译器根本过不了编译。
有一次我在项目里图省事用 VS 2019 凑合，结果编译到一半疯狂报错，最后老老实实升级了。

克隆 Llama.cpp 仓库

好，工具齐了，该拿代码了。

打开终端，找一个你喜欢的目录（别放桌面，太乱），然后：

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
如果你在墙内访问 GitHub 慢，可以试试 git clone https://ghproxy.com/https://github.com/ggerganov/llama.cpp.git 但注意，代理有风险，安全第一。

克隆完成后，你应该能看到一堆文件夹。其中 ggml、examples、models 是重点。咱们后面会频繁用到。

编译 Llama.cpp

编译是整个环境搭建的核心。说白了，就是把 C++ 源码变成你电脑能直接运行的二进制文件。

我个人习惯用标准的 CMake 流程：

mkdir build
cd build
cmake ..
make -j$(nproc)   # macOS 用 make -j$(sysctl -n hw.logicalcpu)

-j 后面的数字是并行编译的线程数，设成 CPU 核心数能大幅提速。如果你机器内存小（比如 8GB），建议减半，否则会爆内存。

编译完成后，build/bin 文件夹下会出现一系列可执行文件：
  • main – 纯文本推理入口
  • server – HTTP API 服务
  • quantize – 模型量化工具
  • perplexity – 评估困惑度

验证一下：

./bin/main -h

如果看到一大段帮助信息，恭喜，环境搭好了。

我曾经在 Ubuntu 20.04 上用系统自带的 GCC 9 编译，结果报了个 "filesystem" 头文件找不到的错误。因为 GCC 9 的 <experimental/filesystem> 和 Llama.cpp 用的 <filesystem> 不兼容。解决方案：升级到 GCC 11 或 12，或者装 gcc-11 g++-11 并设置 CC/CXX 环境变量。

还记得我们学的视觉语言模型吗？

这里一样能编译支持多模态推理的版本。在 cmake .. 这一步，可以加参数开启支持：

cmake .. -DLLAMA_CUDA=ON          # 使用 NVIDIA GPU 加速
cmake .. -DLLAMA_METAL=ON         # Apple Silicon 加速
cmake .. -DLLAMA_CLBLAST=ON       # 用 OpenCL 跨平台加速
如果你只是纯 CPU 跑，什么参数都不加就行。但视觉模型通常需要 GPU，否则推理速度会让人抓狂。
我第一次用纯 CPU 跑 LLaVA 1.6 的 7B 模型，生成一张图片描述等了快三分钟……后来换成 CUDA，5 秒出结果。差距就这么大。

环境搭建整体流程

下面这张图，把整个过程串起来了。你可以把它贴在脑子里：

环境搭建全流程 安装编译器 安装 CMake 安装 Git git clone 仓库 cmake .. make -j ./bin/main -h 可选： -DLLAMA_CUDA=ON 等 GPU 加速 ✅ 看到帮助信息 即表示环境成功

嗯，看到帮助信息那一刻，心里会特别踏实。接下来就可以正式下载模型，运行推理了。

如果你在任何一个步骤卡住了，停下来，看看终端报的错误信息里有没有关键词：version、not found、undefined reference。大概率是版本不对或依赖没装全。
我当年查编译错误，硬是练出了一眼看关键行的技能——错误日志最后几行通常是最有用的。

好了，环境搞定。你已经迈过了最枯燥的一道坎。后面的内容会越来越有趣，咱们马上就能真正跑起来一个视觉语言模型了。

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