模型加载与管理

相关源文件

• convert_hf_to_gguf.py
• convert_hf_to_gguf_update.py
• gguf-py/gguf/constants.py
• gguf-py/gguf/gguf_writer.py
• gguf-py/gguf/tensor_mapping.py
• include/llama.h
• src/llama-arch.cpp
• src/llama-arch.h
• src/llama-hparams.cpp
• src/llama-hparams.h
• src/llama-model.cpp
• src/llama-model.h
• src/llama-vocab.cpp
• src/llama-vocab.h
• src/llama.cpp
• tests/test-tokenizer-0.sh

本文档介绍了 llama.cpp 中的模型加载和管理系统，包括 GGUF 文件格式、模型转换过程、架构检测和张量管理。该系统负责将预训练模型从磁盘加载，检测其架构，管理跨不同设备的权重，并为推理做好准备。

有关模型推理执行和上下文管理的信息，请参阅 上下文管理与推理。有关底层张量操作的详细信息，请参阅 GGML 张量库。

模型加载管道

模型加载过程遵循一个明确定义的管道，该管道会验证、解析并加载模型到内存中进行推理。

模型加载入口点

主要入口点是 llama_model_load_from_file()，它接受模型路径和参数。加载过程支持单个文件和跨多个文件的分割模型。

来源： src/llama.cpp137-261 src/llama.cpp234-245 include/llama.h295-327

GGUF 文件格式

GGUF（GPT-Generated Unified Format）是 llama.cpp 的原生模型格式，旨在实现高效加载和跨平台兼容性。

GGUF 的关键组件:

• 魔术数字：0x46554747（“GGUF”）用于格式识别
• 元数据：架构、超参数和模型信息
• 张量定义：名称、形状、数据类型和文件偏移量
• 权重数据：量化或全精度张量数据

来源： gguf-py/gguf/constants.py10-14 gguf-py/gguf/gguf_writer.py64-106 gguf-py/gguf/constants.py20-88

模型转换过程

模型使用复杂的转换管道从 HuggingFace 格式转换为 GGUF，该管道处理多种架构和分词器类型。

转换架构注册表

转换器维护一个支持的模型架构注册表，每个架构都有特定的处理逻辑

架构	模型类	主要功能
llama	LlamaModel	RMSNorm、RoPE、SwiGLU
gpt2	GPT2Model	LayerNorm、绝对位置嵌入
bert	BertModel	双向注意力、WordPiece
qwen2	Qwen2Model	GQA、自定义分词器
gemma	GemmaModel	RMSNorm、RoPE、特殊归一化

来源： convert_hf_to_gguf.py54-93 convert_hf_to_gguf.py441-463 convert_hf_to_gguf.py466-480

架构检测与超参数

系统会自动检测模型架构并从 GGUF 元数据加载其特定的超参数。

超参数类别:

类别	关键参数	目的
架构	n_embd、n_layer、n_head	模型维度
上下文	n_ctx_train、n_ctx_orig_yarn	序列长度限制
注意力机制	n_head_kv、f_clamp_kqv	注意力配置
归一化	f_norm_rms_eps、f_norm_eps	层归一化
RoPE	rope_freq_base_train、rope_scaling_type_train	位置编码

来源： src/llama-model.cpp416-421 src/llama-model.cpp423-551 src/llama-hparams.h33-139

张量与权重管理

该系统使用复杂的缓冲区分配策略，在不同设备和内存类型之间高效地管理模型权重。

缓冲区类型优先级:

1. ACCEL 缓冲区：专门的加速器设备
2. GPU Host 缓冲区：GPU 可访问的宿主内存，用于大批量处理
3. 额外 CPU 缓冲区：平台特定的优化缓冲区
4. 标准 CPU 缓冲区：默认 CPU 内存

权重加载过程:

• 内存映射：可能时使用 mmap 实现高效加载
• 设备兼容性：根据目标设备验证操作
• 分割模型：处理分布在多个文件中的模型
• 量化支持：加载预量化模型或应用运行时量化

来源： src/llama-model.cpp276-365 src/llama-model.cpp137-257 src/llama-model.cpp367-403

设备与后端选择

模型加载系统会自动选择并配置适合目标硬件配置的后端。

分割模式策略:

模式	描述	用例
NONE	仅单 GPU	小型模型，单设备
LAYER	层级分割	多 GPU，大型模型
ROW	张量并行	高带宽互连

设备选择逻辑:

• RPC 服务器：优先用于远程推理
• GPU 设备：根据内存和能力选择
• 主 GPU：单 GPU 模式下的主设备
• 张量分割：可配置的权重分布比例

来源： src/llama.cpp167-216 include/llama.h222-226 src/llama.cpp336-365

词汇表集成

模型加载过程集成了 GGUF 文件中的词汇表和分词器配置，以实现文本处理。

分词器组件:

• Token 映射：文本到 token ID 的转换
• 特殊 Token：BOS、EOS、UNK、PAD token
• 预分词：特定语言的预处理规则
• 合并规则：用于子词分词的 BPE 合并操作

词汇表元数据:

• Token 属性：普通、控制、用户定义、字节 token
• Token 分数：分词选择的优先级分数
• 编码参数：添加 BOS/EOS、空格处理、归一化

来源： src/llama-vocab.cpp109-238 src/llama-vocab.h12-114 gguf-py/gguf/constants.py183-219