Transformers 中 GLM-4.5/4.6/4.7 的 MoE 实现：Glm4Moe 配置、架构与源码解析

GLM-4.5 系列（含 GLM-4.5、GLM-4.6 与 GLM-4.7）是智谱 AI 面向智能体场景发布的大规模混合专家（MoE）模型系列，本文基于 Transformers 仓库官方文档 docs/source/en/model_doc/glm4_moe.md，并结合其源码实现对 Glm4Moe 模型族进行深度讲解。读完本文，你将掌握 Glm4MoeConfig 的全部关键超参数含义、Glm4MoeModel/Glm4MoeForCausalLM 的模型结构与路由机制，以及如何在 Transformers 中加载、生成与配置这些模型。

文档声明：三类模型共用一个实现类

根据官方模型文档说明，GLM-4.7、GLM-4.6 与 GLM-4.5 语言模型在 Transformers 中统一使用同一个 Glm4Moe 实现类族（model_type = "glm4_moe"），三个版本共享相同的代码路径，通过不同的权重文件与配置体现差异。需要特别注意的是：当前 Transformers 中的实现并不包含 MTP（Multi-Token Prediction）层——模型发布时附带的多 token 预测模块权重在加载时会被忽略，下文会解释这一限制的影响与加载细节。

该文档在 docs/source/en/model_doc/glm4_moe.md 中使用了 [[autodoc]] 指令自动抽取了三个公开 API：Glm4MoeConfig、Glm4MoeModel 和 Glm4MoeForCausalLM，它们分别对应模型配置类、基础主干模型与因果语言模型头，是接入该系列模型的三把钥匙。

版本能力纵览：GLM-4.5 / GLM-4.6 / GLM-4.7

GLM-4.7：更强的编码与"思考"能力

GLM-4.7 定位于新一代编码与智能体模型，模型发布资料中宣称相对前代 GLM-4.6 取得的主要提升包括（数据均来自官方技术博客，未在本仓库中复现）：

• 核心编码能力：多语言 agentic coding 与终端任务有明显提升，如 SWE-bench 上取得 73.8%（+5.8%）、SWE-bench Multilingual 上 66.7%（+12.9%）、Terminal Bench 2.0 上 41%（+16.5%），并支持"先思考再行动"，在 Claude Code、Kilo Code、Cline、Roo Code 等主流 agent 框架的复杂任务上有显著改进；
• Vibe Coding（UI 生成）：能产出更干净、现代的网页与排版更准确的幻灯片；
• 工具调用：在 τ²-Bench 与基于 BrowseComp 的网页浏览类任务上显著提升；
• 复杂推理：在 HLE（Humanity's Last Exam）基准上相对 GLM-4.6 达到 42.8%（+12.4%）。

GLM-4.7 进一步强化了自 GLM-4.5 引入的 Interleaved Thinking，并新增了 Preserved Thinking 与 Turn-level Thinking 两种思考模式：

思考模式	行为说明
Interleaved Thinking	模型在每次响应与工具调用之前先进行思考，提升指令遵循与生成质量
Preserved Thinking	在编码 agent 的长对话中自动保留全部思考块、复用既有推理结果而非从零重新推导，适合长时间、复杂任务，减少信息丢失与不一致
Turn-level Thinking	支持按轮次在会话内开关推理：轻量请求关闭以降低延迟/成本，复杂任务开启以提高准确率与稳定性

注意：以上"思考模式"是模型层能力描述。在本仓库的 Transformers 实现中，思考内容在文本中体现为特殊的 thinking 块结构，需配合模型配套的 reasoning parser / tool parser 使用（文档指出模型代码、tool parser 与 reasoning parser 均可在本仓库的 transformers 实现中找到）。

GLM-4.6：上下文窗口扩到 200K

相对 GLM-4.5，GLM-4.6 的关键改进包括：上下文窗口从 128K 扩展到 200K tokens，可支撑更复杂的 agentic 任务；编码 benchmark 得分更高，且在 Claude Code、Cline、Roo Code、Kilo Code 等真实应用（含前端页面生成）中表现更佳；推理能力明显提升并支持推理过程中使用工具；工具调用与搜索型 agent 能力更强；写作风格更贴近人类偏好，角色扮演更自然。

GLM-4.5：355B/32B 的混合推理底座

GLM-4.5 是面向智能体设计的基座模型系列，其 MoE 变体在本文档中即记作 Glm4Moe：

• GLM-4.5：总参数量 355B、激活参数 32B；
• GLM-4.5-Air：更紧凑的 106B 总参数、12B 激活参数。

GLM-4.5 与 GLM-4.5-Air 均为混合推理模型（hybrid reasoning model），提供两种模式：thinking mode（面向复杂推理与工具使用）与 non-thinking mode（面向即时响应）。发布方开源了基座模型、混合推理模型以及混合推理模型的 FP8 版本，均以 MIT 开源协议发布，可商用与二次开发。模型发布资料中宣称在 12 项行业标准基准综合评测得分 63.2、位列第三方开源与闭源模型综合第 3 名，Air 版本以更高效率取得 59.8。

Glm4MoeConfig：核心配置全解

Glm4MoeConfig 的定义位于 configuration_glm4_moe.py。除普通 Transformer 配置外，它携带一套典型的 DeepSeek 风格 MoE + 分组路由参数。以下是该文件声明的全部默认值：

配置项	默认值	说明
vocab_size	151552	词表大小
hidden_size	4096	隐藏层维度
intermediate_size	10944	稠密 FFN 中间维度
num_hidden_layers	46	解码器层数
num_attention_heads	96	注意力头数
num_key_value_heads	8	GQA 的 KV 头数
hidden_act	"silu"	激活函数（SwiGLU 风格）
max_position_embeddings	131072	最大位置编码长度
initializer_range	0.02	权重初始化标准差
rms_norm_eps	1e-5	RMSNorm 的 epsilon
use_cache	True	是否缓存 KV
tie_word_embeddings	False	是否共享词嵌入与 lm_head
attention_bias	False	注意力投影是否带 bias
attention_dropout	0.0	注意力 dropout
moe_intermediate_size	1408	每个专家 FFN 的中间维度
num_experts_per_tok	8	每个 token 激活的路由专家数（top-k）
n_shared_experts	1	共享专家数量（始终参与计算）
n_routed_experts	128	路由专家总数
routed_scaling_factor	1.0	路由权重缩放因子
n_group	1	路由专家分组数（grouped routing）
topk_group	1	先按组选出的小组数
first_k_dense_replace	1	浅层前 k 层用稠密 MLP 替换 MoE
norm_topk_prob	True	是否对 top-k 权重做归一化
use_qk_norm	False	是否对 Q/K 加 RMSNorm（与 Llama 的主要差异开关）
bos_token_id / eos_token_id / pad_token_id	None	特殊 token id
num_mtp_layers	1	MTP 模块数量（见下文限制说明）

与 Transformer 约定对齐的属性映射

配置类通过 attribute_map 将 Hugging Face 通用属性名对齐到 GLM 系列的自有命名，方便 from_pretrained 时兼容不同命名规范的 checkpoint：

attribute_map = {
    "num_local_experts": "n_routed_experts",
    "num_mtp_layers": "num_nextn_predict_layers",
}

内置并行切分方案

Glm4MoeConfig 是极少数在配置层就内置了**张量并行（TP）、流水线并行（PP）与专家并行（EP）**默认方案的定义，可直接支撑多卡分布式推理/训练：

• base_model_tp_plan：将注意力 q/k/v 投影标记为 colwise、o_proj 为 rowwise；MoE 专家的 gate_up_proj 为 packed_colwise、down_proj 为 rowwise；共享专家与稠密 MLP 的 gate/up/down 亦各自标注切分方向；
• base_model_pp_plan：按 embed_tokens → layers → norm 描述各阶段输入输出张量；
• base_model_ep_plan：将路由器（gate）标记为 ep_router，专家 FFN 的前后投影标记为 grouped_gemm（即聚合多个专家的批量 GEMM），供 expert parallelism 使用。

一个值得注意的差异：MTP 层

配置注释中说明 num_mtp_layers 表示可附加在主干后的多 token 预测模块数量，理论上可用 generate(..., use_mtp=True) 做投机解码；但模型文档明确指出本实现不含 MTP 层。为了平滑加载官方权重，Glm4MoePreTrainedModel 声明了忽略规则：

_keys_to_ignore_on_load_unexpected = [r"model\.layers\.92.*", r"model\.layers\.46.*"]

也就是说，若官方 checkpoint 中带有超过当前 46 层的 MTP 结构（如 model.layers.92.*），这些权重会在加载时被安全忽略，不会因缺少 key 而报错。

架构实现与源码走读

Glm4Moe 的 PyTorch 实现位于 modeling_glm4_moe.py，它是由 modular_glm4_moe.py 自动生成的（文件头部有明确警告：任何修改应施加于 modular 源文件）。模块化文件里可以看到其组件复用关系：从 deepseek_v3 借用了 DecoderLayer/MLP/RMSNorm/TopkRouter 等骨架，从 glm 借用了 GlmRotaryEmbedding，从 cohere 借用了 CohereAttention——这解释了为何 Glm4Moe 与 DeepSeek-V3 系 MoE 结构如此接近。

主干类结构（定义行号见源文件）依次为：Glm4MoeRotaryEmbedding → Glm4MoeAttention → Glm4MoeMLP（稠密）/ Glm4MoeMoE（混合专家）→ Glm4MoeDecoderLayer → Glm4MoeModel → Glm4MoeForCausalLM。

解码层：浅层稠密 + 深层 MoE 的混合堆叠

Glm4MoeDecoderLayer 依据 layer_idx >= config.first_k_dense_replace 决定本层 FFN 采用稠密 MLP 还是 MoE：

if layer_idx >= config.first_k_dense_replace:
    self.mlp = Glm4MoeMoE(config)
else:
    self.mlp = Glm4MoeMLP(config)

默认 first_k_dense_replace=1，意味着第 0 层（嵌入层之后的第一层）为普通稠密 FFN，其余 45 层均为 MoE。每层先做 input_layernorm → 自注意力 → 残差，再做 post_attention_layernorm → MLP → 残差，层实现继承自 GradientCheckpointingLayer，因此天然支持梯度检查点（配置层设置了 supports_gradient_checkpointing = True）。

注意力：GQA + 可选 QK-Norm + 统一 attention backend

Glm4MoeAttention 的核心特征（源码注释明确标注 main diff from Llama）是 use_qk_norm 开关：开启时对 Q/K 在旋转位置编码之前分别应用 Glm4MoeRMSNorm。该模型使用 GQA：96 个注意力头共享 8 个 KV 头（num_key_value_groups = 96 / 8 = 12），推理时可显著节省 KV cache。此外：

• 头维度 head_dim = hidden_size // num_attention_heads，缩放因子为 head_dim ** -0.5；
• 位置编码通过 Glm4MoeRotaryEmbedding 计算，采用 partial rotary 方案：RoPE 只作用在部分维度上（partial_rotary_factor 默认 0.5），即 apply_rotary_pos_emb 中 q_rot / q_pass 的前后拼接逻辑；
• 注意力前向通过 ALL_ATTENTION_FUNCTIONS.get_interface(...) 分发，因此 eager / SDPA / Flash Attention / Flex Attention 皆可用——Glm4MoePreTrainedModel 声明了 _supports_flash_attn = True、_supports_sdpa = True、_supports_flex_attn = True；
• 若开启 QK-Norm，相关归一化权重会注册到 _keep_in_fp32_modules_strict（该集合中还包含路由器的 e_score_correction_bias），保证混合精度下不出现数值问题。

路由与 MoE：分组路由 + 共享专家

Glm4MoeTopkRouter 实现的是带分组约束的 top-k sigmoid 路由（来自 DeepSeek-V3 的 DeepseekV3TopkRouter 设计）：

1. 用 float32 计算路由 logits 并经 sigmoid 得分数；
2. 加上可学习的 e_score_correction_bias 作为专家打分偏置；
3. 组级预选：将 128 个专家按 n_group 分组，取每组前 2 名求和作为组分数，再选 top-topk_group 个组，屏蔽其余组的专家；
4. 在候选组内取 top-num_experts_per_tok 个专家；
5. 若 norm_topk_prob=True 对 top-k 权重归一化，最后乘以 routed_scaling_factor。

Glm4MoeMoE 将路由专家与共享专家结合：路由专家结果与共享专家（一个固定参与、不经过路由的 MLP，中间维度为 moe_intermediate_size * n_shared_experts）的输出相加：

hidden_states = hidden_states + self.shared_experts(residuals)

Glm4MoeExperts 将全部专家的权重保存为 3D 张量（gate_up_proj: [n_experts, 2*intermediate, hidden]；down_proj: [n_experts, hidden, intermediate]），并在 forward 中通过 one-hot 掩码找出被命中的专家后逐个索引计算。该模块被装饰器 @use_experts_implementation 修饰，意味着在特定推理引擎下可用更高效的专家内核替换默认的逐个专家循环。路由分数/权重会以 router_logits 形式保留，可配合 AuxLoss 做负载均衡训练。

主干与前向：Glm4MoeModel / Glm4MoeForCausalLM

• Glm4MoeModel：由 embed_tokens、nn.ModuleList 堆叠的 Glm4MoeDecoderLayer、末层 Glm4MoeRMSNorm 与旋转位置编码构成；forward 接受 input_ids/inputs_embeds（二选一）、attention_mask、position_ids、past_key_values、use_cache 等参数，返回 BaseModelOutputWithPast。缓存默认使用 DynamicCache，位置编码在整个序列上统一计算一次后逐层复用（position_embeddings 作为元组传入各层）。
• Glm4MoeForCausalLM：在主干之上增加无 bias 的 lm_head，并继承 GenerationMixin 支持 generate()；前向支持 labels 计算交叉熵 loss，以及 logits_to_keep 参数（只计算末尾若干位置的 logits，配合投机解码/训练可省显存）。forward docstring 中给出的完整调用示例（注意其中 Glm4MoeForCausalLM.from_pretrained("meta-glm4_moe/Glm4Moe-2-7b-hf") 只是一个占位式伪标识符，实际请替换为你要加载的官方 hub 仓库 id，如 zai-org 名下各版本 checkpoint）如下：

>>> from transformers import AutoTokenizer, Glm4MoeForCausalLM

>>> model = Glm4MoeForCausalLM.from_pretrained("zai-org/GLM-4.5")
>>> tokenizer = AutoTokenizer.from_pretrained("zai-org/GLM-4.5")

>>> prompt = "Hey, are you conscious? Can you talk to me?"
>>> inputs = tokenizer(prompt, return_tensors="pt")

>>> # Generate
>>> generate_ids = model.generate(inputs.input_ids, max_length=30)
>>> tokenizer.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
"Hey, are you conscious? Can you talk to me?\nI'm not conscious, but I can talk to you."

Glm4MoeForCausalLM 在类级还声明了 _tied_weights_keys = {"lm_head.weight": "model.embed_tokens.weight"}（即期望结构上 lm_head 与嵌入解绑，tie_word_embeddings=False）、TP 侧 {"lm_head": "colwise_gather_output"}、PP 侧与 FSDP 侧的 keep_full_weight 计划，便于大规模分布式部署时按计划自动切分。

从配置类到实际模型的接入方式

与所有 Transformers 模型一致，Glm4MoeConfig 支持两种典型用法。其一，从零构造随机初始化模型（权重未经训练，仅供结构测试/预训练起步）：

>>> from transformers import Glm4MoeModel, Glm4MoeConfig

>>> # Initializing a Glm4Moe style configuration
>>> configuration = Glm4MoeConfig()

>>> # Initializing a model from the GLM-4-MOE style configuration
>>> model = Glm4MoeModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

其二（更常见的生产路径），通过 AutoConfig/AutoModelForCausalLM 从 hub 直接加载官方权重。仓库的 tests/models/glm4_moe/test_modeling_glm4_moe.py 中 Glm4MoeModelTest(CausalLMModelTest, unittest.TestCase) 与配套的 Glm4MoeModelTester 覆盖了该架构在 eager/SDPA/Flash Attention 下的前向、KV cache、generate()、梯度检查点、MoE 路由输出等通用因果 LM 行为测试，是验证自定义配置与本地部署正确性的参考基线。

使用注意事项

• MTP 层缺失：若需复现官方完整结构（含多 token 预测加速），需等待官方发布包含 MTP 的实现或配合 vLLM / SGLang 侧实现使用；在 Transformers 中加载官方权重不受影响，多出的 MTP 权重会被忽略。
• 显存与专家执行：128 个路由专家 + 8 路 top-k 意味着单层 MoE 参数量巨大，建议配合 device_map="auto"、4-bit/8-bit 量化或上文的 TP/EP 并行计划部署；路由器与归一化层的 float32 精度约束（_keep_in_fp32_modules_strict）不应被关闭。
• 上下文长度：max_position_embeddings 默认 131072（128K），GLM-4.6/4.7 的官方发布口径为 200K，若需超出默认值使用，请确认所加载配置与 RoPE 外推设置，并按需调整 rope_parameters（源码通过 dynamic_rope_update 支持动态 RoPE 扩展）。
• 思考模式：thinking 块与工具调用的解析依赖模型配套的 parser，请在生成后用相应工具处理输出，而不应假定纯文本中已剥离思考内容。

小结

GLM-4.5/4.6/4.7 系列在 Transformers 中以 glm4_moe 架构落地：Glm4MoeConfig 定义了 128 专家、8 路 top-k、分组路由与浅层稠密替换等 MoE 细节；Glm4MoeModel/Glm4MoeForCausalLM 提供了完整可用的前向与生成能力；配置内置的 TP/PP/EP 方案与模块化生成链路（modular 源文件）则让社区可以在理解其 DeepSeek-V3 系血缘的基础上自由扩展。要查看实现细节、并行方案与测试基线，可继续阅读 configuration_glm4_moe.py、modeling_glm4_moe.py、modular_glm4_moe.py 与 tests/models/glm4_moe/test_modeling_glm4_moe.py。