企业官网建设流程全解析

PaddleOCR 文本识别模块实战指南：模型选型、多引擎推理与二次开发全解析

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR

本指南以 PaddleOCR 官方文档 Text Recognition Module Tutorial 为骨架，结合仓库源码（paddleocr/_models/text_recognition.py、paddleocr/_models/base.py、paddleocr/_common_args.py、configs/rec/PP-OCRv5/PP-OCRv5_server_rec.yml及测试用例）深度扩充，系统讲解文本识别模块的模型清单、CLI / Python API 两种推理方式、四种推理引擎的选择，以及从数据准备到训练、评估、导出的完整二次开发链路。读完本文，你将能够独立完成文本识别模型的选型、调用与定制训练。

1. 模块定位：OCR 系统的"翻译官"

文本识别（Text Recognition）模块是 OCR（光学字符识别）系统的核心组成部分，负责从图像中的文本区域提取文字信息。在 PaddleOCR 的完整链路中，它通常接收文本检测（Text Detection）模块输出的文本行包围盒（bounding box），再通过图像预处理与深度学习算法，将图像中的文字转换为可编辑、可检索的电子文本。识别结果的准确率直接决定信息抽取、数据挖掘等下游应用的效果上限。

从源码结构看，PaddleOCR 将文本识别封装为独立的TextRecognition类，位于 paddleocr/_models/text_recognition.py，其默认模型为PP-OCRv6_medium_rec；同时通过TextRecognitionSubcommandExecutor将 CLI 子命令text_recognition暴露给命令行用户。类的底层继承自PaddleXPredictorWrapper（见 paddleocr/_models/base.py），统一封装了predict()、predict_iter()、close()等接口，并将模型创建委托给 PaddleX 的create_predictor，从而实现多引擎（paddle_static、paddle_dynamic、transformers、onnxruntime）的无缝切换。

2. 模型选型：核心模型与全量模型清单

说明：下表中的推理时间仅包含模型推理耗时，不包含前后处理时间。"Normal Mode"（常规模式）对应本地paddle_static推理引擎。

2.1 核心模型对比

*注：PP-OCRv6 指标在内部多场景评测集上评估，PP-OCRv5/v4 指标基于通用评测集，两者评测集不同，指标不可直接对比。

❗ 上表列出了文本识别模块主要支持的 4 个核心模型。该模块共支持20 个完整模型，包含多个多语言文本识别模型，完整模型清单如下。

2.2 全量模型清单（20 个）

PP-OCRv5 多场景模型

中文识别模型

英文识别模型

多语言识别模型

2.3 测试环境与推理模式说明

性能测试环境：

• 测试数据集：中文识别模型使用 PaddleOCR 自建中文数据集（覆盖街景、网络图片、文档、手写，共 11000 张文本识别图像）；ch_SVTRv2_rec/ch_RepSVTR_rec分别使用 PaddleOCR 算法模型挑战赛任务一 Leaderboard A / B 评测集；英文与多语言识别模型使用 PaddleOCR 自建数据集。
• 硬件配置：GPU NVIDIA Tesla T4；CPU Intel Xeon Gold 6271C @ 2.60GHz。
• 软件环境：Ubuntu 20.04 / CUDA 11.8 / cuDNN 8.9 / TensorRT 8.6.1.6；paddlepaddle-gpu 3.0.0 / paddleocr 3.0.3。

推理模式说明：

3. 快速开始：一行命令体验文本识别

3.1 环境准备

开始前请先安装 PaddleOCR wheel 包，安装细节参见 安装指南。使用默认的paddle_static推理引擎时，还需先按 PaddlePaddle 框架安装 安装 PaddlePaddle；若改用transformers或onnxruntime引擎，则需相应配置 Transformers 或 ONNX Runtime 环境。

注意：官方 PaddleOCR 模型默认从 HuggingFace 下载。若无法访问 HuggingFace，可设置环境变量PADDLE_PDX_MODEL_SOURCE="BOS"将模型源切换为 BOS（百度对象存储），未来将支持更多主流模型源。

3.2 CLI 一键推理

# 使用默认的 paddle_static 推理引擎（推荐，推理性能最佳） paddleocr text_recognition -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_rec_001.png # 使用 transformers 引擎推理 paddleocr text_recognition -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_rec_001.png \ --engine transformers # 使用 onnxruntime 引擎推理 paddleocr text_recognition -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_rec_001.png \ --engine onnxruntime

在大多数场景下，默认的paddle_static推理引擎拥有更好的推理性能，是首选方案。

从 CLI 实现来看，paddleocr/_models/text_recognition.py 中的TextRecognitionSubcommandExecutor注册了text_recognition子命令，--input_shape参数以(C, H, W)三个整数值接收；paddleocr/_utils/cli.py 中的perform_simple_inference会遍历predict_iter返回的生成器，逐个打印结果，并在指定--save_path时调用res.save_all(save_path)保存全部输出。

3.3 Python API 集成

你也可以将文本识别模块的模型推理集成到自己的项目中。运行前请先下载示例图像到本地。

from paddleocr import TextRecognition # 默认使用 paddle_static 推理引擎 model = TextRecognition() output = model.predict(input="general_ocr_rec_001.png", batch_size=1) for res in output: res.print() res.save_to_img(save_path="./output/") res.save_to_json(save_path="./output/res.json")

切换引擎只需在构造时传入engine参数：

# transformers 引擎 model = TextRecognition(engine="transformers") # onnxruntime 引擎 model = TextRecognition(engine="onnxruntime")

TextRecognition的默认模型名在源码中硬编码为PP-OCRv6_medium_rec（见 paddleocr/_models/text_recognition.py），而predict()/predict_iter()在基类 paddleocr/_models/base.py 中实现：predict_iter()直接透传 PaddleX 预测器的生成器，predict()则将其整体物化为列表返回，两者的参数与结果语义完全一致。

若需使用paddle_dynamic或transformers引擎运行自训练模型，请先参考本文第 6.3 节"权重转换"，使用 PaddleX 将模型从pdparams格式转换为safetensors格式。

3.4 结果输出解析

运行后输出结果如下：

{'res': {'input_path': 'general_ocr_rec_001.png', 'page_index': None, 'rec_text': '绿洲仕格维花园公寓', 'rec_score': 0.9823867082595825}}

各字段含义：

• input_path：待预测的文本行图像路径
• page_index：若输入为 PDF 文件，表示当前文本行所在的 PDF 页码；否则为None
• rec_text：文本行图像的预测文字
• rec_score：文本行图像预测文字的置信度

仓库测试用例 tests/models/test_text_recognition.py 验证了结果对象应包含input_path、page_index、input_img、rec_text、rec_score、vis_font等字段，可作为集成时字段约定的参考。

3.5 TextRecognition 构造参数详解

这些参数在 paddleocr/_common_args.py 中统一解析校验：不支持的引擎或精度会直接抛出ValueError；底层会将use_tensorrt/precision映射为 PaddleX 的use_pptrt/pptrt_precision，并在paddle_static引擎下自动生成trt_fp32/trt_fp16/paddle等run_mode配置（见 paddleocr/_common_args.py）。各参数默认值定义于 paddleocr/_constants.py。

3.6 predict() 方法参数

调用predict()进行推理，返回结果列表。模块同时提供predict_iter()方法，两者在参数接受与结果返回上完全一致，区别仅在于predict_iter()返回generator，可逐步处理并获取预测结果，适合大数据集处理或内存节省场景。predict()的参数如下：

3.7 结果对象处理方法

每个样本的预测结果对应一个 Result 对象，支持打印、保存图像、保存 json 等操作：

此外，还可通过属性直接获取预测结果与可视化图像：

4. 二次开发：以 PP-OCRv5_server_rec 为例的训练全流程

当上述模型在自身场景中表现不佳时，可进行二次开发。下面以训练PP-OCRv5_server_rec为例，其他模型只需替换对应配置文件即可。首先准备文本识别数据集，可参考文本识别示例数据 安装 PaddleOCR 所需依赖。

4.1 数据集与预训练模型准备

# 下载示例数据集 wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/ocr_rec_dataset_examples.tar tar -xf ocr_rec_dataset_examples.tar # 下载 PP-OCRv5_server_rec 预训练模型 wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/PP-OCRv5_server_rec_pretrained.pdparams

4.2 模型训练

PaddleOCR 采用模块化代码组织，训练PP-OCRv5_server_rec需使用其配置文件。训练命令如下：

# 单卡训练（默认训练方式） python3 tools/train.py -c configs/rec/PP-OCRv5/PP-OCRv5_server_rec.yml \ -o Global.pretrained_model=./PP-OCRv5_server_rec_pretrained.pdparams # 多卡训练，通过 --gpus 参数指定 GPU ID python3 -m paddle.distributed.launch --gpus '0,1,2,3' tools/train.py -c configs/rec/PP-OCRv5/PP-OCRv5_server_rec.yml \ -o Global.pretrained_model=./PP-OCRv5_server_rec_pretrained.pdparams

从 configs/rec/PP-OCRv5/PP-OCRv5_server_rec.yml 可以看到该模型的关键训练配置：网络架构采用SVTR_HGNet算法，Backbone 为PPHGNetV2_B4（开启text_rec），Head 为 CTC + NRTR 双头结构（MultiHead，其中 CTC 头使用 svtr neck，NRTR 头维度 384、max_text_length25），损失为MultiLoss（CTCLoss + NRTRLoss），后处理为CTCLabelDecode，评估指标为RecMetric的acc。训练数据经RecAug数据增强、MultiScaleSampler多尺度采样（尺度[[320,32],[320,48],[320,64]]、首轮 batch 128），字符表使用 ppocrv5_dict.txt，并开启use_space_char。若需训练其他模型，只需将-c指向对应配置文件，例如 PP-OCRv6 系列配置。

4.3 模型评估

使用如下命令评估训练得到的权重（如output/xxx/xxx.pdparams）：

# 注意：将 pretrained_model 路径设为本地路径。若使用自己训练保存的模型，请将路径和文件名修改为 {path/to/weights}/{model_name} # 示例测试集评估 python3 tools/eval.py -c configs/rec/PP-OCRv5/PP-OCRv5_server_rec.yml -o \ Global.pretrained_model=output/xxx/xxx.pdparams

4.4 模型导出

python3 tools/export_model.py -c configs/rec/PP-OCRv5/PP-OCRv5_server_rec.yml -o \ Global.pretrained_model=output/xxx/xxx.pdparams \ Global.save_inference_dir="./PP-OCRv5_server_rec_infer/"

导出后，静态图模型将存储在当前目录的./PP-OCRv5_server_rec_infer/下，包含以下文件：

./PP-OCRv5_server_rec_infer/ ├── inference.json ├── inference.pdiparams ├── inference.yml

至此二次开发完成，该静态图模型可直接集成到 PaddleOCR API 中。

若希望使用paddle_dynamic或transformers引擎运行自训练模型，请参考第 6.3 节，使用 PaddleX 将模型从pdparams格式转换为safetensors格式。

5. 推理引擎

推理引擎的详细描述、取值、兼容规则与示例，请参考推理引擎与配置说明。

从源码层面看，paddleocr/_common_args.py 定义了完整的引擎白名单：paddle、paddle_static、paddle_dynamic、transformers、onnxruntime。当engine为None或paddle时，框架自动构建{"paddle_static": built}配置并采用paddle_static引擎（paddleocr/_common_args.py）；同时enable_hpi会被透传为 PaddleX 的use_hpip以启用高性能推理。

5.1 各引擎速度数据

下表为 PP-OCRv5_mobile_rec、PP-OCRv5_server_rec、PP-OCRv6_medium_rec、PP-OCRv6_small_rec、PP-OCRv6_tiny_rec 在四种引擎下的耗时对比（单位：ms）：

测试环境说明：

• 测试数据：示例图像
• 硬件配置：GPU NVIDIA A100 40G；CPU Intel(R) Xeon(R) Gold 6248 CPU @ 2.50GHz
• 软件环境：Ubuntu 22.04 / CUDA 12.6 / cuDNN 9.5；paddlepaddle-gpu 3.2.1 / paddleocr 3.5 / transformers 5.4.0 / torch 2.10 / onnxruntime-gpu 1.23.2

5.2 权重转换

使用推理引擎时，系统会自动下载官方预训练模型。若需使用自训练模型搭配paddle_dynamic或transformers引擎，请参照 PaddleX 文档中"文本图像方向分类模块权重转换"一节，使用 PaddleX 将模型从pdparams格式转换为safetensors格式，即可无缝集成到 PaddleOCR API 中推理。若需使用自训练模型搭配onnxruntime引擎，可参照 PaddleX 的 "Paddle2ONNX 获取 ONNX 模型" 文档获取 ONNX 模型，从而无缝集成到 PaddleOCR API 中推理。

6. 常见问题（FAQ）

官方文档 text_recognition.en.md 的 FAQ 章节当前暂未填充具体条目。实际使用中可重点关注的排查方向包括：引擎切换前确认对应运行时（PaddlePaddle / Transformers / ONNX Runtime）已正确安装；engine_config与engine组合不匹配时按 推理引擎与配置说明 的兼容规则调整；模型下载失败时通过PADDLE_PDX_MODEL_SOURCE="BOS"切换模型源；自训练模型接入paddle_dynamic/transformers/onnxruntime引擎前，务必先完成第 5.2 节的权重格式转换。

7. 延伸阅读

• 文本识别中文版教程 与本文互为对照
• 推理引擎与配置说明：引擎取值、兼容规则与示例
• PaddleOCR 快速开始：完整的检测 + 方向分类 + 识别系统体验
• 文本识别源码实现：TextRecognition类与 CLI 子命令注册
• 推理参数解析与校验：引擎白名单、默认值与run_mode构建逻辑
• PP-OCRv5_server_rec 训练配置：SVTR_HGNet + 多尺度训练完整参数
• PP-OCRv6 系列训练配置：PP-OCRv6 默认模型配置
• 文本识别测试用例：结果字段约定的自动化验证

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR