llama.cpp 学习笔记

Appearance

模型加载与 GGUF 格式 — 概念 ​

GGUF 文件格式 ​

GGUF (GGML Universal File) 是二进制格式，结构如下：

┌──────────────────┐
│ Header            │  magic + version + tensor_count + metadata_count
├──────────────────┤
│ Metadata KV Pairs │  key-value 元数据（架构、超参数、词表等）
├──────────────────┤
│ Tensor Info Array │  每个张量的 name、dims、type、offset
├──────────────────┤
│ Alignment Padding │  对齐填充
├──────────────────┤
│ Tensor Data       │  所有张量的实际数据
└──────────────────┘

元数据 (Metadata) ​

GGUF 存储丰富的模型信息：

  • general.architecture — 模型架构名（如 "llama", "gpt2"）
  • llama.context_length — 最大上下文长度
  • llama.embedding_length — embedding 维度
  • llama.block_count — Transformer 层数（注意：hparams 现在区分 n_layer 与 n_layer_all，后者包含 SWA/MTP 等额外层）
  • llama.attention.head_count — 注意力头数
  • tokenizer.ggml.tokens — 词表
  • tokenizer.ggml.scores — token 分数

张量存储 ​

每个张量记录：

  • 名称（如 blk.0.attn_q.weight）
  • 维度（n_dims）
  • 数据类型（F16, Q4_0, NVFP4 等）
  • 在文件中的偏移量

NVFP4 是 NVIDIA 特定的 4-bit 浮点量化格式，通过 convert 工具的 compressed-tensors 模式支持。

GGUF 初始化方式 ​

GGUF 现在支持三种初始化方式，内部统一通过 gguf_init_from_reader() 实现：

函数说明
gguf_init_from_file()从文件路径初始化（原有方式）
gguf_init_from_callback()从用户提供的回调函数初始化（支持网络流、加密存储等）
gguf_init_from_buffer()从内存缓冲区初始化（直接解析已加载的 GGUF 数据）

模型架构 ​

llama-arch.h 定义了支持的模型架构枚举：

c
enum llm_arch {
    LLM_ARCH_LLAMA,
    LLM_ARCH_GPT2,
    LLM_ARCH_FALCON,
    LLM_ARCH_BAICHUAN,
    LLM_ARCH_STARCODER,
    LLM_ARCH_QWEN2,
    LLM_ARCH_DEEPSEEK32,  // DeepSeek V3.2 — DSA lightning indexer
    LLM_ARCH_GEMMA4,      // Gemma 4 (含 Vision 多模态)
    LLM_ARCH_EXAONE4,     // EXAONE 4.5
    LLM_ARCH_MELLUM,      // Mellum
    // ... 55+ 架构
};

每种架构定义了：

  • 层结构（attention, FFN 的组成）
  • 张量命名规则
  • 特殊操作（如 RoPE 变体）

权重映射 ​

模型加载时，将 GGUF 中的张量名映射到模型结构：

GGUF tensor name                    → 模型位置
blk.0.attn_q.weight                 → layers[0].attention.wq
blk.0.attn_k.weight                 → layers[0].attention.wk
blk.0.attn_v.weight                 → layers[0].attention.wv
blk.0.attn_output.weight            → layers[0].attention.wo
blk.0.ffn_gate.weight               → layers[0].ffn.w1
blk.0.ffn_up.weight                 → layers[0].ffn.w3
blk.0.ffn_down.weight               → layers[0].ffn.w2

内存映射 (mmap) ​

llama.cpp 使用 mmap 加载大模型：

  • 不将整个文件读入内存
  • 按需映射权重页到地址空间
  • 操作系统自动管理物理内存
  • 允许加载超过物理内存的模型

相关概念 ​

新增转换功能 ​

  • FP8 → Q8 转换 — convert_hf_to_gguf.py 现支持将 FP8 权重直接转换为 Q8_0 量化
  • Mistral3 NVFP4 scale — 模型加载时自动附加 NVFP4 权重缩放因子
  • 多新架构转换 — 支持 Gemma 4、Step3.7-Flash、MiniCPM5 tokenizer、Granite Embeddings R2