Transformers 与 GGUF 交互实战从量化文件加载到回导出 GGML 生态【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformersGGUFGPT-Generated Unified Format是 GGML 及其下游库如流行的 llama.cpp、whisper.cpp用于保存推理模型的文件格式。本指南以 docs/source/ko/gguf.md 为核心骨架结合本仓库GitHub_Trending/tra/transformers中modeling_gguf_pytorch_utils.py、modeling_utils.py、quantizer_gguf.py等源码实现系统讲解GGUF 单文件格式的构成、在 Transformers 内受支持的量化类型与模型架构、通过gguf_file参数加载 GGUF 权重自动反量化到 FP32 后接入 PyTorch 生态、以及如何借助 llama.cpp 的convert-hf-to-gguf.py将微调后的模型回导成 GGUF 文件。读完你将掌握一套完整的 GGUF → Transformers微调→ GGUF 闭环流程并理解底层反量化与张量映射机制。GGUF 文件格式单文件封装的模型与元数据GGUF 文件格式被 GGML 及其依赖库例如广受欢迎的 llama.cpp 与 whisper.cpp用于存储推理模型。它也被 Hugging Face Hub 所支持并提供了快速检视文件内张量与元数据的能力。该格式被设计为单文件格式single-file-format一个文件内同时包含配置属性、分词器词表、其他属性以及模型加载所需的全部张量。这意味着拿到一个.gguf文件即可独立还原出完整的模型无需额外下载config.json或tokenizer.json。这些文件按文件内使用的量化类型不同而有不同形态Hub 上对各类量化类型有简要说明参见 Hub 文档的 Quantization types 一节。从本仓库源码看这种自包含特性体现在元数据解析上modeling_gguf_pytorch_utils.py 中的load_gguf_checkpoint通过GGUFReader读取文件内的 KV 字段reader.fields并按GGUF_TO_TRANSFORMERS_MAPPING字典将配置字段、分词器字段、tokenizer_config 字段分类解析词表与合并规则同样来自文件内的tokenizer.ggml.tokens、tokenizer.ggml.merges等元数据键正如 gguf_tokenizer_mapping.py 所述GGUF 仓库不附带tokenizer.json词表、合并规则和特殊 token id 都是元数据键。若解析后的配置缺少vocab_size代码还会从分词器参数中的 tokens 数量反推见load_gguf_checkpoint中相关逻辑。[!NOTE] 支持仍处于早期阶段欢迎针对更多量化类型与模型架构做出贡献contributions。Transformers 内的支持范围本仓库为transformers增加了加载gguf文件的能力目标是为 GGUF 模型提供继续训练 / 微调能力之后再转回gguf文件放回ggml生态使用。加载模型时权重先被反量化到 FP32再以 PyTorch 可用的形式载入——这也就是为什么加载完成后你在 PyTorch 生态中获得的是模型的未量化完整版本。支持的量化类型最初支持的量化类型是根据 Hub 上共享的热门量化文件确定的包括浮点格式与 GGML 的 K 系列 / IQ 系列整数量化格式类别支持的量化类型浮点F32、F16、BF16标准整数量化Q4_0、Q4_1、Q5_0、Q5_1、Q8_0K 系列混合量化Q2_K、Q3_K、Q4_K、Q5_K、Q6_KIQ 系列imatrix 量化IQ1_S、IQ1_M、IQ2_XXS、IQ2_XS、IQ2_S、IQ3_XXS、IQ3_S、IQ4_XS、IQ4_NL[!NOTE] 支持 GGUF 反量化需要安装gguf0.10.0。这一依赖约束在源码中有多处印证get_gguf_hf_weights_map与load_gguf_checkpoint在缺失依赖时会直接抛出ImportError提示Loading a GGUF checkpoint in PyTorch, requires both PyTorch and GGUF0.10.0 to be installed见 modeling_gguf_pytorch_utils.py。安装方式如下pip install gguf0.10.0 torch支持的模型架构当前支持的模型架构被限制为 Hub 上非常流行的几类对应GGUF_SUPPORTED_ARCHITECTURES由 modeling_gguf_pytorch_utils.py 中的配置映射键推导得出LLaMaMistralQwen2Qwen2MoePhi3Bloom需要说明的是随着仓库演进源码中的支持范围已经比文档初始列表更广load_gguf_checkpoint对架构名做了归一化处理例如mistral与llama共用llama架构但按general.name区分、qwen2moe→qwen2_moe、gpt_oss→gpt_oss、minimax-m2→minimax_m2并且 ggml.py 中的GGUF_CONFIG_MAPPING还覆盖了qwen3、qwen3_moe、falcon、lfm2、gpt_oss等更多架构TENSOR_PROCESSORS中也注册了t5、gpt2、mamba、nemotron、gemma2、gemma3、lfm2、minimax-m2等处理器。实际是否支持请以当前仓库代码为准并通过下文的可运行示例实际验证。使用示例从 GGUF 文件加载模型在transformers中加载gguf文件需要在from_pretrained方法中指定gguf_file参数。以下示例展示了从同一个 GGUF 文件中同时加载分词器与模型from transformers import AutoTokenizer, AutoModelForCausalLM model_id TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF filename tinyllama-1.1b-chat-v1.0.Q6_K.gguf tokenizer AutoTokenizer.from_pretrained(model_id, gguf_filefilename) model AutoModelForCausalLM.from_pretrained(model_id, gguf_filefilename)加载完成后你便在 PyTorch 生态中拿到了该模型的未量化完整版本可以与其他众多工具组合使用例如继续训练、微调、接入 Trainer 或推理管线。参数说明与本地文件加载model_idHub 上的仓库名如上例TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF也可以是本地目录路径。filename/gguf_file仓库内或本地目录内的.gguf文件名。若传入的是本地文件绝对路径源码会直接使用该文件见 modeling_utils.py 中os.path.isfile(gguf_file)分支否则通过cached_file从 Hub 缓存下载。从源码可以看到加载链路的关键环节modeling_utils.pyfrom_pretrained内部gguf_file从kwargs中被取出并传给PreTrainedModel.from_pretrained加载器识别出.gguf权重文件后hf_quantizer.read_header(...)先解析文件头元数据判断架构是否受支持随后hf_quantizer.get_state_dict(checkpoint_files[0], model)获取反量化后的状态字典dtypeauto时GGUF 文件自身的浮点类型如 F16会决定最终解析出的 dtype源码注释a GGUFs own float type is whatdtypeautoresolves to。分词器一侧同样支持gguf_file在 tokenization_auto.py 中AutoTokenizer.from_pretrained检测到gguf_file后会读取 GGUF 元数据并从中构建分词器配置词表、合并规则、特殊 token id而非寻找独立的tokenizer.json文件。反量化与张量映射的底层原理load_gguf_checkpointmodeling_gguf_pytorch_utils.py是整个流程的核心其工作过程可概括为解析元数据用GGUFReader读取general.architecture、general.name等字段并按架构名做归一化处理构建配置通过GGUF_CONFIG_MAPPING将 GGUF 字段名如llama.block_count、llama.attention.head_count、llama.rope.freq_base映射为 Transformers 配置属性num_hidden_layers、num_attention_heads、rope_theta等并填充GGUF_CONFIG_DEFAULTS_MAPPING中的架构默认值构建张量名映射get_gguf_hf_weights_map借助gguf库的get_tensor_name_map(arch, num_layers)得到 GGUF 张量名如blk.0.attn_q.weight与 HF 参数名的对应关系反量化对每个张量调用dequantize(tensor.data, tensor.tensor_type)还原为浮点权重FP32架构专属处理通过TENSOR_PROCESSORS中注册的处理器如LlamaTensorProcessor、BloomTensorProcessor、Qwen2MoeTensorProcessor执行张量重排——例如 Llama 的注意力权重需要_reverse_permute_weights逆置换Bloom 的attn_qkv需要_reverse_reshape_weights重排Mamba 的ssm_a需要取负对数还原指数参数MoE 架构Qwen2Moe / MiniMaxM2则需要把ffn_gate_exps与ffn_up_exps交错合并成gate_up_proj。此外tie_word_embeddings会根据文件内是否存在output.weight张量自动推断falcon、bloom 架构除外与常见 HF 权重命名约定保持一致。从 PyTorch 回导出 GGUF完整的微调闭环gguf文件格式的典型使用闭环是从 GGML 生态拿到量化模型 → 在本仓库的transformers中反量化并微调 → 再导出回gguf供 llama.cpp 等工具使用。回导出gguf文件时推荐使用 llama.cpp 的convert-hf-to-gguf.py脚本。完成微调后将模型保存下来再运行该脚本即可tokenizer.save_pretrained(directory) model.save_pretrained(directory) !python ${path_to_llama_cpp}/convert-hf-to-gguf.py ${directory}其中directory是保存目录可自定义路径save_pretrained会把config.json、分词器文件与模型权重写入该目录${path_to_llama_cpp}需替换为你本地 llama.cpp 仓库包含convert_hf_to_gguf.py脚本的实际路径脚本会读取该目录下的 HF 格式权重重新打包为 GGUF 单文件并允许你在转换时指定新的量化类型。值得注意的是反量化得到的权重本身是 FP32 精度因此微调时建议按常规流程选择合适的学习率与混合精度策略转换回 GGUF 时则可在 llama.cpp 侧重新选择 Q4_K_M、Q6_K 等量化档位以平衡体积与精度。小结与进阶阅读本文围绕 GGUF 与 Transformers 的交互完整覆盖了GGUF 单文件格式的构成、当前支持的量化类型F32/F16/BF16、Q4_0Q8_0、K 系列与 IQ 系列与模型架构LLaMa、Mistral、Qwen2、Qwen2Moe、Phi3、Bloom 等、通过gguf_file参数一行加载 GGUF 权重内部自动反量化到 FP32以及借助convert-hf-to-gguf.py将微调结果回导出 GGUF 的闭环流程。若想深入了解实现细节可以继续阅读本仓库中的以下文件modeling_gguf_pytorch_utils.pyGGUF 反量化、元数据解析、张量名映射与架构专属张量处理的核心实现modeling_utils.pyPreTrainedModel.from_pretrained中gguf_file参数的加载链路tokenization_auto.pyAutoTokenizer从 GGUF 元数据构建分词器的逻辑ggml.py 与 gguf_tokenizer_mapping.pyGGUF 配置字段与分词器字段到 Transformers 的映射表quantizer_gguf.pyGGUF 权重以块block形式保留的量化加载路径。结合这些源码阅读可以进一步理解不同架构的量化张量如何被精确还原也为向更多架构与量化类型贡献支持提供参考。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考