2. 环境准备
先聊聊我的第一步
说实话，我第一次搞多模态扩展时，光环境就折腾了两天。后来发现，只要理清几个关键点，半小时就能搞定。说白了，这节课就是帮你省掉那些我踩过的坑。
准备工作很简单：一台 Linux 或 macOS 机器（Windows 也能用 WSL），基础编译工具链，以及 Python 3.8+。嗯，这里有个前提——你得有至少 8GB 内存，否则编译时链接阶段容易 OOM。
依赖准备：别漏了这仨
我习惯先用包管理器装好 gcc、cmake 和 git。如果你用 Ubuntu，一行命令就行：
sudo apt update
sudo apt install build-essential cmake git python3 python3-pipmacOS 用户记得先安装 Xcode Command Line Tools：
xcode-select --install
# 然后用 Homebrew 装 cmake
brew install cmake编译 Llama.cpp：标准版 vs 多模态版
Llama.cpp 的编译默认只支持纯文本模型。要玩多模态，你得打开几个开关。我建议你一次编译到位，免得后面重复劳动。
先克隆仓库：
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp标准编译很简单：
cmake -B build
cmake --build build --config Release -j$(nproc)但要支持多模态（比如 Llava、MiniCPM-V 等），必须加上 -DLLAMA_MULTIMODAL=ON。我遇到过很多人漏了这个，结果模型加载时就报“unknown architecture”。
完整的多模态编译命令：
cmake -B build \
-DLLAMA_MULTIMODAL=ON \
-DGGML_CUDA=ON \ # 如果你有 NVIDIA 显卡
-DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j$(nproc)-DGGML_NATIVE=OFF 能减少一些优化步骤。我早期在 4GB 的笔记本上试过，改用 make -j2 才稳住。LLAMA_MULTIMODAL）在较老版本的 llama.cpp 里叫 LLAMA_MULTIMODAL_SUPPORT。如果 cmake 报错，先查一下你那个版本的 cmake 选项：cmake -LH 2>/dev/null | grep -i multimodal。配置 Python 绑定
Python 绑定我们用的是 llama-cpp-python。直接 pip install 默认只编译 CPU 版本，而且不带多模态支持。需要手动指定 cmake 参数。
我建议这样装：
CMAKE_ARGS="-DLLAMA_MULTIMODAL=ON -DGGML_CUDA=ON" pip install llama-cpp-python --force-reinstall --no-cache-dir如果你不用 GPU，把 DGGML_CUDA=ON 去掉即可。装完验证一下：
python -c "import llama_cpp; print(llama_cpp.__version__)"没报错就说明绑定装好了。但多模态支持能不能用，还得看编译时有没有真的开启。可以这样检查：
python -c "from llama_cpp.llama_cpp import LLAMA_API_LEVEL; print('Multimodal supported' if LLAMA_API_LEVEL >= 4 else 'Not supported')"如果输出“Multimodal supported”，恭喜你，基础环境跑通了。否则回去检查 cmake 命令。
不同平台的编译差异
我整理了一张表，方便你对照自己环境做调整。说实话，macOS 和 Linux 差别不大，Windows 用户建议用 WSL。
| 平台 | GPU 加速选项 | 常见问题 |
|---|---|---|
| Linux (NVIDIA) | -DGGML_CUDA=ON |
确保 CUDA Toolkit 11.7+ 已安装，nvcc 在 PATH 里 |
| Linux (AMD ROCm) | -DGGML_HIP=ON |
需要 hipcc 环境，安装 rocm 开发包即可 |
| macOS (Apple Silicon) | -DGGML_METAL=ON |
Xcode 15+ 自带 Metal 支持，编译时记得设 -DLLAMA_MULTIMODAL=ON |
| Windows (WSL2) | 同 Linux 方案 | 推荐用 Ubuntu 22.04 发行版，WSL2 下 CUDA 直通需安装 cuda-toolkit-11-wsl |
整张流程图帮你理清思路
下面这张图展示了我个人习惯的环境准备流程。每个节点都对应一个关键步骤。
验证多模态加载
最后跑一段真正的多模态推理，确保一切就绪。我把测试代码贴在这里，你可以直接复制。
from llama_cpp import Llama
# 路径换成你的多模态模型（比如 llava-v1.6-vicuna-7b.gguf）
llm = Llama(
model_path="./models/llava-v1.6-vicuna-7b.gguf",
n_ctx=2048,
n_gpu_layers=-1, # 全部层放 GPU
chat_format="llava",
verbose=True,
)
# 快速询问
output = llm.create_chat_completion(
messages=[{"role": "user", "content": "Hello, what can you see?"}]
)
print(output["choices"][0]["message"]["content"])如果打印出来有正常回复，恭喜！你的环境已经准备好支撑后续多模态课程了。如果报错，多半是模型文件下载不完整，或者 Python 绑定没开启多模态。回去对照表格和流程图再检查一遍。