Transformers 中的 GLM-OCR 模型使用与源码解析面向复杂文档的多模态 OCR【免费下载链接】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导读本文围绕 Hugging Face Transformers 于 2026-01-27 收录的 GLM-OCR 多模态模型展开结合仓库内模型配置源码与建模源码讲解如何用AutoProcessorGlmOcrForConditionalGeneration完成单图与批量文档识别并深入说明其轻量视觉编码器 高效 token 下采样 0.5B 语言解码器的架构原理、M-RoPE 三维位置编码机制与 Flash Attention 2 加速方法。读完本文你将掌握在 Transformers 中一键推理 GLM-OCR并能读懂其每个配置项的来源与底层调用链。GLM-OCR 模型概览GLM-OCR 是 Z.aizai-org团队提出的多模态光学字符识别OCR模型专门面向复杂文档理解场景。模型的文档页位于 docs/source/en/model_doc/glm_ocr.md在仓库中被归类为一个完整可用的model_type glm_ocr的自动映射模型注册于 auto_mappings.py 与 modeling_auto.py。根据官方文档介绍GLM-OCR 的骨干结构由三部分组成CogViT 视觉编码器在大规模图文数据上预训练负责把文档图像编码为视觉特征轻量跨模态连接器cross-modal connector通过高效 token 下采样压缩视觉 token 数量降低后续语言模型的注意力计算成本GLM-0.5B 语言解码器以自回归方式输出识别结果。官方文档同时给出三个关键特性轻量总参数量仅 0.9B却在 OmniDocBench V1.5 上取得 94.62 的成绩注此分数与称号均引自官方模型文档作为选型参考而非本文评测结论多任务擅长文本识别、公式识别、表格识别与信息抽取多模态可同时处理文档图像中的文字、公式与表格。从源码结构看GLM-OCR 不是从零实现的独立代码而是基于同一仓库中 GLM-4V 系列进行模块化复用。在 modular_glm_ocr.py 中可以清楚地看到GlmOcrRMSNorm(Glm4vRMSNorm)、GlmOcrTextConfig(Glm4vTextConfig)、GlmOcrConfig(Glm4vConfig)、GlmOcrModel(Glm4vModel)、GlmOcrForConditionalGeneration(Glm4vForConditionalGeneration)等一系列继承关系而由 modular 自动生成、供用户实际加载的完整实现在 modeling_glm_ocr.py。环境准备与模型加载运行 GLM-OCR 需要一个支持 CUDA 的 PyTorch 环境以及可联网访问 Hugging Face Hub 的网络条件。之后通过 Transformers 的 Auto API 即可加载处理器与模型from transformers import AutoProcessor, GlmOcrForConditionalGeneration model_id zai-org/GLM-OCR processor AutoProcessor.from_pretrained(model_id) model GlmOcrForConditionalGeneration.from_pretrained( model_id, device_mapauto, )说明两点处理器仓库中并未为 GLM-OCR 单独新增一个 processor 类src/transformers/models/glm_ocr/下只有__init__.py、configuration_glm_ocr.py、modeling_glm_ocr.py与modular_glm_ocr.py四个文件AutoProcessor.from_pretrained依据 checkpoint 自身配置中声明的 processor 家族完成解析。测试用例 test_modeling_glm_ocr.py 中同样直接使用AutoProcessor.from_pretrained(zai-org/GLM-OCR)说明这套用法是官方验证过的标准路径。模型GlmOcrForConditionalGeneration在内部由GlmOcrModel包含visual视觉塔与language_model文本塔与一个lm_head线性层构成参数量约为 0.9B普通单卡即可运行。单图推理官方文档给出的单图推理方式是把图片与指令按chat template形式组织成消息交给处理器做模板化 tokenize再交给模型generate。完整可运行代码如下from transformers import AutoProcessor, GlmOcrForConditionalGeneration model_id zai-org/GLM-OCR processor AutoProcessor.from_pretrained(model_id) model GlmOcrForConditionalGeneration.from_pretrained( model_id, device_mapauto, ) messages [ { role: user, content: [ {type: image, url: https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/car.jpg}, {type: text, text: Text Recognition:}, ], } ] inputs processor.apply_chat_template( messages, tokenizeTrue, add_generation_promptTrue, return_dictTrue, return_tensorspt, ).to(model.device) output model.generate(**inputs, max_new_tokens512) print(processor.decode(output[0], skip_special_tokensTrue))几个值得注意的实操要点任务提示词以英文冒号结尾Text Recognition:、Formula Recognition:这类指令风格沿用 GLM 系列 VLM 的惯例冒号用于衔接模型输出图片以 URL 形式给出消息中的{type: image, url: ...}由处理器在内部下载并预处理为像素张量无需手动调用图像加载工具apply_chat_template完成全部组装它内部按模型自带的对话模板填充特殊占位 token如 image token并返回可直接送入模型的input_ids等张量输出解码generate结果需经processor.decode(..., skip_special_tokensTrue)去掉特殊 token得到干净的 OCR 文本。模型forward的 docstring 示例modeling_glm_ocr.py也演示了httpx下载图片 PIL打开 chat template 的标准组合可作为本地文件图片推理时的参考。批量推理为了在多页文档、多张票据等场景下提高吞吐GLM-OCR 支持一次前向处理多张图片。此时只需把多个单图消息放进一个列表并给apply_chat_template传paddingTruefrom transformers import AutoProcessor, GlmOcrForConditionalGeneration model_id zai-org/GLM-OCR processor AutoProcessor.from_pretrained(model_id) model GlmOcrForConditionalGeneration.from_pretrained( model_id, device_mapauto, ) # First document message1 [ { role: user, content: [ {type: image, url: https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/car.jpg}, {type: text, text: Text Recognition:}, ], } ] # Second document message2 [ { role: user, content: [ {type: image, url: https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/bee.jpg}, {type: text, text: Text Recognition:}, ], } ] messages [message1, message2] inputs processor.apply_chat_template( messages, tokenizeTrue, add_generation_promptTrue, return_dictTrue, return_tensorspt, paddingTrue, ).to(model.device) output model.generate(**inputs, max_new_tokens128) print(processor.batch_decode(output, skip_special_tokensTrue))批量模式与单图模式仅有三点差别消息外层多包了一层列表、paddingTrue打开用于把不等长的序列对齐到同一 batch、解码改用processor.batch_decode。测试集成用例test_modeling_glm_ocr.py中多次验证了apply_chat_template→model.generate的端到端流程包括 beam search 等多返回序列场景说明批量生成路径是可靠支持的。注意文档示例中图片来自远程 URL。若在离线或内网环境使用请先把图片下载到本地再在消息中改用本地可访问的文件路径处理器对URL / 本地路径两种来源均可识别。使用 Flash Attention 2 加速推理文档说明 GLM-OCR 支持 Flash Attention 2用于显著降低注意力计算耗时与显存占用。加载分两步走第一步安装最新版 flash-attn 内核pip install -U flash-attn --no-build-isolation第二步以attn_implementation指定内核后加载模型from transformers import GlmOcrForConditionalGeneration model GlmOcrForConditionalGeneration.from_pretrained( zai-org/GLM-OCR, attn_implementationkernels-community/flash-attn2, # other options: kernels-community/vllm-flash-attn3, kernels-community/paged-attention device_mapauto, )除kernels-community/flash-attn2外文档还列出了两个可替换的社区内核选项kernels-community/vllm-flash-attn3与kernels-community/paged-attention后者为分页注意力配合 PagedAttention 推理服务使用。从源码层面可以印证 Flash Attention 在 GLM-OCR 中的落地方式视觉与文本两路的注意力实现都通过ALL_ATTENTION_FUNCTIONS抽象来按需选取内核。以视觉注意力为例modeling_glm_ocr.py 中的GlmOcrVisionAttention前向时先通过qkv融合线性层一次性投影出 Q/K/V并做 RMSNorm 归一化调用ALL_ATTENTION_FUNCTIONS.get_interface(self.config._attn_implementation, eager_attention_forward)选择当前配置对应的注意力函数当is_flash_attention_requested(self.config)为真时走 Flash Attention 分支不展开 padding而是借助cu_seqlens描述每条样本的真实长度配合max_seqlen对变长图像序列做无 padding 的批量注意力非 Flash 分支则按cu_seqlens将 batch 切分成若干块逐块做标准注意力后再拼接。因此Flash Attention 2 模式下省去了大量显存用于存储完整注意力矩阵同时对同一 batch 内尺寸不一的文档图也更友好。配置类详解GlmOcrConfig / GlmOcrVisionConfig / GlmOcrTextConfigGLM-OCR 采用与 GLM-4V 相同的三明治配置结构顶层GlmOcrConfig聚合了视觉子配置与文本子配置。全部默认值定义在 configuration_glm_ocr.py下面逐类列出。GlmOcrConfig顶层多模态配置model_type glm_ocr通过sub_configs声明两个子配置vision_config: GlmOcrVisionConfig与text_config: GlmOcrTextConfig。初始化时若传入 dict 会自动实例化为对应的子配置对象。默认字段如下参数默认值含义image_token_id59280图片占位 token在文本序列中代表此处插入图像特征video_token_id59281视频占位 token模型沿 GLM-4V 保留视频能力image_start_token_id59256图像内容起始标记image_end_token_id59257图像内容结束标记video_start_token_id59258视频内容起始标记video_end_token_id59259视频内容结束标记tie_word_embeddingsFalse是否让lm_head与词嵌入共享权重一个向后兼容细节值得注意configuration_glm_ocr.pyv5 之前的旧 checkpoint 会把tie_word_embeddings存在text_config内部__post_init__中会自动把它前移到顶层配置保证新旧权重都能正确加载。GlmOcrVisionConfig视觉塔配置默认值对应一个 24 层、隐层 1024、16 头、336×336 输入、patch 14×14 的视觉 Transformer具体如下参数默认值含义depth24Transformer 层数hidden_size1024视觉隐层维度hidden_actsilu激活函数attention_biasTrue注意力投影是否带 bias视觉 MLP 复用此开关attention_dropout0.0注意力 dropout 概率num_heads16注意力头数in_channels3输入通道数RGBimage_size336输入图像边长patch_size14patch 尺寸rms_norm_eps1e-05RMSNorm 的 epsilonspatial_merge_size2空间下采样合并因子token 压缩关键参数temporal_patch_size2时间维 patch 尺寸视频帧合并out_hidden_size1536视觉输出维度送入文本侧前对齐的维度intermediate_size4096视觉 MLP 中间层维度initializer_range0.02参数初始化范围其中spatial_merge_size 2是高效 token 下采样的核心视觉特征在送入语言模型前会按 2×2 邻域合并token 数量直接缩减到原来的 1/4这是把整页文档图 token 数量压到可控规模的关键设计。GlmOcrTextConfig文本解码器配置文本侧是一个标准 decoder-only LLMGLM-0.5B 同源结构默认值参数默认值含义vocab_size59392词表大小hidden_size1024隐层维度intermediate_size4096MLP 中间层维度num_hidden_layers16Transformer 层数num_attention_heads16Q 头数num_key_value_heads8KV 头数GQA 分组查询注意力hidden_actsilu激活函数对应 SwiGLU MLPmax_position_embeddings131072最大位置编码长度128Kinitializer_range0.02初始化范围rms_norm_eps1e-05RMSNorm epsilonuse_cacheTrue生成时是否使用 KV cacheattention_dropout0.0注意力 dropout文本配置还声明了张量并行TP与流水线并行PP的默认切分方案configuration_glm_ocr.pyq_proj/k_proj/v_proj按列切分、o_proj按行切分、mlp.gate_up_proj因包含chunk操作需复制输入down_proj则反向切分输入。如果需要用transformers的张量并行工具分发模型这些默认 plan 会被自动采用。另外配置层用keys_to_ignore_at_inference [past_key_values]和ignore_keys_at_rope_validation {mrope_section}分别屏蔽推理期不参与序列化的字段与 M-RoPE 校验豁免项。模型类详解与核心前向链路文档为如下六个模型类提供了 autodoc 条目它们全部定义在 modeling_glm_ocr.pyGlmOcrVisionModelCogViT 风格视觉塔负责把pixel_values变成视觉 tokenGlmOcrTextModelGLM-0.5B 文本解码器GlmOcrModelvisuallanguage_model的组合主干负责图像特征与文本序列的融合GlmOcrForConditionalGeneration顶层自回归生成入口叠加lm_head输出词表 logits。视觉前向patch、RoPE 与 token 下采样GlmOcrVisionModel.forwardmodeling_glm_ocr.py接收hidden_states即 patch 化后的像素序列与描述每张图时空布局的grid_thw流程如下patch_embed卷积把像素 patch 投影到hidden_size用grid_thwspatial_merge_size生成视觉侧 3D 位置并计算旋转位置编码依序经过 24 层GlmOcrVisionBlock其间用cu_seqlens/max_seqlen表示可变长度以兼容 Flash Attentionpost_layernorm后把序列 reshape 成(N, spatial_merge_size, spatial_merge_size, C)再 permute经downsample完成 2×2 token 合并下采样送入merger即跨模态连接器一个带silu的 MLP映射到out_hidden_size 1536作为pooler_output返回。因为out_hidden_size(1536) hidden_size(1024) × in_channels(3) / 2代码中 merger 的输入维度写作context_dim out_hidden_size * in_channels由GlmOcrVisionModel在构造时从配置直接推导modular_glm_ocr.py。图像特征注入与占位 token 机制GlmOcrModel层负责把视觉 token 注入文本嵌入序列modeling_glm_ocr.py文本先通过get_input_embeddings()(input_ids)得到inputs_embedsget_image_features调用视觉塔得到视觉特征并按image_grid_thw.prod(-1) // spatial_merge_size**2切分成每张图独立的特征块get_placeholder_mask在input_ids中定位image_token_id59280的位置并通过inputs_embeds.masked_scatter(image_mask, image_embeds)把占位 token 的嵌入原地替换为真正的视觉特征向量同时校验占位 token 数 × 隐藏维度 视觉特征元素总数不一致会直接报错若存在视频输入pixel_values_videos则同理替换video_token_id位置。M-RoPE 三维位置编码由于视觉 token 数量远多于其在序列中的占位个数文本与图像需要各自独立的位置编号GLM-OCR 沿用 GLM-4V 的多模态 RoPEM-RoPE方案处理器的输出中包含mm_token_type_ids约定 text0、image1、video2见 get_rope_index 的注释前向要求一旦传了image_grid_thw/video_grid_thw却缺少mm_token_type_ids模型会抛出显式报错提示compute_3d_position_ids因为无法正确计算 M-RoPEcompute_3d_position_ids生成 shape 为(3, batch, seq)的位置张量三个平面分别对应时间、高度、宽度维的位置视频场景还按时间戳把video_grid_thw拆分成逐帧网格与 Qwen2VL 的差异点被源码明确注释增量生成阶段通过缓存的rope_deltas推算后续 token 的三维位置保证长文档续写时位置连续不漂移顶层GlmOcrForConditionalGeneration._prepare_position_ids_for_generationmodeling_glm_ocr.py专门重写了父类逻辑把文本位置 视觉位置拼接成[4, bs, seq]的高维位置张量返回给生成循环。生成与前向参数GlmOcrForConditionalGeneration.forward除常规的input_ids/attention_mask/past_key_values/labels外还接受pixel_values、image_grid_thw、mm_token_type_ids等多模态张量并支持logits_to_keep只计算序列末尾若干位置的 logits 以减少生成开销_tied_weights_keys声明lm_head.weight与embed_tokens.weight的映射关系便于权重绑定加载。文本层的_keys_to_ignore_on_load_unexpected则用于在加载上游 checkpoint 时忽略模型中不存在的第 16 层权重layers.16.*之后的层因为 GLM-OCR 文本侧只有 16 层。总结与进一步阅读GLM-OCR 把一个 0.9B 级别的轻量解码器与擅长视觉特征的 CogViT 编码器相结合通过 2×2 空间 token 下采样和 merger 连接器把文档图像高效地桥接到语言模型从而在文本、公式、表格识别与信息抽取等文档理解任务上给出了一条可本地部署的路线。在 Transformers 中使用它只需三步AutoProcessor组装 chat 消息、GlmOcrForConditionalGeneration.from_pretrained加载权重、model.generate输出识别文本需要吞吐时可批量推理需要速度时可切换kernels-community系列注意力内核。如果想继续深入推荐以下仓库内一手资料配置定义src/transformers/models/glm_ocr/configuration_glm_ocr.py完整建模实现src/transformers/models/glm_ocr/modeling_glm_ocr.py模块化源头GLM-4V 继承关系与差异:src/transformers/models/glm_ocr/modular_glm_ocr.py官方集成测试tests/models/glm_ocr/test_modeling_glm_ocr.py官方模型文档docs/source/en/model_doc/glm_ocr.md本文涉及的默认参数值、token id、注意力内核选项与评测表述均以当前仓库及官方模型文档为准实际使用时请确认你的 Transformers 版本包含glm_ocr模型族并以目标硬件上的真实性能为准进行方案取舍。【免费下载链接】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），仅供参考