使用 [特殊字符] Transformers 推理 PP-OCRv5_server_rec：文本识别模型架构、预处理流程与端到端实战

使用 Transformers 推理 PP-OCRv5_server_rec文本识别模型架构、预处理流程与端到端实战【免费下载链接】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本文基于当前仓库 docs/source/en/model_doc/pp_ocrv5_server_rec.md 编写围绕 PP-OCRv5_server_rec 文本识别模型讲解其在 Transformers 中的架构组成、图像预处理管线与解码后处理逻辑并给出可直接运行的单张与批量推理示例。PP-OCRv5_server_rec是 PaddleOCR 团队开发的 PP-OCRv5_rec 系列中的服务端文本识别模型其设计目标是仅用单个模型即可高效、准确识别简体中文、繁体中文、英文、日文并覆盖手写体、竖排文本、拼音与生僻字等复杂文本场景。2026-03-19 起该模型由社区贡献正式集成进当前 Transformers 仓库可以通过标准的AutoModelForTextRecognition与AutoImageProcessor接口完成从图片到文本的完整推理链路。阅读本文后你将掌握该模型的网络结构HGNetV2 骨干 SVTR 编码器 CTC 分类头、动态宽度 resize 的预处理细节以及如何用不到十行代码完成单张与批量识别。目录模型概述与适用场景模型架构骨干、SVTR 编码器与识别头配置类解析PPOCRV5ServerRecConfig图像处理器动态宽度预处理与文本解码使用 AutoModel 进行推理仓库类与参考实现索引模型概述与适用场景依据 模型文档 的 Overview 描述PP-OCRv5_server_rec是一个专用于**文本识别text recognition**的轻量模型聚焦于高效识别与理解多语言文档和自然场景中的文本元素。它与 PP-OCRv5_server_det检测与 PP-OCRv5_mobile_rec / mobile_det移动端系列共同构成完整的 PP-OCRv5 文字识别方案模型系列定位PP-OCRv5_server_det服务端文本检测定位文本框PP-OCRv5_server_rec服务端文本识别将文本框内容转为文字PP-OCRv5_mobile_det / mobile_rec移动端轻量化检测与识别在典型流程中检测 识别通常串联使用先由检测模型框出文本区域再由识别模型对每个文本框逐个转写。本文介绍的server_rec即承担第二步的识别任务服务于票据、证件、屏幕截图、文档扫描等各类文档理解场景。其核心能力特征为单模型多语种同时支持简中、繁中、英文、日文复杂文本兼容覆盖手写体、竖排文本、拼音与生僻字等情形性能权衡在维持识别精度的同时兼顾推理速度与鲁棒性。模型架构骨干、SVTR 编码器与识别头仓库中 PP-OCRv5_server_rec 的实现分为两个文件通用模块定义实际编辑源头modular_pp_ocrv5_server_rec.py由模块化工具自动生成的完整实现modeling_pp_ocrv5_server_rec.py整个模型由主干特征提取Backbone、**带 SVTR 的识别编码器EncoderWithSVTR与线性分类头Head**三部分组成组合逻辑可以在PPOCRV5ServerRecForTextRecognition的构造中看到modeling_pp_ocrv5_server_rec.pyself.model PPOCRV5ServerRecModel(config) # Backbone 下采样 self.head PPOCRV5ServerRecHead(config) # SVTR 编码器 CTC 分类头骨干网络HGNetV2PPOCRV5ServerRecModel通过load_backbone(config)加载骨干modeling_pp_ocrv5_server_rec.py。其默认骨干配置类型为hgnet_v2、架构等级为L见下文 Config 小节forward取最后一张特征图outputs.feature_maps[-1]再做一次F.avg_pool2d(hidden_state, (3, 2))平均池化下采样得到送入识别头的特征。SVTR 编码器PPOCRV5ServerRecEncoderWithSVTRPPOCRV5ServerRecHead内部先是PPOCRV5ServerRecEncoderWithSVTR(config)——一个源自 SVTRScene Text Recognition with a Single Visual Model见 modeling_pp_ocrv5_server_rec.py 的 docstring 引用的编码器然后接一个把hidden_size映射到head_out_channels个类别的线性层并对最后一维做softmax产生逐字符概率self.encoder PPOCRV5ServerRecEncoderWithSVTR(config) self.head nn.Linear(config.hidden_size, config.head_out_channels) # forward: softmax(hidden_states, dim2)编码器内部结构结合 modeling_pp_ocrv5_server_rec.py包含两个可辨识的阶段卷积适配层conv_block由 5 个PPOCRV5ServerRecConvLayerConv2dBatchNorm2d SiLU 激活实现组成负责把骨干输出的特征图经 2D 展平为 token 序列flatten(2).transpose(1, 2)送入 Transformer 块SVTR Transformer 块svtr_block按config.depth默认 2重复堆叠PPOCRV5ServerRecBlock。每个 Block 是先 LayerNorm 再残差的 Pre-LN 结构LayerNorm → 自注意力 → 残差 → LayerNorm → MLP → 残差实现。自注意力层PPOCRV5ServerRecAttention采用类似 ViT/CLIP 的融合 QKV 投影但有一处关键差异QKV 线性层默认不带 bias仅当qkv_biasTrue时额外加入 Q 与 V 的 bias且 K 的 bias 恒为 0modeling_pp_ocrv5_server_rec.py。注意力实现在 eager 模式下与 SIGLIP 的eager_attention_forward保持一致但不对注意力权重做 fp32 强转同时支持 Transformers 标准的注意力后端接口ALL_ATTENTION_FUNCTIONS。编码器最后经过LayerNorm、还原为 2D 特征view(batch_size, height, width, channels).permute(0, 3, 1, 2)与最初的residual拼接后通过剩余卷积层压缩成(batch, seq, hidden)的序列输出。前向路径与注意力机制支持从PPOCRV5ServerRecPreTrainedModel的声明可以看出modeling_pp_ocrv5_server_rec.pymain_input_name pixel_valuesinput_modalities (image,)输入为图像张量supports_gradient_checkpointing True可在训练/微调时用梯度检查点换显存_supports_flash_attn / sdpa / flex_attn True可切换 Flash Attention、SDPA 等不同注意力后端_can_compile_fullgraph True支持torch.compile全图编译。配置类解析PPOCRV5ServerRecConfig配置定义位于 configuration_pp_ocrv5_server_rec.py模型类型标识为model_type pp_ocrv5_server_rec。它的参数分两层模型自身超参 嵌套的骨干配置backbone_config。顶层超参数默认值参数默认值含义hidden_size120SVTR 编码器隐藏维度embed_dimmlp_ratio2.0MLP 隐层宽度 hidden_size * mlp_ratiodepth2SVTR Transformer 块堆叠层数num_attention_heads8注意力头数须整除hidden_sizeattention_dropout0.0注意力 dropout 概率head_out_channels18385识别头输出类别数最终分类词典规模conv_kernel_size[1, 3]卷积适配层卷积核尺寸默认为[1, 3]见__post_init__qkv_biasTrue是否给 QKV 投影添加 Q/V biashidden_actsilu隐藏层激活函数layer_norm_eps1e-6LayerNorm 数值稳定项其中head_out_channels 18385对应模型词典大小含 blank/空白类与下文后处理中忽略索引 0呼应。嵌套骨干配置HGNetV2backbone_config未显式指定时__post_init__会调用consolidate_backbone_kwargs_to_config生成默认的hgnet_v2骨干configuration_pp_ocrv5_server_rec.py关键参数包括arch L选用 HGNetV2 的 Large 变体return_idx [0, 1, 2, 3]、out_features对应 stage1–stage4freeze_stem_only True、freeze_at 0、freeze_norm True默认冻结 stem 与归一化层参数典型迁移/微调场景lr_mult_list [1.0] * 5各阶段学习率倍率stage_downsample [True]*4、stem_strides [2, 1, 1, 1, 1]控制下采样节奏把输入图逐步压到适合识别的高宽比例。在 tests/models/pp_ocrv5_server_rec/test_modeling_pp_ocrv5_server_rec.py 的PPOCRV5ServerRecModelTester中可以找到同样的参数基线hidden_size10、depth2、num_attention_heads2等小规模版本用于快速跑通前向与梯度测试。图像处理器动态宽度预处理与文本解码识别模型的预处理与文本解码全部封装在PPOCRV5ServerRecImageProcessor中image_processing_pp_ocrv5_server_rec.py它继承自TorchvisionBackend通过AutoImageProcessor可自动实例化仓库映射见 auto_mappings.py。默认预处理参数resample PILImageResampling.BILINEAR image_mean IMAGENET_STANDARD_MEAN # [0.485, 0.456, 0.406] image_std IMAGENET_STANDARD_STD # [0.229, 0.224, 0.225] size {height: 48, width: 320} # 目标高度 48默认参考宽度 320 pad_size {height: 48, width: 320} do_resize True do_rescale True do_convert_rgb True do_normalize True do_pad True max_image_width 3200 # 单 batch 内容许的最大宽度一次_preprocess大致按顺序执行按原始尺寸分组 → 动态 resize → 重新按尺寸分组 → rescale normalize1/255 后按 ImageNet 均值方差归一→ 不足pad_size宽度时右侧填充。预处理输出张量键名为pixel_values。动态宽度策略get_target_size文本行图片宽高比差异极大固定尺寸会严重拉伸变形。因此该处理器采用按 batch 内最宽图等比缩放的策略其规则在get_target_sizeimage_processing_pp_ocrv5_server_rec.py与图像处理测试 test_image_processing_pp_ocrv5_server_rec.py 中均有镜像实现找出 batch 中最宽的图width最大者取它的(width, height)计算ratio max(max_width / max_height, 320 / 48)target_width int(48 * ratio)target_height恒为 48若target_width max_image_width3200裁剪至 3200否则若计算所得不小于按原始宽高比ceil(48 * width/height)的期望值则改用该更贴合原始比例的宽度。也就是说高度固定为 48 像素宽度按输入图片比例动态计算从而保留文本行的宽高信息batch 中所有图被统一拉伸到同一目标宽度以满足 batch 张量堆叠要求。后处理解码post_process_text_recognition模型输出经过image_processor.post_process_text_recognition(outputs)即可得到可读文本。其解码逻辑image_processing_pp_ocrv5_server_rec.py本质上是CTC 贪心解码 去重 去空白取模型输出last_hidden_state形状(batch, seq_len, vocab)在最后一维上取max得到逐位置最大概率索引preds_idx与置信度preds_prob去重remove_duplicate删除与前一位置重复的字符索引对应 CTC 折叠相邻重复字符忽略 blank过滤掉索引为0的空白类 token将剩余索引映射到character_list词典拼接得到text置信度score取幸存位置preds_prob的均值。每个 batch 元素最终返回形如{text: ..., score: 0.987}的字典。使用 AutoModel 进行推理运行下方示例需要已安装transformers、torch、Pillow与requests联网下载图片与权重权重可从 Hub 自动获取。单张图片推理模型文档 给出的标准用法AutoModel 模式import requests from PIL import Image from transformers import AutoImageProcessor, AutoModelForTextRecognition model_path PaddlePaddle/PP-OCRv5_server_rec_safetensors model AutoModelForTextRecognition.from_pretrained(model_path, device_mapauto) image_processor AutoImageProcessor.from_pretrained(model_path) image Image.open( requests.get(https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_rec_001.png, streamTrue).raw ).convert(RGB) inputs image_processor(imagesimage, return_tensorspt).to(model.device) outputs model(**inputs) results image_processor.post_process_text_recognition(outputs) for result in results: print(result)预期输出为按图对应的文本结果例如{text: ……识别出的文本……, score: 0.99...}注意AutoModelForTextRecognition与AutoImageProcessor之所以能自动定位到本模型得益于 modeling_auto.py 与 auto_mappings.py 中把pp_ocrv5_server_rec注册到对应自动类。Batch 批量推理把多个图片以列表传入image_processor即可一次处理多张import requests from PIL import Image from transformers import AutoImageProcessor, AutoModelForTextRecognition model_path PaddlePaddle/PP-OCRv5_server_rec_safetensors model AutoModelForTextRecognition.from_pretrained(model_path, device_mapauto) image_processor AutoImageProcessor.from_pretrained(model_path) image Image.open( requests.get(https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_rec_001.png, streamTrue).raw ).convert(RGB) inputs image_processor(images[image, image], return_tensorspt).to(model.device) outputs model(**inputs) results image_processor.post_process_text_recognition(outputs) for result in results: print(result)批量场景下image processor 会按前文以最宽图为基准的动态宽度策略统一缩放并补齐post_process_text_recognition返回的列表长度与 batch 内图片数量一一对应可按索引取出每张图的结果。自定义推理参数除了文档默认用法处理器还暴露了可在调用时覆盖的关键参数定义于PPOCRV5ServerRecImageProcessorKwargsimage_processing_pp_ocrv5_server_rec.pymax_image_width默认3200resize 阶段允许的最大图片宽度控制长文本行的处理上限与显存开销character_list默认[]识别所用词典需与模型权重的head_out_channels18385匹配通常由 checkpoint 的preprocessor_config.json自动加载无需手工指定。仓库类与参考实现索引下面对照 模型文档 末尾列出的 autodoc 条目给出各类的仓库位置便于按需深入阅读文档中的类名角色实现位置PPOCRV5ServerRecForTextRecognition完整文本识别模型Backbone SVTR 编码器 Headmodeling_pp_ocrv5_server_rec.pyPPOCRV5ServerRecConfig配置类含 HGNetV2 骨干子配置configuration_pp_ocrv5_server_rec.pyPPOCRV5ServerRecModel骨干特征提取 池化下采样modeling_pp_ocrv5_server_rec.pyPPOCRV5ServerRecEncoderWithSVTRSVTR 编码器Conv 适配 Transformer 块modeling_pp_ocrv5_server_rec.pyPPOCRV5MobileRecEncoderWithSVTR移动端系列对应的 SVTR 编码器变体见同目录模块架构与 server 版本存在差异PPOCRV5ServerRecImageProcessor动态宽度预处理 CTC 解码后处理image_processing_pp_ocrv5_server_rec.py相关源码入口模块化定义源改动应落地于此生成的实现文件由 CI 自动同步modular_pp_ocrv5_server_rec.py模型测试test_modeling_pp_ocrv5_server_rec.py覆盖前向、配置校验与慢速集成推理图像处理测试test_image_processing_pp_ocrv5_server_rec.py其中单测复刻了get_target_size的动态宽度期望值计算Auto 注册auto_mappings.py、modeling_auto.py、image_processing_auto.py同系其他模型检测端见 pp_ocrv5_server_det移动端识别见 pp_ocrv5_mobile_rec可对比 server 与 mobile 两档架构差异构成完整检测 识别文档理解方案。如果你在真实项目中对整页文档做文字提取可将本文模型与 PP-OCRv5_server_det 检测模型串联先框后识结合下游的版面分析/结构化模块即可搭建一套完整的文档理解流水线。【免费下载链接】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），仅供参考