llama.cpp 源码分析:GGUF 权重与计算图的绑定

模型加载常被简单理解为“把文件读到内存”。但在 llama.cpp 里，llama_model_load_from_file() 的核心任务其实是把磁盘上 GGUF 文件的静态张量，绑定到计算图（compute graph）中对应的节点上。只有完成这个绑定，后续的 llama_decode() 才能沿着图节点一路执行前向传播。本文先分别讲清楚“计算图长什么样”和“GGUF 怎么存权重”，再讲二者在加载阶段是如何关联起来的。

1. 计算图：模型真正的执行计划

1.1 llama_model 与 llama_context 的分工

在 llama.cpp 中，模型加载生成 llama_model，上下文初始化生成 llama_context。二者的职责界限非常明确：

关键源码：src/llama-model.h 中的 llama_model 和 src/llama-context.h 中的 llama_context。

llama_model 并不直接保存“可执行的图”，它只保存如何构图的规则和权重。真正的图是在 llama_context 里根据当前 batch、序列长度、采样需求动态构建出来的。

1.2 构图入口：build_graph()

每个架构（Llama、Qwen、Gemma、DeepSeek 等）都会实现自己的 build_graph()。以 Llama 为例，其逻辑大致是：

// src/llama-model.h 中定义的接口
struct llama_model {
    // ...
    std::unique_ptr<llm_arch> arch;
    // ...
    bool build_graph(llama_context & ctx, const llama_ubatch & batch);
};

build_graph() 会按顺序往 ggml_cgraph 里添加节点：

1. 输入嵌入
   ：token_embd.weight × one-hot token id → inp_tokens
2. 逐层 Transformer block
   ：对每个 layer i：
3. RMSNorm
4. Self-Attention：attn_q/k/v.weight 投影 → RoPE → softmax → attn_o.weight 投影
5. Residual add
6. FFN：gate/up 投影 → SiLU/gelu → down 投影
7. Residual add
8. 最终 RMSNorm
9. 输出层
   ：output.weight 投影到词表维度 → logits

这些节点全部是 ggml_tensor 对象，通过 ggml_add()、ggml_mul_mat()、ggml_rope() 等 API 连接成有向无环图（DAG）。

1.3 ggml_cgraph 的结构

源码位置：ggml/include/ggml.h

struct ggml_cgraph {
    int n_nodes;
    int n_leafs;
    int n_threads;

    struct ggml_tensor ** nodes;   // 按拓扑序排列的计算节点
    struct ggml_tensor ** leafs;   // 叶子节点：常量/权重/输入
    struct ggml_tensor ** grads;   // 反向用，推理时为空
    // ...
};

• leafs
  ：权重张量和输入张量，它们没有“前驱”运算节点。
• nodes
  ：真正的运算节点，按执行顺序排列。调度器（scheduler）会按这个顺序分发给 backend。

1.4 权重张量在图中的角色

在构图阶段，build_graph() 会引用模型中已创建的权重张量，例如：

// 示意代码，来自 src/llama-model.cpp 中 Llama 架构的 build_graph 逻辑
cur = ggml_mul_mat(ctx0, model.tok_embd, inp_tokens);  // 词嵌入
cur = ggml_add(ctx0, cur, model.output);               // 输出投影

这里的 model.tok_embd、model.output 等就是 ggml_tensor*，它们在模型加载阶段被创建，并在 load_all_data() 之后拥有真正的数据指针或 GPU buffer 句柄。图节点本身不复制权重，只保存对权重张量的引用。

2. GGUF：磁盘上的张量仓库

2.1 文件整体布局

GGUF 是 llama.cpp 使用的二进制格式，文件结构如下：

┌─────────────────────────────────────┐
│              Header                 │  magic + version + n_tensors + n_kv
├─────────────────────────────────────┤
│        Tensor Infos (索引区)         │  每个 tensor 的名字/维度/类型/偏移
├─────────────────────────────────────┤
│           KV Metadata               │  模型架构、超参数、词表元数据等
├─────────────────────────────────────┤
│  Padding (对齐到 32 字节)            │
├─────────────────────────────────────┤
│          Tensor Data (数据区)        │  真正的权重数据，按 tensor info 顺序存放
└─────────────────────────────────────┘

源码实现：ggml/src/gguf.cpp 中的 gguf_init_from_file_ptr() 负责解析前三部分，数据区则通过偏移按需读取或 mmap。

2.2 Tensor Info：每个权重的“身份证”

// ggml/include/ggml.h
struct gguf_tensor_info {
    char name[GGUF_MAX_NAME];  // 例如 "blk.0.attn_q.weight"
    uint32_t n_dims;
    uint64_t ne[GGML_MAX_DIMS];
    enum ggml_type type;       // 量化类型，如 GGML_TYPE_Q4_0
    uint64_t offset;           // 数据区内的字节偏移
    size_t size;               // 占用的字节数（含量化块头）
};

每个 tensor info 回答三个问题：

- 它叫什么：名字决定它会被绑定到计算图的哪个位置。

- 它多大：ne[] 给出维度，type 决定每个元素/块的存储方式。

- 它在哪：offset 指向数据区地址。

2.3 量化类型与数据布局

llama.cpp 支持大量量化格式：Q4_0、Q4_1、Q5_0、Q8_0、Q8_K、IQ 系列等。以最常见的 Q4_0 为例：

// 每个 block 32 个权重
struct block_q4_0 {
    ggml_half d;      // 缩放因子
    uint8_t qs[16];   // 32 个 4-bit 权重，每字节存 2 个
};

• 量化不是简单压缩，而是按 block 分组存储 scale + quantized values。
• ggml_nbytes(tensor)
   会根据 type 和 ne[] 计算出实际占用字节数，通常不是 nelements × sizeof(element)。
• 反量化发生在 kernel 内部：ggml_backend 在 MUL_MAT 等算子里读取 block，现场反量化为 fp16/fp32 再做矩阵乘。

2.4 命名约定与架构元数据

GGUF 里的 tensor 名字遵循固定约定，例如一个 24 层的 Qwen 模型：

token_embd.weight                  # 词嵌入，[vocab_size, hidden_size]
blk.0.attn_norm.weight             # 第 0 层 attention 前的 RMSNorm
blk.0.attn_q.weight                # Q 投影，[hidden_size, hidden_size]
blk.0.attn_k.weight                # K 投影，[hidden_size, kv_hidden_size]
blk.0.attn_v.weight                # V 投影
blk.0.attn_output.weight           # 输出投影
blk.0.ffn_norm.weight              # FFN 前的 RMSNorm
blk.0.ffn_gate.weight              # FFN gate
blk.0.ffn_up.weight                # FFN up
blk.0.ffn_down.weight              # FFN down
...
output_norm.weight                 # 最终 RMSNorm
output.weight                      # 输出层（可能与 token_embd 共享）

这些名字与 llama_model 中 load_tensors() 创建的张量名字一一对应。架构元数据（如 general.architecture、block_count、attention.head_count）则告诉加载器应该创建哪些张量、维度是多少。

3. 绑定的关键时刻：从 GGUF tensor 到 graph node

3.1 模型加载的整体链路

llama_model_load_from_file()
    ↓
llama_model_load_from_file_impl()
    ↓
llama_model_load()
    ├── llama_model_loader()       打开 GGUF、解析 KV、建立 tensor 索引
    ├── llama_model_create()       按架构创建模型对象
    ├── load_hparams()             读取超参数
    ├── load_vocab()               加载词表
    ├── load_tensors()             创建权重张量并决定 backend/buft
    └── load_all_data()            把 GGUF 数据绑定到张量

其中第 1 步建立索引，第 6 步创建“图中会用到的空张量”，第 7 步把数据填进去。真正体现“图与权重关联”的是第 6 和第 7 步。

3.2 load_tensors()：创建图将来要引用的权重张量

源码位置：src/llama-model.cpp 中各架构的 load_tensors() 实现。

以 Llama 为例，load_tensors() 会遍历每一层，调用 create_tensor() 创建该层需要的所有权重：

// 示意逻辑
for (int i = 0; i < n_layer; ++i) {
    auto & layer = layers[i];

    layer.attn_norm = create_tensor(tn(LLM_TENSOR_ATTN_NORM, "weight", i), {n_embd}, 0);

    layer.wq = create_tensor(tn(LLM_TENSOR_ATTN_Q,   "weight", i), {n_embd, n_embd}, 0);
    layer.wk = create_tensor(tn(LLM_TENSOR_ATTN_K,   "weight", i), {n_embd, n_embd_k_gqa}, 0);
    layer.wv = create_tensor(tn(LLM_TENSOR_ATTN_V,   "weight", i), {n_embd, n_embd_v_gqa}, 0);
    layer.wo = create_tensor(tn(LLM_TENSOR_ATTN_OUT, "weight", i), {n_embd, n_embd}, 0);

    layer.ffn_norm = create_tensor(tn(LLM_TENSOR_FFN_NORM, "weight", i), {n_embd}, 0);
    layer.ffn_gate = create_tensor(tn(LLM_TENSOR_FFN_GATE, "weight", i), {n_embd,   n_ff}, 0);
    layer.ffn_down = create_tensor(tn(LLM_TENSOR_FFN_DOWN, "weight", i), {n_ff,    n_embd}, 0);
    layer.ffn_up   = create_tensor(tn(LLM_TENSOR_FFN_UP,   "weight", i), {n_embd,   n_ff}, 0);
}

create_tensor() 内部做三件事：

1. 按名字到 GGUF 索引中查找对应的 llama_tensor_weight
   。
2. 用 GGUF 里的 type 和 ne[] 初始化 ggml_tensor
   ，同时校验维度是否与架构预期一致。
3. 为这个张量选择 backend buffer type（buft）
   ，也就是决定它驻留在 CPU 还是 GPU。

3.3 名字匹配：权重如何找到自己在图中的位置

tn(LLM_TENSOR_ATTN_Q, "weight", i) 会生成类似 "blk.0.attn_q.weight" 的字符串。create_tensor() 用这个字符串在 llama_model_loader::weights_map 中查找：

// src/llama-model-loader.cpp
const llama_tensor_weight & llama_model_loader::require_weight(const char * name) const {
    const auto it = weights_map.find(name);
    if (it == weights_map.end()) {
        throw std::runtime_error(...);
    }
    return it->second;
}

这里的关系非常直接：GGUF 中的字符串名字就是图节点在模型对象中的“坐标”。名字对不上，加载直接报错。

3.4 Backend/Buffer Type 选择：权重住在哪里

create_tensor() 会调用 buft_for_tensor() 为每个权重选择 buffer type：

// src/llama-model-loader.cpp
static ggml_backend_buffer_type_t buft_for_tensor(
    const llama_model_loader & ml,
    const ggml_tensor * tensor,
    const llama_model::impl::layer_dev & dev)
{
    // 1. 用户是否通过 tensor_buft_overrides 显式指定？
    // 2. 否则按 dev 选择默认 buft
    // 3. 如果目标 backend 不支持该量化类型，回退到 CPU
}

n_gpu_layers 决定哪些层放到 GPU：

// src/llama-model.cpp
uint32_t llama_model::n_gpu_layers() const {
    return params.n_gpu_layers >= 0 ? params.n_gpu_layers : hparams.n_layer_all + 1;
}

• n_gpu_layers = -1
  ：所有层（含输出层）都放 GPU。
• n_gpu_layers = 0
  ：纯 CPU。
• n_gpu_layers = N
  ：输出层 + 最接近输出的 N 层放 GPU。

为什么从输出层开始数？因为生成阶段最频繁访问的是输出层和靠近输出的层，优先卸载它们收益最大。

3.5 load_data_for()：把 GGUF 数据塞给张量

当所有权重张量都创建好并分配好 buffer 后，load_all_data() 遍历它们，逐个调用 load_data_for()：

// src/llama-model-loader.cpp
void llama_model_loader::load_data_for(struct ggml_tensor * cur) const {
    const auto & w = require_weight(ggml_get_name(cur));

    if (use_mmap) {
        const auto & mapping = mappings.at(w.idx);
        if (cur->data == nullptr) {
            // mmap 零拷贝：直接把 tensor->data 指向映射内存
            cur->data = (uint8_t *)mapping->addr() + w.offs;
        } else {
            // 已分配 buffer，需要从映射内存拷贝过去
            memcpy(cur->data, (uint8_t *)mapping->addr() + w.offs, ggml_nbytes(cur));
        }
    } else {
        // 非 mmap：从文件 seek + read
        GGML_ASSERT(cur->data != nullptr);
        const auto & file = files.at(w.idx);
        file->seek(w.offs, SEEK_SET);
        file->read_raw(cur->data, ggml_nbytes(cur));
    }
}

这一步完成了最终绑定：

- 如果是 mmap 且张量没有专属 buffer，cur->data 直接指向 GGUF 文件映射中的偏移地址。图节点引用的就是这个地址。

- 如果张量需要独占 buffer（例如 GPU 权重），则把数据从文件或映射内存拷贝/上传到对应 backend buffer。

3.6 非 mmap 下的异步 GPU 上传

当不使用 mmap 且权重目标为 GPU 时，load_all_data() 会使用 staging buffer 异步上传：

// src/llama-model-loader.cpp
static const size_t prefetch_elem_size = 1024 * 1024; // 1 MB staging buffer

// 对 GPU 张量调用
ggml_backend_tensor_set_async(backend, tensor, staging_data, 0, ggml_nbytes(tensor));

如果 backend 不支持异步，则回退到同步的 ggml_backend_tensor_set()。这一步完成后，GPU 上的权重 buffer 才真正有数据，ggml_cgraph 在 GPU backend 上执行时才能读到权重。

4. 多 GPU 与 split_mode 下的绑定

4.1 llama_split_mode 概览

// include/llama.h
enum llama_split_mode {
    LLAMA_SPLIT_MODE_NONE   = 0, // 单 GPU
    LLAMA_SPLIT_MODE_LAYER  = 1, // 按层切分到多张卡
    LLAMA_SPLIT_MODE_ROW    = 2, // 层切分 + 张量并行
    LLAMA_SPLIT_MODE_TENSOR = 3, // 纯张量并行
};

4.2 层切分下的张量分配

在 LLAMA_SPLIT_MODE_LAYER 下，load_tensors() 会把不同 layer 的权重分配到不同 GPU：

// src/llama-model.cpp 中 load_tensors 的 layer_dev 逻辑
auto get_layer_buft_list = [&](int il) -> llama_model::impl::layer_dev {
    if (il < i_gpu_start || (il - i_gpu_start) >= act_gpu_layers) {
        return {cpu_dev, &pimpl->cpu_buft_list};
    }
    const int layer_gpu = std::upper_bound(splits.begin(), splits.begin() + n_devices(),
        float(il - i_gpu_start)/act_gpu_layers) - splits.begin();
    auto * dev = devices.at(layer_gpu).dev;
    return {dev, &pimpl->gpu_buft_list.at(dev)};
};

• splits
   来自 tensor_split 参数，表示每张 GPU 负责的权重比例。
• 一旦某层权重被分配到 GPU X，load_data_for() 就会把该层数据上传到 GPU X 的 buffer。
• 构图时，build_graph() 仍然引用同一个 ggml_tensor*，但 backend 调度器会根据张量所在的 buffer 把它路由到正确的 GPU。

4.3 张量并行与张量切分

ROW/TENSOR 模式下，单个权重张量会被进一步切分到多个 GPU。例如矩阵乘的某一行/列放在不同卡上，计算时需要集合通信（NCCL/MPI）同步。此时 GGUF 里的一个 tensor 可能对应多个 backend buffer，加载逻辑会更复杂，涉及 ggml_backend_tensor_copy 和跨卡同步。

5. 为什么理解这个关联很重要

理解“计算图 ←→ GGUF 权重”的绑定关系，能解释很多实际现象：

1. 为什么第一次加载慢？

2. 不只是读文件，还要解析 KV、构建 tensor 索引、为每个权重选择 backend、分配 CPU/GPU buffer、上传数据、编译 Metal/CUDA kernel。

3. 为什么 --mmap 省内存？

4. mmap 模式下，很多 CPU 权重的 tensor->data 直接指向文件映射地址。操作系统按需分页加载，多个进程加载同一个 GGUF 还能共享物理页。

5. 为什么 -ngl 能控制显存？

6. load_tensors() 根据 n_gpu_layers 决定哪些层从 GPU backend buffer 分配。层数越多，需要上传/分配的 GPU buffer 越多。

7. 为什么量化模型报错“tensor not found”或 shape mismatch？

8. 通常是因为 GGUF 里的 tensor 名字或维度与当前架构 load_tensors() 的预期不一致。例如新模型用了不同的 attention 命名，或 GQA 维度算错。

9. 为什么后端适配（如高通 NPU）要改加载流程？

10. 新 backend 需要提供自己的 ggml_backend_buffer_type 和 ggml_backend_tensor_set 实现。load_tensors() 和 load_data_for() 是权重进入该 backend 的入口。

6. 小结

                    GGUF 文件
                       │
    ┌──────────────────┼──────────────────┐
    │                  │                  │
    ▼                  ▼                  ▼
  Header          Tensor Infos         Tensor Data
    │                  │                  │
    │          建立 weights_map          │
    │                  │                  │
    ▼                  ▼                  ▼
 load_hparams()   load_tensors()    load_data_for()
    │                  │                  │
    │           创建 ggml_tensor        绑定 data/buffer
    │                  │                  │
    └──────────────────┴──────────────────┘
                       │
                       ▼
                llama_model
                       │
                       │ build_graph()
                       ▼
                 ggml_cgraph
                       │
                       │ scheduler + backend
                       ▼
                  token out

llama.cpp 的模型加载本质上是一次从静态数据文件到动态执行图的绑定过程：

• GGUF
   提供“叫什么名字、存在哪、什么类型”的静态描述。
• load_tensors()
   按架构预期创建图将来要引用的权重张量，并决定它们住 CPU 还是 GPU。
• load_data_for()
   通过名字索引把 GGUF 数据区映射或拷贝到这些张量的 buffer 上。
• build_graph()
   运行时只关心“这个张量有没有数据、在哪个 backend”，而不关心数据最初从哪个文件来。

掌握这个链路后，再去看 KV cache 管理、计算图调度、后端抽象就会清晰很多。

参考

• src/llama.cpp:426-430
  ：llama_model_load_from_file()
• src/llama-model-loader.cpp:512-821
  ：llama_model_loader 构造函数
• src/llama-model-loader.cpp:576-585
  ：建立 weights_map
• src/llama-model-loader.cpp:1080-1190
  ：buft_for_tensor()
• src/llama-model-loader.cpp:1385-1406
  ：load_data_for()
• src/llama-model.cpp:1209-1283
  ：load_tensors()
• src/llama-model.cpp:1658-1661
  ：n_gpu_layers()
• ggml/src/gguf.cpp:928
  ：gguf_init_from_file_ptr()
• ggml/include/ggml.h
  ：ggml_cgraph、ggml_type、gguf_tensor_info
• GGUF 格式规范