AI 概念 · GGUF - 模型文件格式

官方介绍

GGUF is a file format for storing models for inference with GGML and executors based on GGML.
GGUF 是一种模型文件格式，用于存储供 GGML 以及基于 GGML 的执行器（executors）进行推理的模型。
GGUF is a binary format that is designed for fast loading and saving of models, and for ease of reading. Models are traditionally developed using PyTorch or another framework, and then converted to GGUF for use in GGML.
GGUF 是一种二进制格式，其设计目标是实现模型的快速加载和保存，同时便于读取。模型通常使用 PyTorch 或其他框架进行开发，然后转换为 GGUF 格式，以便在 GGML 中使用。
It is a successor file format to GGML, GGMF and GGJT, and is designed to be unambiguous by containing all the information needed to load a model.
GGUF 是 GGML、GGMF 和 GGJT 等早期文件格式的后继格式。它通过在文件中包含加载模型所需的全部信息，力求消除格式上的歧义。
It is also designed to be extensible, so that new information can be added to models without breaking compatibility.
GGUF 还具有可扩展性（extensible）：可以向模型文件中加入新的信息，而不会破坏已有的兼容性。

理解

GGUF 一种用于存储机器学习模型的二进制文件格式，专为快速加载和保存模型而优化，因此在推理场景中效率很高。
可以在单个文件中保存模型的 Tensor（权重等张量数据）和 Metadata（模型架构、Tokenizer、参数等元数据），并针对模型数据的快速加载与保存进行了设计。
GGUF 专为配合 GGML 及其他执行引擎使用而设计，由 ggerganov 开发，同时也是也是 llama.cpp （一个广受欢迎的 C/C++ 大语言模型推理框架）的开发者。
GGML 是一个面向机器学习的 Tensor (张量) 库，强调 C/C++、跨平台、低依赖、本地高效推理，并支持 CPU、GPU 等多种后端以及 2～8 bit 等量化类型，llama.cpp 等项目常使用 GGML 生态。
常和量化一起出现，但 GGUF 不是量化方法，但非常适合保存和分发量化模型，经常看到 Q4_K_M、Q5_K_M、Q8_0 等量化模型以 .gguf 文件提供。
已经成为本地 LLM 推理生态中非常常见的模型格式，可被 llama.cpp、Ollama、LM Studio 等工具直接使用；

GGML/llama.cpp 生态 → GGUF 文件格式 → Tensor + Metadata → 常用于量化模型 → .gguf → 文件名中通常直接体现模型规模、微调类型、量化 Encoding 和分片。

GGUF Naming Convention

Naming Convention 最大的价值：不用打开模型卡，仅从文件名就能获得模型的核心信息。比如：Qwen3-8B-Instruct-Q4_K_M.gguf，快速得出以下结论：

Qwen3 系列 → 80 亿参数级 → 指令微调模型 → Q4_K_M 量化/编码 → GGUF 格式。

规则：[<Sidecar>]<BaseName><SizeLabel><FineTune><Version><Encoding><Type><Shard>.gguf，每个部分通常使用 - 进行分割：

[附属模块]-模型名-参数规模-用途-版本-编码/量化-文件类型-分片.gguf

该约定描述的是 GGUF 文件名里各个字段的标准写法，是为了让人类快速阅读，不保证所有现实中的 GGUF 文件名都能严格按照这个规则解析。

但实际社区发布的文件很多是"约定俗成"而非严格照搬官方规范，经常能看到变体写法。

Qwen3-8B-Instruct-Q4_K_M.gguf
│     │  │        │       └─ GGUF 文件格式
│     │  │        └───────── Q4_K_M 编码/量化
│     │  └────────────────── Instruct 微调
│     └───────────────────── 8B 参数规模
└─────────────────────────── 模型名称

	标记	用途	备注
1	`Sidecar`	附属模块前缀	可选 mmproj:多模态投影器； mtp：Multi-Token Prediction heads，多token预测头；
2	`BaseName`	模型名	比如：Qwen3
3	`SizeLabel`	模型参数规模	8B、14B、32B、70B等； K = Thousand 千 M = Million 百万 B = Billion 十亿 T = Trillion 万亿 Q = Quadrillion 千万亿
4	`FineTune`	表示模型进行了什么类型/用途的微调	没有固定枚举值，以下是社区里最常见、约定俗成的写法：对话/指令类 - `Instruct`:指令微调,擅长遵循单轮指令 - `Chat`:对话微调,针对多轮对话优化 - `RP` / `Roleplay`:角色扮演微调推理/思维链类 - `Reasoning`:强化推理能力的微调 - `Thinking`:带显式思维链输出的微调代码/专业领域类 - `Coder` / `Code`:代码生成微调 - `Math`:数学能力微调内容风格类 - `Uncensored`:去审查/放松内容限制的微调(你之前那个例子里就有) - `Abliterated`:一种特定的"去拒绝"技术处理(不完全等同于常规微调,但也常标注在这个位置) 基座/未微调 - `Base`:表示未经指令/对话微调的基座模型(有时也会省略这个字段,直接不写代表基座)
5	`Version`	版本号	可选；表示模型的版本号,格式为 `v<主版本号>.<次版本号>`；该字段可以从 gguf 元数据中的 `general.version` 推导得出；
6	`Encoding`	模型权重采用什么编码/量化方式保存；表示该模型所采用的权重编码方案；不过具体的内容、类型混合方式以及排列组合方式是由使用者的代码决定的,会根据项目需求有所不同；	最核心的字段，常见：F16、BF16、Q8_0、Q6_K、Q5_K_M、Q4_K_M、Q4_K_S、Q3_K_M； Q4、Q5、Q8 描述的是模型权重经过量化后，大致用多少 bit 来表示。数字越小，通常模型越小、内存/显存需求越低，但信息损失越大。具体参见 Encoding 解释
7	`Type`	文件本身是什么类型的 GGUF 文件、用途是什么	- 不写:代表这是一个正常的、完整的 GGUF 张量模型文件(也就是最常见的情况)； - `LoRA`:表示这个 GGUF 文件是一个 LoRA 适配器(GGUF file is a LoRA adapter),而不是完整模型,需要搭配基础模型加载使用； - `vocab`:表示这个 GGUF 文件只包含词表(vocab)数据和元数据(GGUF file with only vocab data and metadata),不含权重张量；
8	`Shard`	分片	可选表示该模型已被拆分为多个分片文件,格式为 `<分片编号>-of-<分片总数>`； - ShardNum(分片编号):该分片在整个模型中的位置。必须是补零至 5 位的数字。 - 分片编号始终从 `00001` 开始(例如,第一个分片始终是 `00001-of-XXXXX`,而不是 `00000-of-XXXXX`)。 - ShardTotal(分片总数):该模型的分片总数。必须是补零至 5 位的数字。

Encoding 解释

假设模型有 8B = 80 亿 参数，每个参数权重使用 FP16，那么：

\begin{aligned} &8B \times 16bit \\[1em] &\text{粗略估算： } 8\times10^9\times2\ bytes \approx16GB \\[1em] &\text{权重约： } 16GB \\[1em] &\text{变成 8 bit： } 8B\times1\ byte\approx8GB \\ &\text{变成 4 bit： } 8B\times0.5\ byte\approx4GB \\[1em] &\text{可以建立一个非常有用的粗算公式： } \\[1em] &\text{权重大小} \approx &\text{参数量}\times\frac{\text{bits}}{8} \end{aligned}

模型	FP16	8 bit	4 bit
7B	~14 GB	~7 GB	~3.5 GB
14B	~28 GB	~14 GB	~7 GB
32B	~64 GB	~32 GB	~16 GB

Q = Quantization，量化。

高精度 / 大体积
        ↑
FP16
Q8
Q6
Q5
Q4      ← 很常见
Q3
Q2
        ↓
低精度 / 小体积

一般而言：

bit 越高

→ 文件更大
→ 内存/显存占用更高
→ 通常模型质量保留更多

bit 越低

→ 文件更小
→ 内存/显存占用更低
→ 更容易运行大模型
→ 通常量化损失增加

Q4，大约是 4-bit 量化级别；

Q4_K_M，使用 GGML 的 K-quant 系列方案，以 4-bit 为主体，并采用 M 对应的 tensor-type mixture。

K 表示 GGML/llama.cpp 后来引入的一套 K-quant（K-quants）量化体系。 K-quants 会采用更复杂的分块、scale 等量化表示，并允许模型中的不同 Tensor 使用不同量化类型。

S/M/L 反映的是：模型中的不同 Tensor 使用怎样的量化类型组合（quantization mix）。

Q4_K_M
│  │ │
│  │ └── M：一种中等/混合量化配置
│  │
│  └──── K：K-quant 量化体系
│
└─────── Q4：以 4-bit 级别量化为主体

              模型质量
                 ↑
 
Q8_0         较高
Q6_K
Q5_K_M
Q5_K_S
Q4_K_M       ← 常见平衡点
Q4_K_S
Q3_K_M
Q3_K_S
Q2_K
 
                 ↓
          文件体积 / 内存需求降低

官方介绍

理解

GGUF Naming Convention

Encoding 解释

相关连接