Transformers 中的 Glm4vMoe 模型GLM-4.5V / GLM-4.1V-Thinking 视觉语言 MoE 架构解析与实战指南【免费下载链接】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/transformersGLM-VGLM-4.5V、GLM-4.6V 与 GLM-4.1V-Thinking是由 zai-org 提出的一族开源视觉语言模型VLM面向通用多模态理解与推理。本文以docs/source/en/model_doc/glm4v_moe.md为骨架结合 Transformers 仓库内 Glm4vMoe 的源码实现配置、建模、模块化生成、转换脚本与测试完整讲解 Glm4vMoe 在 Transformers 中的注册方式、Glm4vMoeConfig/Glm4vMoeTextConfig/Glm4vMoeVisionConfig全部关键超参数、从“视觉 patch 编码 → 视觉 Transformer → Patch Merger → MoE 语言解码器”的前向数据流、M-RoPE 三维位置编码与视频时间戳处理以及用AutoProcessor加载真实 checkpoint 做图像/视频条件文本生成的完整可用示例。读完你既能无障碍阅读 Glm4vMoe 相关源码也能直接跑通 GLM-4.5V 系列 checkpoint 的多模态推理。模型背景与支持情况该模型在 Hugging Face 论文平台上发布于 2025-07-01并已于 2025-08-08 合入本仓库见 模型文档 头注。文档所引论文标题为GLM-4.5V and GLM-4.1V-Thinking: Towards Versatile Multimodal Reasoning with Scalable Reinforcement Learning其摘要指出该系列 VLM 由大规模预训练的视觉基础模型起步提出带课程采样的强化学习RLCS框架以提升 STEM 解题、视频理解、内容识别、代码、grounding、GUI Agent 与长文档解读等多维能力论文同时引入原生工具调用、128K 上下文窗口的 GLM-4.6V 系列。这些为论文所述背景非本仓库实现层面的度量结论。文档声明本模型类型支持以下 zai-org checkpoint即对应model_typeglm4v_moe的模型仓库zai-org/GLM-4.5Vzai-org/GLM-4.6V在配置类 docstring 中另见zai-org/GLM-4.1V-9B-Thinking其视觉编码器配置Glm4vMoeVisionConfig即以该 checkpoint 为示例。模型由 Raushan Turganbay 与 Yuxuan Zhang 贡献。架构血缘从源码看继承关系Glm4vMoe 并不是从零写成的巨型建模文件而是通过 Transformers v5 的modular 机制组装而来。本源文件 modeling_glm4v_moe.py 顶部有醒目告警该文件由 modular_glm4v_moe.py 自动生成改动应写入 modular 文件、由 CI 再生成。阅读 modular 文件可清晰看到架构“拼图”文本侧Glm4vMoeTextConfig继承Glm4MoeConfigGlm4vMoeTextAttention继承Glm4AttentionRouter 继承Glm4MoeTopkRouter解码层继承Glm4MoeDecoderLayerMoE 专家权重类Glm4vMoeTextExperts直接复用DeepSeek-V3 风格的融合专家参数DeepseekV3Experts顶层Glm4vMoeConfig继承Glm4vConfig视觉侧Glm4vMoeVisionModel继承Glm4vVisionModel输出结构体Glm4vMoeModelOutputWithPast/Glm4vMoeCausalLMOutputWithPast与辅助负载均衡损失复用自Qwen3-VL-MoE的实现。因此可将 Glm4vMoe 通俗理解为“GLM-4V 的多模态视觉外壳 GLM-4-MoE 的稀疏文本解码器 DeepSeek-V3 的专家参数排布”的组合体这也是理解其源码的关键捷径。配置体系三个 Config 类全解Glm4vMoe 采用复合配置结构由 configuration_glm4v_moe.py 定义注册的模型类型分别为glm4v_moe、glm4v_moe_text、glm4v_moe_vision。Glm4vMoeConfig通过sub_configs把vision_config与text_config两个子配置组合到一起并在__post_init__中把 dict 形态的子配置实例化configuration_glm4v_moe.pyL184-L215。Glm4vMoeConfig顶层复合配置核心字段对应文档中的[[autodoc]] Glm4vMoeConfig参数默认值含义image_token_id151363占位图片 token在输入序列中会被替换为真实视觉特征video_token_id151364占位视频 tokenimage_start_token_id151339标记图像片段的起始 tokenimage_end_token_id151340标记图像片段的结束 tokenvideo_start_token_id151341标记视频片段的起始 tokenvideo_end_token_id151342标记视频片段的结束 tokentie_word_embeddingsFalse是否绑定输入/输出词嵌入值得注意的 BC向后兼容逻辑L209-L213v5 之前的部分保存把tie_word_embeddings放在text_config内部若根级保持默认而子配置为 True则__post_init__会把该标志提升到根级确保旧 checkpoint 加载行为一致。Glm4vMoeTextConfigMoE 文本解码器对应[[autodoc]] Glm4vMoeTextConfig。除常规解码器参数外MoE 相关参数尤为关键参数默认值含义vocab_size151424词表大小hidden_size/intermediate_size4096 / 10944隐层维度 / 稠密 FFN 中间维度num_hidden_layers46解码器层数num_attention_heads/num_key_value_heads96 / 8GQA 头配置分组因子 12max_position_embeddings65536最大序列长度GLM-4.6V 的 128K 上下文由 checkpoint 配置覆盖n_routed_experts128路由专家总数num_local_experts为其属性映射别名见 L75-L77num_experts_per_tok8每个 token 激活的专家数top-kn_shared_experts1共享专家数量n_group/topk_group1 / 1分组路由先按组粗筛再在入选组内选专家routed_scaling_factor1.0路由权重的缩放系数first_k_dense_replace1浅层前 k 层用稠密 MLP 而非 MoE见 L362-L365norm_topk_probTrue对 top-k 权重做归一化后再乘缩放因子moe_intermediate_size1408每个专家的中间维度router_aux_loss_coef0.0001辅助负载均衡损失系数attention_bias/attention_dropoutTrue / 0.0注意力偏置与 dropoutpartial_rotary_factor0.5RoPE 仅旋转头维度的一半__post_init__强制给定默认值L110-L112此外该类还携带 v5 的并行分片方案元数据base_model_tp_planQ/K/V 与 gate/up 投影按列切分、o/down 按行切分、base_model_pp_plan流水线切分、base_model_ep_plan专家并行gate 作为ep_router、专家参数走 grouped-gemmL54-L74可用于大规模分布式推理/训练。Glm4vMoeVisionConfig视觉编码器对应[[autodoc]] Glm4vMoeVisionConfig示例 checkpoint 为 GLM-4.1V-9B-Thinking参数默认值含义depth24视觉 Transformer 层数hidden_size1536视觉隐层维度num_heads12注意力头数image_size/patch_size336 / 14输入分辨率与空间 patch 尺寸temporal_patch_size2时间维 patch 尺寸视频抽帧/时间聚合spatial_merge_size2空间合并因子H/W 各除以 2配合 2×2 卷积下采样in_channels3输入通道out_hidden_size4096视觉输出维度需对齐文本hidden_sizeintermediate_size13696Patch Merger 中间维度rms_norm_eps1e-05RMSNorm epsilon建模实现纵深解析建模代码位于 modeling_glm4v_moe.py共 1783 行。Glm4vMoePreTrainedModelL402-L431声明了能力清单支持 gradient checkpointing、flash attention、SDPA、FlexAttention、输出录制与 kernel-from-hubRMSNorm并将e_score_correction_bias这类路由偏置严格保持在 FP32_keep_in_fp32_modules_strict这正对应后文路由的精度处理。视觉编码器从 3D Patch 到语言空间视觉模型Glm4vMoeVisionModelL734-L836的输入不是整图而是“扁平化 patch token”测试中pixel_values形状为(样本patch总数, 通道×patch²×时间patch)。处理链路如下Glm4vMoeVisionPatchEmbedL495-L512用步长等于核尺寸的3D 卷积Conv3d把(in_channels, temporal_patch, patch, patch)直接投影为视觉 token——temporal_patch_size2意味着每 2 帧合并为一个 token。Glm4vMoeVisionEmbeddingsL532-L603不直接查表取位置编码而是依据每张图/每段视频的真实(T,H,W)网格用F.grid_samplebicubic 插值把预训练的 2D 位置嵌入自适应地重采样到任意分辨率L593-L594支持 10800 等超大分辨率输入而无需重训。24 层Glm4vMoeVisionBlockL703-L730RMSNorm 预归一化 双向注意力 MLP。注意力支持 Flash Attention 的变长序列模式通过cu_seqlens打包L657-L674非 Flash 路径则按cu_seqlens切段逐个执行后拼接L676-L696。空间合并与维度对齐post_layernorm之后token 按spatial_merge_size2重排为 2×2 邻域经downsample2×2 Conv2dL760-L765把每 4 个 patch 合并为 1 个随后Glm4vMoeVisionPatchMergerL515-L529把视觉 token 从out_hidden_size4096经门控 MLPSiLU升维、再投影回文本侧隐层维度——以pooler_output形式返回供语言模型消费。Glm4vMoeModel.get_image_features/get_video_featuresL1192-L1230随后按image_grid_thw/video_grid_thw计算每个视觉样本的 token 数grid_thw.prod(-1) // spatial_merge_size²并把拼接的特征split回各样本交给上层masked_scatter使用。稀疏解码器共享专家 分组 top-k 路由 DeepSeek-V3 专家文本解码器由 46 层Glm4vMoeTextDecoderLayer堆叠。代码在first_k_dense_replace阈值处二选一L362-L365前 k 层用普通Glm4vMoeTextMLPSiLU 门控其余层用Glm4vMoeTextMoE。MoE 模块L294-L315输出 路由专家加权和 共享专家输出共享专家shared_experts是一个以moe_intermediate_size × n_shared_experts为中间维的稠密 MLP每层恒定计算负责吸收公共知识L304-L306路由专家Glm4vMoeTextExperts把全部专家参数压成三维张量——gate_up_proj形状(128, 2×1408, 4096)、down_proj形状(128, 4096, 1408)L263-L264即 DeepSeek-V3 的 fused gateup 排布配合 grouped-gemm 类 kernel 可显著提升访存效率。该类的use_experts_implementation装饰器允许接入仓库注册的高性能专家 kernel 后端Glm4vMoeTextTopkRouterL213-L251的前向值得细读用 sigmoid 把路由 logits 压到 (0,1)而非 softmax并累加e_score_correction_bias保持 FP32L224做专家偏差修正先把专家分成n_group组对每组取top-2 分数之和作为组得分筛出topk_group个候选组分组路由L231-L244仅在候选组内取 top-num_experts_per_tok个专家L245回查原始 sigmoid 分数作为权重norm_topk_probTrue时对 top-k 权重归一化最后乘routed_scaling_factorL247-L250。从这份路由实现可以推断这是对 DeepSeek/Router-zoo 式“先分组、再 top-k”路由策略的复刻相比全局 top-k它在 128 专家规模下缩小了候选空间、降低负载不均。多模态对齐与占位符替换顶层Glm4vMoeModel.forwardL1325-L1384的工作流程文本 token 先经词嵌入得inputs_embeds若提供pixel_values调用get_image_features得到图像特征并torch.cat拼接随后get_placeholder_maskL1232-L1272在input_ids上定位image_token_id/video_token_id占位符并用torch_compilable_check校验“占位 token 数 × 隐层维 特征元素数”最后masked_scatter把特征写入占位位置L1351。文档对 GLM-4.1V 与 GLM-4.5V 特别注释视频占位掩码与图像占位掩码相同L1253-L1255即两者共用一个imagetoken 占位视频路径同理由pixel_values_videosvideo_grid_thw注入L1353-L1359。M-RoPE时间/高/宽三维位置编码与视频帧多模态位置编码是该模型与普通 MoE LLM 的最大差异点对应文本Glm4vMoeTextRotaryEmbeddingL839-L904rope_parameters定义旋转类型与mrope_section[8,12,12]默认三段分别服务文本/高度/宽度等坐标分量的旋转维度L856partial_rotary_factor0.5只旋转头维度的前一半其余通过q_pass原样拼接见apply_rotary_pos_embL128-L139前向时把inv_freq沿第 0 维扩展为3 份对应 temporal/height/width 三个位置坐标L887经apply_mrope按 section 取模轮转拼接L900-L904。Glm4vMoeModel.get_rope_indexL1096-L1187按mm_token_type_ids文本0、图像1、视频2由 processor 一并返回把输入序列切成文本段与视觉段逐段计算位置文本段位置连续递增视觉段由get_vision_position_idsL1044-L1094从grid_thw生成三维坐标并叠加start_position偏移。与 Qwen2-VL 的关键差异在代码注释中明确写出L1106-L1107GLM-V 用时间戳分隔视频帧因此video_grid_thw会先按T帧数repeat_interleave、每帧T1L1131-L1133逐帧独立计算视觉位置。同时输出rope_deltas位置最大值与真实文本长度的差值缓存于self.rope_deltas供增量解码阶段推断正确三维位置compute_3d_position_idsL1274-L1321。解码阶段通过覆写_prepare_position_ids_for_generationL1594-L1630产出[4, bs, seq]形状的位置张量前 1 维是纯文本位置、后 3 维是视觉三维坐标。提示若向模型传了image_grid_thw/video_grid_thw却漏传mm_token_type_ids前向会直接抛出ValueErrorL1286-L1291请始终使用随 processor 返回的mm_token_type_ids。训练辅助损失与生成输出Glm4vMoeForConditionalGenerationL1456-L1774实现文档列出的forward/get_image_features/get_video_features。其特性复用了 Qwen3-VL-MoE 系的load_balancing_loss_funcL1387-L1453以 Switch Transformer 论文Equations 4-6的形式对每层路由 logits 统计各专家的 token 分配占比与概率之和惩罚路由不均且按层累加、把峰值内存维持在O(seq_len×num_experts)当output_router_logitsTrue时返回router_logits与aux_loss训练时把aux_loss乘上router_aux_loss_coef0.0001叠加到主损失L1570-L1581forward支持labelsLM 损失自动忽略填充与视觉占位外的位置见 Transformers 统一loss_function、logits_to_keep仅计算末尾 logits 以省显存L1563-L1564结果类型Glm4vMoeCausalLMOutputWithPast/Glm4vMoeModelOutputWithPast携带rope_deltas、router_logits、aux_loss其中rope_deltas字段已标记弃用v5.20 移除应改读model.base_model.rope_deltas覆写_expand_inputs_for_generationL1688-L1774以支持 batch 扩展场景下无 batch 维的视觉张量pixel_values、image_grid_thw、pixel_values_videos、video_grid_thw、second_per_grid_ts的正确复制并用_get_image_nums_and_video_numsL1632-L1686借助起止 token 的累计和识别“视频跨度内”的图像 token避免 beam/采样多路复制时视觉数据错位。使用示例图像问答与视频描述文档对应的[[autodoc]]代码示例源自Glm4vMoeForConditionalGeneration.forwarddocstring展示的完整链路是AutoProcessor负责apply_chat_template构造含视觉占位符的对话、把远程图片下载为 PIL、并返回input_ids/pixel_values/image_grid_thw/mm_token_type_ids等模型端则直接从这些输入generate。以下是自洽的最小可运行范式图像场景import httpx from io import BytesIO from PIL import Image from transformers import AutoProcessor, Glm4vMoeForConditionalGeneration model Glm4vMoeForConditionalGeneration.from_pretrained(zai-org/GLM-4.5V) processor AutoProcessor.from_pretrained(zai-org/GLM-4.5V) messages [ { role: user, content: [ {type: image, url: https://www.ilankelman.org/stopsigns/australia.jpg}, {type: text, text: What is shown in this image?}, ], }, ] with httpx.stream(GET, messages[0][content][0][url]) as response: image Image.open(BytesIO(response.read())) text processor.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue) # 图像场景url 已被读取为 image 后可改写 content 中的 url 为本地 PIL 对象 # 或按 processor 约定传 images[image] 并配合 vision_infos。 inputs processor(text[text], images[image]) generate_ids model.generate(**inputs, max_new_tokens256) output processor.batch_decode(generate_ids, skip_special_tokensTrue)[0] print(output)关键使用约定可归纳为四条一切输入交给 processorapply_chat_template 视觉输入会返回input_ids、attention_mask、pixel_values、image_grid_thw视频则为pixel_values_videos、video_grid_thw以及必需的mm_token_type_ids这些键可直接展开传给generate对话模板原生支持图片与视频 content typeGLM-4.1V/4.5V 的视频与图像在 token 流中共用image占位processor 内部自行管理起止 token若手动拼输入务必把占位 token 数image_token_id出现次数与视觉特征 token 数对齐否则前向中的torch_compilable_check会报“Image features and image tokens do not match”生成阶段由模型内部覆写的 3D position ids 逻辑接管无需手动传position_ids。测试与质量保障仓库测试见 test_modeling_glm4v_moe.py单元级Glm4vMoeModelTest继承ModelTesterMixinGenerationTesterMixin使用缩小版配置如 2 层、8 路由专家、GQA、112px 图、mrope_section[2,2]覆盖通用建模测试并对inputs_embeds与input_ids两条路径的输出做assert_close等价验证测试构造中刻意把视频/图像 token 全部替换为 pad防止随机 id 命中特殊占位符L158-L163慢速集成测试Glm4vMoeIntegrationTest真实加载zai-org/GLM-4.5V覆盖 batch 内混合“图A 图B 纯文本”三种样本的生成、视频描述生成并对 tokenizer 产出的前 17 个input_ids、pixel_values切片做数值级断言L362-L381FlashAttention-2 专项用attn_implementationflash_attention_2bfloat16重复 batch 生成测试L434-L463。注意 Flash 下mm_token_type_ids/grid 信息仍需照常传入视觉注意力依赖cu_seqlens的变长打包路径。扩展权重转换、Auto 注册与相关阅读权重转换脚本 convert_glm4v_moe_mgt_weights_to_hf.py762 行用于把原始 Megatron 训练权重映射为 HF 格式Auto API 已完成注册配置类见 auto_mappings.pyglm4v_moe→Glm4vMoeConfig等模型类见 modeling_auto.py 与 L1109Glm4vMoeForConditionalGenerationprocessor 见 processing_auto.pyglm4v_moe→Glm4vProcessor若想对比同一家族的紧凑/稠密变体可阅读同目录的 glm4v 模型文档GLM-4.1V/GLM-4.5V 的稠密实现与Glm4vProcessor用法与 glm46v 模型文档文本侧稀疏化细节可参考glm4_moe与qwen3_vl_moe模型目录。小结围绕 Glm4vMoe可以从仓库得到一条完整的技术链modular 元文件定义了“视觉Glm4v、稀疏文本Glm4Moe/DeepseekV3、输出Qwen3VLMoe”的架构配方复合配置对象承载三份子配置并完成 BC 兼容Glm4vMoeForConditionalGeneration把 3D patch 卷积视觉塔、bicubic 可插值位置编码、Patch Merger、128 专家分组路由 共享专家的 MoE 解码器以及 M-RoPE 三维位置/视频时间戳机制串联成端到端可用的多模态语言模型。使用层面记住“chat template 生成对话、processor 返回全部视觉键、生成交给模型”的三步法即可稳定跑通 GLM-4.5V / GLM-4.6V 的图像理解与视频理解任务。【免费下载链接】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），仅供参考
Transformers 中的 Glm4vMoe 模型：GLM-4.5V / GLM-4.1V-Thinking 视觉语言 MoE 架构解析与实战指南
Transformers 中的 Glm4vMoe 模型GLM-4.5V / GLM-4.1V-Thinking 视觉语言 MoE 架构解析与实战指南【免费下载链接】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/transformersGLM-VGLM-4.5V、GLM-4.6V 与 GLM-4.1V-Thinking是由 zai-org 提出的一族开源视觉语言模型VLM面向通用多模态理解与推理。本文以docs/source/en/model_doc/glm4v_moe.md为骨架结合 Transformers 仓库内 Glm4vMoe 的源码实现配置、建模、模块化生成、转换脚本与测试完整讲解 Glm4vMoe 在 Transformers 中的注册方式、Glm4vMoeConfig/Glm4vMoeTextConfig/Glm4vMoeVisionConfig全部关键超参数、从“视觉 patch 编码 → 视觉 Transformer → Patch Merger → MoE 语言解码器”的前向数据流、M-RoPE 三维位置编码与视频时间戳处理以及用AutoProcessor加载真实 checkpoint 做图像/视频条件文本生成的完整可用示例。读完你既能无障碍阅读 Glm4vMoe 相关源码也能直接跑通 GLM-4.5V 系列 checkpoint 的多模态推理。模型背景与支持情况该模型在 Hugging Face 论文平台上发布于 2025-07-01并已于 2025-08-08 合入本仓库见 模型文档 头注。文档所引论文标题为GLM-4.5V and GLM-4.1V-Thinking: Towards Versatile Multimodal Reasoning with Scalable Reinforcement Learning其摘要指出该系列 VLM 由大规模预训练的视觉基础模型起步提出带课程采样的强化学习RLCS框架以提升 STEM 解题、视频理解、内容识别、代码、grounding、GUI Agent 与长文档解读等多维能力论文同时引入原生工具调用、128K 上下文窗口的 GLM-4.6V 系列。这些为论文所述背景非本仓库实现层面的度量结论。文档声明本模型类型支持以下 zai-org checkpoint即对应model_typeglm4v_moe的模型仓库zai-org/GLM-4.5Vzai-org/GLM-4.6V在配置类 docstring 中另见zai-org/GLM-4.1V-9B-Thinking其视觉编码器配置Glm4vMoeVisionConfig即以该 checkpoint 为示例。模型由 Raushan Turganbay 与 Yuxuan Zhang 贡献。架构血缘从源码看继承关系Glm4vMoe 并不是从零写成的巨型建模文件而是通过 Transformers v5 的modular 机制组装而来。本源文件 modeling_glm4v_moe.py 顶部有醒目告警该文件由 modular_glm4v_moe.py 自动生成改动应写入 modular 文件、由 CI 再生成。阅读 modular 文件可清晰看到架构“拼图”文本侧Glm4vMoeTextConfig继承Glm4MoeConfigGlm4vMoeTextAttention继承Glm4AttentionRouter 继承Glm4MoeTopkRouter解码层继承Glm4MoeDecoderLayerMoE 专家权重类Glm4vMoeTextExperts直接复用DeepSeek-V3 风格的融合专家参数DeepseekV3Experts顶层Glm4vMoeConfig继承Glm4vConfig视觉侧Glm4vMoeVisionModel继承Glm4vVisionModel输出结构体Glm4vMoeModelOutputWithPast/Glm4vMoeCausalLMOutputWithPast与辅助负载均衡损失复用自Qwen3-VL-MoE的实现。因此可将 Glm4vMoe 通俗理解为“GLM-4V 的多模态视觉外壳 GLM-4-MoE 的稀疏文本解码器 DeepSeek-V3 的专家参数排布”的组合体这也是理解其源码的关键捷径。配置体系三个 Config 类全解Glm4vMoe 采用复合配置结构由 configuration_glm4v_moe.py 定义注册的模型类型分别为glm4v_moe、glm4v_moe_text、glm4v_moe_vision。Glm4vMoeConfig通过sub_configs把vision_config与text_config两个子配置组合到一起并在__post_init__中把 dict 形态的子配置实例化configuration_glm4v_moe.pyL184-L215。Glm4vMoeConfig顶层复合配置核心字段对应文档中的[[autodoc]] Glm4vMoeConfig参数默认值含义image_token_id151363占位图片 token在输入序列中会被替换为真实视觉特征video_token_id151364占位视频 tokenimage_start_token_id151339标记图像片段的起始 tokenimage_end_token_id151340标记图像片段的结束 tokenvideo_start_token_id151341标记视频片段的起始 tokenvideo_end_token_id151342标记视频片段的结束 tokentie_word_embeddingsFalse是否绑定输入/输出词嵌入值得注意的 BC向后兼容逻辑L209-L213v5 之前的部分保存把tie_word_embeddings放在text_config内部若根级保持默认而子配置为 True则__post_init__会把该标志提升到根级确保旧 checkpoint 加载行为一致。Glm4vMoeTextConfigMoE 文本解码器对应[[autodoc]] Glm4vMoeTextConfig。除常规解码器参数外MoE 相关参数尤为关键参数默认值含义vocab_size151424词表大小hidden_size/intermediate_size4096 / 10944隐层维度 / 稠密 FFN 中间维度num_hidden_layers46解码器层数num_attention_heads/num_key_value_heads96 / 8GQA 头配置分组因子 12max_position_embeddings65536最大序列长度GLM-4.6V 的 128K 上下文由 checkpoint 配置覆盖n_routed_experts128路由专家总数num_local_experts为其属性映射别名见 L75-L77num_experts_per_tok8每个 token 激活的专家数top-kn_shared_experts1共享专家数量n_group/topk_group1 / 1分组路由先按组粗筛再在入选组内选专家routed_scaling_factor1.0路由权重的缩放系数first_k_dense_replace1浅层前 k 层用稠密 MLP 而非 MoE见 L362-L365norm_topk_probTrue对 top-k 权重做归一化后再乘缩放因子moe_intermediate_size1408每个专家的中间维度router_aux_loss_coef0.0001辅助负载均衡损失系数attention_bias/attention_dropoutTrue / 0.0注意力偏置与 dropoutpartial_rotary_factor0.5RoPE 仅旋转头维度的一半__post_init__强制给定默认值L110-L112此外该类还携带 v5 的并行分片方案元数据base_model_tp_planQ/K/V 与 gate/up 投影按列切分、o/down 按行切分、base_model_pp_plan流水线切分、base_model_ep_plan专家并行gate 作为ep_router、专家参数走 grouped-gemmL54-L74可用于大规模分布式推理/训练。Glm4vMoeVisionConfig视觉编码器对应[[autodoc]] Glm4vMoeVisionConfig示例 checkpoint 为 GLM-4.1V-9B-Thinking参数默认值含义depth24视觉 Transformer 层数hidden_size1536视觉隐层维度num_heads12注意力头数image_size/patch_size336 / 14输入分辨率与空间 patch 尺寸temporal_patch_size2时间维 patch 尺寸视频抽帧/时间聚合spatial_merge_size2空间合并因子H/W 各除以 2配合 2×2 卷积下采样in_channels3输入通道out_hidden_size4096视觉输出维度需对齐文本hidden_sizeintermediate_size13696Patch Merger 中间维度rms_norm_eps1e-05RMSNorm epsilon建模实现纵深解析建模代码位于 modeling_glm4v_moe.py共 1783 行。Glm4vMoePreTrainedModelL402-L431声明了能力清单支持 gradient checkpointing、flash attention、SDPA、FlexAttention、输出录制与 kernel-from-hubRMSNorm并将e_score_correction_bias这类路由偏置严格保持在 FP32_keep_in_fp32_modules_strict这正对应后文路由的精度处理。视觉编码器从 3D Patch 到语言空间视觉模型Glm4vMoeVisionModelL734-L836的输入不是整图而是“扁平化 patch token”测试中pixel_values形状为(样本patch总数, 通道×patch²×时间patch)。处理链路如下Glm4vMoeVisionPatchEmbedL495-L512用步长等于核尺寸的3D 卷积Conv3d把(in_channels, temporal_patch, patch, patch)直接投影为视觉 token——temporal_patch_size2意味着每 2 帧合并为一个 token。Glm4vMoeVisionEmbeddingsL532-L603不直接查表取位置编码而是依据每张图/每段视频的真实(T,H,W)网格用F.grid_samplebicubic 插值把预训练的 2D 位置嵌入自适应地重采样到任意分辨率L593-L594支持 10800 等超大分辨率输入而无需重训。24 层Glm4vMoeVisionBlockL703-L730RMSNorm 预归一化 双向注意力 MLP。注意力支持 Flash Attention 的变长序列模式通过cu_seqlens打包L657-L674非 Flash 路径则按cu_seqlens切段逐个执行后拼接L676-L696。空间合并与维度对齐post_layernorm之后token 按spatial_merge_size2重排为 2×2 邻域经downsample2×2 Conv2dL760-L765把每 4 个 patch 合并为 1 个随后Glm4vMoeVisionPatchMergerL515-L529把视觉 token 从out_hidden_size4096经门控 MLPSiLU升维、再投影回文本侧隐层维度——以pooler_output形式返回供语言模型消费。Glm4vMoeModel.get_image_features/get_video_featuresL1192-L1230随后按image_grid_thw/video_grid_thw计算每个视觉样本的 token 数grid_thw.prod(-1) // spatial_merge_size²并把拼接的特征split回各样本交给上层masked_scatter使用。稀疏解码器共享专家 分组 top-k 路由 DeepSeek-V3 专家文本解码器由 46 层Glm4vMoeTextDecoderLayer堆叠。代码在first_k_dense_replace阈值处二选一L362-L365前 k 层用普通Glm4vMoeTextMLPSiLU 门控其余层用Glm4vMoeTextMoE。MoE 模块L294-L315输出 路由专家加权和 共享专家输出共享专家shared_experts是一个以moe_intermediate_size × n_shared_experts为中间维的稠密 MLP每层恒定计算负责吸收公共知识L304-L306路由专家Glm4vMoeTextExperts把全部专家参数压成三维张量——gate_up_proj形状(128, 2×1408, 4096)、down_proj形状(128, 4096, 1408)L263-L264即 DeepSeek-V3 的 fused gateup 排布配合 grouped-gemm 类 kernel 可显著提升访存效率。该类的use_experts_implementation装饰器允许接入仓库注册的高性能专家 kernel 后端Glm4vMoeTextTopkRouterL213-L251的前向值得细读用 sigmoid 把路由 logits 压到 (0,1)而非 softmax并累加e_score_correction_bias保持 FP32L224做专家偏差修正先把专家分成n_group组对每组取top-2 分数之和作为组得分筛出topk_group个候选组分组路由L231-L244仅在候选组内取 top-num_experts_per_tok个专家L245回查原始 sigmoid 分数作为权重norm_topk_probTrue时对 top-k 权重归一化最后乘routed_scaling_factorL247-L250。从这份路由实现可以推断这是对 DeepSeek/Router-zoo 式“先分组、再 top-k”路由策略的复刻相比全局 top-k它在 128 专家规模下缩小了候选空间、降低负载不均。多模态对齐与占位符替换顶层Glm4vMoeModel.forwardL1325-L1384的工作流程文本 token 先经词嵌入得inputs_embeds若提供pixel_values调用get_image_features得到图像特征并torch.cat拼接随后get_placeholder_maskL1232-L1272在input_ids上定位image_token_id/video_token_id占位符并用torch_compilable_check校验“占位 token 数 × 隐层维 特征元素数”最后masked_scatter把特征写入占位位置L1351。文档对 GLM-4.1V 与 GLM-4.5V 特别注释视频占位掩码与图像占位掩码相同L1253-L1255即两者共用一个imagetoken 占位视频路径同理由pixel_values_videosvideo_grid_thw注入L1353-L1359。M-RoPE时间/高/宽三维位置编码与视频帧多模态位置编码是该模型与普通 MoE LLM 的最大差异点对应文本Glm4vMoeTextRotaryEmbeddingL839-L904rope_parameters定义旋转类型与mrope_section[8,12,12]默认三段分别服务文本/高度/宽度等坐标分量的旋转维度L856partial_rotary_factor0.5只旋转头维度的前一半其余通过q_pass原样拼接见apply_rotary_pos_embL128-L139前向时把inv_freq沿第 0 维扩展为3 份对应 temporal/height/width 三个位置坐标L887经apply_mrope按 section 取模轮转拼接L900-L904。Glm4vMoeModel.get_rope_indexL1096-L1187按mm_token_type_ids文本0、图像1、视频2由 processor 一并返回把输入序列切成文本段与视觉段逐段计算位置文本段位置连续递增视觉段由get_vision_position_idsL1044-L1094从grid_thw生成三维坐标并叠加start_position偏移。与 Qwen2-VL 的关键差异在代码注释中明确写出L1106-L1107GLM-V 用时间戳分隔视频帧因此video_grid_thw会先按T帧数repeat_interleave、每帧T1L1131-L1133逐帧独立计算视觉位置。同时输出rope_deltas位置最大值与真实文本长度的差值缓存于self.rope_deltas供增量解码阶段推断正确三维位置compute_3d_position_idsL1274-L1321。解码阶段通过覆写_prepare_position_ids_for_generationL1594-L1630产出[4, bs, seq]形状的位置张量前 1 维是纯文本位置、后 3 维是视觉三维坐标。提示若向模型传了image_grid_thw/video_grid_thw却漏传mm_token_type_ids前向会直接抛出ValueErrorL1286-L1291请始终使用随 processor 返回的mm_token_type_ids。训练辅助损失与生成输出Glm4vMoeForConditionalGenerationL1456-L1774实现文档列出的forward/get_image_features/get_video_features。其特性复用了 Qwen3-VL-MoE 系的load_balancing_loss_funcL1387-L1453以 Switch Transformer 论文Equations 4-6的形式对每层路由 logits 统计各专家的 token 分配占比与概率之和惩罚路由不均且按层累加、把峰值内存维持在O(seq_len×num_experts)当output_router_logitsTrue时返回router_logits与aux_loss训练时把aux_loss乘上router_aux_loss_coef0.0001叠加到主损失L1570-L1581forward支持labelsLM 损失自动忽略填充与视觉占位外的位置见 Transformers 统一loss_function、logits_to_keep仅计算末尾 logits 以省显存L1563-L1564结果类型Glm4vMoeCausalLMOutputWithPast/Glm4vMoeModelOutputWithPast携带rope_deltas、router_logits、aux_loss其中rope_deltas字段已标记弃用v5.20 移除应改读model.base_model.rope_deltas覆写_expand_inputs_for_generationL1688-L1774以支持 batch 扩展场景下无 batch 维的视觉张量pixel_values、image_grid_thw、pixel_values_videos、video_grid_thw、second_per_grid_ts的正确复制并用_get_image_nums_and_video_numsL1632-L1686借助起止 token 的累计和识别“视频跨度内”的图像 token避免 beam/采样多路复制时视觉数据错位。使用示例图像问答与视频描述文档对应的[[autodoc]]代码示例源自Glm4vMoeForConditionalGeneration.forwarddocstring展示的完整链路是AutoProcessor负责apply_chat_template构造含视觉占位符的对话、把远程图片下载为 PIL、并返回input_ids/pixel_values/image_grid_thw/mm_token_type_ids等模型端则直接从这些输入generate。以下是自洽的最小可运行范式图像场景import httpx from io import BytesIO from PIL import Image from transformers import AutoProcessor, Glm4vMoeForConditionalGeneration model Glm4vMoeForConditionalGeneration.from_pretrained(zai-org/GLM-4.5V) processor AutoProcessor.from_pretrained(zai-org/GLM-4.5V) messages [ { role: user, content: [ {type: image, url: https://www.ilankelman.org/stopsigns/australia.jpg}, {type: text, text: What is shown in this image?}, ], }, ] with httpx.stream(GET, messages[0][content][0][url]) as response: image Image.open(BytesIO(response.read())) text processor.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue) # 图像场景url 已被读取为 image 后可改写 content 中的 url 为本地 PIL 对象 # 或按 processor 约定传 images[image] 并配合 vision_infos。 inputs processor(text[text], images[image]) generate_ids model.generate(**inputs, max_new_tokens256) output processor.batch_decode(generate_ids, skip_special_tokensTrue)[0] print(output)关键使用约定可归纳为四条一切输入交给 processorapply_chat_template 视觉输入会返回input_ids、attention_mask、pixel_values、image_grid_thw视频则为pixel_values_videos、video_grid_thw以及必需的mm_token_type_ids这些键可直接展开传给generate对话模板原生支持图片与视频 content typeGLM-4.1V/4.5V 的视频与图像在 token 流中共用image占位processor 内部自行管理起止 token若手动拼输入务必把占位 token 数image_token_id出现次数与视觉特征 token 数对齐否则前向中的torch_compilable_check会报“Image features and image tokens do not match”生成阶段由模型内部覆写的 3D position ids 逻辑接管无需手动传position_ids。测试与质量保障仓库测试见 test_modeling_glm4v_moe.py单元级Glm4vMoeModelTest继承ModelTesterMixinGenerationTesterMixin使用缩小版配置如 2 层、8 路由专家、GQA、112px 图、mrope_section[2,2]覆盖通用建模测试并对inputs_embeds与input_ids两条路径的输出做assert_close等价验证测试构造中刻意把视频/图像 token 全部替换为 pad防止随机 id 命中特殊占位符L158-L163慢速集成测试Glm4vMoeIntegrationTest真实加载zai-org/GLM-4.5V覆盖 batch 内混合“图A 图B 纯文本”三种样本的生成、视频描述生成并对 tokenizer 产出的前 17 个input_ids、pixel_values切片做数值级断言L362-L381FlashAttention-2 专项用attn_implementationflash_attention_2bfloat16重复 batch 生成测试L434-L463。注意 Flash 下mm_token_type_ids/grid 信息仍需照常传入视觉注意力依赖cu_seqlens的变长打包路径。扩展权重转换、Auto 注册与相关阅读权重转换脚本 convert_glm4v_moe_mgt_weights_to_hf.py762 行用于把原始 Megatron 训练权重映射为 HF 格式Auto API 已完成注册配置类见 auto_mappings.pyglm4v_moe→Glm4vMoeConfig等模型类见 modeling_auto.py 与 L1109Glm4vMoeForConditionalGenerationprocessor 见 processing_auto.pyglm4v_moe→Glm4vProcessor若想对比同一家族的紧凑/稠密变体可阅读同目录的 glm4v 模型文档GLM-4.1V/GLM-4.5V 的稠密实现与Glm4vProcessor用法与 glm46v 模型文档文本侧稀疏化细节可参考glm4_moe与qwen3_vl_moe模型目录。小结围绕 Glm4vMoe可以从仓库得到一条完整的技术链modular 元文件定义了“视觉Glm4v、稀疏文本Glm4Moe/DeepseekV3、输出Qwen3VLMoe”的架构配方复合配置对象承载三份子配置并完成 BC 兼容Glm4vMoeForConditionalGeneration把 3D patch 卷积视觉塔、bicubic 可插值位置编码、Patch Merger、128 专家分组路由 共享专家的 MoE 解码器以及 M-RoPE 三维位置/视频时间戳机制串联成端到端可用的多模态语言模型。使用层面记住“chat template 生成对话、processor 返回全部视觉键、生成交给模型”的三步法即可稳定跑通 GLM-4.5V / GLM-4.6V 的图像理解与视频理解任务。【免费下载链接】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），仅供参考
