2023 年 3 月，Georgi Gerganov 用一个周末把 Meta 泄出的 LLaMA 权重跑在了 MacBook 上——没有 Python、没有 CUDA、没有任何依赖，一个 C++ 文件起步。三年后，这个「周末项目」成了地球上部署最广的推理引擎：每一台跑 Ollama、LM Studio 的电脑里都住着它。

1.1零依赖哲学：为什么是 C/C++

llama.cpp 的一切怪癖都源自一条纲领：在任何机器上、不装任何东西、跑起来。由此推出全部技术决策：

• 纯 C/C++ 实现：没有 Python 运行时、没有框架依赖——编译产物是一个几 MB 的二进制，从树莓派到 H100 通吃。底座是同作者的 ggml 张量库（也驱动着 whisper.cpp）。
• 量化是一等公民：端侧显存/内存金贵，4-bit 起步是常态而非选项——于是量化格式的工程深度独步业界（第 3 章）。
• CPU 是正经后端：其他引擎把 CPU 当摆设，llama.cpp 的 CPU 路径用 SIMD 手工优化到极限——没有 GPU 也能有可用的速度，这是「任何机器」承诺的底气。
• mmap 加载：GGUF 文件按内存布局设计，内存映射直接用，秒级启动、多进程共享一份权重——与服务端引擎「分钟级加载」形成鲜明对照。

深入：一段值得知道的历史——从 llama.cpp 到本地 AI 运动

时间线：2022 年 9 月 ggerganov 写 whisper.cpp（端侧跑 Whisper）验证了 ggml 路线；2023 年 3 月 LLaMA 权重流出后一个周末产出 llama.cpp；随后社区爆炸——GGML 格式（GGUF 前身）、K-quants（2023 年 6 月的传奇 PR）、Metal/CUDA 后端接连落地；2023 年 8 月 GGUF 格式定稿（自描述、可扩展、mmap 友好），成为本地模型的事实标准；Ollama（2023）与 LM Studio 把它包装成消费级产品。这段历史的启示：「跑在自己机器上」的需求被所有大厂低估了——隐私、离线、零成本、可折腾，四个动机撑起了一个与云端平行的生态。ggerganov 后来成立 ggml.org 公司维持全职开发，但项目治理仍是社区式的。

1.2生态全景：都是 llama.cpp 的壳

1.3端侧 vs 服务端：边界在哪

技术含义值得展开：端侧 batch≈1 意味着推理永远处于 memory-bound 区（vLLM §1.4 roofline 的最左端）——所以 llama.cpp 的优化重心不在调度与 batching，而在把每字节权重变小（量化）、把每次访存变快（SIMD/后端）。理解了这一点，两个世界的技术分野就完全清晰了：同一张 roofline，两端各有各的活法。

这一章全程可以在你的 Mac 上实操——Apple Silicon 的统一内存 + Metal 后端正是 llama.cpp 的主场之一。目标：跑通两个入口、下载一个 GGUF、读懂加载日志。

2.1获取与构建：三条路

# 路线 A：包管理器（最快）
brew install llama.cpp

# 路线 B：源码构建（推荐，理解构建矩阵）—— Mac 上 Metal 后端默认开启
git clone https://github.com/ggml-org/llama.cpp && cd llama.cpp
cmake -B build && cmake --build build --config Release -j

# 其他平台的后端开关：-DGGML_CUDA=ON（N 卡）/ -DGGML_VULKAN=ON（通用 GPU）
# 什么都不开 = 纯 CPU（SIMD 自动检测 AVX/NEON）

构建矩阵即第 4 章的后端矩阵：Metal（Apple）、CUDA（NVIDIA）、Vulkan（跨厂商 GPU）、CPU（兜底，永远可用）。同一份代码、同一个 GGUF，四个后端随构建切换——「任何机器」承诺的工程形态。

2.2llama-cli 与 llama-server

# 从 HuggingFace 直接拉 GGUF 并进入交互对话（-hf 自动下载缓存）
llama-cli -hf ggml-org/Qwen2.5-7B-Instruct-Q4_K_M-GGUF

# OpenAI 兼容 server + 自带 WebUI（浏览器开 http://localhost:8080）
llama-server -hf ggml-org/Qwen2.5-7B-Instruct-Q4_K_M-GGUF \
  -c 8192 -ngl 99 --port 8080

加载日志是第一堂课，逐行能看到：GGUF 元数据（架构/词表/量化类型逐层列出）、mmap 加载、各后端的显存/内存分配、KV cache 尺寸。与 vLLM 启动日志对照读（§2.2），你会发现同一套账、不同的规模观：这边算的是「几 GB 内存装不装得下」，那边算的是「几万 token 的 KV 池」。llama-server 的 WebUI 近年已长成完整产品（多会话、多模态、甚至 MCP 工具调用），学习期直接用它做实验台。

2.3关键参数与 Ollama 捷径

Ollama 捷径：ollama run qwen2.5:7b 一行搞定下载与运行——它内部就是 llama.cpp + 模型仓库 + 进程管理（5.3 节拆开看）。学习建议：日常用 Ollama 图省事，学习用 llama.cpp 见机制——前者是后者的封装，两者的知识完全互通。

GPTQ/AWQ 的量化数学在 vLLM 指南 §4.2；llama.cpp 的量化是另一个门派：不依赖校准数据的直接舍入 + 极致的位打包工程 + 一套自成体系的命名法。理解它，HuggingFace 上满屏的 Q4_K_M.gguf 就从乱码变成菜单。

3.1GGUF 文件解剖

3.2块量化机制：打包动画

llama.cpp 的量化不需要校准数据集——它对每小块权重独立做「找缩放、舍入、打包」。先看动画再读解释：

这套机制的取舍一目了然：优点——无需校准、任何模型即到即量、解码只是一次乘法（SIMD 友好）；弱点——块内如果有一个 outlier，scale 被它撑大，其余权重的精度全被牺牲。动物园里的演化史就是围绕这个弱点展开的。

3.3动物园导览：Q4_K_M 们的命名法

3.4imatrix 与验收

importance matrix（imatrix）是 llama.cpp 向「校准派」的一次靠拢：先用代表性文本跑一遍模型，统计各权重的激活加权重要性，量化时对重要权重优先保精度——思想与 AWQ 的「保护显著通道」同源（vLLM §4.2），实现却嫁接在块量化体系上。低位宽（Q3 以下与全部 i-quants）收益显著，HuggingFace 上的高质量 GGUF 几乎都标注「with imatrix」。

# 亲手量化三部曲（本机可完成）
python convert_hf_to_gguf.py ./Qwen2.5-1.5B --outfile q.f16.gguf   # HF → GGUF(F16)
llama-imatrix -m q.f16.gguf -f calib.txt -o q.imatrix              # 可选：算 imatrix
llama-quantize --imatrix q.imatrix q.f16.gguf q.Q4_K_M.gguf Q4_K_M # 量化
llama-perplexity -m q.Q4_K_M.gguf -f wiki.test.raw                 # 困惑度验收

验收纪律与服务端一致：困惑度只是烟雾测试，拿你的真实任务样本对比 F16 与量化版的输出才是硬验收——尤其低位宽档的格式遵循与长输出稳定性（§4.2.3 的告诫原样适用）。

llama.cpp 的执行核心是 ggml 的静态计算图：每次前向构一张图，交给后端执行。没有 Python、没有动态分发——这个「笨」设计恰恰是它跑遍所有硬件的原因。

4.1ggml 计算图与后端抽象

• 图构建：llama_decode() 每步把整个前向（embedding → N 层 → logits）构成一张 ggml 图——节点是算子、边是张量，全部静态、无控制流。
• 后端调度：ggml 的 backend 抽象把图切分给设备——Metal/CUDA/Vulkan 各自实现算子集，CPU 永远兜底；一张图可以跨后端分段执行（这正是 -ngl 混合执行的机制基础）。
• 与服务端引擎的对照：vLLM 靠 torch.compile 生成 kernel、CUDA Graph 消 launch 开销（§4.4）；ggml 的算子是手写的、图是每步重建的——在 batch=1 的端侧，图构建的微秒级开销无关痛痒，手写算子的确定性反而是跨平台的保障。规模不同，最优解不同。

4.2CPU 的尊严：SIMD 与线程

llama.cpp 的 CPU 路径不是摆设：矩阵乘配合量化解码全部用 SIMD 指令手工向量化（x86 的 AVX2/AVX-512、ARM 的 NEON/SVE），4-bit 码字的解包与乘加融合在一个内循环里——这正是 3.2 节「解码只是一次乘法」的兑现现场。线程侧按行分块并行，-t 取物理核数最佳；内存带宽通常先于算力饱和（端侧 roofline 的常态），所以加线程的收益很快见顶——你在第 2 章实验里已经见过这条曲线。

4.3层级 offload：-ngl 动画

端侧最常见的现实：模型比显存大、比内存小。llama.cpp 的答案是按层切分——前 N 层放 GPU、其余留 CPU，每个 token 的前向在边界处交接一次激活：

调优要领：① 显存装得下就 -ngl 99 全放，混合执行永远是妥协；② 装不下时，offload 的每一层都是纯赚（那层的权重访存走了 GPU 带宽）；③ Mac 统一内存没有「搬运」问题，Metal 后端默认全 GPU——这正是 Apple Silicon 成为端侧宠儿的架构原因（对照 vLLM §1.3 的分立显存模型）。

4.4KV cache、slot 并发与服务端概念的回响

• KV cache：统一大缓冲 + 按 cell 记账（无分页——单机少并发用不上页表复杂度）；context shift 在上下文写满时丢弃最旧 token 的 KV 并平移，长对话不重算——服务端引擎反而少有这招（它们直接抢占重算）。
• server 的 slot 并发：-np N 开 N 个并发槽位，上下文切片分配；请求间做 continuous batching（vLLM §3.3 的端侧微缩版）与公共前缀 KV 复用——概念全是老朋友，规模小了两个数量级。
• 投机解码：支持 draft 模型（如 0.5B 给 7B 起草）——端侧 batch=1 恰是投机的最佳工况（§4.1 的结论：低并发收益最大）；
• GBNF 语法约束：结构化输出的鼻祖实现——用 BNF 语法逐 token mask 非法选项，思想直通 vLLM 的 xgrammar 与 SGLang 的压缩 FSM（§2.3.2）；写一个 JSON 语法文件试试，你会对「语法约束解码」有最直观的理解。

llama-server 这几年从演示工具长成了功能完整的本地服务：并发、路由、多模态、嵌入、工具调用一应俱全。本章盘点这套武器库、划清它的能力边界，最后拆开 Ollama 看看壳与核的关系。

5.1server 的完整武器库

一个值得体会的格局：这张表几乎是 vLLM 功能面的「单机镜像」——两个世界在功能上趋同，在规模假设上分道。学完四个指南再看这张表，每一行你都能说出背后的机制与出处。

5.2何时不该用 llama.cpp

5.3Ollama 内幕、源码与贡献

• Ollama = llama.cpp + 模型管理 + 常驻服务：Go 写的外壳负责模型仓库（ollama pull 的 registry）、Modelfile（模板/参数打包格式）、进程守护与 API；推理引擎就是内嵌的 llama.cpp/ggml。理解此关系后：Ollama 的性能问题去 llama.cpp 找答案，模型管理体验才是它自己的增值。
• 源码地图：ggml/（张量库与各后端）、src/llama.cpp 本体（模型加载/图构建/KV 管理）、tools/（cli/server/quantize/perplexity 等工具）、gguf-py/（转换脚本）。C++ 但结构直白，从 tools/main（llama-cli 主循环）读起是社区公认的入门路径——一个文件看完 tokenize → 图执行 → 采样全流程。
• 贡献文化：PR 驱动、CI 覆盖全平台矩阵；新量化类型、新后端、新模型架构是三大贡献热区。项目由 ggml.org 维持全职开发，治理仍是开放社区式——与 vLLM/SGLang 的基金会/实验室模式、TRT-LLM 的厂商模式构成三种开源形态的完整样本。

文档与源码

与其他指南共用的基础

推理物理、量化算法谱系、continuous batching、投机原理——见 vLLM 指南。学习闭环建议：本指南学完后重读 vLLM §1.4（roofline）——从端侧回望，「batch 是唯一杠杆」这句话会有全新的重量。

术语表

正文里带虚线下划线的词可悬停查看解释；此处为本指南新增术语。