GGUF（GGML通用文件）是一种二进制文件格式，旨在将张量和元数据存储于单个文件中，从而实现模型数据的快速保存与加载。该格式由llama.cpp项目于2023年8月引入，旨在随着对更多模型架构的支持而提升向后兼容性。GGUF取代了该项目早期使用的格式（如GGML），通常通过转换使用其他机器学习库（如PyTorch）开发的模型来生成。该格式已成为分发用于本地推理的量化大型语言模型的标准，并得到llama.cpp、Ollama、LM Studio、GPT4All、Jan和koboldcpp等工具的原生支持。截至2026年，Hugging Face上托管了数以万计的GGUF检查点，并提供了一流的集成支持，包括元数据查看器、推理端点服务和JavaScript解析器库。
历史
llama.cpp项目使用的模型文件格式经历了四个命名阶段：GGML、GGMF、GGJT和GGUF。最初的GGML格式是一个轻量级张量容器，将模型超参数和分词器信息硬编码在加载器中；添加对新模型架构或量化方案的支持通常需要修改代码，这会破坏与现有文件的兼容性。
随着llama.cpp在2023年期间扩展以支持Llama之外的更多架构（包括Mistral、Falcon等），这些限制变得越来越难以管理。GGUF于2023年8月21日作为不向后兼容的继任者被引入，其规范通过ggerganov/ggml仓库中的拉取请求#302正式确定。该格式继承了GGJT的整体布局，但将其扁平的超参数列表替换为结构化的键值元数据系统，从而允许在不修改加载器或破坏旧模型的情况下添加新字段（如架构细节、分词器词汇表、训练参数）。
该格式本身经历了三个内部版本。版本1确立了基本结构；版本2添加了显式对齐填充以支持内存映射；版本3（当前版本）添加了可选的大端支持。
设计
GGUF专注于量化，即降低模型权重的精度。这可以减少内存使用并提高速度，但代价是模型精度降低。该格式的设计特点包括：
- 自包含 - 单个文件包含张量、分词器以及加载和运行模型所需的所有元数据，无需附带配置文件。
- 可内存映射 - 张量数据对齐（默认对齐到32字节边界），以便权重可以通过指针直接访问，而无需将整个文件加载到RAM中，从而允许通过操作系统分页提供大于可用内存的模型。
- 可扩展 - 键值元数据块允许添加新字段，而不会破坏与旧读取器的兼容性。
GGUF支持2位到8位的量化整数类型、常见的浮点数据格式（如float32、float16和bfloat16）以及1.58位量化。多种“K-quant”变体（如Q4_K、Q5_K和Q6_K）使用基于块的方案，每个超级块具有单独的缩放和最小值，通常在给定位宽下比更简单的传统量化（如Q4_0和Q8_0）提供更好的质量。GGUF包含运行GPT类语言模型所需的信息，如分词器词汇表、上下文长度、张量信息和其他属性。
文件结构
GGUF文件由四个顺序部分组成：固定大小的头部、键值元数据块、张量信息块和张量数据本身。
字节级结构（小端）
在版本3之前，文件隐式使用小端；版本3允许大端存储，但不包含指示字节序的标志，因此必须从上下文中推断。
#### 元数据块
元数据块是一系列类型化的键值对。键是命名空间字符串（例如general.*、tokenizer.*或架构特定的前缀如llama.*），值可以是标量、字符串或数组（包括多维数组）。
#### 张量信息块
对于每个张量，信息块存储其名称、维度数、形状、数据类型以及后续tensor_data[]区域中的字节偏移量。命名方案跨架构标准化（例如blk.0.ffn_gate.weight），以便加载器无论源框架如何都能定位权重。
#### 张量数据
张量数据在信息块之后，并从下一个对齐边界开始。对齐值本身存储在元数据的general.alignment键下；如果不存在，则默认为32字节。以这种方式对齐数据是文件可直接内存映射的原因：张量权重可以通过指针读取而无需额外复制，这对于SIMD操作、GPU DMA传输和CPU缓存效率至关重要。
工具
存储在其他框架中的模型通常使用llama.cpp附带的convert_hf_to_gguf.py脚本转换为GGUF，该脚本读取Hugging Face检查点（通常为safetensors格式）并生成所选基础精度（如f16或bf16）的GGUF文件。生成的文件随后可以使用llama-quantize工具重新量化为GGUF整数格式之一，而非常大的模型可以使用llama-gguf-split分片到多个文件中。
llama.cpp项目还提供了C/C++ API（在ggml/include/gguf.h中声明）和Python包gguf-py，用于以编程方式读写GGUF文件。
采用
GGUF是llama.cpp和Ollama的原生模型格式，后者使用llama.cpp作为其推理后端；从Ollama注册表拉取的模型内部是GGUF文件，并且可以通过引用hf.co/{user}/{repo}来加载来自Hugging Face的任意GGUF文件。其他直接使用GGUF的推理应用包括LM Studio、GPT4All、Jan和koboldcpp。
Hugging Face在其模型中心将这种格式作为一流公民支持，提供GGUF元数据查看器、按gguf标签过滤、推理端点集成以及大量社区上传的GGUF检查点集合。