GGUF（GGUF 格式）

GGUF 是专为本地 LLM 推理设计的二进制容器格式，于 2023 年 8 月取代旧版 GGML 格式正式发布。

• 单文件封装：将模型权重、词表（tokenizer）、架构参数、量化配置全部打包进一个 .gguf 文件，无需额外配置文件
• 向前兼容：采用键值元数据结构，新增字段不破坏旧加载器
• 跨平台：同一文件可在 CPU（仅内存）、混合 CPU+GPU 或纯 GPU 模式下运行
• 广泛采用：Ollama、LM Studio、GPT4All、koboldcpp、Jan 等工具原生支持，Hugging Face 提供专用元数据查看器
• 事实标准：截至 2026 年，Hugging Face 上已托管数万个 GGUF 格式检查点

一个 GGUF 文件由四段顺序结构组成，加载器可线性读取，无需随机访问。

• 魔数与头部：固定标识符 GGUF + 版本号，用于格式检测与版本校验
• 键值元数据块：存储架构类型（如 llama、mistral）、上下文长度、注意力头数、词表内容等；采用自描述类型系统，扩展字段无需修改加载器
• 张量信息块：列举所有张量的名称、形状、数据类型（量化级别）和在文件中的偏移量
• 张量数据体：连续存储量化后的权重数据，按内存对齐排列以实现 mmap（内存映射）快速加载
• 内存映射加载：支持按需加载张量，大幅缩短冷启动时间

GGUF 内置多种量化等级，命名格式为 Q{位数}_{变体}，兼顾模型质量与硬件限制。

• Q4_0 / Q5_0：传统线性量化，文件最小，适合极低 VRAM 场景，质量损失较明显
• Q4_K_M / Q5_K_M：K-quant 混合精度，关键层（注意力层、输出层）保留更高精度，整体质量显著优于同位数传统量化
• Q8_0：8 位量化，质量接近 FP16，文件约为 FP32 的一半，推荐 16 GB+ 显存使用
• F16 / BF16：半精度浮点，无量化损失，质量最高，适合推理服务或微调场景
• IQ（I-quant）系列：采用向量量化，相同位数下压缩率更高，为新一代量化算法

GGUF 在本地推理和边缘部署场景中应用广泛，覆盖个人开发者到生产级离线推理。

• 消费级 PC 本地运行：通过 Ollama 或 LM Studio 一键下载并运行量化模型，无需 GPU
• 边缘设备与端侧推理：Q4/Q5 量化使模型可在笔记本 CPU 或 NPU 上运行，适用于隐私敏感场景
• 离线与私有化部署：企业在无网络或安全隔离环境中部署 LLM，GGUF 单文件易于分发和版本管理
• 快速模型实验：研究者和开发者从 Hugging Face 下载社区量化模型，快速验证效果
• 嵌入式 Agent 系统：结合 llama.cpp 后端作为本地 LLM 推理引擎，驱动轻量 Agent 工作流

GGUF 与其他常见模型格式各有侧重，需根据使用场景选择。

• GGUF vs GGML：GGML 是 GGUF 的前身，已废弃；GGUF 增加了键值元数据和向前兼容性，现代工具均不再支持 GGML
• GGUF vs SafeTensors：SafeTensors 是 Hugging Face 推出的安全张量格式，主要用于训练和 transformers 生态推理，不含词表和量化元数据；GGUF 专为 llama.cpp 生态本地推理优化
• GGUF vs ONNX：ONNX 是跨框架模型交换格式，侧重计算图描述；GGUF 专注权重存储与量化，推理效率更高
• GGUF vs AWQ/GPTQ：AWQ 和 GPTQ 是量化方法，通常与 PyTorch 或 vLLM 配合；GGUF 是完整格式，量化算法内嵌其中
• 关键优势：单文件、可 mmap、支持 CPU 推理，是 GGUF 在本地部署场景的核心竞争力

GGUF 有其适用边界，使用时需注意以下误区和限制。

• 误区：GGUF 等于量化——GGUF 是文件格式，F16/BF16 的 GGUF 文件无量化损失；量化是可选的压缩手段
• 误区：位数越低越好——过低量化（Q2、Q3）会显著损害模型质量，生产场景通常选 Q4_K_M 及以上
• 训练不支持：GGUF 为推理格式，不支持反向传播和梯度计算，不能直接用于微调
• 多模态支持有限：视觉-语言模型的图像编码器部分对 GGUF 的支持仍在完善中
• 工具链依赖：主要绑定 llama.cpp 生态；TensorRT、vLLM 等高性能推理框架需转换为其他格式

GGUF 的演化与本地 LLM 推理生态的成熟紧密相连。

• 2023 年 3 月：llama.cpp 项目发布，首次实现消费级硬件运行 LLaMA，使用旧版 GGML 格式
• 2023 年 8 月：GGUF 格式正式发布（ggml PR #302），替代 GGML，引入键值元数据和多架构支持
• 2023 年下半年：Mistral、Falcon、Code Llama 等模型社区量化版以 GGUF 格式大规模分发
• 2024 年：Ollama、LM Studio 将 GGUF 作为核心格式；Hugging Face 上线 GGUF 元数据查看器；K-quant 和 I-quant 量化算法加入
• 2025–2026 年：GGUF 成为本地 LLM 部署事实标准，多模态和更大上下文窗口的 GGUF 支持持续完善