llama.cpp 学习笔记

Appearance

项目概览与构建系统 — 概念 ​

项目架构 ​

llama.cpp 采用分层架构设计：

模块划分 ​

目录职责
ggml/GGML 张量库：张量定义、计算图、后端抽象
include/llama.h对外 C API 接口
src/llama 核心实现：模型加载、推理、采样、KV Cache
src/models/各架构独立的 forward pass 图实现（一架构一文件，现 154 个 .cpp）
app/统一可执行入口（llama serve/cli/bench/quantize/...），由 LLAMA_BUILD_APP 控制（默认启用）
common/通用工具：参数解析、采样、日志、chat 模板（common/parsers/ 收纳各模型专用 parser）
examples/示例程序
tools/完整工具：cli、server、quantize、imatrix、mtmd、tts、tuning 等
gguf-py/Python GGUF 读写工具

版本号 ​

项目已转向语义化版本（680a9ae63）：llama.cpp 走 LLAMA_VERSION_MAJOR/MINOR/PATCH（CMake，当前 0.4.0），GGML 子树独立编号（当前 0.23.0）。版本宏不再以 compile definition 注入，改由 configure_file 生成 src/llama-version.h（模板 llama-version.h.in）与 ggml/src/ggml-version.h（ggml-version.h.in）——版本号变化不再触发全量重编译（86b351fd6、d230ddd76）。新增公共 API llama_version() 返回版本字符串（include/llama.h）。

构建系统 ​

llama.cpp 使用 CMake 构建，关键选项：

bash
# 基础编译
cmake -B build
cmake --build build --config Release

# 启用 CUDA 后端
cmake -B build -DGGML_CUDA=ON

# 启用 Metal 后端 (macOS)
cmake -B build -DGGML_METAL=ON

# 启用 Vulkan 后端
cmake -B build -DGGML_VULKAN=ON

核心 CMake 变量：

  • GGML_CUDA / GGML_METAL / GGML_VULKAN — 后端开关
  • GGML_BLAS — BLAS 加速
  • LLAMA_CURL — 启用 HTTP 下载支持
  • CMAKE_BUILD_TYPE — Release / Debug

C API 设计哲学 ​

include/llama.h 遵循 C 风格 OOP：

  • 不透明指针（llama_model *, llama_context *）
  • 创建/销毁配对（llama_model_load_from_file / llama_model_free）
  • 枚举驱动的配置（llama_context_param）

统一入口与 CLI ​

llama 可执行文件通过子命令分发到各工具（cli / serve / quantize / bench / perplexity / …）。近期补充：

  • llama download 子命令 — 直接从统一入口下载模型（基于 LLAMA_CURL 的 HTTP 下载）；现支持 --offline，可在不联网的情况下探测模型是否已缓存、可直接服务（便于脚本化检查），顺带修复 URL-task on_done 回调的 use-after-free
  • llama version / llama licenses / llama help — 统一入口放开这几个标准子命令（非命令行 flag，而是分发到对应子工具）
  • self-update 收紧 — 自动更新仅在用 llama-install.sh 构建时启用
  • 二进制命名改进：rpc-server、export-graph-ops 名称更清晰
  • llama-cli 改为 HTTP 客户端 — 不再直接链接 libllama，而是连接到运行中的 llama serve（支持 router 模式）来完成交互；serve 仍是直接链库的 server（c264f65ff，#24948）
  • server 能力增强 — MCP stdio 传输（20455a4ad）、--cors-* 选项（6e52db5b7）、SSE replay buffer；新增 common/subproc.{cpp,h} 包装供 MCP stdio 使用
  • chat parser 拆分 — 各模型专用的 chat 解析器（cohere2moe、deepseek 等）从单体文件拆分进 common/parsers/ 目录（895c045fd）
  • --log-jsonl — 以 JSONL（每行一个 JSON 对象）向 stdout 输出结构化日志，同时禁用彩色日志（7620399f5）；build info 的输出流也改为可配置（c390d0abb）
  • Web UI 资产内嵌 — server 的 UI 静态资产改由 CMake 直接内嵌进二进制（c457e3bf7）；对话导出改为从数据库导出而非缓存 store（1863ac033）；聊天消息渲染性能优化（0afb805b1）

第三方依赖 ​

llama.cpp 尽量保持轻量，少量 vendored 依赖会随上游同步升级：

  • cpp-httplib — HTTP 服务器（server 后端），现 0.54.1
  • BoringSSL — TLS（HTTPS 下载 / 鉴权），现 0.20260903.0
  • nlohmann/json — JSON 解析；上层新增 common/json.h 抽象层（d9f918d2d），业务代码不再直接 include 第三方头
  • OpenVINO — Intel 推理后端，现 2026.2.1
  • 其余 vendored 小库：vendor/hash、vendor/miniaudio（音频输入）、vendor/sheredom（jsonrpc）、vendor/stb（图像解码）

相关概念 ​