GGUF——一种用于存储大模型的文件格式

1. GGUF 简介

GGUF 是一种用于存储推理模型的文件格式，主要用于加速模型加载和推理。
简单介绍其特点，适当了解，不深究：

单文件

GGUF将模型的所有必要信息（包括模型架构、权重、超参数、元数据等）都整合到一个文件中。
文件结构明确且所有数据都在一个文件，加快了模型的加载速度。

支持拓展，向下兼容

GGUF使用模块化设计，允许不破坏原有结构情况下，添加新模块。
读取文件时，可忽略新字段，向下兼容旧版本

支持内存映射（mmap）
包含加载模型的所有信息

2. GGUF 命名规范

第1位：模型基础名称或架构

llama，deepseek

第2位：模型参数规模

7B，13B，32B

第3位：微调标识

-chat：多轮对话优化 微调版本，适合聊天机器人。
-instruct：指令跟随数据 微调，擅长执行任务型指令，比如：摘要、翻译、问答。
-dpo：使用 直接偏好优化 技术微调，优化输出指令以更贴近人类偏好。
-orpo：使用 开放人类反馈强化学习 方式微调，效果类似 DPO ，但可能更开放。
-code：专为 编程任务 微调，擅长代码生成、补全、修复、解释。
-Qwen：说明该模型融合了 Qwen 数据风格，或是从 Qwen 模型迁移微调而来，可能有多语言能力。

第4位：模型版本号（可选）

-v1，-v2，-v0.1

第5位：量化编码方式或精度类型

-fp32 / -f32：32位浮点数，全精度
-fp16 / -f16：16位浮点数，半精度
-bf16：BFloat16 格式
-Q8_0：8位
-Q6_K：6位
-Q5_1：5位，精度比 Q5_0 更优
-Q5_0：5位
-Q4_K：4位，精度更好
-Q4_0：4位
-Q3_K：3位
-Q2_K：2位
——————————————————————
_K：使用 块量化，保留更多局部信息，精度更好。具体原理请自行学习。

第6位：文件类型（可选）

模型文件，-lora，-vocab

第7位：分片（可选）

用于大型模型按文件分片存储
00003-of-00009：第3片，共9片

3. GGUF 文件结构

GGUF文件采样 二进制 格式。

二进制格式与文本格式的区别，请自行学习

GGUF 文件主要由 文件头，元数据，张量信息，张量数据 组成。

3.1 文件头（Header）

大小：48 字节
采用 小端字节序 ，具体情况请自行学习。
————————————————————
前4位字节叫做：魔数（magic number）
接下来4位字节为：版本号（version）
接下来8位字节为：元数据条目数量（n_kv），元数据中的键值对数量

键值对的概念请自行学习。
具体例子：
小明读书证号：3001
张三读书证号：3002

接下来8位字节为：张量的数量（n_tensors）
后面的24位字节不做了解。感兴趣可自行学习。

4+4+8+8+24=48 位字节

实例（十六进制表示）：

47 47 55 46  02 00 00 00  0E 00 00 00 00 00 00 00  
32 00 00 00 00 00 00 00  80 00 00 00 00 00 00 00  
C0 10 00 00 00 00 00 00  00 20 10 00 00 00 00 00

47 47 55 46：魔数，ASCII：“GGUF”
02 00 00 00：版本号为：2
0E 00 00 00 00 00 00 00：元数据条目数量为：14
32 00 00 00 00 00 00 00：张量的数量为：50

3.2 元数据（Key-Value）

键值对 类型，存储模型的配置信息和描述性数据。
部分键值对：
general.architecture：模型基础名称或架构，llama
general.quantization_version：量化版本
[llm].context_length：上下文长度
[llm].block_count：注意力块数量
[llm].attention.head_count：注意力头数量
general.file_type：张量量化类型

3.3 张量信息

存储模型权重及相关参数。

张量名称
维度信息：如：[4096,512]
数据类型：如：FP32，Q4_K
数据偏移量：张量数据在文件中的起始位置

3.4 张量数据

存储模型实际参数值
实例：全精度浮点张量

结构：
[维度：2，2] + 数据类型：F32 + 数据：[0.25，-1.8，3.14，0.01]
二进制表示：
00 00 80 3E // 0.25 (IEEE754编码)
66 66 E6 BF // -1.8
C3 F5 48 40 // 3.14
7B 14 AE 3C // 0.01