Hugging Face Transformers 中的 PP-OCRv6_tiny_rec 轻量级文字识别模型指南

2026-09-07 11:52:54作者：昌雅子Ethen

🤗 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

导读

PP-OCRv6_tiny_rec 是 PaddleOCR PP-OCRv6 系列中最轻量的文字识别（Text Recognition）模型，已于 2026-05-19 由 PaddlePaddle 团队贡献并完整集成到 Hugging Face Transformers 中。它采用 LCNetV4 作为骨干网络（backbone）、免去编码器颈部（encoder neck）的直接 reshape 投影、以及 CTC + NRTR 多头解码结构，官方文档声明其支持 49 种语言、参数量约为 1.1M。阅读本文后，你将掌握该模型在 Transformers 生态中的架构细节、配置类与 Image Processor 的工作原理，并能直接用几行代码完成单张图片与批量图片的文字识别推理。

本文内容以官方模型文档 pp_ocrv6_tiny_rec.md 为核心骨架，并结合仓库内模型源码、配置文件与集成测试进行源码级佐证。

一、模型概览：PP-OCRv6 系列中的轻量识别模型

根据官方模型文档，PP-OCRv6_tiny_rec 具备以下核心特征：

骨干网络：使用 LCNetV4（PP-LCNetV4）作为 backbone，模型源码中通过 load_backbone 动态加载，且配置默认指向 pp_lcnet_v4；
颈部简化：直接使用 reshape 投影替代传统的 encoder neck，去掉序列建模头部，进一步压低计算量；
多头解码器：采用 CTC + NRTR 多任务结构，同时保留 CTC 风格的空字符（blank）机制；
多语言支持：覆盖 49 种语言，输出字典规模较大，最终分类头输出通道数以配置文件中的 head_out_channels 决定；
轻量化：约 1.1M 参数，适合移动端与边缘设备场景。

在 Transformers 生态中，该模型以 pp_ocrv6_tiny_rec 为 model_type 注册，与之配套的类是：

组件	类名	仓库文件
配置	`PPOCRV6TinyRecConfig`	configuration_pp_ocrv6_tiny_rec.py
基类模型	`PPOCRV6TinyRecModel`	modeling_pp_ocrv6_tiny_rec.py
识别任务模型	`PPOCRV6TinyRecForTextRecognition`	同上
图像处理器	`PPOCRV6SmallRecImageProcessor`	pp_ocrv6_small_rec/image_processing_pp_ocrv6_small_rec.py

值得注意的是：Tiny Rec 没有独立实现 Image Processor，而是复用同一系列的 PPOCRV6SmallRecImageProcessor。这一点可以从 Auto 映射中确认——image_processing_auto.py 将 pp_ocrv6_tiny_rec 直接映射到 PPOCRV6SmallRecImageProcessor（torchvision 后端），见 image_processing_auto.py。

二、模型架构与源码剖析

1. 骨干网络：PP-LCNetV4 + 平均池化投影

PPOCRV6TinyRecModel 的结构非常简洁（见 modeling_pp_ocrv6_tiny_rec.py）：

通过 load_backbone(config) 载入 PP-LCNetV4 骨干网络；
取骨干网络最后一个阶段的 feature_maps[-1] 作为特征；
用 F.avg_pool2d(hidden_state, (3, 2)) 做一次固定尺寸核的平均池化，在空间维度上压缩特征图，替代传统的序列化编码 neck；
以 BaseModelOutputWithNoAttention 形式返回 last_hidden_state。

def forward(self, pixel_values, **kwargs):
    outputs = self.backbone(pixel_values, **kwargs)
    hidden_state = outputs.feature_maps[-1]
    hidden_state = F.avg_pool2d(hidden_state, (3, 2))
    return BaseModelOutputWithNoAttention(
        last_hidden_state=hidden_state,
        hidden_states=outputs.hidden_states,
    )

由于整体不含 attention 结构，模型基类 PPOCRV6TinyRecPreTrainedModel 中相关声明如下（modeling_pp_ocrv6_tiny_rec.py）：

base_model_prefix = "model"，主输入为 pixel_values，输入模态为图片（input_modalities = ("image",)）；
supports_gradient_checkpointing = False，即不支持梯度检查点；
同时声明 _supports_flash_attn = True、_supports_sdpa = True、_supports_flex_attn = True，说明在推理时具备接入加速后端的兼容能力（实际层内无注意力实现）。

从源码结构看，PP-LCNetV4 的完整结构信息由 backbone_config 提供，其中 block_configs 描述了各阶段的卷积块配置，最终阶段的输出通道数将直接决定预测头的输入维度。测试文件 test_modeling_pp_ocrv6_tiny_rec.py 展示了一个带 4 个 stage、out_features=["stage1".."stage4"] 的完整 backbone 配置样例，可作为理解该格式的参考。

2. 预测头：从特征图到逐时刻字符概率

PPOCRV6TinyRecHead（见 modeling_pp_ocrv6_tiny_rec.py）在代码层面实现了文档所述的轻量解码：

去掉池化后的单高度维度（squeeze(2)），得到序列化的时间步特征；
依次经过深度可分离 Conv1d（kernel=5，grouped）+ BatchNorm + Hardswish 激活，以及 1×1 Conv1d + BatchNorm + Hardswish，完成上下文融合；
接入两个全连接层：fc1 将特征投影到 hidden_size（默认 120），fc2 将中间维度映射到 head_out_channels 个字符类别；
最后在最后一维（字符字典维）做 F.softmax，输出“每个时间步上的字符概率分布”。

PPOCRV6TinyRecForTextRecognition 则将 backbone（self.model）与预测头（self.head）串联起来，直接对 pixel_values 返回概率张量（modeling_pp_ocrv6_tiny_rec.py）。

需要说明的是，模型文档所述“CTC + NRTR 多头解码”在最终训练结构中体现；而在 Transformers 推理路径中，解码工作由 Image Processor 提供的 post_process_text_recognition 以 CTC 风格贪心解码完成（去重 + 忽略 blank），下文将详细展开。

3. 配置类：PPOCRV6TinyRecConfig

PPOCRV6TinyRecConfig 直接继承 PreTrainedConfig，是刻意精简的纯视觉配置类（见 configuration_pp_ocrv6_tiny_rec.py）：

model_type = "pp_ocrv6_tiny_rec"；
hidden_size: int = 120：预测头中间层维度；
head_out_channels: int = 6625：最终分类输出的类别数（代码内默认值；加载官方 checkpoint 时会被其自身配置覆盖，例如类文档中自动从官方 checkpoint 引用到的 18714）；
sub_configs = {"backbone_config": AutoConfig}：允许以字典形式传入骨干配置；
__post_init__ 调用 consolidate_backbone_kwargs_to_config，当未显式给出 backbone_config 时自动创建默认的 pp_lcnet_v4 配置（configuration_pp_ocrv6_tiny_rec.py）。

因此推理时最省心的方式就是：AutoConfig / AutoModel 从 checkpoint 加载，所有 head 输出维度、骨干结构均由远端配置自动对齐，用户无需手写任何超参数。该模型相关的文件均为 modular 方式生成，手工源文件在 modular_pp_ocrv6_tiny_rec.py，文件头部明确标注“请勿直接编辑生成文件，改动应落到 modular 源”。

三、实战：单张图片推理

文档给出了使用 AutoModel API 的标准用法。由于模型已注册进自动映射（modeling_auto.py 中 pp_ocrv6_tiny_rec → PPOCRV6TinyRecForTextRecognition），用户无需关心具体类名。下面脚本改编自官方文档（去掉了示例中未使用的 BytesIO/httpx 导入）：

from transformers import AutoImageProcessor, AutoModelForTextRecognition
from transformers.image_utils import load_image

model_path = "PaddlePaddle/PP-OCRv6_tiny_rec_safetensors"
model = AutoModelForTextRecognition.from_pretrained(model_path, device_map="auto")
image_processor = AutoImageProcessor.from_pretrained(model_path)

image_url = "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_rec_001.png"
image = load_image(image_url)
inputs = image_processor(images=image, return_tensors="pt").to(model.device)
outputs = model(**inputs)

results = image_processor.post_process_text_recognition(outputs)
for result in results:
    print(result)

流程拆解：

加载模型与处理器：AutoModelForTextRecognition.from_pretrained(model_path, device_map="auto") 支持自动设备映射；AutoImageProcessor 会自动解析出正确的预处理配置（含字符表、尺寸、均值方差等）。
加载图片：load_image（transformers.image_utils）可直接读取本地路径或 URL。
预处理 + 前向：image_processor(images=..., return_tensors="pt") 输出标准化后的 pixel_values，再送入模型。
后处理解码：post_process_text_recognition(outputs) 返回列表，每个元素是包含 "text"（解码文本）与 "score"（平均置信度）的字典。

官方集成测试可以验证该链路的正确性。见 test_modeling_pp_ocrv6_tiny_rec.py：对 general_ocr_rec_001.png 推理，期望识别出文本 "绿洲仕格维花园公寓"，平均置信度约 0.9835（容差内比对）。

四、实战：批量图片推理

文字识别在真实业务中往往是批量处理的。批量推理与单张推理几乎完全一致，只需把图片组装成列表传入 Image Processor。以下同样改编自官方文档：

from transformers import AutoImageProcessor, AutoModelForTextRecognition
from transformers.image_utils import load_image

model_path = "PaddlePaddle/PP-OCRv6_tiny_rec_safetensors"
model = AutoModelForTextRecognition.from_pretrained(model_path, device_map="auto")
image_processor = AutoImageProcessor.from_pretrained(model_path)

image_url = "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_rec_001.png"
image = load_image(image_url)
inputs = image_processor(images=[image, image], return_tensors="pt").to(model.device)
outputs = model(**inputs)

results = image_processor.post_process_text_recognition(outputs)
for result in results:
    print(result)

要点提示：

batch 内尺寸不一时不必手动 pad：Image Processor 会按批次中最宽的图计算目标尺寸并对齐，并自动完成右侧 padding（默认 pad 到宽 320）；
结果顺序与输入一致：post_process_text_recognition 返回一个与 batch 对应的列表，每个元素 {"text": ..., "score": ...}；
device_map="auto" 下注意将 inputs .to(model.device)，保证张量与模型在同一设备。

五、图像预处理原理解读：PPOCRV6SmallRecImageProcessor

前文提到，Tiny Rec 复用的是 PPOCRV6SmallRecImageProcessor。它是一个基于 Torchvision 后端 的 ImageProcessor（继承自 TorchvisionBackend），源码位于 image_processing_pp_ocrv6_small_rec.py。理解它的预处理行为对识别准确率至关重要。

1. 类级默认配置

类属性即默认配置（image_processing_pp_ocrv6_small_rec.py）：

属性	默认值	含义
`size`	`{"height": 48, "width": 320}`	识别网络的输入高度固定 48、参考宽度 320
`pad_size`	`{"height": 48, "width": 320}`	尾部 padding 的目标尺寸
`resample`	`BILINEAR`	缩放插值方式
`image_mean` / `image_std`	ImageNet 标准值	归一化统计量
`do_resize`	`True`	是否缩放
`do_rescale` / `do_normalize`	`True`	是否执行像素缩放与归一化
`do_convert_rgb`	`True`	是否统一转为 RGB
`do_pad`	`True`	是否执行 padding
`max_image_width`	`3200`	缩放阶段允许的最大宽度
`character_list`	`[]`	文字识别使用的字符表（从 checkpoint 配置自动加载）

运行期可通过 max_image_width、character_list 等 Kwargs 覆盖默认值，见 PPOCRV6SmallRecImageProcessorKwargs 的定义（image_processing_pp_ocrv6_small_rec.py）。

2. 与通用 OCR 流水线对齐的几个“关键改动”

_preprocess 的注释明确标注了两处为对齐 OpenCV（cv2.resize）等 PaddleOCR 原生预处理而做的特殊处理（image_processing_pp_ocrv6_small_rec.py）：

关闭抗锯齿（antialias=False）：使缩放结果尽量贴近 cv2.resize 的行为，保证与 Paddle 原始 checkpoint 的数值语义一致；
RGB → BGR 通道翻转：stacked_images = stacked_images[:, [2, 1, 0], :, :]，与 PaddleOCR 训练时的通道顺序对齐；
批量尺寸分组与目标尺寸计算：先按原始形状分组缩放，再通过 get_target_size 依据 batch 内最宽图计算统一的目标尺寸（image_processing_pp_ocrv6_small_rec.py），并在目标宽度小于 320 时 pad 到 pad_size（宽 320）。

3. 后处理：`post_process_text_recognition` 与 CTC 贪心解码

该处理器内置了解码逻辑（image_processing_pp_ocrv6_small_rec.py），接收模型输出的概率序列（batch, 时间步, 字典大小），对每个样本依次执行：

取每个时间步概率最大的类别索引（logits.max(dim=-1)）并记录对应概率；
去除连续重复：selection[1:] = preds_idx[idx][1:] != preds_idx[idx][:-1]；
忽略 blank 字符：字典中索引 0 被约定为 blank，selection &= preds_idx[idx] != 0；
用剩余的字符索引查 character_list，拼接成最终文本；
对保留下来的字符概率取均值作为该样本的 "score"。

返回值即前文示例中打印的字典列表：{"text": str, "score": float}。

六、可验证的行为与使用注意

1. 集成测试中的数值基线

需要说明的是：识别网络对“时序特征轴”做的是与 CTC 相似的一维聚合，输出不含 attention 权重，因此：

模型 has_attentions = False，不支持注意力可视化；
隐藏层输出来自骨干网络各阶段，数量为 num_stages + 1（含 embedding），见测试 test_hidden_states_output；
forward 的签名仅有 pixel_values 一个位置参数（test_forward_signature）。

2. 精度与设备支持

测试覆盖 float32、float16、bfloat16 三种精度的推理（test_modeling_pp_ocrv6_tiny_rec.py），可在 GPU 上启用混合精度；
基类声明了 SDPA / Flash Attention / Flex Attention 兼容标记，但由于模型本身无注意力层，实际加速取决于骨干网络的算子实现；
该模型不参与 get_input_embeddings、模型并行等文本模型相关机制，相关通用测试被显式跳过（test_modeling_pp_ocrv6_tiny_rec.py）。

3. 在 Pipeline / 任务生态中的位置

pipeline_model_mapping 将该模型注册为 image-feature-extraction 任务族成员（test_modeling_pp_ocrv6_tiny_rec.py），表明它可嵌入 Transformers 的 Pipeline 基础设施做特征提取用途；而完整 OCR 链路（检测 + 识别）通常需要结合检测模型分步完成。

七、小结

从官方模型文档到仓库源码，可以清晰地归纳出 PP-OCRv6_tiny_rec 在 Transformers 中的完整技术画像：

架构：LCNetV4 骨干 → 平均池化 reshape 投影（省去 encoder neck）→ 轻量 CTC/NRTR 风格预测头，全流程不含 attention、支持批量变长文本行图片；
接入方式：AutoModelForTextRecognition + AutoImageProcessor 两个自动 API 即可完成从 checkpoint 到单张/批量推理的全部装配；
预处理：复用 PPOCRV6SmallRecImageProcessor，以“关闭抗锯齿 + RGB→BGR + 动态目标尺寸”对齐 PaddleOCR 原生数值语义；
后处理：内置 CTC 风格贪心解码（去重、忽略 blank、按字符表映射），返回 text 与 score。