BroadRouter

GGUF

更新于

GGUF 是一种二进制文件格式,用于存储语言模型,供 llama.cpp 等基于 GGML 的运行时推理。一个 GGUF 文件包含权重(通常已量化)以及加载模型所需的元数据,如分词器和架构信息,并且可以通过内存映射快速加载。

又称: GGUF 文件、GGUF 格式、GGUF 模型、GGUF 量化、llama.cpp 格式、GGUF file、GGUF format、llama.cpp format

如果你下载过模型在笔记本电脑上运行,那很可能是一个以 .gguf 结尾的文件。

工作原理

ggml 规范把 GGUF 描述为一种二进制格式,用于存储模型,供 GGML 及基于 GGML 的执行器推理,设计目标是快速加载和保存。它取代了更早的 GGML、GGMF 和 GGJT 格式。规范列出的目标包括:

  • 单文件。 模型无需额外文件即可分享和加载。
  • 兼容 mmap。 运行时可以对权重做内存映射,而不必复制。
  • 可扩展。 可以添加新的元数据,而不会破坏旧模型。
  • 信息完整。 加载模型所需的一切都在文件里。

GGUF 文件依次包含:文件头(魔数、格式版本、张量数和元数据数)、带类型的元数据键值对、记录张量名称、形状、类型和偏移量的表、对齐到边界的填充(默认 32 字节),最后是张量数据。

文件名遵循一套约定。规范中的示例 Mixtral-8x7B-v0.1-KQ2.gguf 可以拆分为基础名称、规模标签(8 个 7B 专家,参见混合专家模型)、版本和编码。

大多数 GGUF 文件都经过量化。Hugging Face 的表格列出了常见类型:

类型 每权重位数 说明
Q8_0 8 传统的就近取整,32 权重为一块
Q6_K 6.5625 k-quant 超级块
Q5_K 5.5 k-quant 超级块
Q4_K 4.5 k-quant 超级块
IQ4_XS 4.25 使用重要性矩阵
Q2_K 2.625 k-quant 超级块

为什么重要

  • 本地和边缘部署。 Hugging Face 列出 llama.cpp、LM Studio、GPT4All 和 Ollama 是使用 GGUF 的工具。在 CPU、Mac 或单张消费级 GPU 上运行开放权重模型,它是常见途径。
  • 分词器与权重一起分发。 因为元数据就在文件里,转换时对话模板或分词器设置有误或缺失,都可能改变输出质量。
  • 质量取决于量化类型。 同一个模型的 Q2 文件和 Q8 文件,在实际使用中并不是同一个模型。要同类相比。
  • 不同于 GPU 服务格式。 vLLM 等服务端引擎把 GGUF 列为支持的格式之一,但生产环境的 GPU 服务更常用 AWQ 或 FP8 等格式。

在 BroadNet Inference 上

BroadNet 的 API 通过 HTTP 提供模型服务;它不分发 GGUF 文件,你也从不需要自己加载权重。BroadNet 的模型目录报告,它在实验室中用 llama.cpp 以 GGUF Q4_K_M 运行过 Qwen3.8 27B,带视觉投影器和多 token 预测草稿模型,同时还在 AMD ROCm 上用 vLLM 运行了 AWQ INT4 版本。它没有说明公开 API 使用的是哪种格式。如果你在权衡本地 GGUF 部署和 API,自托管与 API 成本对比和开放权重模型与闭源模型介绍了其中的取舍。

常见问题

Q4_K 这样的名称是什么意思?

它是量化类型。Hugging Face 的表格把 Q4_K 描述为 4 位量化,由 8 个块组成超级块,每块 32 个权重,约合每个权重 4.5 位。位数越少,占用内存越少,通常质量损失也越大。

可以用 OpenAI API 格式调用 GGUF 模型吗?

文件本身不行。你需要把它加载到 llama.cpp 的 server、Ollama 或 LM Studio 等运行时中,由运行时提供服务。它暴露什么 API,请查看运行时的文档。

GGUF 和 safetensors 是一回事吗?

不是。Hugging Face 把 safetensors 描述为只存张量的格式,而 GGUF 在一个文件中同时编码了张量和一组标准化的元数据。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity