夜雨聆风模型加载常被简单理解为“把文件读到内存”。但在 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。二者的职责界限非常明确：
llama_model | build_graph() 方法 | |
llama_context | ggml_cgraph）、输入/输出张量、调度状态 |
关键源码：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 里添加节点：
- 输入嵌入
： token_embd.weight× one-hot token id →inp_tokens - 逐层 Transformer block
：对每个 layer i： RMSNorm Self-Attention： attn_q/k/v.weight投影 → RoPE → softmax →attn_o.weight投影Residual add FFN：gate/up 投影 → SiLU/gelu → down 投影 Residual add - 最终 RMSNorm
- 输出层
： 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() 内部做三件事：
- 按名字到 GGUF 索引中查找对应的
llama_tensor_weight。 - 用 GGUF 里的
type和ne[]初始化ggml_tensor，同时校验维度是否与架构预期一致。 - 为这个张量选择 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 权重”的绑定关系，能解释很多实际现象：
- 为什么第一次加载慢？
不只是读文件，还要解析 KV、构建 tensor 索引、为每个权重选择 backend、分配 CPU/GPU buffer、上传数据、编译 Metal/CUDA kernel。
为什么
--mmap省内存？mmap 模式下，很多 CPU 权重的
tensor->data直接指向文件映射地址。操作系统按需分页加载，多个进程加载同一个 GGUF 还能共享物理页。为什么
-ngl能控制显存？load_tensors()根据n_gpu_layers决定哪些层从 GPU backend buffer 分配。层数越多，需要上传/分配的 GPU buffer 越多。为什么量化模型报错“tensor not found”或 shape mismatch？
通常是因为 GGUF 里的 tensor 名字或维度与当前架构
load_tensors()的预期不一致。例如新模型用了不同的 attention 命名，或 GQA 维度算错。为什么后端适配（如高通 NPU）要改加载流程？
新 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_mapsrc/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_infoGGUF 格式规范