👁 25 次阅读

如何在 Hugging Face Transformers 中支持更多的 GGUF 模型架构？

来源：Hugging Face Transformers Issue #33260

现象描述

在讨论的初期，Hugging Face 的 transformers 库增加了对 gguf 文件的支持，允许用户进一步训练或微调他们的 gguf 模型。随后，社区成员要求将此支持集成到更多的模型架构中，目前已支持 Llama、Mistral、Qwen2 等架构。

背景原因

gguf 文件格式的引入旨在提供更为高效的模型存储和传输方式。通过将权重从量化态转回浮点态（fp32），用户可以利用 PyTorch 等框架进行模型训练或微调，之后再将模型转回 gguf 格式，以便在 ggml 生态系统中使用。

支持更多架构的探索

用户和开发者积极参与讨论，希望扩展 GGUF 支持，涵盖的额模型架构包括：

Phi3
Qwen2Moe
Gemma2
T5
Falcon
Bloom
StableLM
gpt2
starcoder2
llama4
Deepseekv3
c4ai-command-a

为获得官方支持，用户需遵循特定协议：更新 GGUF_TENSOR_MAPPING 和 GGUF_CONFIG_MAPPING 以映射 gguf 文件的张量和配置，创建相应的转换器类。

当前进展和社区动态

截至最后一条评论日期（2026-09-11），社区成员提出了多个关注点和动态：

某些用户报告尝试 Llama 4 的 GGUF 兼容性时遇到问题，且希望解决这些兼容性问题。
讨论者继续请求对新架构的支持，例如 Naver HyperCLOVAX 模型和 OLMo-2。
一些用户成功实施了兼容性代码，但仍需要官方审查和合并。

进展模型	讨论者	见表状态
Llama 4	deepayansanyal93, garybadwal	未完全支持
DeepSeek V3	gideonphilip	需要添加支持
Phi-2	vibhorxpandey	已有开发实现

解决方案与实现方法

为实现更多架构的 GGUF 支持，社区需要遵循如下步骤： 1. 更新 GGUF_TENSOR_MAPPING 和 GGUF_CONFIG_MAPPING，以将 gguf 架构的张量与配置映射到 transformers 中的对应架构。 2. 创建相应的转换器类，如 GGUFXXXConverter(XXXConverter)，来适配 gguf 字段与 transformers 字段之间的差异。

实现要点

根据社区讨论，实现更多架构的 GGUF 支持需遵循以下步骤： 1. 更新 GGUF_TENSOR_MAPPING 和 GGUF_CONFIG_MAPPING，以将 gguf 架构的张量与配置映射到 transformers 中的对应架构（如 cohere2、deepseek_v3、gemma4 等）。 2. 创建相应的转换器类（如 GGUFGPTConverter 等），来适配 gguf 字段与 transformers 字段之间的差异。社区成员已在 PR #45546、#47421、#47052、#46718、#47400 等中针对 Llama 4、DeepSeek-V3、Command-A、glm4moe、Phi-2 等架构展开工作，但截至讨论结束仍未全部合并。

典型问题与解决方案

1. 初始化时出错：如果在加载未支持的架构时出现错误，可根据讨论中的最新进展，尝试用户提供的更改。 2. 模型保存与恢复成功：虽然支持不齐全，但许多模型可能在社区版本下成功保存与恢复，具体步骤参考社区提交的 PR。 3. 错误信息未定义：某些错误由于未更新的映射导致，解决方案是进行映射更新。

实践建议

开发者和社区成员可以参考现有的 PR 和讨论，依照已被接受的模式进行更新或贡献。推荐在 src/transformers/integrations/gguf/ 目录下贡献代码。

常见问题

1. 我可以贡献新的模型架构 GGUF 支持吗？ 是的，可以在社区讨论中声明贡献意向，并遵循已启动的方案标准开发。 2. 如已知存在问题的模型应如何处理？ 参照社区未解决的开放问题，可尝试协同开发或贡献代码进行修复。 3. 是否需要官方批准？ 开发者贡献的代码需经历社区审查和官方合并流程。 4. 社区侧已提供的缓解方案有哪些？ 具体的社区实践已在 github 上发布的 PR 中给出，如需详细信息，参见对应的讨论和代码。 5. 何时官方将推进全面支持？ 根据最新的贡献和开发进展，对部分模型支持正在积极开发中，需要终局考量及社区和官方协作的进一步验证。