👁 137 次阅读

transformers加载GGUF模型报not supported如何解决

本文内容基于 huggingface/transformers 仓库 Issue #33260 的真实讨论整理，来源链接：https://github.com/huggingface/transformers/issues/33260 。该 Issue 创建于 2024-09-02，截至 2026-08-16 仍为 open 状态，累计 52 条评论、17 个 heart 反应，标签为 Good Second Issue 与 Feature request。

现象描述

使用 transformers 加载 GGUF 格式模型时，如果 GGUF 文件中记录的架构字段不在 transformers 的映射表中，会直接抛出 Architecture {name} not supported 错误。典型报错案例来自用户 Mett-2002 在 2025-03-14 的反馈：加载 gte-Qwen2-7B-instruct-Q4_K_M.gguf 时触发 Architecture qwen2 not supported，原因是该 GGUF 文件中的架构标识尚未写入 ggml.py 的映射配置。 GGUF 加载在 transformers 中按架构逐个扩展，未添加的架构一律报 not supported，不存在自动回退或通配匹配机制。

背景原因

transformers 对 GGUF 文件的支持流程为：先将 GGUF 权重反量化到 fp32，再以 PyTorch 张量形式加载，目的是让用户能对 GGUF 模型继续训练或微调。该流程依赖两个核心映射表：

GGUF_TENSOR_MAPPING：将 GGUF 文件中的张量名称映射到 transformers 模型内部名称。
GGUF_CONFIG_MAPPING：将 GGUF 文件中的配置参数映射到 transformers 的配置字段。

每个新架构都需要同时更新这两个映射表，并创建对应的 GGUFXXXConverter 类将 GGUF tokenizer 转换为 transformers 的 tokenizer 格式，最后编写测试用例。维护者 SunMarc、LysandreJik、ArthurZucker 负责 review。初始支持的架构仅包括 Llama、Mistral、Qwen2。此后社区通过 PR 逐步扩展，已合入的架构包括 Phi3（PR #31844）、Qwen2Moe（PR #33264）、T5（PR #33389）、Falcon（PR #33437）、Bloom（PR #33473）、StableLM（PR #33793）、gpt2（PR #34044）、starcoder2（PR #34094）、Nemotron（PR #34725）。该 Issue 当前仍为 open 状态，官方未合入统一方案或自动适配机制，新架构仍需逐个提交 PR。

排查或量化方法

遇到 not supported 报错时，按以下步骤定位： 1. 确认 GGUF 文件中记录的架构名称。可通过 gguf 工具或 llama.cpp 的 convert_hf_to_gguf.py 脚本查看文件头部的架构字段。 2. 检查 transformers 源码中 src/transformers/models/ggml.py 文件内的 GGUF_TENSOR_MAPPING 和 GGUF_CONFIG_MAPPING 字典，确认目标架构是否存在。 3. 确认目标架构在 transformers 中是否已有建模支持（即 AutoModelForCausalLM 等类是否能加载该架构的 PyTorch 权重）。如果 transformers 本身尚未支持该架构，则 GGUF 加载也无法实现。 4. 检查是否有已认领但尚未合入的 PR。据 issue 讨论，DeepSeek V3、llama4、OLMo-2、Phi-2、cohere2 等架构已有社区认领但截至 2026-08-16 仍无合入记录。

完整解决方案

加载已支持的 GGUF 模型

对于已合入映射的架构，使用以下 API 加载：

from transformers import AutoTokenizer, AutoModelForCausalLM

model_id = "meta-llama/Llama-3.1-8B"
filename = "llama-3.1-8b-instruct.Q4_K_M.gguf"

tokenizer = AutoTokenizer.from_pretrained(model_id, gguf_file=filename)
model = AutoModelForCausalLM.from_pretrained(model_id, gguf_file=filename)

加载后可正常进行微调训练。训练完成后，通过 model.save_pretrained 保存为 PyTorch 格式，再使用 llama.cpp 的 convert_hf_to_gguf.py 脚本转回 GGUF 生态。

添加新架构支持

按 PR #31175 确立的流程，添加新架构需完成以下工作：

# 1. 在 ggml.py 中更新映射表
GGUF_TENSOR_MAPPING = {
    "my_architecture": {
        "model.layers.0.attn_q.weight": "model.layers.0.attn_q.weight",
        "model.layers.0.attn_k.weight": "model.layers.0.attn_k.weight",
        # ... 按实际张量名称补充
    }
}

GGUF_CONFIG_MAPPING = {
    "my_architecture": {
        "n_ctx": "max_position_embeddings",
        "n_embd": "hidden_size",
        "n_head": "num_attention_heads",
        "n_layer": "num_hidden_layers",
        # ... 按实际配置字段补充
    }
}

# 2. 创建 GGUFConverter 类
class GGUFXxxConverter:
    def convert_tokenizer(self, gguf_tokenizer):
        # 将 GGUF tokenizer 转换为 transformers tokenizer
        return tokenizer

# 3. 编写测试用例
def test_load_gguf_xxx():
    model = AutoModelForCausalLM.from_pretrained(
        "org/xxx-model", gguf_file="xxx.Q4_K_M.gguf"
    )
    assert model.config.hidden_size == expected_value

完成以上三步后提交 PR，由维护者 review 合入。

参数或对比表格

架构	合入状态	对应 PR	备注
Llama	已合入	初始支持	基础架构
Mistral	已合入	初始支持	基础架构
Qwen2	已合入	初始支持	基础架构
Phi3	已合入	#31844	社区贡献
Qwen2Moe	已合入	#33264	社区贡献
T5	已合入	#33389	社区贡献
Falcon	已合入	#33437	社区贡献
Bloom	已合入	#33473	社区贡献
StableLM	已合入	#33793	社区贡献
gpt2	已合入	#34044	社区贡献
starcoder2	已合入	#34094	社区贡献
Nemotron	已合入	#34725	社区贡献
DeepSeek V3	未合入	待处理	2026-07-04 社区认领，涉及 MoE expert 张量与 MLA 投影
llama4	未合入	待处理	2025-05-19 开始，2026-04-17 实测仍有问题
OLMo-2	未合入	待处理	2026-06-30 社区认领
Phi-2	未合入	待处理	2026-07-18 社区认领
cohere2	未合入	待处理	2026-07-03 社区认领
MiniCPM-V	暂不添加	无	依赖 trust_remote_code，维护者明确拒绝

常见错误排查

错误一：Architecture qwen2 not supported GGUF 文件中的架构字段未在 ggml.py 的映射表中。该报错来自用户 Mett-2002 在 2025-03-14 使用 gte-Qwen2-7B-instruct-Q4_K_M.gguf 时的反馈。解决方案：确认 Qwen2 架构是否已合入（已合入），若仍报错则检查 transformers 版本是否过旧，需升级到包含 Qwen2 映射的版本。 错误二：Cohere 模型能加载模型但无法加载 tokenizer 用户 010kim 在 2024-10-06 实测发现，Cohere 的 slow tokenizer 在 transformers 中未实现（仅有 FastTokenizer），导致 GGUF 文件中的模型权重可正常加载，但 tokenizer 加载失败。该问题截至 issue 更新时仍未解决。 错误三：MiniCPM-V 架构无法添加 GGUF 支持 维护者 SunMarc 在 2024-09-03 明确说明，MiniCPM-V 依赖 trust_remote_code=True，transformers 不希望核心代码依赖 hub 上的 modeling 文件，因此暂不添加该架构的 GGUF 支持。该决定为架构层面的限制，非版本问题。 错误四：Smol 模型需要额外适配 维护者 SunMarc 在 2024-09-23 说明，Smol 模型本身即为 llama 架构，无需额外工作即可通过现有 llama 映射加载 GGUF 文件。若加载失败，应检查 GGUF 文件中架构字段是否正确标记为 llama。 错误五：llama4 GGUF 加载仍遇到问题 用户 deepayansanyal93 在 2026-04-17 实测加载 Llama 4 GGUF 检查点仍遇到问题，认为支持可能不完整。该架构截至 2026-08-16 仍无合入记录。

实践建议

加载 GGUF 模型前，先确认目标架构是否已在映射表中。可通过 GitHub 搜索 GGUF_TENSOR_MAPPING 关键词查看当前支持的架构列表。
对于已合入架构的模型，优先使用 AutoTokenizer.from_pretrained 和 AutoModelForCausalLM.from_pretrained 的 gguf_file 参数加载，避免手动反量化流程。
微调完成后可通过 llama.cpp 的 convert_hf_to_gguf.py 脚本将模型转回 GGUF 格式，或借助 gguf-my-repo 空间完成转换。
需要添加新架构支持时，按 PR #31175 的三步流程（更新映射表、创建 Converter 类、编写测试）提交社区 PR，由维护者 review 合入。
避免依赖 trust_remote_code=True 的架构进行 GGUF 适配，此类架构已被维护者明确排除。
对于尚未合入的架构（DeepSeek V3、llama4、OLMo-2、Phi-2、cohere2 等），关注对应认领者的 PR 进展，避免重复开发。

FAQ

Q1：transformers 加载 GGUF 模型的工作原理是什么？ transformers 先将 GGUF 文件中的量化权重反量化到 fp32，再以 PyTorch 张量形式加载到模型中。该流程依赖 GGUF_TENSOR_MAPPING 和 GGUF_CONFIG_MAPPING 两个映射表将 GGUF 的张量名称和配置字段转换为 transformers 内部格式。加载后的模型可正常进行训练或微调，训练完成后可通过 llama.cpp 的 convert_hf_to_gguf.py 脚本转回 GGUF 格式。 Q2：为什么我的架构报 not supported？ GGUF 加载按架构逐个扩展，未添加的架构一律报 not supported，不存在自动回退机制。需确认目标架构是否已在 ggml.py 的映射表中，以及 transformers 本身是否已支持该架构的建模。若两者均已满足，则可能是 transformers 版本过旧，需升级到包含该架构映射的版本。 Q3：MiniCPM-V 为什么不支持 GGUF 加载？ 维护者 SunMarc 在 2024-09-03 明确说明，MiniCPM-V 依赖 trust_remote_code=True，transformers 不希望核心代码依赖 hub 上的 modeling 文件，因此暂不添加该架构的 GGUF 支持。该限制为架构层面的设计决策，非版本或配置问题。 Q4：如何为 transformers 添加新架构的 GGUF 支持？ 按 PR #31175 确立的流程：第一步更新 GGUF_TENSOR_MAPPING 和 GGUF_CONFIG_MAPPING，将 GGUF 文件的张量与配置映射到 transformers；第二步创建 GGUFXXXConverter 类将 GGUF tokenizer 转换为 transformers 的 tokenizer；第三步编写测试用例。完成后提交 PR，由维护者 SunMarc、LysandreJik、ArthurZucker review 合入。 Q5：DeepSeek V3 和 llama4 的 GGUF 支持进展如何？ 截至 2026-08-16，两个架构均未合入。DeepSeek V3 方面，2026-07-04 gideonphilip 声称认领，已检查 GGUF_CONFIG_MAPPING 与 GGUF_TENSOR_MAPPING 中尚无 deepseek_v3 条目且无开放 PR，计划处理 MoE expert 张量与 MLA（multi-head latent attention）投影。llama4 方面，2025-05-19 yijun-lee 开始处理，2026-04-17 deepayansanyal93 实测加载仍遇到问题，认为支持可能不完整。该 Issue 整体仍为 open 状态，官方未合入统一方案。