获取 YOLO 许可
返回 Ultralytics 术语表

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 的内存。

探索解决方案

体育领域的计算机视觉

体育领域的计算机视觉

了解 Ultralytics YOLO 如何通过球员和球追踪、表现分析、教练洞察及运动员康复,推动体育视觉技术的发展。
了解详情
航空影像计算机视觉

航空影像计算机视觉

使用 Ultralytics YOLO 将无人机和航空影像转化为农业、水产养殖、保护工作和地理空间分析的实时洞察。
了解详情
航空航天中的计算机视觉

航空航天中的计算机视觉

使用 Ultralytics YOLO 将计算机视觉应用于航空航天领域,包括飞机检查、跑道 FOD 检测、机场地面作业和复合材料缺陷检测。
了解详情
安防领域的计算机视觉

安防领域的计算机视觉

使用 Ultralytics YOLO 模型守护每个场所。视觉 AI 可用于周界监控、威胁检测、车牌识别和工作场所安全。
了解详情
机器人领域的计算机视觉

机器人领域的计算机视觉

使用 Ultralytics YOLO 模型提升智能机器的能力。机器人领域的视觉 AI 可用于自主导航、感知、目标跟踪和实时控制。
了解详情
物流中的计算机视觉

物流中的计算机视觉

借助 Ultralytics YOLO 模型优化物流流程。视觉 AI 可用于包裹检查、分拣、车辆跟踪和仓库安全实时监控。
了解详情
零售中的计算机视觉

零售中的计算机视觉

借助 Ultralytics YOLO 模型重新构想零售。视觉 AI 可用于库存跟踪、货架监控、排队管理和更深入的客户洞察。
了解详情
医疗领域的计算机视觉

医疗领域的计算机视觉

借助 Ultralytics YOLO 模型构建医疗解决方案。医疗领域的视觉 AI 可加快医学影像处理、优化诊断并监测患者。
了解详情
制造业中的计算机视觉

制造业中的计算机视觉

利用 Ultralytics YOLO 模型优化制造流程。视觉 AI 可用于质量控制、缺陷检测、个人防护装备合规检查和装配线自动化。
了解详情
汽车领域的计算机视觉

汽车领域的计算机视觉

利用 Ultralytics YOLO 模型在汽车领域应用计算机视觉。视觉 AI 可提升道路安全、驾驶辅助和车辆自动化水平,让道路更智能。
了解详情
农业中的计算机视觉

农业中的计算机视觉

借助 Ultralytics YOLO 模型,将视觉 AI 引入智慧农业。为作物监测、牲畜追踪和精准农业提供支持,从而提高产量并实现更智能的生产。
了解详情

让我们携手构建 AI 的未来!

开启你的旅程,迎接机器学习的未来