GGUF
GGUF 是 llama.cpp 用于存储 LLM 权重、分词器和元数据的单文件格式,通常会量化到 4 至 8 位,以适配本地硬件。
GGUF 是一种二进制文件格式,用于存储在 GGML(C 张量库)及基于它构建的工具上运行的模型;GGML 是 llama.cpp 背后的张量库。一个 GGUF 文件包含运行大型语言模型(LLM)所需的一切:架构和超参数、分词器词表、聊天模板,以及模型权重;权重通常经过模型量化,压缩到每个权重 2 至 8 位。llama.cpp 项目于 2023 年 8 月推出 GGUF,以取代早期的 GGML、GGMF 和 GGJT 格式。如今,GGUF 已成为分享开放权重模型的标准方式,可在笔记本电脑 CPU、Apple Silicon Mac 或消费级 GPU 上进行本地推理;Hugging Face 上已有数千个 GGUF 仓库。
GGUF 文件内部结构#
GGUF 规范按顺序定义了四个部分。文件头包含魔数 GGUF、格式版本(目前为 3),以及张量和元数据条目的数量。接下来是带类型的键值元数据,例如 general.architecture、llama.context_length、tokenizer.ggml.tokens 和 tokenizer.chat_template;这些元数据会将模型的分词和提示格式嵌入文件本身。随后是一个表格,列出每个张量的名称、形状、数据类型和偏移量;最后是张量数据,默认会填充至 32 字节对齐,让运行时可以通过内存映射读取文件并几乎即时加载。读取程序按键查找元数据,因此无需破坏旧文件,就能添加新架构和字段。
每个张量都有自己的类型,因此一个文件可以混合使用不同精度。由 llama.cpp 仓库维护的 gguf Python 包可以读写这种格式,并实现多种量化类型:
import numpy as np
from gguf import GGMLQuantizationType, GGUFReader, GGUFWriter
from gguf.quants import dequantize, quantize
weights = np.random.default_rng(0).standard_normal((1024, 1024)).astype(np.float32)
# A GGUF file holds metadata key-value pairs plus named tensors, each with its own type
writer = GGUFWriter("tiny.gguf", arch="llama")
writer.add_context_length(4096)
for qtype in [GGMLQuantizationType.F16, GGMLQuantizationType.Q8_0, GGMLQuantizationType.Q4_0]:
writer.add_tensor(f"weight.{qtype.name}", quantize(weights, qtype), raw_dtype=qtype)
writer.write_header_to_file()
writer.write_kv_data_to_file()
writer.write_tensors_to_file()
writer.close()
# Read the file back: metadata keys, then each tensor's bits per weight and rounding error
reader = GGUFReader("tiny.gguf")
print([name for name in reader.fields if not name.startswith("GGUF.")])
for tensor in reader.tensors:
error = np.abs(dequantize(tensor.data, tensor.tensor_type).reshape(weights.shape) - weights).mean()
print(f"{tensor.tensor_type.name}: {8 * tensor.n_bytes / weights.size:.1f} bits per weight, mean error {error:.4f}")它会列出两个元数据键 general.architecture 和 llama.context_length,然后报告各格式的数据: F16 为每个权重 16.0 位、平均误差 0.0001;Q8_0 为 8.5 位、误差 0.0045;Q4_0 为 4.5 位、误差 0.0719。Q8_0 和 Q4_0 每 32 个权重组成一个块,每块使用一个 FP16 缩放因子,因此额外增加了半个位。
量化类型#
GGUF 的量化类型分为三代。Q4_0 和 Q8_0 等早期块格式为每 32 个权重使用一个缩放因子。Q4_K 和 Q6_K 等 K 量化格式将块组合成包含 256 个权重的超块,并对缩放因子进行量化;例如 Q4_K_M 这样的文件名表示一种混合格式,其中最敏感的张量会保留更高精度。IQ2_XXS 和 IQ4_XS 等 I 量化格式可达到每个权重约 2 至 4 位,通常会参考重要性矩阵;llama-imatrix 会根据示例文本计算该矩阵,让影响最大的权重保留最高精度。较新的格式还包括 MXFP4,即 OpenAI 发布 gpt-oss 时使用的4 位浮点格式。大多数已发布的 GGUF 文件都来自同一种转换流程:
GGUF 与其他模型格式的区别#
- GGML、GGMF 和 GGJT: 早期的 llama.cpp 格式会将超参数存储为无类型列表,且没有架构字段,因此添加参数就会破坏现有文件。
- Safetensors: Hugging Face 用于安全存储原始张量的格式,通常采用全精度或半精度;配置和分词器则保存在单独的文件中。
- ONNX: 将完整计算图与权重一并存储,因此任何兼容 ONNX 的运行时都能执行模型,无需特定架构的代码。
运行 GGUF 模型#
llama.cpp 可以通过命令行运行 GGUF 文件,也可以作为 llama-server 运行;后者提供兼容 OpenAI 的 API。它还可以将任意数量的层卸载到 GPU,其余层则在 CPU 上运行,因此即使模型大于 GPU 内存,也仍可运行。Ollama 和 LM Studio 提供模型库和聊天界面,用于运行 GGUF 模型;Hugging Face Hub 则会在浏览器中显示每个 GGUF 文件的元数据和张量类型。本地推理会让提示保留在设备上,这对数据隐私和离线边缘 AI应用很重要。Ultralytics LLM 接口可以通过 llama-server 或 Ollama 提供的 OpenAI 兼容 Chat Completions 端点调用 GGUF 模型,因此 YOLO26 流水线可以让本地模型描述检测结果,而无需将数据发送到云端 API。这种格式也不只用于语言模型:ComfyUI-GGUF 自定义节点会从 GGUF 文件加载 FLUX.1 等量化扩散模型,让模型能够装入消费级 GPU 的内存。










