项目概览与构建系统 — 代码走读

CMakeLists.txt 入口

顶层 CMakeLists.txt 定义了项目的构建结构：

# 项目定义
project(llama.cpp C CXX)

# GGML 子项目
add_subdirectory(ggml)

# llama 库
add_library(llama ...)

# 工具目标
add_subdirectory(tools)

关键构建流程：

1. 先编译 ggml 静态库（含选定的后端）
2. 编译 llama 库（依赖 ggml）
3. 编译工具和示例

include/llama.h — 核心 API

这是整个项目对外的唯一公共头文件，定义了：

核心类型

struct llama_vocab;      // 词表（不透明）
struct llama_model;      // 模型（不透明）
struct llama_context;    // 推理上下文（不透明）
struct llama_sampler;    // 采样器（不透明）
typedef int32_t llama_token;  // token ID
typedef int32_t llama_pos;    // 位置编码

核心流程

// 1. 模型加载
struct llama_model * llama_model_load_from_file(
    const char * path_model, struct llama_model_params params);

// 2. 创建上下文
struct llama_context * llama_init_from_model(
    struct llama_model * model, struct llama_context_params params);

// 3. 分词
int32_t llama_tokenize(
    const struct llama_model * model, const char * text,
    llama_token * tokens, int32_t n_max_tokens, bool add_bos, bool special);

// 4. 推理（batch decode）
int32_t llama_decode(struct llama_context * ctx, struct llama_batch batch);

// 5. 采样
llama_token llama_sampler_sample(struct llama_sampler * smpl,
    struct llama_context * ctx, int32_t idx);

// 6. 清理
void llama_free(struct llama_context * ctx);
void llama_model_free(struct llama_model * model);

src/ 目录结构

文件	职责
llama.cpp	顶层初始化与模型加载编排
llama-model.cpp	模型基类、加载各阶段与建图入口（forward 分发到 models/）
llama-model-loader.cpp	GGUF 文件解析与权重加载（支持 lazy mode）
llama-vocab.cpp	分词器与词表
llama-sampler.cpp	可组合采样器链
llama-context.cpp	推理上下文管理
llama-memory.cpp	KV Cache 管理接口（llama_memory_i）
llama-batch.cpp	批处理编码
llama-arch.cpp	模型架构定义（150 个架构）
llama-graph.cpp	计算图构建
llama-kv-cache.cpp	KV Cache 基类实现
llama-kv-cache-{msa,dsa,dsv4,iswa,dsa-iswa}.cpp	各注意力变体的专用 cache
llama-memory-{recurrent,hybrid,hybrid-idx,hybrid-iswa}.cpp	循环 / 混合记忆实现
models/（目录）	每架构一个 .cpp 的 forward pass 图实现（154 个文件）

app/llama.cpp — 统一入口

llama.cpp 现在提供统一的 llama 可执行文件，通过子命令分发到不同工具：

llama serve          → HTTP API 服务器（别名 server）
llama cli            → 命令行交互界面（别名 client）
llama update         → 更新到最新发布版
llama download       → 下载模型（别名 get）
llama completion     → 文本补全（别名 complete）
llama bench          → 性能基准测试
llama batched-bench  → 批量解码性能基准
llama fit-params     → 计算可装入显存的参数量
llama quantize       → 模型量化
llama perplexity     → 计算困惑度与 KL 散度
llama version        → 显示版本
llama licenses       → 显示第三方许可证（别名 credits）
llama help           → 显示可用命令

由 LLAMA_BUILD_APP CMake 选项控制（默认 ON）。对应的旧工具仍保留在 tools/ 目录下，按功能分目录组织，例如 tools/cli/、tools/server/、tools/quantize/ 等——绝大多数目录名不带 llama- 前缀（tools/llama-bench/ 是少数例外）。

关键函数索引

函数	文件	说明
llama_model_load_from_file	llama.cpp	从 GGUF 加载模型
llama_init_from_model	llama-context.cpp	从模型创建推理上下文
llama_decode	llama-context.cpp	执行 batch decode
llama_tokenize	llama-vocab.cpp	文本转 token
llama_sampler_sample	llama-sampler.cpp	从 logits 采样 token