GGML-with-C++

class Member {
public:
    Member() { 
        std::cout << "Member 默认构造\n"; 
    }
    Member(int x) { 
        std::cout << "Member 带参构造: " << x << "\n"; 
    }
};

class MyClass {
    Member m1;  // 成员对象
    Member m2;
    int value;
    
public:
    // 情况1: 不使用初始化列表
    MyClass() {
        std::cout << "构造函数体开始\n";
        value = 10;  // 这是赋值，不是初始化！
    }
    
    // 情况2: 使用初始化列表
    MyClass(int v) : m1(1), m2(2), value(v) {
        std::cout << "构造函数体开始\n";
    }
};

情况 1 输出
Member 默认构造    // m1 在构造函数体前被默认构造
Member 默认构造    // m2 在构造函数体前被默认构造
构造函数体开始

情况 2 输出
Member 带参构造: 1  // m1 在构造函数体前初始化
Member 带参构造: 2  // m2 在构造函数体前初始化
构造函数体开始

// 方式1：栈上分配
MyClass obj;           // 直接得到实例（对象本身）
MyClass obj2(10);      // 带参数构造

// 方式2：堆上分配  
MyClass* ptr = new MyClass();     // 得到指针
MyClass* ptr2 = new MyClass(10);  // 带参数构造

auto &ctx = this->ctx_w;
// 此时 this->ctx_w 还没有被初始化，可以认为是 NULL
{
 ggml_init_params params = {
            /*.mem_size   =*/ctx_size,
            /*.mem_buffer =*/NULL,
            /*.no_alloc   =*/false,
        };

        this->ctx_w = ggml_init(params);
}

{
 // 此时 this->ctx_w 已经被初始化了，所以引用它的 ctx 也有效
 this->ln_f_g = ggml_new_tensor_1d(ctx, GGML_TYPE_F32, n_embd);
 this->ln_f_b = ggml_new_tensor_1d(ctx, GGML_TYPE_F32, n_embd);
}

struct ggml_context * ctx = NULL;  // ctx 是一个指针，它的值是 NULL

struct gguf_init_params params = {
    /*.no_alloc = */ true,
    /*.ctx      = */ &ctx,  // ⭐ 这里传递的是 ctx 的地址，不是 ctx 的值！
};

------

// 1. ctx 是一个指针变量
struct ggml_context * ctx = NULL;

// 内存布局：
// 地址: 0x7fff1234  (假设 ctx 变量存储在这个地址)
// 值:   NULL (0x0)

// 2. &ctx 是"指向指针的指针"
struct ggml_context ** ptr_to_ctx = &ctx;

// &ctx 的值是 0x7fff1234 (ctx 变量的地址)
// 这个地址本身不是 NULL！

// main.cpp
#include "person.h"  // Only includes declarations from person.h
                     // Does NOT automatically include person.cpp

int main() {
    Person p("Alice", 25);  // Linker will find implementation in person.cpp
    p.introduce();
    return 0;
}

model.a = ggml_new_tensor_2d(ctx, GGML_TYPE_F32, cols_A, rows_A);
model.b = ggml_new_tensor_2d(ctx, GGML_TYPE_F32, cols_B, rows_B);

struct ggml_tensor * ggml_new_tensor_2d(
        struct ggml_context * ctx,
        enum   ggml_type      type,
        int64_t ne0,
        int64_t ne1) {
    const int64_t ne[2] = { ne0, ne1 };
    return ggml_new_tensor(ctx, type, 2, ne);
}


// ne0 -> col
// ne1 -> row
// nb0 -> 在 ne0 维度中，移动到相邻的元素（a[row][0] -> a[row][1]），需要在内存中前进多少字节
// nb1 -> 在 ne1 维度中，移动到相邻的元素(a[0][col] -> a[1][col])，需要在内存中前进多少字节


ggml_tensor * c = ggml_mul_mat(ctx, a, b)

=> c = b @ a^T

// 张量：[3, 2] 矩阵
// ne = {3, 2}
// nb = {4, 12}  // 4 = sizeof(float), 12 = 4*3
// 
// 内存布局：
// [a0, a1, a2, b0, b1, b2]
//  ↑________↑   ↑________↑
//   row 0        row 1
//
// nb[0] = 4  (每个元素 4 字节)
// nb[1] = 12 (跳过 3 个元素 = 12 字节才到下一行)

struct ggml_tensor * ggml_view_2d(
        struct ggml_context * ctx,
        struct ggml_tensor  * a,
        int64_t               ne0,
        int64_t               ne1,
        size_t                nb1,    // ← 第二维的 stride
        size_t                offset) { // ← 起始偏移
    
    const int64_t ne[2] = { ne0, ne1 };

    struct ggml_tensor * result = ggml_view_impl(ctx, a, 2, ne, offset);

    // 手动设置 stride
    result->nb[1] = nb1;
    result->nb[2] = result->nb[1]*ne1;
    result->nb[3] = result->nb[2];

    return result;
}

// 目标(dst)张量的数据指针，它指向一块连续内存
char * d_data = (char *) dst->data;

// 源(src)张量的数据指针
const char * s_data = (const char *) src->data;

// 遍历所有维度 (以4D为例)
for (int i3 = 0; i3 < src->ne[3]; i3++) {
 for (int i2 = 0; i2 < src->ne[2]; i2++) {
  for (int i1 = 0; i1 < src->ne[1]; i1++) {
   
   // 1. 计算非连续的源(src)地址
   //    它使用 'nb' (步长) 来跳跃
   const char * s_ptr = s_data + i3*src->nb[3] + i2*src->nb[2] + i1*src->nb[1];

   // 2. 计算连续的目标(dst)地址
   //    它只是简单地在 d_data 基础上累加
   
   // 3. 复制最内层维度的连续块
   //    (src->ne[0] 个元素, 每个元素 src->nb[0] 字节)
   memcpy(d_data, s_ptr, src->ne[0] * src->nb[0]);

   // 4. 推进连续的目标(dst)指针
   d_data += src->ne[0] * src->nb[0];
  }
 }
}

struct ggml_tensor * ggml_permute(
        struct ggml_context * ctx,
        struct ggml_tensor  * a,
        int                   axis0,
        int                   axis1,
        int                   axis2,
        int                   axis3) {
    // ...参数检查...
    
    struct ggml_tensor * result = ggml_view_tensor(ctx, a);  // ← 创建视图
    ggml_format_name(result, "%s (permuted)", a->name);

    int ne[GGML_MAX_DIMS];
    int nb[GGML_MAX_DIMS];

    // 重新排列 ne（形状）
    ne[axis0] = a->ne[0];
    ne[axis1] = a->ne[1];
    ne[axis2] = a->ne[2];
    ne[axis3] = a->ne[3];

    // 重新排列 nb（stride）
    nb[axis0] = a->nb[0];
    nb[axis1] = a->nb[1];
    nb[axis2] = a->nb[2];
    nb[axis3] = a->nb[3];

    // 更新 result 的形状和 stride
    result->ne[0] = ne[0];
    result->ne[1] = ne[1];
    result->ne[2] = ne[2];
    result->ne[3] = ne[3];

    result->nb[0] = nb[0];
    result->nb[1] = nb[1];
    result->nb[2] = nb[2];
    result->nb[3] = nb[3];

    result->op     = GGML_OP_PERMUTE;
    result->src[0] = a;

    return result;
}

内存地址:  [0]  [4]  [8]  [12]
数据:       a    b    c    d

原tensor (2, 2):

ne0 = 2 ne1 = 2
nb0 = 4 nb1 = 8

访问 a[i][j] = data[i*nb1 + j*nb0]
a[0][1] = data[4] -> b

ggml_permute(ctx, A, 1, 0, 2, 3)

ne0 = 2 ne1 = 2
nb0 = 8 nb1 = 4

访问 p[i][j] = data[i*nb1 + j*nb0]
p[0][0] = data[0] -> a
p[0][1] = data[8] -> c
p[1][0] = data[4] -> b
p[1][1] = data[12] -> d

struct ggml_tensor {
 enum ggml_type type;
 struct ggml_backend_buffer * buffer;
 int64_t ne[GGML_MAX_DIMS]; // number of elements
 size_t  nb[GGML_MAX_DIMS]; // stride in bytes:
          // nb[0] = ggml_type_size(type)
          // nb[1] = nb[0]   * (ne[0] / ggml_blck_size(type)) + padding
          // nb[i] = nb[i-1] * ne[i-1]
 // compute data
 enum ggml_op op;
 // op params - allocated as int32_t for alignment
 int32_t op_params[GGML_MAX_OP_PARAMS / sizeof(int32_t)];
 int32_t flags;
 struct ggml_tensor * src[GGML_MAX_SRC];
 // source tensor and offset for views
 struct ggml_tensor * view_src;
 size_t               view_offs;
 void * data;
 char name[GGML_MAX_NAME];
 void * extra; // extra things e.g. for ggml-cuda.cu
 char padding[8];
};

struct ggml_cgraph {
    int size;    // maximum number of nodes/leafs/grads/grad_accs
    int n_nodes; // number of nodes currently in use
    int n_leafs; // number of leafs currently in use

    struct ggml_tensor ** nodes;     // tensors with data that can change if the graph is evaluated
    struct ggml_tensor ** leafs;     // tensors with constant data
    int32_t             * use_counts;// number of uses of each tensor, indexed by hash table slot

    struct ggml_hash_set visited_hash_set;
    enum ggml_cgraph_eval_order order;
};

ggml_init_params params = {
            /*.mem_size   =*/ctx_size,
            /*.mem_buffer =*/NULL,
            /*.no_alloc   =*/false,
        };
ctx_w = ggml_init(params);

// ggml.c: 1640
static struct ggml_tensor * ggml_new_tensor_impl(...){

size_t obj_alloc_size = 0;

if (view_src == NULL && !ctx->no_alloc) {
 // allocate tensor data in the context's memory pool
 obj_alloc_size = data_size;
}

struct ggml_object * const obj_new = ggml_new_object(ctx, GGML_OBJECT_TYPE_TENSOR, GGML_TENSOR_SIZE + obj_alloc_size);

 *result = (struct ggml_tensor) {
  // ...
  /*.data         =*/ obj_alloc_size > 0 ? (void *)(result + 1) : data,
  /*.name         =*/ { 0 },
  /*.extra        =*/ NULL,
  /*.padding      =*/ { 0 },
 };

}

size_t ctx_size = 0;

//...

ctx_size += ggml_row_size(GGML_TYPE_F32, n_embd); // ln_f_g
ctx_size += ggml_row_size(GGML_TYPE_F32, n_embd); // ln_f_b

ctx_size += ggml_row_size(wtype, n_vocab * n_embd);       // wte
ctx_size += ggml_row_size(GGML_TYPE_F32, n_ctx * n_embd); // wpe
ctx_size += ggml_row_size(wtype, n_vocab * n_embd);       // lm_head

// ...
 

static size_t buf_size = 256u * 1024 * 1024;
static void *buf = malloc(buf_size);

struct ggml_init_params params = {
 /*.mem_size   =*/buf_size,
 /*.mem_buffer =*/buf,
 /*.no_alloc   =*/false,
};

struct ggml_context *ctx0 = ggml_init(params);

 ggml_gallocr_t allocr = NULL;
    // allocate the compute buffer
{
 allocr = ggml_gallocr_new(ggml_backend_cpu_buffer_type());

 // create the worst case graph for memory usage estimation
 int n_tokens = std::min(model.hparams.n_ctx, params.n_batch);
 int n_past = model.hparams.n_ctx - n_tokens;
 struct ggml_cgraph * gf = gpt2_graph(model, n_past, n_tokens);

 // pre-allocate the compute buffer for the worst case (optional)
 ggml_gallocr_reserve(allocr, gf);
 size_t mem_size =  ggml_gallocr_get_buffer_size(allocr, 0);
 fprintf(stderr, "%s: compute buffer size: %.2f MB\n", __func__, mem_size/1024.0/1024.0);
}

reserve() {
    1. 分析图结构，确定节点分配给哪个后端
    2. 计算每个后端需要的最大内存
    3. 为每个后端创建 buffer（但不分配给 tensor）
    
    Example:
    GPU buffer: 2GB (预留但未使用)
    CPU buffer: 512MB (预留但未使用)
}

alloc_graph(graph) {
    1. 遍历当前图的所有节点
    2. 从预留的 buffer 中切分内存
    3. 设置每个 tensor->data 指向对应位置
    
    Example:
    tensor_Q->data = gpu_buffer + offset_0
    tensor_K->data = gpu_buffer + offset_1024
    ...
}

struct ggml_gallocr {
    ggml_backend_buffer_type_t * bufts; // [n_buffers]
    struct vbuffer ** buffers; // [n_buffers]
    struct ggml_dyn_tallocr ** buf_tallocs; // [n_buffers]
    int n_buffers;

    struct ggml_hash_set hash_set;
    struct hash_node * hash_values; // [hash_set.size]

    struct node_alloc * node_allocs; // [n_nodes]
    int n_nodes;

    struct leaf_alloc * leaf_allocs; // [n_leafs]
    int n_leafs;
};

// virtual buffer with contiguous memory range, split into multiple backend buffers (chunks)

struct vbuffer {
    ggml_backend_buffer_t chunks[GGML_VBUFFER_MAX_CHUNKS];
};

bool ggml_gallocr_reserve_n(...){


 // initialize ggml hash set
 
 // allocate in hash table
 // 这个函数并不会实际分配内存，相当于是 Dry Run
 ggml_gallocr_alloc_graph_impl(galloc, graph, node_buffer_ids, leaf_buffer_ids){
  for (int i = 0; i < graph->n_leafs; i++) {
         struct ggml_tensor * leaf = graph->leafs[i];
         ggml_gallocr_allocate_node(galloc, leaf, get_node_buffer_id(leaf_buffer_ids, i));
     }
  for (int i = 0; i < graph->n_nodes; i++) {
         struct ggml_tensor * node = graph->nodes[i];
      // allocate nodes
     }
 };
 
 // 从 Dry Run 中提取 hash table 的信息
 for (int i = 0; i < graph->n_nodes; i++) {...}
 for (int i = 0; i < graph->n_leafs; i++) {...}
 
 // 分配空间
  if (realloc) {
  ggml_vbuffer_free(galloc->buffers[i]);
  galloc->buffers[i] = ggml_vbuffer_alloc(galloc->bufts[i], galloc->buf_tallocs[i], GGML_BACKEND_BUFFER_USAGE_COMPUTE){
   for (int n = 0; n < talloc->n_chunks; n++) {
          size_t chunk_size = talloc->chunks[n]->max_size;
          buf->chunks[n] = ggml_backend_buft_alloc_buffer(buft, chunk_size);
          if (buf->chunks[n] == NULL) {
              ggml_vbuffer_free(buf);
              return NULL;
          }
          ggml_backend_buffer_set_usage(buf->chunks[n], usage);
      }
      return buf;
  };
    } 
}

bool ggml_gallocr_alloc_graph(ggml_gallocr_t galloc, struct ggml_cgraph * graph) {
    // reset buffers
    for (int i = 0; i < galloc->n_buffers; i++) {
        if (galloc->buffers[i] != NULL) {
            ggml_vbuffer_reset(galloc->buffers[i]);
        }
    }
    // allocate the graph tensors from the previous assignments
    // leafs
    for (int i = 0; i < graph->n_leafs; i++) {
        struct ggml_tensor * leaf = graph->leafs[i];
        struct leaf_alloc * leaf_alloc = &galloc->leaf_allocs[i];
        ggml_gallocr_init_tensor(galloc, leaf, &leaf_alloc->leaf);
    }
    // nodes
    for (int i = 0; i < graph->n_nodes; i++) {
        struct ggml_tensor * node = graph->nodes[i];
        struct node_alloc * node_alloc = &galloc->node_allocs[i];
        for (int j = 0; j < GGML_MAX_SRC; j++) {
            struct ggml_tensor * src = node->src[j];
            if (src == NULL) {
                continue;
            }
            ggml_gallocr_init_tensor(galloc, src, &node_alloc->src[j]);
        }
        ggml_gallocr_init_tensor(galloc, node, &node_alloc->dst);
    }
    return true;
}

size_t n_tensors = 2 + 6 + 12*model.hparams.n_layer;
struct ggml_init_params params = {
 /*.mem_size   =*/ ggml_tensor_overhead() * n_tensors,
 /*.mem_buffer =*/ NULL,
 /*.no_alloc   =*/ true,
};

ctx = ggml_init(params);

// allocate the model tensors in a backend buffer
model.buffer_w = ggml_backend_alloc_ctx_tensors(ctx, model.backend);

// allocate the tensor
ggml_backend_t backend = tensor_backends[name];
ggml_tallocr * alloc = &backend_buffers.find(backend)->second;
ggml_tallocr_alloc(alloc, tensor);

reserve() {
    1. 分析图结构，确定节点分配给哪个后端
    2. 计算每个后端需要的最大内存
    3. 为每个后端创建 buffer（但不分配给 tensor）
    
    Example:
    GPU buffer: 2GB (预留但未使用)
    CPU buffer: 512MB (预留但未使用)
}

alloc_graph(graph) {
    1. 遍历当前图的所有节点
    2. 从预留的 buffer 中切分内存
    3. 设置每个 tensor->data 指向对应位置
    
    Example:
    tensor_Q->data = gpu_buffer + offset_0
    tensor_K->data = gpu_buffer + offset_1024
    ...
}

bool ggml_backend_sched_reserve(ggml_backend_sched_t sched, struct ggml_cgraph * measure_graph) {
    GGML_ASSERT(sched);
    GGML_ASSERT((int)sched->hash_set.size >= measure_graph->n_nodes + measure_graph->n_leafs);

    ggml_backend_sched_synchronize(sched);

    ggml_backend_sched_split_graph(sched, measure_graph);

    if (!ggml_gallocr_reserve_n(sched->galloc, &sched->graph, sched->node_backend_ids, sched->leaf_backend_ids)) {
        return false;
    }

    ggml_backend_sched_reset(sched);

    return true;
}

// assigns backends to ops and splits the graph into subgraphs that can be computed on the same backend
void ggml_backend_sched_split_graph(ggml_backend_sched_t sched, struct ggml_cgraph * graph) {}

struct llm_graph_context {  // ← 基类
    virtual ~llm_graph_context() = default;
    
    // 通用的构建方法
    ggml_tensor * build_norm(...);
    ggml_tensor * build_ffn(...);
    ggml_tensor * build_attn(...);
    
    ggml_context * ctx0;
    ggml_cgraph * gf;
};

// 每个模型架构有自己的图构建器
struct llm_build_qwen3 : public llm_graph_context {  // ← 子类
    llm_build_qwen3(const llama_model & model, const llm_graph_params & params);
    // 构造函数中构建 Qwen3 特定的计算图
};

struct llm_build_llama : public llm_graph_context {  // ← 子类
    llm_build_llama(const llama_model & model, const llm_graph_params & params);
    // 构造函数中构建 Llama 特定的计算图
};

// 1. 创建统一的 llama_model 对象
llama_model * model = new llama_model(params);

// 2. 从 GGUF 读取架构类型
model->arch = LLM_ARCH_QWEN3;  // 或 LLM_ARCH_LLAMA 等

// 3. 所有模型共享相同的权重存储结构
model->layers.resize(32);
model->layers[0].wq = ml.create_tensor(...);  // Qwen3 用这个
model->layers[0].wk = ml.create_tensor(...);  // Llama 也用这个

ggml_cgraph * llama_model::build_graph(const llm_graph_params & params) const {
    std::unique_ptr<llm_graph_context> llm;  // ← 多态指针
    
    // 根据架构类型创建不同的图构建器
    switch (arch) {
        case LLM_ARCH_QWEN3:
            llm = std::make_unique<llm_build_qwen3>(*this, params);
            //    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
            //    构造函数中会构建 Qwen3 特定的计算图
            break;
            
        case LLM_ARCH_LLAMA:
            llm = std::make_unique<llm_build_llama>(*this, params);
            //    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
            //    构造函数中会构建 Llama 特定的计算图
            break;
            
        // ... 其他架构
    }
    
    return llm->gf;  // 返回构建好的计算图
}

struct llama_model::impl {
    impl() {}
    ~impl() {}

    uint64_t n_elements = 0;

    size_t n_bytes = 0;

    std::string desc_str;

    // model memory mapped files
    llama_mmaps mappings;

    // objects representing data potentially being locked in memory
    llama_mlocks mlock_bufs;
    llama_mlocks mlock_mmaps;

    // contexts where the model tensors metadata is stored
    std::vector<ggml_context_ptr> ctxs;

    // the model memory buffers for the tensor data
    std::vector<ggml_backend_buffer_ptr> bufs;

    buft_list_t cpu_buft_list;
    std::map<ggml_backend_dev_t, buft_list_t> gpu_buft_list;

    struct layer_dev {
        ggml_backend_dev_t dev;
        buft_list_t * buft_list;
    };

    layer_dev dev_input = {};
    layer_dev dev_output = {};
    std::vector<layer_dev> dev_layer;

    bool has_tensor_overrides;
};

No.1 Prompt Procesing Graph

auto * gf = graph_reserve(n_tokens, n_seqs, n_tokens, mctx.get());
//                        ^^^^^^^^  ^^^^^^  ^^^^^^^^
//                        批次大小   序列数  输出数

No.2 Token Generation Graph

auto * gf = graph_reserve(n_seqs, n_seqs, n_seqs, mctx.get());
//                        ^^^^^^  ^^^^^^  ^^^^^^
//                        每序列1个token

No.3 Worst Case?

auto * gf = graph_reserve(n_tokens, n_seqs, n_tokens, mctx.get());

// 1. 声明模型权重（在持久 context 中）
ggml_context * ctx = ggml_init({.mem_size = size, .no_alloc = true});
ggml_tensor * wq = ml.create_tensor(ctx, "blk.0.attn_q.weight", {n_embd, n_embd});

// 2. 为权重分配 backend buffer
ggml_backend_buffer_t buf = ggml_backend_alloc_ctx_tensors_from_buft(ctx, buft);
// 这会：
//   a. 计算所有 tensor 的总大小
//   b. 分配一个大的 backend buffer
//   c. 为每个 tensor 设置 tensor->buffer 和 tensor->data

// 3. 从文件复制数据到 buffer
for (tensor : ctx) {
    file.read(tensor->data, tensor_size);  // 直接写入 GPU/CPU 内存
}

// 1. 声明模型权重（同样在持久 context 中）
ggml_context * ctx = ggml_init({.mem_size = size, .no_alloc = true});
ggml_tensor * wq = ml.create_tensor(ctx, "blk.0.attn_q.weight", {n_embd, n_embd});

// 2a. mmap 文件到内存
llama_mmap mapping(file, prefetch);
void * mmap_addr = mapping.addr();  // 文件内容映射到这里

// 2b. 创建 buffer_from_host_ptr（关键！）
ggml_backend_buffer_t buf = ggml_backend_dev_buffer_from_host_ptr(
    dev, 
    (char*)mmap_addr + first_offset, 
    last_offset - first_offset,
    max_tensor_size
);
// 这会：
//   a. 创建一个 backend buffer，但它只是**包装** mmap 地址
//   b. 不分配新内存！
//   c. Metal/CUDA 可能会 pin 住这块内存用于 DMA

// 2c. 为每个 tensor 关联 mmap 内存
for (tensor : ctx) {
    tensor->data = mmap_addr + tensor_offset;  // 直接指向 mmap 内存
    tensor->buffer = buf;
}

// 3. 不需要复制数据！（跳过）
// 数据已经通过 mmap 在内存中了

enum ggml_status ggml_backend_tensor_alloc(
    ggml_backend_buffer_t buffer, 
    struct ggml_tensor * tensor, 
    void * addr  // ← 关键：手动指定地址！
) {
    GGML_ASSERT(tensor->buffer == NULL);
    GGML_ASSERT(tensor->data == NULL);
    GGML_ASSERT(tensor->view_src == NULL);
    
    // 验证地址在 buffer 范围内
    GGML_ASSERT(addr >= ggml_backend_buffer_get_base(buffer));
    GGML_ASSERT((char *)addr + ggml_backend_buffer_get_alloc_size(buffer, tensor) <=
                (char *)ggml_backend_buffer_get_base(buffer) + ggml_backend_buffer_get_size(buffer));

    // 直接设置 tensor 的数据指针
    tensor->buffer = buffer;
    tensor->data = addr;  // ← 使用传入的地址，不重新分配！
    
    return ggml_backend_buffer_init_tensor(buffer, tensor);
}

struct llama_tensor_weight {
    uint16_t idx;       // 文件索引
    size_t   offs;      // ← tensor 在文件中的偏移量（字节）
    ggml_tensor * tensor;

    llama_tensor_weight(const llama_file * file, uint16_t idx, 
                       const struct gguf_context * gguf_ctx, 
                       ggml_tensor * tensor) : idx(idx), tensor(tensor) {
        
        const int tensor_idx = gguf_find_tensor(gguf_ctx, ggml_get_name(tensor));
        
        // 从 GGUF 文件头读取偏移量
        offs = gguf_get_data_offset(gguf_ctx) +           // 数据区起始位置
               gguf_get_tensor_offset(gguf_ctx, tensor_idx); // + tensor 相对偏移
        //     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        //     这个偏移量是在转换模型为 GGUF 时就确定的！
    }
};

void llama_model_loader::init_mappings(bool prefetch, llama_mlocks * mlock_mmaps) {
    if (use_mmap) {
        mappings.reserve(files.size());
        mmaps_used.reserve(files.size());
        
        for (size_t idx = 0; idx < files.size(); idx++) {
            const auto & file = files.at(idx);
            
            // 创建 mmap 对象，映射整个文件
            std::unique_ptr<llama_mmap> mapping = 
                std::make_unique<llama_mmap>(file.get(), prefetch ? -1 : 0, is_numa);
            //                               ^^^^^^^^^^
            //                               整个文件被映射到虚拟地址空间
            
            mmaps_used.emplace_back(mapping->size(), 0);
            
            mappings.emplace_back(std::move(mapping));
        }
    }
}

if (ml.use_mmap && use_mmap_buffer && buffer_from_host_ptr_supported) {
    for (uint32_t idx = 0; idx < ml.files.size(); idx++) {
        void * addr = nullptr;
        size_t first, last;
        
        // 获取这个文件中实际使用的 tensor 范围
        ml.get_mapping_range(&first, &last, &addr, idx, ctx);
        //                    ^^^^^  ^^^^   ^^^^
        //                    最小   最大   mmap基址
        
        if (first >= last) continue;
        
        // 创建包装 mmap 内存的 buffer
        const size_t max_size = ggml_get_max_tensor_size(ctx);
        ggml_backend_buffer_t buf = ggml_backend_dev_buffer_from_host_ptr(
            dev, 
            (char *)addr + first,  // ← buffer 起始地址
            last - first,          // ← buffer 大小（不是整个文件）
            max_size
        );
        
        buf_map.emplace(idx, buf);
    }
}

void llama_model_loader::get_mapping_range(
    size_t * first, size_t * last, void ** addr, int idx, ggml_context * ctx
) const {
    const auto & mapping = mappings.at(idx);
    
    *first = mapping->size();  // 初始化为最大值
    *last  = 0;                 // 初始化为最小值
    *addr  = mapping->addr();   // mmap 基址
    
    // 遍历所有 tensor，找到实际使用的范围
    for (ggml_tensor * tensor = ggml_get_first_tensor(ctx); 
         tensor; 
         tensor = ggml_get_next_tensor(ctx, tensor)) {
        
        const auto * weight = get_weight(ggml_get_name(tensor));
        if (!weight || weight->idx != idx) continue;
        
        // 更新使用范围
        *first = std::min(*first, weight->offs);
        //                        ^^^^^^^^^^^^
        //                        从 GGUF 读取的偏移量
        *last  = std::max(*last,  weight->offs + ggml_nbytes(tensor));
    }
}

if (use_mmap) {
    const auto & mapping = mappings.at(weight->idx);
    ggml_backend_buffer_t buf_mmap = bufs.at(weight->idx);
    
    // 计算 tensor 在 mmap 内存中的实际地址
    uint8_t * data = (uint8_t *)mapping->addr() + weight->offs;
    //                ^^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^
    //                mmap 基址                     文件中的偏移量
    
    if (buf_mmap && cur->data == nullptr) {
        // 使用预先计算好的地址分配 tensor
        ggml_backend_tensor_alloc(buf_mmap, cur, data);
        //                                       ^^^^
        //                                       直接传入地址！
        
        // 记录实际使用的内存范围（用于后续 unmap 未使用部分）
        auto & mmap_used = mmaps_used[weight->idx];
        mmap_used.first  = std::min(mmap_used.first,  weight->offs);
        mmap_used.second = std::max(mmap_used.second, weight->offs + n_size);
    }
}