GGUF 集成

相关源文件

• docs/source/en/gguf.md
• src/transformers/convert_slow_tokenizer.py
• src/transformers/integrations/ggml.py
• src/transformers/modeling_gguf_pytorch_utils.py
• src/transformers/models/llama/tokenization_llama.py
• src/transformers/models/llama/tokenization_llama_fast.py
• src/transformers/models/seamless_m4t/tokenization_seamless_m4t.py
• src/transformers/models/siglip/tokenization_siglip.py
• src/transformers/models/t5/tokenization_t5.py
• src/transformers/models/t5/tokenization_t5_fast.py
• src/transformers/models/udop/tokenization_udop.py
• src/transformers/models/udop/tokenization_udop_fast.py
• src/transformers/tokenization_utils.py
• src/transformers/tokenization_utils_fast.py
• tests/models/llama/test_tokenization_llama.py
• tests/models/t5/test_tokenization_t5.py
• tests/quantization/ggml/test_ggml.py
• tests/tokenization/test_tokenization_fast.py
• tests/tokenization/test_tokenization_utils.py

本页面介绍了 Transformers 库中的 GGUF（GGML Universal Format）集成，该集成允许加载和使用以 GGUF 格式存储的量化模型。GGUF 是一种为 GGML 推理框架开发的文件格式，它能够将模型权重（包括量化权重）高效地存储在单个文件中。

有关量化技术的更多信息，请参阅 量化。

概述

Transformers 中的 GGUF 集成实现了

1. 从 GGUF 文件加载量化模型进行推理
2. 将 GGUF 分词器转换为 Transformers 分词器
3. 将 GGUF 权重去量化为 PyTorch 张量
4. 支持各种模型架构和量化类型

来源

• src/transformers/modeling_gguf_pytorch_utils.py346-496
• src/transformers/tokenization_utils_fast.py98-148

支持的模型架构

GGUF 集成支持广泛的模型架构，包括

架构	模型类型
LLM	Llama、Mistral、Qwen2、Qwen2MoE、Phi3
仅编码器	Bloom、Falcon
编码器-解码器	T5
其他	StableLM、GPT2、Starcoder2、Mamba、Nemotron、Gemma2、Gemma3

来源

• src/transformers/integrations/ggml.py36-226
• src/transformers/modeling_gguf_pytorch_utils.py38-53

量化类型

GGUF 支持多种量化类型，从全精度（FP16/BF16）到高度压缩格式

类别	量化类型
全精度	F32 (float32)、F16 (float16)、BF16 (bfloat16)
标准量化	Q8_0、Q5_0、Q4_0
K-量化	Q2_K、Q3_K、Q4_K、Q5_K、Q6_K
I-矩阵	IQ1_S、IQ1_M、IQ2_XXS、IQ2_XS、IQ2_S、IQ3_XXS、IQ3_S、IQ4_XS、IQ4_NL

来源

• tests/quantization/ggml/test_ggml.py38-106

加载 GGUF 模型

基本用法

从 GGUF 文件加载模型

来源

• tests/quantization/ggml/test_ggml.py50-56
• docs/source/en/gguf.md32-44

指定 Torch Dtype

在加载 GGUF 模型时，可以指定 PyTorch 的 dtype

来源

• tests/quantization/ggml/test_ggml.py205-211

架构

GGUF 集成包含几个关键组件

来源

• src/transformers/modeling_gguf_pytorch_utils.py346-496
• src/transformers/modeling_gguf_pytorch_utils.py61-244

加载过程

GGUF 加载过程包括几个步骤

1. 读取 GGUF 文件：使用 GGUFReader 从 gguf 库中读取文件
2. 解析元数据：提取模型配置、分词器信息及其他元数据
3. 将 GGUF 字段映射到 Transformers：将 GGUF 特定的字段名称转换为 Transformers 配置
4. 张量去量化：将量化权重转换为全精度 PyTorch 张量
5. 处理张量：对张量应用模型特定的转换
6. 创建模型：使用去量化权重初始化 Transformers 模型

来源

• src/transformers/modeling_gguf_pytorch_utils.py346-496
• src/transformers/tokenization_utils_fast.py98-148

分词器集成

GGUF 文件包含可转换为 Transformers 分词器的分词器信息

来源

• src/transformers/integrations/ggml.py276-1000
• src/transformers/tokenization_utils_fast.py98-148

分词器转换过程

分词器转换过程包括

1. 从 GGUF 文件中提取分词器数据
2. 根据模型架构识别合适的分词器转换器
3. 将 GGUF 分词器转换为 Transformers 分词器
4. 处理特殊 token 和附加配置

例如，对于 Llama 模型

来源

• src/transformers/tokenization_utils_fast.py123-130
• src/transformers/integrations/ggml.py319-387

模型特定处理

不同的模型架构需要特定的张量处理

Llama/Mistral 处理

对于 Llama 和 Mistral 模型，注意力权重需要特殊处理

来源

• src/transformers/modeling_gguf_pytorch_utils.py69-84

Bloom 处理

对于 Bloom 模型，注意力 QKV 权重需要重塑

来源

• src/transformers/modeling_gguf_pytorch_utils.py129-141

Qwen2MoE 处理

对于 Qwen2MoE 模型，专家张量需要拆分

来源

• src/transformers/modeling_gguf_pytorch_utils.py99-114

限制和注意事项

在使用 Transformers 中的 GGUF 模型时，请考虑以下事项

1. 内存使用：去量化模型比量化模型占用更多内存
2. 磁盘卸载：GGUF 模型不支持磁盘卸载
3. 转换回 GGUF：修改模型后，您需要使用外部工具将其转换回 GGUF 格式
4. 分词器兼容性：某些分词器功能在 GGUF 和 Transformers 之间可能无法完全兼容

来源

• tests/quantization/ggml/test_ggml.py221-262
• docs/source/en/gguf.md46-53

示例：端到端工作流程

以下是使用 GGUF 集成的完整工作流程示例

1. 加载量化模型:

2. 微调或修改模型:

3. 保存模型:

4. 转换回 GGUF 格式（使用外部工具）

来源

• docs/source/en/gguf.md32-53
• tests/quantization/ggml/test_ggml.py182-203

结论

Transformers 中的 GGUF 集成为高效量化模型和 Transformers 生态系统之间搭建了一座桥梁。这允许用户

1. 加载量化模型进行推理
2. 微调或调整量化模型
3. 将 Transformers API 与 GGUF 模型结合使用
4. 处理各种模型架构和量化类型

该集成处理了权重去量化、配置映射和分词器转换的复杂性，使得在 PyTorch 中使用 GGUF 模型变得更加容易。