生成日期：2026-05-08
版本语境：以 ggml-org/llama.cpp 官方 master 文档、README、server README、build 文档与 GitHub Releases 当前页面为依据。GitHub Releases 页面在检索时显示 b9071 为 Latest 构建。
说明：llama.cpp 迭代非常快，本文聚焦“当前主线架构与运行路径”，不是逐行源码审计。

---

1. 总结

llama.cpp 是一个以 C/C++ 为核心的本地/边缘/云端 LLM 推理引擎。它的核心价值不只是“跑 LLaMA”，而是提供一套轻量、跨平台、量化优先、硬件后端可插拔的推理栈：上层提供 llama-cli、llama-server、转换/量化工具与语言绑定；中间由 libllama 负责模型加载、上下文、KV cache、批处理、采样与模型架构编排；底层由 ggml/ggml-backend 构建和执行张量计算图，并把计算映射到 CPU、Metal、CUDA、HIP、Vulkan、SYCL、OpenCL、CANN、OpenVINO、RPC 等后端。

官方 README 明确说明：llama.cpp 的目标是在本地与云端以最少配置实现高性能 LLM 推理；模型文件当前要求使用 GGUF，其他格式需通过转换脚本转成 GGUF。server 侧则提供轻量 HTTP 服务、Web UI、OpenAI 兼容接口、并发/连续批处理、多模态、嵌入、rerank、约束输出、函数调用与投机解码等能力。

---

2. 顶层分层架构

层级	主要目录/实体	职责	关键点
工具与接口层	tools/cli、tools/server、quantize/convert/bench、第三方 bindings	面向用户或上层应用的入口	CLI 交互、HTTP API、OpenAI/Anthropic 兼容、Web UI、模型下载与缓存
公共编排层	common/、server slot/request queue	参数解析、聊天模板、prompt 构造、采样配置、请求调度	把 CLI/server 的请求整理成 libllama 可执行的批次
核心推理层	include/llama.h、src/llama*.cpp	C ABI、模型、上下文、tokenizer、KV cache、batch、sampler、graph 构建	连接“模型语义”和“张量执行”
模型与文件层	GGUF、converter、quantizer	存储权重、元数据、tokenizer 信息、量化格式	单文件、可 mmap、可扩展 key-value 元数据、tensor descriptors
计算图层	ggml tensor graph	将 transformer/MoE/SSM 等结构转成算子图	matmul、norm、RoPE、attention、FFN、MoE routing、Flash Attention 等
后端执行层	ggml-backend 与具体后端	分配 buffer、调度 graph、执行 kernel	CPU+GPU 混合、multi-GPU split、动态后端、设备选择
输出层	sampler、detokenizer、server response	logits → token 或 embeddings/rerank 结果	流式输出、JSON API、grammar/schema constrained generation

---

3. 代码实体如何对应运行时对象

3.1 llama_model

llama_model 可以理解为“只读模型对象”。它通常包含：

• 从 GGUF 读取出来的模型架构元数据；
• vocab/tokenizer 信息；
• tensor 名称、形状、类型、量化格式；
• 权重所在的 host/device buffer；
• 分层卸载到 GPU 的映射信息；
• 架构相关的超参数，例如层数、hidden size、attention head、GQA/MQA 配置、RoPE 配置、MoE expert 配置等。

它的生命周期通常比单次请求更长：服务端会加载一次模型，然后让多个请求共享这个不可变模型对象。

3.2 llama_context

llama_context 是“运行时会话/执行上下文”。它持有可变状态，典型包括：

• KV cache：自回归生成的核心缓存；
• sequence/slot 状态：多用户、多序列并发时尤其重要；
• 运行时参数：上下文长度、batch/ubatch、线程数、Flash Attention、K/V cache 类型等；
• ggml backend scheduler 与临时 compute buffer；
• perf 统计、abort callback、embedding/logits 输出配置。

在 server 场景里，一个模型可以配合多个逻辑 slot；slot 用于隔离不同请求的 token 序列、KV 片段、采样器与流式响应状态。

3.3 llama_batch

llama_batch 是 decode/encode 的输入批次结构。它把 token 或 embedding、position、sequence id、是否输出 logits 等信息组织在一起。这个设计是并发与 continuous batching 的基础：同一个物理 decode 调用可以携带多个序列的 token，服务端再按 seq_id 把结果分发回各个请求。

3.4 llama_sampler

采样器把 logits 转成下一个 token。新版 llama.cpp 更倾向“sampler chain”风格：先应用重复惩罚、DRY、top-k、typical/top-p/min-p、temperature、Mirostat 或其他策略，最后选出 token。server README 中的默认 sampler 顺序已经体现出这是一个可配置链，而不是一个单一采样函数。

---

4. GGUF：为什么它在架构里这么核心

GGUF 是 llama.cpp 当前模型加载路径的中心。它不是简单的“权重二进制文件”，而是把模型运行所需的结构信息一起封进文件：

1. Header：magic、版本、tensor 数量、metadata kv 数量。
2. Metadata key-value：模型架构、上下文长度、embedding 维度、层数、attention 配置、tokenizer、chat template、量化版本、license/source 等。
3. Tensor descriptors：tensor 名称、维度、类型、在 tensor data 中的偏移。
4. Aligned tensor data：权重数据，可是 F16/BF16/F32，也可以是多种 Q/IQ/TQ/MXFP4/NVFP4 等量化格式。

GGUF 的关键设计目标包括：单文件部署、可扩展元数据、mmap 友好、无需外部依赖即可读取、文件包含加载模型所需的完整信息。这解释了为什么 llama.cpp 的工具链会围绕 GGUF 展开：convert_* 把 HF/PyTorch 等来源转成 GGUF，llama-quantize 或相关流程把权重压成目标量化格式，运行时则直接从 GGUF 读取并映射 tensor。

---

5. 推理主路径：从 prompt 到 token

下面是典型的自回归文本生成流程。

5.1 请求进入

入口可能是：

• llama-cli -m model.gguf；
• llama-cli -hf repo/model[:quant]；
• llama-server -m model.gguf --port 8080；
• OpenAI 兼容 /v1/chat/completions；
• embeddings、rerank、多模态、grammar/schema constrained 输出接口；
• 第三方 bindings 或上层应用。

server 侧还会处理并发请求、request queue、slot 分配、SSE 流式返回、metrics/health 等服务逻辑。

5.2 Prompt 规范化与 tokenization

对 chat/completions 来说，请求中的 messages 不会直接喂给模型，而是先经过：

1. chat template 渲染；
2. system/user/assistant/tool 内容拼接；
3. 多模态 marker 或 function/tool call 格式化；
4. tokenizer 编码为 token id；
5. 生成 llama_batch，包含 token、position、sequence id 和 logits 输出标记。

如果 GGUF 内嵌了 tokenizer.chat_template，llama.cpp 可以自动选择相应模板；也可以由 CLI 参数手动指定模板或前后缀。

5.3 Prefill

prefill 是把 prompt token 一次或分批送入模型，建立 KV cache：

1. llama_decode 接收 llama_batch；
2. libllama 根据模型架构构建当前 batch 的计算图；
3. 图中包含 embedding、RoPE/position、attention、KV 写入、FFN/MoE、norm、输出 logits 等节点；
4. ggml scheduler 将 graph 分配给 CPU/GPU/其他后端；
5. 后端执行 kernel；
6. KV cache 中保存历史 token 的 K/V。

prefill 通常是长 prompt 的主要耗时阶段，batch size、ubatch size、Flash Attention、KV cache 数据类型、设备卸载策略会显著影响性能和内存。

5.4 Decode loop

生成阶段通常循环执行：

1. 取上一步 logits；
2. sampler chain 选出下一个 token；
3. detokenize 并输出/流式返回；
4. 把新 token 加入下一次 llama_batch；
5. llama_decode 只对新 token 做增量计算，复用 KV cache；
6. 直到 EOS、长度限制、stop words、grammar/schema 约束或用户中断。

5.5 Embedding / rerank / encoder 路径

不是所有请求都走“生成 token”的路径：

• embedding 模式会启用 embedding 输出与 pooling；
• rerank 模型会使用 ranking head；
• encoder 或非 causal attention 模型会更依赖 llama_encode 或对应 attention 配置；
• 多模态模型会通过 mmproj 或相关视觉投影，把图像等信息映射到语言模型可消费的 embedding/token 流。

---

6. ggml 与后端抽象

6.1 ggml tensor graph

libllama 负责“知道模型该怎么算”，ggml 负责“把计算表达成 tensor graph”。典型节点包括：

• token embedding lookup；
• RMSNorm/LayerNorm；
• Q/K/V projection；
• RoPE 或变体；
• attention 或 Flash Attention；
• KV cache read/write；
• FFN up/gate/down；
• MoE router 与 expert matmul；
• SSM/RWKV 等非标准 transformer 结构的相关算子；
• output projection 与 logits。

6.2 ggml-backend

ggml-backend 将同一张 graph 映射到不同设备：

• CPU 后端：通用基线，配合 SIMD、BLAS、KleidiAI、AMX/AVX/NEON 等优化；
• Metal：Apple Silicon GPU；
• CUDA：NVIDIA GPU；
• HIP/ROCm：AMD GPU；
• Vulkan、SYCL、OpenCL：跨平台 GPU/加速器路径；
• CANN/OpenVINO/zDNN/Hexagon/WebGPU/RPC/VirtGPU 等：面向特定硬件或远程执行。

这一层的关键对象是 device、buffer type、backend buffer、scheduler。它允许同一个模型的不同 tensor 或 graph segment 放在不同设备上，并根据 --n-gpu-layers、--device、--split-mode、--tensor-split 等参数做 CPU/GPU 混合或多 GPU 分配。

6.3 CPU+GPU 混合执行

典型场景：

• 显存足够：尽量将层和 KV cache 放到 GPU；
• 显存不足：部分层在 GPU，部分层在 CPU；
• 多 GPU：按 layer、row 或 tensor split 分配；
• MoE 模型：可以选择将部分 expert 或 MoE 权重留在 CPU；
• KV cache：可选择是否 offload，以及 K/V cache 类型，如 f16、bf16、q8_0、q4_0 等。

这种设计的代价是运行时配置复杂，但它让 llama.cpp 可以覆盖从手机、笔记本、Apple Silicon、消费级显卡到服务器多 GPU 的广泛设备。

---

7. llama-server 架构

llama-server 是生产/集成场景下最常用的入口之一。它不是“CLI 外面套一层 HTTP”，而是包含一套服务端调度逻辑：

1. HTTP 层
   基于轻量 C++ HTTP/JSON 库，提供 REST API、Web UI、OpenAI 兼容 chat/completions/responses/embeddings、Anthropic Messages 兼容接口、健康检查与监控端点。

2. 请求解析层
   解析 sampling 参数、模型参数、grammar/schema、tools/function calling、多模态内容、stop 规则、stream 开关等。

3. Slot 调度层
   为每个请求分配 slot，跟踪 prompt cache、KV cache 范围、生成进度和流式响应状态。

4. Continuous batching
   多个请求可以在同一次 decode 中合并，提升吞吐；-np、--parallel、context size、batch size 与 KV cache 大小共同决定并发能力。

5. 输出层
   将 token/embedding/rerank 结果转换成 OpenAI 兼容 JSON、SSE chunk、普通 JSON 或 Web UI 输出。

6. 高级能力
   包括 speculative decoding、schema constrained JSON、grammar、function calling/tool use、assistant prefilling、多模态、metrics 等。

---

8. 内存模型

llama.cpp 的性能瓶颈通常不是单一“显存够不够”，而是多个内存区域共同决定。

内存区域	存什么	影响因素
模型权重	GGUF tensor data，经 mmap 或加载到 RAM/VRAM	模型规模、量化格式、--n-gpu-layers、split mode
KV cache	每层历史 token 的 K/V	context size、并发序列数、cache type K/V、是否 offload、GQA/MQA
compute buffer	graph 执行临时张量	batch/ubatch、后端、Flash Attention、模型结构
sampler/request state	logits、候选 token、grammar 状态、slot 元数据	并发数、vocab size、grammar/schema 复杂度
多模态缓存	图像投影、mmproj 相关中间结果	图像数量、视觉 encoder/mmproj、上下文拼接策略

几个实战判断：

• 权重量化主要降低模型权重占用；
• KV cache 量化主要降低长上下文和并发时的缓存占用；
• ubatch影响单次物理执行的峰值临时内存；
• Flash Attention通常降低 attention 中间内存并提升长上下文效率，但具体收益依赖后端和模型；
• mmap可加快加载并降低复制成本，但 I/O、页面缓存、mlock、DirectIO 策略会影响稳定性。

---

9. 构建与后端选择

官方 build 文档强调：很多后端可以同时编译进同一套构建，并在运行时通过 --device 选择；也支持动态后端库，使同一二进制在不同 GPU 机器上加载不同后端。常见选择如下：

硬件/场景	优先后端	说明
Apple Silicon	Metal	macOS 上通常首选
NVIDIA GPU	CUDA	高性能路径，Windows/Linux 均常见
AMD GPU	HIP/ROCm 或 Vulkan	ROCm 支持取决于系统与显卡
Intel GPU	SYCL / OpenVINO	数据中心/Arc/iGPU 依环境选择
纯 CPU	CPU + BLAS/BLIS/KleidiAI/ZenDNN	适合小模型、边缘设备或无 GPU 环境
Android/移动端	CPU/OpenCL/Hexagon 等	依 SoC 能力与构建链选择
跨平台 GPU	Vulkan/OpenCL/WebGPU	可用性广，但性能与算子覆盖依后端
多机/远程	RPC	用于把部分计算转发到远端后端

---

10. 最新主线中值得关注的变化点

以下是当前主线中与架构相关、对使用者和二次开发者有影响的趋势：

1. GGUF 与 Hugging Face 工作流更紧密
   README 支持 -hf repo/model[:quant] 直接下载运行 GGUF 模型，且近期提到 Hugging Face cache 迁移，使 llama.cpp 下载的模型可与其他 HF 工具共享缓存。

2. server 能力从“简单 HTTP”扩展为“兼容 API 服务端”
   当前 server README 列出 OpenAI 兼容 chat/completions/responses/embeddings、Anthropic Messages、rerank、parallel decoding、continuous batching、多模态、schema constrained JSON、function calling、speculative decoding、Web UI 等能力。

3. 后端数量和运行时选择能力继续扩展
   README 的 supported backends 已覆盖 Metal、BLAS/BLIS、SYCL、OpenVINO、MUSA、CUDA、HIP、ZenDNN、Vulkan、CANN、OpenCL、zDNN、WebGPU、RPC、Hexagon、VirtGPU 等；build 文档还说明可构建多个后端并通过 --device 运行时选择。

4. 量化类型继续丰富
   llama.h 的 file type 枚举已包含 Q 系列、IQ 系列、TQ、MXFP4 MoE、NVFP4、Q1_0 等，这表明 llama.cpp 的架构仍在围绕低比特、MoE 与新硬件格式演进。

5. KV cache 与并发配置更细
   server 参数支持 K/V cache type、KV offload、context size、parallel requests、batch/ubatch、Flash Attention 等组合，说明服务端吞吐与长上下文优化已经成为核心路径，而不只是单用户 CLI 推理。

---

11. 二次开发阅读顺序

如果要读源码或做架构改造，建议按下面顺序：

1. 先跑通工具层
   用 llama-cli 和 llama-server 跑同一个 GGUF，理解参数如何影响速度、内存和输出。

2. 读 include/llama.h
   先掌握公开 C API：llama_model、llama_context、llama_batch、llama_sampler、model/context params、cache/offload/split 相关配置。

3. 读模型加载路径
   关注 GGUF metadata 如何映射到模型架构、tensor 名称如何匹配、buffer type 如何选择、mmap/mlock/direct I/O 如何影响加载。

4. 读 decode 路径
   从 llama_decode 入口追到 graph builder，理解每个 batch 如何生成 ggml graph。

5. 读 ggml backend scheduler
   重点看 graph 如何切分到 CPU/GPU buffer，什么情况下发生 host-device copy，multi-GPU split 如何生效。

6. 最后读 server
   理解请求队列、slot、continuous batching、KV cache 复用、SSE stream、OpenAI 兼容响应如何围绕 libllama 组织。

---

12. 常见架构误区

误区 1：llama.cpp 只是一个单文件 C++ 程序

早期印象已经不准确。当前 llama.cpp 是一个完整推理栈：工具、服务端、公共参数层、核心 C API、模型格式、转换量化、ggml 后端、测试与多平台构建都在持续演进。

误区 2：量化只影响模型文件大小

量化首先影响权重大小和带宽，但也会影响 kernel 选择、后端支持、速度、精度、是否需要 runtime repack。KV cache 还可以独立选择 K/V 类型，它影响长上下文和并发内存。

误区 3：-ngl all 永远最快

不一定。全 GPU 对大模型通常有利，但如果显存不足、PCIe 传输瓶颈、后端 kernel 覆盖不足、batch 太小或 CPU 特定优化很强，最佳点可能是分层卸载或调整 ubatch/batch。

误区 4：server 并发只看 -np

并发能力取决于 -np、context size、KV cache、batch/ubatch、显存、slot 调度、prompt 长度分布与模型结构。长上下文多用户场景通常是 KV cache 先成为瓶颈。

误区 5：GGUF 只是权重，不含运行语义

GGUF 存储大量 metadata，包括架构、tokenizer、chat template、上下文长度、attention 配置、量化信息、来源与 license 等。运行时很多默认行为都来自 GGUF。

---

13. 架构总结

llama.cpp 的当前架构可以概括为：

User / API
  -> common 参数、模板、请求与批处理
  -> libllama 模型语义与推理状态
  -> GGUF 权重与元数据
  -> ggml tensor graph
  -> ggml-backend scheduler
  -> CPU/GPU/加速器 kernel
  -> logits/embeddings
  -> sampler/detokenizer/API response

它的设计核心不是单一优化，而是“可移植的最小核心 + 可插拔后端 + 量化优先 + 服务端批处理”。因此，在学习或改造 llama.cpp 时，不能只看某个 kernel，也不能只看 server API；真正的架构边界在 libllama 与 ggml-backend 之间：前者表达模型和推理语义，后者负责把张量图高效执行到各种硬件上。

---

参考资料

1. ggml-org/llama.cpp README：https://github.com/ggml-org/llama.cpp
2. ggml-org/llama.cpp Releases：https://github.com/ggml-org/llama.cpp/releases
3. llama.cpp server README：https://raw.githubusercontent.com/ggml-org/llama.cpp/master/tools/server/README.md
4. llama.cpp build 文档：https://raw.githubusercontent.com/ggml-org/llama.cpp/master/docs/build.md
5. llama.cpp public C API：https://raw.githubusercontent.com/ggml-org/llama.cpp/master/include/llama.h
6. GGUF specification：https://raw.githubusercontent.com/ggml-org/ggml/master/docs/gguf.md
7. DeepWiki llama.cpp overview（用于辅助定位源码实体）：https://deepwiki.com/ggml-org/llama.cpp