llama.cpp框架下GGUF格式及量化参数全解析

前言：

在人工智能领域，语言模型的高效部署和推理一直是研究热点。随着模型规模的不断扩大，如何在有限的硬件资源上实现快速、高效的推理，成为了一个关键问题。llama.cpp框架以其出色的性能和灵活性，为这一问题提供了有效的解决方案。其中，GGUF格式和模型量化参数是实现高效推理的重要技术手段。本文将对llama.cpp框架下的GGUF格式及量化参数进行详细解析，帮助读者更好地理解和应用这些技术，提升模型的部署效率和推理性能。

1：GGUF格式是什么？

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

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

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

以下是对文件结构的重新描述：

1. 文件头部（Header）：

包含文件类型标识（GGUF）、版本信息以及张量的数量。

2. 元数据区（Metadata）：

采用类似JSON的格式存储模型相关的信息，以键值对的形式组织。

3. 张量数据区（Tensors）：

根据量化方式存储模型的权重数据。

文件整体遵循在general.alignment元数据字段中定义的全局对齐规则，必要时，文件会通过添加0x00字节来填充至general.alignment指定的对齐边界。除非特别指明，所有字段（包括数组）都将按顺序连续写入文件，且不进行额外的对齐操作。模型数据默认采用小端字节序，但为了兼容大端字节序的计算机系统，它们也可以以大端字节序的形式存储，在这种情况下，包括元数据和张量在内的所有数据都将采用大端字节序。

2：GGUF命名约定

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

每个组件的含义如下：

1. 「BaseName」 ：模型基础类型或架构的描述性名称。

   • 1可以从 gguf 元数据 general.basename 派生，将空格替换为连字符。

2. 「SizeLabel」 ：参数权重类别（在排行榜中有用），表示为 <专家数量>x<数量><量级前缀> 。

   • Q ：千万亿参数。
   • T ：万亿参数。
   • B ：十亿参数。
   • M ：百万参数。
   • K ：千参数。
   • 如果可用，可以从 gguf 元数据 general.size_label 派生，如果缺失则进行计算。
   • 支持带有单个字母量级前缀的十进制点的四舍五入，以帮助显示浮点指数，如下所示：
   • 可以根据需要附加额外的 -<属性><数量><量级前缀> 以指示其他感兴趣的属性。

3. 「FineTune」 ：模型微调目标的描述性名称（例如 Chat 、 Instruct 等）。

   • 可以从 gguf 元数据 general.finetune 派生，将空格替换为连字符。

4. 「Version」 ：表示模型版本号，格式为 v<主版本>.<次版本> 。

   • 如果模型缺少版本号，则假设为 v1.0 （首次公开发布）。
   • 可以从 gguf 元数据 general.version 派生。

5. 「Encoding」 ：指示应用于模型的权重编码方案。内容、类型混合和排列由用户代码决定，可以根据项目需求而有所不同。

6. 「Type」 ：指示 gguf 文件的类型及其预期用途。

   • 如果缺失，则文件默认为典型的 gguf 张量模型文件。
   • LoRA ：GGUF文件是 LoRA 适配器。
   • vocab ：仅包含词汇数据和元数据的 GGUF 文件。

7. 「Shard」 ：（可选）指示模型已被拆分为多个分片，格式为 <分片编号>-of-<总分片数> 。

   • 分片编号始终从 00001 开始（例如，第一个分片总是从 00001-of-XXXXX 开始，而不是 00000-of-XXXXX ）。
   • 「分片编号」 ：此模型中的分片位置。必须用零填充为 5 位数字。
   • 「总分片数」 ：此模型中的总分片数。必须用零填充为 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 命名约定。例如，如果省略版本号，那么编码很容易被误认为是微调。

3：GGUF格式转换

GGUF 格式是推理框架 llama.cpp 使用的格式，但是通常模型是使用 PyTorch 之类的训练框架训练的，保存的格式一般使用 HuggingFace 的 safetensors 格式，因此使用 llama.cpp 进行推理之前需要把其他格式的模型转换为 GGUF 格式。

首先从魔搭社区（或 HuggingFace ）下载模型：

pip install modelscope

modelscope download –model deepseek-ai/DeepSeek-R1-Distill-Qwen-7B –local_dir DeepSeek-R1-Distill-Qwen-7B下载好的模型是以 safetensors 格式存放的，可以调用 llama.cpp 的转换脚本把模型转换为 GGUF 格式：

# 安装python依赖库

pip install -r requirements.txt

# 转换模型

python convert_hf_to_gguf.py DeepSeek-R1-Distill-Qwen-7B/

转换成功后，在该目录下会生成一个 FP16 精度、 GGUF 格式的模型文件 DeepSeek-R1-Distill-Qwen-7B-F16.gguf 。