llama.cpp：编译、工具链与 GGUF 生态

「本系列第 5/17 章」。前四章已经把 GGML 的张量、量化、GGUF 与 Backend 收成最小闭环。从本章起进入 llama.cpp：先把源码编成可复制的二进制，并把 Hugging Face 权重变成引擎能加载的 GGUF。

1. 先认产物

一次完整构建，至少要能指认出五件东西：

产物	路径 / 头文件	职责
libllama	src/ + include/llama.h	模型、context、decode、采样的 C API
libggml	ggml/	张量、计算图、量化、多 Backend
llama-cli	tools/cli/	命令行推理与对话
llama-server	tools/server/	OpenAI 兼容 HTTP
llama-quantize	tools/quantize/	把 F16 GGUF 压成 Q4_K_M 等

工具都链到 libllama，libllama 再链 libggml。调试「编过了却跑不起来」时，先分清是库没编出来、模型文件不对，还是运行时缺 .so。默认动态库构建要把 build/bin 加进 LD_LIBRARY_PATH；虚拟机或跨机拷贝更适合静态链接。

2. 一份可移植的 CMake

目标如果是虚拟机，或要把二进制拷到另一台 x86_64 机器，不要用本机最优指令集：

cmake -B build -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_NATIVE=OFF \
  -DGGML_AVX2=ON \
  -DGGML_CUDA=OFF \
  -DLLAMA_BUILD_UI=ON
cmake --build build --config Release -j$(nproc) \
  --target llama-cli llama-server llama-quantize

记住这几条开关，而不是背一整页 CMake：

• BUILD_SHARED_LIBS=OFF：核心库静态链进可执行文件，复制时少拖一堆 .so
• GGML_NATIVE=OFF：关掉 -march=native，避免在另一台 CPU 上遇到 Illegal instruction
• GGML_AVX2：给通用 x86_64 一个稳妥的 SIMD 下限；更老的机器再退到 GGML_SSE42=ON 并关掉 AVX
• GGML_CUDA：有 NVIDIA GPU 再打开，运行时配合 -ngl 99；本章冒烟可以先关
• LLAMA_BUILD_UI：把 Web UI 嵌进 llama-server

只开 LLAMA_BUILD_UI 不够。前端资源必须先落到 tools/ui/dist（至少要有 index.html）。没有这份目录，服务端仍可能编过，浏览器打开却是空壳。先放好 dist，再编 llama-server。Apple 上 Metal 通常默认打开；Linux 上 Vulkan / SYCL 都是显式 CMake 选项。

3. GGUF 是一条单向流水线

llama.cpp 不直接吃 PyTorch / SafeTensors。标准路径是：

HuggingFace 模型
    → convert_hf_to_gguf.py
    → F16 GGUF
    → llama-imatrix   # IQ / 高质量 K-quant 建议走
    → llama-quantize Q4_K_M

convert_hf_to_gguf.py 负责架构映射、词表和 metadata，先产出 F16 GGUF，作为保真的中间态。conversion/ 里按 LlamaForCausalLM、Qwen2ForCausalLM 等名字注册转换器。漏掉 bos / eos 或把 general.architecture 写错，后面文件能打开，建图会对不上层数或头数。

llama-imatrix 在校准文本上统计激活重要性，得到 imatrix.dat，再交给 llama-quantize。Q4_K_M 是生产默认；IQ 系列强制 imatrix，跳过会明显掉质量。量化发生在 ggml-quants.c 的参考实现里，不走 CUDA mmq。分片模型的两个 .gguf 必须放在同一目录，-m 只指向第一片。

4. 冒烟：先跑通，再谈优化

日常验证不要一上来就上大模型。推荐 Qwen2.5-0.5B-Instruct-GGUF 的 q4_k_m：体积大约四百多 MB，中文可用，内存友好。不要用 llama-cli -hf 在弱网上边下边起服务，网络卡住时几乎没有日志。更稳的做法是 HF_ENDPOINT=https://hf-mirror.com hf download 先把文件落到磁盘。

./build/bin/llama-cli -m qwen2.5-0.5b-instruct-q4_k_m.gguf \
  -co -cnv -p "You are Qwen..." -t 4 -n 64
./build/bin/llama-server -m qwen2.5-0.5b-instruct-q4_k_m.gguf \
  --host 0.0.0.0 --port 8080 -t 4 --parallel 4

llama-cli 证明库和模型都对；llama-server 必须等到日志出现 HTTP server is listening 再打 /health、/v1/models、/v1/chat/completions。吞吐可以用 llama-bench -m ... -t 4 -p 128 -n 64 看 prefill 与 decode。工具箱里还有 llama-tokenize、llama-gguf-split、llama-mtmd-cli，但闭环只要求 cli + server + quantize 三件套。

下一章《llama.cpp：推理原理与 C API》会从「能跑」走到「每次调用在做什么」：自回归、prefill / decode，以及 llama_model 与 llama_context 的分工。