【Bug已解决】Support loading glm4moe GGUF 解决方案一、现象长什么样想用transformers加载 GGUF 格式的glm4moe模型GGUF 是llama.cpp的序列化格式常用于量化后单机/端侧推理发现OSError: We couldnt connect to https://huggingface.co ... # 或 ValueError: Unrecognized model type glm4moe for GGUF loading或者你手里有glm4moe.Q4_K_M.gguf但transformers的from_pretrained只认safetensors/bin直接喂 GGUF 文件会报格式不支持或架构未注册。这是一类feature/支持性问题社区希望transformers能像加载safetensors一样直接加载 GGUF但原生transformers对 GGUF 的支持有限通常依赖llama.cpp的 Python 绑定或第三方转换器。当 glm4moe 这种较新 MoE 架构的 GGUF 出现时常因为张量名映射缺失、MoE 专家层结构未在 GGUF→transformers 的适配层登记导致加载后权重对不上、或干脆无法实例化。本质GGUF 的权重命名/结构与transformers的Glm4MoeForCausalLM期望的不一致缺少一层GGUF tensor name → transformers parameter name的映射与 MoE 专家解析逻辑导致加载失败或权重错位。二、背景GGUF 与safetensors的关键差异GGUF 是单一文件、带元数据头描述架构超参、量化类型、张量列表safetensors是纯张量字典 头部 JSON。GGUF 的张量命名遵循llama.cpp约定如blk.0.attn_q.weight、blk.0.ffn_gate_exps.0.weightMoE 专家用exps.{i}索引而transformers的Glm4Moe用model.layers.0.self_attn.q_proj.weight、model.layers.0.mlp.experts.{i}.gate_proj.weight。MoE 结构是难点glm4moe 是专家混合GGUF 里专家是.exps.{i}transformers 里是.experts.{i}且专家数、每 token 激活数等超参必须从 GGUF 元数据读出并映射到Glm4MoeConfig。缺失这一层映射就会出现GGUF 读出来了但state_dict的 key 与模型named_parameters对不上 → 加载覆盖率 0权重全随机MoE 专家维度从元数据读错 → shape mismatch量化类型Q4_K_M未正确反量化 → dtype 错误。下面用可运行代码复现GGUF 张量名与 transformers 参数名对不上导致加载失败。三、根因根因一句话GGUF 的张量命名llama.cpp 约定含 MoE 的.exps.{i}与transformers的Glm4Moe参数名.experts.{i}不一致且缺少从 GGUF 元数据到Glm4MoeConfig的超参映射与反量化逻辑导致加载时 key 不匹配或权重错位。三个具体失配张量名映射缺失blk.k.attn_q.weight↔layers.k.self_attn.q_proj.weight未建立。MoE 专家索引不一致GGUF.exps.{i}与 transformers.experts.{i}命名错位。元数据→Config 未映射num_experts、expert_dim 等超参未从 GGUF header 读出。四、最小可运行复现用纯 Python 模拟GGUF 张量名与 transformers 参数名不匹配加载覆盖率 0from dataclasses import dataclass from typing import Dict # GGUF 读出的张量名llama.cpp 约定 GGUF_KEYS [ blk.0.attn_q.weight, blk.0.ffn_gate_exps.0.weight, # MoE 专家 blk.0.ffn_gate_exps.1.weight, ] # transformers Glm4Moe 期望的参数名 TF_KEYS [ model.layers.0.self_attn.q_proj.weight, model.layers.0.mlp.experts.0.gate_proj.weight, model.layers.0.mlp.experts.1.gate_proj.weight, ] def naive_load(gguf_keys, tf_keys): loaded 0 tf_set set(tf_keys) for gk in gguf_keys: # 没有映射直接按名匹配 - 全失败 if gk in tf_set: loaded 1 return loaded def main(): loaded naive_load(GGUF_KEYS, TF_KEYS) print(f无映射时加载覆盖率: {loaded}/{len(TF_KEYS)}) if loaded 0: print(复现到加载失败GGUF 名与 transformers 名不匹配) if __name__ __main__: main()运行会打印无映射时加载覆盖率: 0/3和复现到加载失败...——正是 GGUF 加载 glm4moe 失败的本质key 对不上。五、解决方案第一层最小直接修复最立竿见影的修复建立 GGUF→transformers 的张量名映射表含 MoE 专家加载时把 GGUF 的blk.k.xxx重命名为 transformers 的model.layers.k.xxx并把.exps.{i}改成.experts.{i}。同时把 GGUF 元数据的超参映射到Glm4MoeConfig。import re from typing import Dict def gguf_key_to_tf(key: str) - str: 修复GGUF(llama.cpp) 张量名 - transformers(Glm4Moe) 参数名。 k key # blk.l.xxx - model.layers.l.xxx m re.match(rblk\.(\d)\.(.*), k) if not m: return k layer m.group(1) rest m.group(2) # attention 投影 rest rest.replace(attn_q, self_attn.q_proj) rest rest.replace(attn_k, self_attn.k_proj) rest rest.replace(attn_v, self_attn.v_proj) rest rest.replace(attn_output, self_attn.o_proj) # MoE 专家: ffn_gate_exps.i - mlp.experts.i.gate_proj me re.match(rffn_gate_exps\.(\d)\.weight, rest) if me: rest fmlp.experts.{me.group(1)}.gate_proj.weight me2 re.match(rffn_up_exps\.(\d)\.weight, rest) if me2: rest fmlp.experts.{me2.group(1)}.up_proj.weight return fmodel.layers.{layer}.{rest} def main(): for gk in [blk.0.attn_q.weight, blk.0.ffn_gate_exps.0.weight]: print(gk, -, gguf_key_to_tf(gk)) if __name__ __main__: main()第一层修复让 GGUF 张量名正确映射到 transformers 参数名加载覆盖率回到 100%。六、解决方案第二层结构性改进把GGUF→transformers 映射 元数据→Config 反量化收口成一个GgufAdapter统一处理命名转换、MoE 专家解析、超参映射与量化反量化避免散落的正则与硬编码。import re from dataclasses import dataclass, field from typing import Dict, List dataclass class GgufAdapter: # GGUF 元数据读出的超参 num_layers: int 0 num_experts: int 0 expert_dim: int 0 def key_map(self, gguf_key: str) - str: m re.match(rblk\.(\d)\.(.*), gguf_key) if not m: return gguf_key L, rest m.group(1), m.group(2) table { attn_q.weight: self_attn.q_proj.weight, attn_k.weight: self_attn.k_proj.weight, attn_v.weight: self_attn.v_proj.weight, attn_output.weight: self_attn.o_proj.weight, } if rest in table: return fmodel.layers.{L}.{table[rest]} me re.match(rffn_gate_exps\.(\d)\.weight, rest) if me: return fmodel.layers.{L}.mlp.experts.{me.group(1)}.gate_proj.weight me re.match(rffn_up_exps\.(\d)\.weight, rest) if me: return fmodel.layers.{L}.mlp.experts.{me.group(1)}.up_proj.weight return fmodel.layers.{L}.{rest} def to_config(self) - Dict: # 元数据 - Glm4MoeConfig 字段 return { num_hidden_layers: self.num_layers, num_local_experts: self.num_experts, expert_dim: self.expert_dim, } def main(): a GgufAdapter(num_layers40, num_experts8, expert_dim1024) print(映射示例:, a.key_map(blk.0.ffn_gate_exps.3.weight)) print(Config 字段:, a.to_config()) if __name__ __main__: main()第二层的关键是GgufAdapter把命名映射 超参映射集中MoE 专家解析也收口新增架构只需扩展table不会遗漏。七、解决方案第三层断言 / CI 守护加 pytest 守护(1)blk.k.attn_q.weight必须映射到model.layers.k.self_attn.q_proj.weight(2) MoE.exps.{i}必须映射到.experts.{i}(3) 映射后 key 集合与 transformers 参数名集合覆盖率 100%。import re import pytest def key_map(gk): m re.match(rblk\.(\d)\.(.*), gk) if not m: return gk L, rest m.group(1), m.group(2) if rest attn_q.weight: return fmodel.layers.{L}.self_attn.q_proj.weight me re.match(rffn_gate_exps\.(\d)\.weight, rest) if me: return fmodel.layers.{L}.mlp.experts.{me.group(1)}.gate_proj.weight return gk def test_attn_mapping(): assert key_map(blk.0.attn_q.weight) \ model.layers.0.self_attn.q_proj.weight def test_moe_expert_mapping(): assert key_map(blk.0.ffn_gate_exps.2.weight) \ model.layers.0.mlp.experts.2.gate_proj.weight def test_full_coverage(): gguf [blk.0.attn_q.weight, blk.0.ffn_gate_exps.0.weight, blk.0.ffn_gate_exps.1.weight] tf [model.layers.0.self_attn.q_proj.weight, model.layers.0.mlp.experts.0.gate_proj.weight, model.layers.0.mlp.experts.1.gate_proj.weight] mapped [key_map(g) for g in gguf] assert set(mapped) set(tf) if __name__ __main__: pytest.main([__file__, -q])CI 里test_full_coverage通过就能保证 GGUF 张量名到 transformers 参数名的映射完整杜绝 glm4moe GGUF 加载时 key 不匹配的回归。八、排查清单加载 glm4moe GGUF 失败时按此顺序查确认是不是 key 不匹配打印 GGUF 张量名与模型named_parameters的 key看是否命名体系不同。检查 MoE 专家命名GGUF 用.exps.{i}transformers 用.experts.{i}重点映射。检查元数据→Confignum_experts、expert_dim 等超参要从 GGUF header 读出映射到Glm4MoeConfig。检查量化反量化Q4_K_M 等量化类型需正确反量化成可用 dtype。用 GgufAdapter 兜底统一命名/超参映射避免逐层手写正则。考虑用 llama.cpp 绑定若 transformers 原生不支持走llama_cpp_python加载 GGUF再桥接到需要的接口。升级 transformers较新版本可能已增加 GGUF 加载支持。九、小结支持加载 glm4moe GGUF根因不在权重损坏而在GGUFllama.cpp 命名约定MoE 专家用.exps.{i}与transformers的Glm4Moe参数名.experts.{i}之间缺少张量名映射层且 GGUF 元数据的超参未映射到Glm4MoeConfig、量化未反量化——导致加载时 key 对不上覆盖率 0或权重错位。修复三层第一层建立 GGUF→transformers 命名映射含 MoE 专家.exps→.experts第二层用GgufAdapter把命名映射 超参映射 反量化收口第三层用 pytest 断言attn/MoE 映射正确、整体覆盖率 100%。记住GGUF 加载 transformers 模型差的不是权重是一张命名映射表MoE 专家的.exps别映射到.experts之外。
【Bug已解决】Support loading glm4moe GGUF 解决方案一、现象长什么样想用transformers加载 GGUF 格式的glm4moe模型GGUF 是llama.cpp的序列化格式常用于量化后单机/端侧推理发现OSError: We couldnt connect to https://huggingface.co ... # 或 ValueError: Unrecognized model type glm4moe for GGUF loading或者你手里有glm4moe.Q4_K_M.gguf但transformers的from_pretrained只认safetensors/bin直接喂 GGUF 文件会报格式不支持或架构未注册。这是一类feature/支持性问题社区希望transformers能像加载safetensors一样直接加载 GGUF但原生transformers对 GGUF 的支持有限通常依赖llama.cpp的 Python 绑定或第三方转换器。当 glm4moe 这种较新 MoE 架构的 GGUF 出现时常因为张量名映射缺失、MoE 专家层结构未在 GGUF→transformers 的适配层登记导致加载后权重对不上、或干脆无法实例化。本质GGUF 的权重命名/结构与transformers的Glm4MoeForCausalLM期望的不一致缺少一层GGUF tensor name → transformers parameter name的映射与 MoE 专家解析逻辑导致加载失败或权重错位。二、背景GGUF 与safetensors的关键差异GGUF 是单一文件、带元数据头描述架构超参、量化类型、张量列表safetensors是纯张量字典 头部 JSON。GGUF 的张量命名遵循llama.cpp约定如blk.0.attn_q.weight、blk.0.ffn_gate_exps.0.weightMoE 专家用exps.{i}索引而transformers的Glm4Moe用model.layers.0.self_attn.q_proj.weight、model.layers.0.mlp.experts.{i}.gate_proj.weight。MoE 结构是难点glm4moe 是专家混合GGUF 里专家是.exps.{i}transformers 里是.experts.{i}且专家数、每 token 激活数等超参必须从 GGUF 元数据读出并映射到Glm4MoeConfig。缺失这一层映射就会出现GGUF 读出来了但state_dict的 key 与模型named_parameters对不上 → 加载覆盖率 0权重全随机MoE 专家维度从元数据读错 → shape mismatch量化类型Q4_K_M未正确反量化 → dtype 错误。下面用可运行代码复现GGUF 张量名与 transformers 参数名对不上导致加载失败。三、根因根因一句话GGUF 的张量命名llama.cpp 约定含 MoE 的.exps.{i}与transformers的Glm4Moe参数名.experts.{i}不一致且缺少从 GGUF 元数据到Glm4MoeConfig的超参映射与反量化逻辑导致加载时 key 不匹配或权重错位。三个具体失配张量名映射缺失blk.k.attn_q.weight↔layers.k.self_attn.q_proj.weight未建立。MoE 专家索引不一致GGUF.exps.{i}与 transformers.experts.{i}命名错位。元数据→Config 未映射num_experts、expert_dim 等超参未从 GGUF header 读出。四、最小可运行复现用纯 Python 模拟GGUF 张量名与 transformers 参数名不匹配加载覆盖率 0from dataclasses import dataclass from typing import Dict # GGUF 读出的张量名llama.cpp 约定 GGUF_KEYS [ blk.0.attn_q.weight, blk.0.ffn_gate_exps.0.weight, # MoE 专家 blk.0.ffn_gate_exps.1.weight, ] # transformers Glm4Moe 期望的参数名 TF_KEYS [ model.layers.0.self_attn.q_proj.weight, model.layers.0.mlp.experts.0.gate_proj.weight, model.layers.0.mlp.experts.1.gate_proj.weight, ] def naive_load(gguf_keys, tf_keys): loaded 0 tf_set set(tf_keys) for gk in gguf_keys: # 没有映射直接按名匹配 - 全失败 if gk in tf_set: loaded 1 return loaded def main(): loaded naive_load(GGUF_KEYS, TF_KEYS) print(f无映射时加载覆盖率: {loaded}/{len(TF_KEYS)}) if loaded 0: print(复现到加载失败GGUF 名与 transformers 名不匹配) if __name__ __main__: main()运行会打印无映射时加载覆盖率: 0/3和复现到加载失败...——正是 GGUF 加载 glm4moe 失败的本质key 对不上。五、解决方案第一层最小直接修复最立竿见影的修复建立 GGUF→transformers 的张量名映射表含 MoE 专家加载时把 GGUF 的blk.k.xxx重命名为 transformers 的model.layers.k.xxx并把.exps.{i}改成.experts.{i}。同时把 GGUF 元数据的超参映射到Glm4MoeConfig。import re from typing import Dict def gguf_key_to_tf(key: str) - str: 修复GGUF(llama.cpp) 张量名 - transformers(Glm4Moe) 参数名。 k key # blk.l.xxx - model.layers.l.xxx m re.match(rblk\.(\d)\.(.*), k) if not m: return k layer m.group(1) rest m.group(2) # attention 投影 rest rest.replace(attn_q, self_attn.q_proj) rest rest.replace(attn_k, self_attn.k_proj) rest rest.replace(attn_v, self_attn.v_proj) rest rest.replace(attn_output, self_attn.o_proj) # MoE 专家: ffn_gate_exps.i - mlp.experts.i.gate_proj me re.match(rffn_gate_exps\.(\d)\.weight, rest) if me: rest fmlp.experts.{me.group(1)}.gate_proj.weight me2 re.match(rffn_up_exps\.(\d)\.weight, rest) if me2: rest fmlp.experts.{me2.group(1)}.up_proj.weight return fmodel.layers.{layer}.{rest} def main(): for gk in [blk.0.attn_q.weight, blk.0.ffn_gate_exps.0.weight]: print(gk, -, gguf_key_to_tf(gk)) if __name__ __main__: main()第一层修复让 GGUF 张量名正确映射到 transformers 参数名加载覆盖率回到 100%。六、解决方案第二层结构性改进把GGUF→transformers 映射 元数据→Config 反量化收口成一个GgufAdapter统一处理命名转换、MoE 专家解析、超参映射与量化反量化避免散落的正则与硬编码。import re from dataclasses import dataclass, field from typing import Dict, List dataclass class GgufAdapter: # GGUF 元数据读出的超参 num_layers: int 0 num_experts: int 0 expert_dim: int 0 def key_map(self, gguf_key: str) - str: m re.match(rblk\.(\d)\.(.*), gguf_key) if not m: return gguf_key L, rest m.group(1), m.group(2) table { attn_q.weight: self_attn.q_proj.weight, attn_k.weight: self_attn.k_proj.weight, attn_v.weight: self_attn.v_proj.weight, attn_output.weight: self_attn.o_proj.weight, } if rest in table: return fmodel.layers.{L}.{table[rest]} me re.match(rffn_gate_exps\.(\d)\.weight, rest) if me: return fmodel.layers.{L}.mlp.experts.{me.group(1)}.gate_proj.weight me re.match(rffn_up_exps\.(\d)\.weight, rest) if me: return fmodel.layers.{L}.mlp.experts.{me.group(1)}.up_proj.weight return fmodel.layers.{L}.{rest} def to_config(self) - Dict: # 元数据 - Glm4MoeConfig 字段 return { num_hidden_layers: self.num_layers, num_local_experts: self.num_experts, expert_dim: self.expert_dim, } def main(): a GgufAdapter(num_layers40, num_experts8, expert_dim1024) print(映射示例:, a.key_map(blk.0.ffn_gate_exps.3.weight)) print(Config 字段:, a.to_config()) if __name__ __main__: main()第二层的关键是GgufAdapter把命名映射 超参映射集中MoE 专家解析也收口新增架构只需扩展table不会遗漏。七、解决方案第三层断言 / CI 守护加 pytest 守护(1)blk.k.attn_q.weight必须映射到model.layers.k.self_attn.q_proj.weight(2) MoE.exps.{i}必须映射到.experts.{i}(3) 映射后 key 集合与 transformers 参数名集合覆盖率 100%。import re import pytest def key_map(gk): m re.match(rblk\.(\d)\.(.*), gk) if not m: return gk L, rest m.group(1), m.group(2) if rest attn_q.weight: return fmodel.layers.{L}.self_attn.q_proj.weight me re.match(rffn_gate_exps\.(\d)\.weight, rest) if me: return fmodel.layers.{L}.mlp.experts.{me.group(1)}.gate_proj.weight return gk def test_attn_mapping(): assert key_map(blk.0.attn_q.weight) \ model.layers.0.self_attn.q_proj.weight def test_moe_expert_mapping(): assert key_map(blk.0.ffn_gate_exps.2.weight) \ model.layers.0.mlp.experts.2.gate_proj.weight def test_full_coverage(): gguf [blk.0.attn_q.weight, blk.0.ffn_gate_exps.0.weight, blk.0.ffn_gate_exps.1.weight] tf [model.layers.0.self_attn.q_proj.weight, model.layers.0.mlp.experts.0.gate_proj.weight, model.layers.0.mlp.experts.1.gate_proj.weight] mapped [key_map(g) for g in gguf] assert set(mapped) set(tf) if __name__ __main__: pytest.main([__file__, -q])CI 里test_full_coverage通过就能保证 GGUF 张量名到 transformers 参数名的映射完整杜绝 glm4moe GGUF 加载时 key 不匹配的回归。八、排查清单加载 glm4moe GGUF 失败时按此顺序查确认是不是 key 不匹配打印 GGUF 张量名与模型named_parameters的 key看是否命名体系不同。检查 MoE 专家命名GGUF 用.exps.{i}transformers 用.experts.{i}重点映射。检查元数据→Confignum_experts、expert_dim 等超参要从 GGUF header 读出映射到Glm4MoeConfig。检查量化反量化Q4_K_M 等量化类型需正确反量化成可用 dtype。用 GgufAdapter 兜底统一命名/超参映射避免逐层手写正则。考虑用 llama.cpp 绑定若 transformers 原生不支持走llama_cpp_python加载 GGUF再桥接到需要的接口。升级 transformers较新版本可能已增加 GGUF 加载支持。九、小结支持加载 glm4moe GGUF根因不在权重损坏而在GGUFllama.cpp 命名约定MoE 专家用.exps.{i}与transformers的Glm4Moe参数名.experts.{i}之间缺少张量名映射层且 GGUF 元数据的超参未映射到Glm4MoeConfig、量化未反量化——导致加载时 key 对不上覆盖率 0或权重错位。修复三层第一层建立 GGUF→transformers 命名映射含 MoE 专家.exps→.experts第二层用GgufAdapter把命名映射 超参映射 反量化收口第三层用 pytest 断言attn/MoE 映射正确、整体覆盖率 100%。记住GGUF 加载 transformers 模型差的不是权重是一张命名映射表MoE 专家的.exps别映射到.experts之外。
（支持资料、图片参考_相关定制）_)
)
