llama.cpp： GGUF格式及模子量化参数介绍

GGUF格式介绍

GGUF（GPT-Generated Unified Format）是推理框架llama.cpp 中使用的一种专为大语言模子设计的二进制文件格式，旨在实现模子的快速加载和生存，同时易于读取。GGUF格式的特点：

• 单文件部署：模子可以轻松分发和加载，不需要任何外部文件来提供额外信息。
  
• 可扩展性：可以在不破坏与现有模子的兼容性的情况下，向基于GGML的执行器添加新功能或向GGUF模子添加新信息。
  
• mmap兼容性：可以使用mmap加载模子，以实现快速加载和生存。
  
• 易于使用：可以使用少量代码轻松加载和生存模子，无论使用何种语言，无需外部库。
  
• 完整信息：加载模子所需的全部信息都包含在模子文件中，用户无需提供任何额外信息。
  

GGUF文件的结构如下图所示：

紧张包括以下几个部分：

• 文件头（Header）：标识文件类型（GGUF）、版本号、张量数量。
  
• 元数据段（Metadata）：JSON-like键值对存储模子信息。
  
• 张量数据段（Tensors）：按量化类型存储模子权重。
  

它们使用general.alignment元数据字段中指定的全局对齐，如果需要，文件将用0x00字节填充到general.alignment的下一个倍数。除非另有说明，字段（包括数组）将按顺序连续写入，不进行对齐。模子默以为小端序，当然它们也可以是大端序以供大端序计算机使用，在这种情况下，全部值（包括元数据值和张量）也将是大端序。
GGUF定名约定

GGUF遵循<BaseName><SizeLabel><FineTune><Version><Encoding><Type><Shard>.gguf的定名约定，其中每个组件由-分隔（如果存在）,这种定名方式的终极目的是为了让人们能够快速了解模子的关键信息。
每个组件的含义如下：

• BaseName：模子基础类型或架构的描述性名称。
  
  
  
  • 可以从gguf元数据general.basename派生，将空格更换为连字符。
    
  
  
• SizeLabel：参数权重种别（在排行榜中有用），表示为<专家数量>x<数量><量级前缀>。
  
  
  
  • 如果可用，可以从gguf元数据general.size_label派生，如果缺失则进行计算。
    
  • 支持带有单个字母量级前缀的十进制点的四舍五入，以帮助显示浮点指数，如下所示：
    
    
    
    • Q：千万亿参数。
      
    • T：万亿参数。
      
    • B：十亿参数。
      
    • M：百万参数。
      
    • K：千参数。
      
    
    
  • 可以根据需要附加额外的-<属性><数量><量级前缀>以指示其他感爱好的属性。
    
  
  
• FineTune：模子微调目标的描述性名称（例如Chat、Instruct等）。
  
  
  
  • 可以从gguf元数据general.finetune派生，将空格更换为连字符。
    
  
  
• Version：表示模子版本号，格式为v<主版本>.<次版本>。
  
  
  
  • 如果模子缺少版本号，则假设为v1.0（初次公开发布）。
    
  • 可以从gguf元数据general.version派生。
    
  
  
• Encoding：指示应用于模子的权重编码方案。内容、类型混淆和排列由用户代码决定，可以根据项目需求而有所差别。
  
• Type：指示gguf文件的类型及其预期用途。
  
  
  
  • 如果缺失，则文件默以为典型的gguf张量模子文件。
    
  • LoRA：GGUF文件是LoRA适配器。
    
  • vocab：仅包含词汇数据和元数据的GGUF文件。
    
  
  
• Shard：（可选）指示模子已被拆分为多个分片，格式为<分片编号>-of-<总分片数>。
  
  
  
  • 分片编号：此模子中的分片位置。必须用零填充为5位数字。
    
    
    
    • 分片编号始终从00001开始（例如，第一个分片总是从00001-of-XXXXX开始，而不是00000-of-XXXXX）。
      
    
    
  • 总分片数：此模子中的总分片数。必须用零填充为5位数字。
    
  
  

下面是对几个GGUF模子文件名的解释：

• Mixtral-8x7B-v0.1-KQ2.gguf：
  
  
  
  • 模子名称：Mixtral
    
  • 专家数量：8
    
  • 参数数量：7B
    
  • 版本号：v0.1
    
  • 权重编码方案：KQ2
    
  
  
• Hermes-2-Pro-Llama-3-8B-F16.gguf：
  
  
  
  • 模子名称：Hermes 2 Pro Llama 3
    
  • 专家数量：0
    
  • 参数数量：8B
    
  • 版本号：v1.0
    
  • 权重编码方案：F16
    
  • 分片：不适用
    
  
  
• Grok-100B-v1.0-Q4_0-00003-of-00009.gguf：
  
  
  
  • 模子名称：Grok
    
  • 专家数量：0
    
  • 参数数量：100B
    
  • 版本号：v1.0
    
  • 权重编码方案：Q4_0
    
  • 分片：3 out of 9 total shards
    
  
  

GGUF定名规则约定全部模子文件都应该有基本名称、大小标签和版本，以便能够轻松验证其是否符合GGUF定名约定。例如，如果省略版本号，那么编码很容易被误以为是微调。
GGUF与其他格式对比

格式特点典型场景GGUF专为 CPU 推理优化，支持量化，元数据丰富本地部署（llama.cpp）PyTorch .pt原生训练格式，未量化，依赖 GPU 和 PyTorch 情况模子训练/微调HuggingFace .safetensors安全序列化格式，未量化，需加载完整模子到内存云端推理（GPU 加快）ONNX跨框架通用格式，支持硬件加快，但量化功能有限跨平台部署 GGUF格式转换

GGUF格式是推理框架llama.cpp使用的格式，但是通常模子是使用PyTorch之类的训练框架训练的，生存的格式一般使用HuggingFace的safetensors格式，因此使用llama.cpp进行推理之前需要把其他格式的模子转换为GGUF格式。
下面以DeepSeek R1的蒸馏模子DeepSeek-R1-Distill-Qwen-7B为例介绍怎样将模子转换为GGUF格式。
起首从魔搭社区（或HuggingFace）下载模子：

1. pip install modelscope
2. modelscope download --model deepseek-ai/DeepSeek-R1-Distill-Qwen-7B --local_dir DeepSeek-R1-Distill-Qwen-7B

复制代码

下载好的模子是以safetensors格式存放的，可以调用llama.cpp的转换脚本把模子转换为GGUF格式：

1. # 安装python依赖库
2. pip install -r requirements.txt
3. # 转换模型
4. python convert_hf_to_gguf.py DeepSeek-R1-Distill-Qwen-7B/

复制代码

转换乐成后，在该目录下会天生一个FP16精度、GGUF格式的模子文件DeepSeek-R1-Distill-Qwen-7B-F16.gguf。
如果不想本身转模子，也可以在魔搭社区或HuggingFace上找带gguf后缀的模子，大概使用HuggingFace的gguf-my-repo进行转换，网址如下：

1. https://huggingface.co/spaces/ggml-org/gguf-my-repo

复制代码

在该界面的Hub Modeil ID框中查找你想转的模子，然后Quantization Method中选择你想要的模子量化方式（关于GGUF模子的各种量化参数将在下文进行介绍），末了点击Submit就可以开始模子转换了。

GGUF量化参数介绍

llama.cpp的模子量化方法紧张采用了分块量化（Block-wise Quantization）和K-Quantization算法来实现模子压缩与加快，其核心计谋包括以下关键技能：

• 分块量化（Block-wise Quantization）
  该方法将权重矩阵划分为固定大小的子块（如32或64元素为一组），每个子块独立进行量化。通过为每个子块分配独立的缩放因子（Scale）和零点（Zero Point），有用淘汰量化偏差。例如，Q4_K_M表示每个权重用4比特存储，且子块内采用动态范围调解。
  
• K-Quantization（混淆精度量化）
  在子块内部进一步划分更小的单元（称为“超块”），根据数值分布动态选择量化参数。例如，Q4_K_M将超块拆分为多个子单元，每个子单元使用差别位数的缩放因子（如6bit的缩放因子和4bit的量化值），通过混淆精度均衡精度与压缩率。
  
• 紧张性矩阵（Imatrix）优化
  通过分析模子推理过程中各层激活值的紧张性，动态调解量化计谋。高紧张性区域保存更高精度（如FP16），低紧张性区域采用激进量化（如Q2_K），从而在整体模子性能丧失可控的条件下实现高效压缩。
  
• 量化类型分级计谋
  提供Q2_K至Q8_K等多种量化级别，其中字母后缀（如_M、_S）表示优化级别：
  
  
  
  • Q4_K_M：中等优化级别，均衡推理速率与精度（常用保举）。
    
  • Q5_K_S：轻量化级别，侧重淘汰内存占用
    
  
  

在GGUF的量化类型定名如 Q4_K_M中，Q4表示模子的主量化精度为4比特，K 和 M 分别代表量化过程中的分块计谋（Block-wise Quantization）和混淆精度优化级别。以下是具体解释：
K 的含义：分块量化（Block-wise Quantization）

• 核心思想：将权重矩阵划分为多个小块（Block），对每个块单独进行量化，以降低整体偏差。
  
• 技能细节：
  
  
  
  • 每个块（Block）的大小通常为32/64/128个权重值（具体数值由量化算法决定）。
    
  • 块内共享量化参数（如缩放因子和零点），淘汰存储开销。
    
  
  
• 上风：
  
  
  
  • 相比全矩阵量化，分块量化能保存更多局部细节，降低信息丧失。
    
  • 进步量化后模子的天生质量和数学能力。
    
  
  

M 的含义：混淆精度优化级别
GGUF在分块量化的基础上，进一步通过混淆差别精度来提升效果，M 表示混淆计谋的强度品级为中等，另外还有S和L两个品级：
后缀全称说明SSmall/Simple轻度混淆，仅对关键块使用更高精度（如 6-bit），其他块用低精度（如 4-bit）MMedium中等混淆，更多块使用高精度，均衡速率和精度（保举默认选择）LLarge高度混淆，最大化高精度块比例，靠近原始模子精度（速率最慢） 以下是关于 GGUF 量化方法选择计谋的具体剖析，包含差别场景下的量化建议和性能对比：
GGUF量化方法分类与特性

量化类型比特数内存占用（以7B模子为例）推理速率精度保持适用场景Q2_K2-bit~2.8GB最快低极低资源装备（手机）Q3_K_M3-bit~3.3GB快中低快速测试/简单问答Q4_04-bit~3.8GB快中等均衡型通用场景Q4_K_M4-bit~4.0GB中等中高保举默认选择Q5_05-bit~4.5GB中等高复杂任务（代码天生）Q5_K_M5-bit~4.7GB中等很高高质量天生（保举首选）Q6_K6-bit~5.5GB较慢靠近原始学术研究/最小精度丧失Q8_08-bit~7.0GB最慢无损基准测试/对比实验 选择建议

• 优先选择 _K_M 后缀：在相同比特数下，质量和速率均衡最佳。
  
• 极端资源场景：可用 _K_S 捐躯少量质量换取更快速率。
  
• 研究用途：使用 _K_L 或非混淆量化（如 Q6_K）作为基准。
  

按硬件资源选择：

• 手机/嵌入式装备：
  
  
  
  • 首选 Q4_0 或 Q3_K_M（内存 <4GB）
    
  • 示例：在 iPhone 14 上运行 Q4_K_M 的 7B 模子，推理速率约 20 tokens/s
    
  
  
• 低配 PC（8GB 内存）：
  
  
  
  • 选择 Q4_K_M 或 Q5_K_M（7B 模子占用约4-5GB）
    
  
  
• 高性能 CPU（服务器/工作站）：
  
  
  
  • 使用 Q5_K_M 或 Q6_K 以获得最佳质量
    
  
  

只要明白了 K 和 M 的含义，我们就可以更精准地根据硬件和任务类型选择合适的量化模子了。
参考资料

• https://github.com/ggml-org/ggml/blob/master/docs/gguf.md
  
• https://huggingface.co/docs/hub/gguf
  
• DeepSeek关于GGUF的介绍
  

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。