---
comments: true
---
# 通用OCR产线使用教程
## 1. OCR产线介绍
OCR(光学字符识别,Optical Character Recognition)是一种将图像中的文字转换为可编辑文本的技术。它广泛应用于文档数字化、信息提取和数据处理等领域。OCR 可以识别印刷文本、手写文本,甚至某些类型的字体和符号。
通用 OCR 产线用于解决文字识别任务,提取图片中的文字信息以文本形式输出,本产线集成了业界知名的 PP-OCRv3 和 PP-OCRv4 的端到端 OCR 串联系统,支持超过 80 种语言的识别,并在此基础上,增加了对图像的方向矫正和扭曲矫正功能。基于本产线,可实现 CPU 上毫秒级的文本内容精准预测,使用场景覆盖通用、制造、金融、交通等各个领域。本产线同时提供了灵活的服务化部署方式,支持在多种硬件上使用多种编程语言调用。不仅如此,本产线也提供了二次开发的能力,您可以基于本产线在您自己的数据集上训练调优,训练后的模型也可以无缝集成。
通用OCR产线中包含必选的文本检测模块和文本识别模块,以及可选的文档图像方向分类模块、文本图像矫正模块和文本行方向分类模块。其中,文档图像方向分类模块和文本图像矫正模块作为文档预处理子产线被集成到通用OCR产线中。每个模块都包含多个模型,您可以根据下方的基准测试数据选择使用的模型。
如果您更注重模型的精度,请选择精度较高的模型;如果您更在意模型的推理速度,请选择推理速度较快的模型;如果您关注模型的存储大小,请选择存储体积较小的模型。
文档图像方向分类模块(可选):
| 模型 | 模型下载链接 |
Top-1 Acc(%) |
GPU推理耗时(ms) |
CPU推理耗时 (ms) |
模型存储大小(M) |
介绍 |
| PP-LCNet_x1_0_doc_ori | 推理模型/训练模型 |
99.06 |
3.84845 |
9.23735 |
7 |
基于PP-LCNet_x1_0的文档图像分类模型,含有四个类别,即0度,90度,180度,270度 |
注:以上精度指标的评估集是自建的数据集,覆盖证件和文档等多个场景,包含 1000 张图片。GPU 推理耗时基于 NVIDIA Tesla T4 机器,精度类型为 FP32, CPU 推理速度基于 Intel(R) Xeon(R) Gold 5117 CPU @ 2.00GHz,线程数为 8,精度类型为 FP32。
文本图像矫正模块(可选):
| 模型 | 模型下载链接 |
CER |
模型存储大小(M) |
介绍 |
| UVDoc | 推理模型/训练模型 |
0.179 |
30.3 M |
高精度文本图像矫正模型 |
注:模型的精度指标测量自 DocUNet benchmark。
文本检测模块:
| 模型 | 模型下载链接 |
检测Hmean(%) |
GPU推理耗时(ms) |
CPU推理耗时 (ms) |
模型存储大小(M) |
介绍 |
| PP-OCRv4_server_det | 推理模型/训练模型 |
82.56 |
83.3501 |
2434.01 |
109 |
PP-OCRv4 的服务端文本检测模型,精度更高,适合在性能较好的服务器上部署 |
| PP-OCRv4_mobile_det | 推理模型/训练模型 |
77.35 |
10.6923 |
120.177 |
4.7 |
PP-OCRv4 的移动端文本检测模型,效率更高,适合在端侧设备部署 |
| PP-OCRv3_mobile_det | 推理模型/训练模型 |
78.68 |
|
|
2.1 |
PP-OCRv3 的移动端文本检测模型,效率更高,适合在端侧设备部署 |
| PP-OCRv3_server_det | 推理模型/训练模型 |
80.11 |
|
|
102.1 |
PP-OCRv3 的服务端文本检测模型,精度更高,适合在性能较好的服务器上部署 |
文本识别模块:
| 模型 | 模型下载链接 |
识别 Avg Accuracy(%) |
GPU推理耗时(ms) |
CPU推理耗时 (ms) |
模型存储大小(M) |
介绍 |
| PP-OCRv4_server_rec_doc | 推理模型/训练模型 |
81.53 |
|
|
74.7 M |
PP-OCRv4_server_rec_doc是在PP-OCRv4_server_rec的基础上,在更多中文文档数据和PP-OCR训练数据的混合数据训练而成,增加了部分繁体字、日文、特殊字符的识别能力,可支持识别的字符为1.5万+,除文档相关的文字识别能力提升外,也同时提升了通用文字的识别能力 |
| PP-OCRv4_mobile_rec | 推理模型/训练模型 |
78.74 |
7.95018 |
46.7868 |
10.6 M |
PP-OCRv4的轻量级识别模型,推理效率高,可以部署在包含端侧设备的多种硬件设备中 |
| PP-OCRv4_server_rec | 推理模型/训练模型 |
80.61 |
7.19439 |
140.179 |
71.2 M |
PP-OCRv4的服务器端模型,推理精度高,可以部署在多种不同的服务器上 |
| en_PP-OCRv4_mobile_rec | 推理模型/训练模型 |
70.39 |
|
|
6.8 M |
基于PP-OCRv4识别模型训练得到的超轻量英文识别模型,支持英文、数字识别 |
注:以上精度指标的评估集是 PaddleOCR 自建的中文数据集,覆盖街景、网图、文档、手写多个场景,其中文本识别包含 1.1w 张图片。所有模型 GPU 推理耗时基于 NVIDIA Tesla T4 机器,精度类型为 FP32, CPU 推理速度基于 Intel(R) Xeon(R) Gold 5117 CPU @ 2.00GHz,线程数为8,精度类型为 FP32。
> ❗ 以上列出的是文本识别模块重点支持的4个核心模型,该模块总共支持18个全量模型,包含多个多语言文本识别模型,完整的模型列表如下:
👉模型列表详情
* 中文识别模型
| 模型 | 模型下载链接 |
识别 Avg Accuracy(%) |
GPU推理耗时(ms) |
CPU推理耗时 (ms) |
模型存储大小(M) |
介绍 |
| PP-OCRv4_server_rec_doc | 推理模型/训练模型 |
81.53 |
|
|
74.7 M |
PP-OCRv4_server_rec_doc是在PP-OCRv4_server_rec的基础上,在更多中文文档数据和PP-OCR训练数据的混合数据训练而成,增加了部分繁体字、日文、特殊字符的识别能力,可支持识别的字符为1.5万+,除文档相关的文字识别能力提升外,也同时提升了通用文字的识别能力 |
| PP-OCRv4_mobile_rec | 推理模型/训练模型 |
78.74 |
7.95018 |
46.7868 |
10.6 M |
PP-OCRv4的轻量级识别模型,推理效率高,可以部署在包含端侧设备的多种硬件设备中 |
| PP-OCRv4_server_rec | 推理模型/训练模型 |
80.61 |
7.19439 |
140.179 |
71.2 M |
PP-OCRv4的服务器端模型,推理精度高,可以部署在多种不同的服务器上 |
| PP-OCRv3_mobile_rec | 推理模型/训练模型 |
72.96 |
|
|
9.2 M |
PP-OCRv3的轻量级识别模型,推理效率高,可以部署在包含端侧设备的多种硬件设备中 |
注:以上精度指标的评估集是 PaddleOCR 自建的中文数据集,覆盖街景、网图、文档、手写多个场景,其中文本识别包含 8367 张图片。所有模型 GPU 推理耗时基于 NVIDIA Tesla T4 机器,精度类型为 FP32, CPU 推理速度基于 Intel(R) Xeon(R) Gold 5117 CPU @ 2.00GHz,线程数为8,精度类型为 FP32。
| 模型 | 模型下载链接 |
识别 Avg Accuracy(%) |
GPU推理耗时(ms) |
CPU推理耗时 |
模型存储大小(M) |
介绍 |
| ch_SVTRv2_rec | 推理模型/训练模型 |
68.81 |
8.36801 |
165.706 |
73.9 M |
SVTRv2 是一种由复旦大学视觉与学习实验室(FVL)的OpenOCR团队研发的服务端文本识别模型,其在PaddleOCR算法模型挑战赛 - 赛题一:OCR端到端识别任务中荣获一等奖,A榜端到端识别精度相比PP-OCRv4提升6%。
|
注:以上精度指标的评估集是 PaddleOCR算法模型挑战赛 - 赛题一:OCR端到端识别任务A榜。 所有模型 GPU 推理耗时基于 NVIDIA Tesla T4 机器,精度类型为 FP32, CPU 推理速度基于 Intel(R) Xeon(R) Gold 5117 CPU @ 2.00GHz,线程数为8,精度类型为 FP32。
| 模型 | 模型下载链接 |
识别 Avg Accuracy(%) |
GPU推理耗时(ms) |
CPU推理耗时 |
模型存储大小(M) |
介绍 |
| ch_RepSVTR_rec | 推理模型/训练模型 |
65.07 |
10.5047 |
51.5647 |
22.1 M |
RepSVTR 文本识别模型是一种基于SVTRv2 的移动端文本识别模型,其在PaddleOCR算法模型挑战赛 - 赛题一:OCR端到端识别任务中荣获一等奖,B榜端到端识别精度相比PP-OCRv4提升2.5%,推理速度持平。 |
注:以上精度指标的评估集是 PaddleOCR算法模型挑战赛 - 赛题一:OCR端到端识别任务B榜。 所有模型 GPU 推理耗时基于 NVIDIA Tesla T4 机器,精度类型为 FP32, CPU 推理速度基于 Intel(R) Xeon(R) Gold 5117 CPU @ 2.00GHz,线程数为8,精度类型为 FP32。
* 英文识别模型
| 模型 | 模型下载链接 |
识别 Avg Accuracy(%) |
GPU推理耗时(ms) |
CPU推理耗时 |
模型存储大小(M) |
介绍 |
| en_PP-OCRv4_mobile_rec | 推理模型/训练模型 |
70.39 |
|
|
6.8 M |
基于PP-OCRv4识别模型训练得到的超轻量英文识别模型,支持英文、数字识别 |
| en_PP-OCRv3_mobile_rec | 推理模型/训练模型 |
70.69 |
|
|
7.8 M |
基于PP-OCRv3识别模型训练得到的超轻量英文识别模型,支持英文、数字识别 |
* 多语言识别模型
| 模型 | 模型下载链接 |
识别 Avg Accuracy(%) |
GPU推理耗时(ms) |
CPU推理耗时 |
模型存储大小(M) |
介绍 |
| korean_PP-OCRv3_mobile_rec | 推理模型/训练模型 |
60.21 |
|
|
8.6 M |
基于PP-OCRv3识别模型训练得到的超轻量韩文识别模型,支持韩文、数字识别 |
| japan_PP-OCRv3_mobile_rec | 推理模型/训练模型 |
45.69 |
|
|
8.8 M |
基于PP-OCRv3识别模型训练得到的超轻量日文识别模型,支持日文、数字识别 |
| chinese_cht_PP-OCRv3_mobile_rec | 推理模型/训练模型 |
82.06 |
|
|
9.7 M |
基于PP-OCRv3识别模型训练得到的超轻量繁体中文识别模型,支持繁体中文、数字识别 |
| te_PP-OCRv3_mobile_rec | 推理模型/训练模型 |
95.88 |
|
|
7.8 M |
基于PP-OCRv3识别模型训练得到的超轻量泰卢固文识别模型,支持泰卢固文、数字识别 |
| ka_PP-OCRv3_mobile_rec | 推理模型/训练模型 |
96.96 |
|
|
8.0 M |
基于PP-OCRv3识别模型训练得到的超轻量卡纳达文识别模型,支持卡纳达文、数字识别 |
| ta_PP-OCRv3_mobile_rec | 推理模型/训练模型 |
76.83 |
|
|
8.0 M |
基于PP-OCRv3识别模型训练得到的超轻量泰米尔文识别模型,支持泰米尔文、数字识别 |
| latin_PP-OCRv3_mobile_rec | 推理模型/训练模型 |
76.93 |
|
|
7.8 M |
基于PP-OCRv3识别模型训练得到的超轻量拉丁文识别模型,支持拉丁文、数字识别 |
| arabic_PP-OCRv3_mobile_rec | 推理模型/训练模型 |
73.55 |
|
|
7.8 M |
基于PP-OCRv3识别模型训练得到的超轻量阿拉伯字母识别模型,支持阿拉伯字母、数字识别 |
| cyrillic_PP-OCRv3_mobile_rec | 推理模型/训练模型 |
94.28 |
|
|
7.9 M |
基于PP-OCRv3识别模型训练得到的超轻量斯拉夫字母识别模型,支持斯拉夫字母、数字识别 |
| devanagari_PP-OCRv3_mobile_rec | 推理模型/训练模型 |
96.44 |
|
|
7.9 M |
基于PP-OCRv3识别模型训练得到的超轻量梵文字母识别模型,支持梵文字母、数字识别 |
注:以上精度指标的评估集是 PaddleX 自建的多语种数据集。 所有模型 GPU 推理耗时基于 NVIDIA Tesla T4 机器,精度类型为 FP32, CPU 推理速度基于 Intel(R) Xeon(R) Gold 5117 CPU @ 2.00GHz,线程数为8,精度类型为 FP32。
文本行方向分类模块(可选):
| 模型 |
模型下载链接 |
Top-1 Acc(%) |
GPU推理耗时(ms) |
CPU推理耗时 (ms) |
模型存储大小(M) |
介绍 |
| PP-LCNet_x0_25_textline_ori | 推理模型/训练模型 |
95.54 |
- |
- |
0.32 |
基于PP-LCNet_x0_25的文本行分类模型,含有两个类别,即0度,180度 |
注:以上精度指标的评估集是自建的数据集,覆盖证件和文档等多个场景,包含 1000 张图片。GPU 推理耗时基于 NVIDIA Tesla T4 机器,精度类型为 FP32, CPU 推理速度基于 Intel(R) Xeon(R) Gold 5117 CPU @ 2.00GHz,线程数为 8,精度类型为 FP32。
## 2. 快速开始
PaddleX 所提供的模型产线均可以快速体验效果,你可以在星河社区线体验通用 OCR 产线的效果,也可以在本地使用命令行或 Python 体验通用 OCR 产线的效果。
### 2.1 在线体验
您可以[在线体验](https://aistudio.baidu.com/community/app/91660/webUI?source=appMineRecent)通用 OCR 产线的效果,用官方提供的 Demo 图片进行识别,例如:
如果您对产线运行的效果满意,可以直接进行集成部署。您可以选择从云端下载部署包,也可以参考[2.2节本地体验](#22-本地体验)中的方法进行本地部署。如果对效果不满意,您可以利用私有数据对产线中的模型进行微调训练。如果您具备本地训练的硬件资源,可以直接在本地开展训练;如果没有,星河零代码平台提供了一键式训练服务,无需编写代码,只需上传数据后,即可一键启动训练任务。
### 2.2 本地体验
> ❗ 在本地使用通用OCR产线前,请确保您已经按照[PaddleX安装教程](../../../installation/installation.md)完成了PaddleX的wheel包安装。
#### 2.2.1 命令行方式体验
* 一行命令即可快速体验OCR产线效果,使用 [测试文件](https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png),并将 `--input` 替换为本地路径,进行预测
```bash
paddlex --pipeline OCR \
--input general_ocr_002.png \
--use_doc_orientation_classify False \
--use_doc_unwarping False \
--use_textline_orientation False \
--save_path ./output \
--device gpu:0
```
相关的参数说明可以参考[2.2.2 Python脚本方式集成](#222-python脚本方式集成)中的参数说明。
运行后,会将结果打印到终端上,结果如下:
```bash
{'res': {'input_path': 'general_ocr_002.png', 'model_settings': {'use_doc_preprocessor': False, 'use_textline_orientation': False}, 'doc_preprocessor_res': {'input_path': '0.jpg', 'model_settings': {'use_doc_orientation_classify': True, 'use_doc_unwarping': False}, 'angle': 0},'dt_polys': [array([[ 3, 10],
[82, 10],
[82, 33],
[ 3, 33]], dtype=int16), ...], 'text_det_params': {'limit_side_len': 960, 'limit_type': 'max', 'thresh': 0.3, 'box_thresh': 0.6, 'unclip_ratio': 2.0}, 'text_type': 'general', 'textline_orientation_angles': [-1, ...], 'text_rec_score_thresh': 0.0, 'rec_texts': ['www.99*', ...], 'rec_scores': [0.8980069160461426, ...], 'rec_polys': [array([[ 3, 10],
[82, 10],
[82, 33],
[ 3, 33]], dtype=int16), ...], 'rec_boxes': array([[ 3, 10, 82, 33], ...], dtype=int16)}}
```
运行结果参数说明可以参考[2.2.2 Python脚本方式集成](#222-python脚本方式集成)中的结果解释。
可视化结果保存在`save_path`下,其中OCR的可视化结果如下:
#### 2.2.2 Python脚本方式集成
* 上述命令行是为了快速体验查看效果,一般来说,在项目中,往往需要通过代码集成,您可以通过几行代码即可完成产线的快速推理,推理代码如下:
```python
from paddlex import create_pipeline
pipeline = create_pipeline(pipeline="OCR")
output = pipeline.predict(
input="./general_ocr_002.png",
use_doc_orientation_classify=False,
use_doc_unwarping=False,
use_textline_orientation=False,
)
for res in output:
res.print()
res.save_to_img(save_path="./output/")
res.save_to_json(save_path="./output/")
```
在上述 Python 脚本中,执行了如下几个步骤:
(1)通过 `create_pipeline()` 实例化 OCR 产线对象,具体参数说明如下:
| 参数 |
参数说明 |
参数类型 |
默认值 |
pipeline |
产线名称或是产线配置文件路径。如为产线名称,则必须为 PaddleX 所支持的产线。 |
str |
None |
device |
产线推理设备。支持指定GPU具体卡号,如“gpu:0”,其他硬件具体卡号,如“npu:0”,CPU如“cpu”。 |
str |
gpu:0 |
use_hpip |
是否启用高性能推理,仅当该产线支持高性能推理时可用。 |
bool |
False |
(2)调用 OCR 产线对象的 `predict()` 方法进行推理预测。该方法将返回一个 `generator`。以下是 `predict()` 方法的参数及其说明:
| 参数 |
参数说明 |
参数类型 |
可选项 |
默认值 |
input |
待预测数据,支持多种输入类型,必填 |
Python Var|str|list |
- Python Var:如
numpy.ndarray 表示的图像数据
- str:如图像文件或者PDF文件的本地路径:
/root/data/img.jpg;如URL链接,如图像文件或PDF文件的网络URL:示例;如本地目录,该目录下需包含待预测图像,如本地路径:/root/data/(当前不支持目录中包含PDF文件的预测,PDF文件需要指定到具体文件路径)
- List:列表元素需为上述类型数据,如
[numpy.ndarray, numpy.ndarray],[\"/root/data/img1.jpg\", \"/root/data/img2.jpg\"],[\"/root/data1\", \"/root/data2\"]
|
None |
device |
产线推理设备 |
str|None |
- CPU:如
cpu 表示使用 CPU 进行推理;
- GPU:如
gpu:0 表示使用第 1 块 GPU 进行推理;
- NPU:如
npu:0 表示使用第 1 块 NPU 进行推理;
- XPU:如
xpu:0 表示使用第 1 块 XPU 进行推理;
- MLU:如
mlu:0 表示使用第 1 块 MLU 进行推理;
- DCU:如
dcu:0 表示使用第 1 块 DCU 进行推理;
- None:如果设置为
None, 将默认使用产线初始化的该参数值,初始化时,会优先使用本地的 GPU 0号设备,如果没有,则使用 CPU 设备;
|
None |
use_doc_orientation_classify |
是否使用文档方向分类模块 |
bool|None |
- bool:
True 或者 False;
- None:如果设置为
None, 将默认使用产线初始化的该参数值,初始化为True;
|
None |
use_doc_unwarping |
是否使用文档扭曲矫正模块 |
bool|None |
- bool:
True 或者 False;
- None:如果设置为
None, 将默认使用产线初始化的该参数值,初始化为True;
|
None |
use_textline_orientation |
是否使用文本行方向分类模块 |
bool|None |
- bool:
True 或者 False;
- None:如果设置为
None, 将默认使用产线初始化的该参数值,初始化为True;
|
None |
text_det_limit_side_len |
文本检测的图像边长限制 |
int|None |
- int:大于
0 的任意整数;
- None:如果设置为
None, 将默认使用产线初始化的该参数值,初始化为 960;
|
None |
text_det_limit_type |
文本检测的图像边长限制类型 |
str|None |
- str:支持
min 和 max,min 表示保证图像最短边不小于 det_limit_side_len,max 表示保证图像最长边不大于 limit_side_len
- None:如果设置为
None, 将默认使用产线初始化的该参数值,初始化为 max;
|
None |
text_det_thresh |
检测像素阈值,输出的概率图中,得分大于该阈值的像素点才会被认为是文字像素点 |
float|None |
- float:大于
0 的任意浮点数
- None:如果设置为
None, 将默认使用产线初始化的该参数值 0.3 |
None |
text_det_box_thresh |
检测框阈值,检测结果边框内,所有像素点的平均得分大于该阈值时,该结果会被认为是文字区域 |
float|None |
- float:大于
0 的任意浮点数
- None:如果设置为
None, 将默认使用产线初始化的该参数值 0.6 |
None |
text_det_unclip_ratio |
文本检测扩张系数,使用该方法对文字区域进行扩张,该值越大,扩张的面积越大 |
float|None |
- float:大于
0 的任意浮点数
- None:如果设置为
None, 将默认使用产线初始化的该参数值 2.0 |
None |
text_rec_score_thresh |
文本识别阈值,得分大于该阈值的文本结果会被保留 |
float|None |
- float:大于
0 的任意浮点数
- None:如果设置为
None, 将默认使用产线初始化的该参数值 0.0。即不设阈值 |
None |
(3)对预测结果进行处理,每个样本的预测结果均为`dict`类型,且支持打印、保存为图片、保存为`json`文件的操作:
| 方法 |
方法说明 |
参数 |
参数类型 |
参数说明 |
默认值 |
print() |
打印结果到终端 |
format_json |
bool |
是否对输出内容进行使用 JSON 缩进格式化 |
True |
indent |
int |
指定缩进级别,以美化输出的 JSON 数据,使其更具可读性,仅当 format_json 为 True 时有效 |
4 |
ensure_ascii |
bool |
控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时,所有非 ASCII 字符将被转义;False 则保留原始字符,仅当format_json为True时有效 |
False |
save_to_json() |
将结果保存为json格式的文件 |
save_path |
str |
保存的文件路径,当为目录时,保存文件命名与输入文件类型命名一致 |
无 |
indent |
int |
指定缩进级别,以美化输出的 JSON 数据,使其更具可读性,仅当 format_json 为 True 时有效 |
4 |
ensure_ascii |
bool |
控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时,所有非 ASCII 字符将被转义;False 则保留原始字符,仅当format_json为True时有效 |
False |
save_to_img() |
将结果保存为图像格式的文件 |
save_path |
str |
保存的文件路径,支持目录或文件路径 |
无 |
- 调用`print()` 方法会将结果打印到终端,打印到终端的内容解释如下:
- `input_path`: `(str)` 待预测图像的输入路径
- `model_settings`: `(Dict[str, bool])` 配置产线所需的模型参数
- `use_doc_preprocessor`: `(bool)` 控制是否启用文档预处理子产线
- `use_textline_orientation`: `(bool)` 控制是否启用文本行方向分类功能
- `doc_preprocessor_res`: `(Dict[str, Union[str, Dict[str, bool], int]])` 文档预处理子产线的输出结果。仅当`use_doc_preprocessor=True`时存在
- `input_path`: `(Union[str, None])` 图像预处理子产线接受的图像路径,当输入为`numpy.ndarray`时,保存为`None`
- `model_settings`: `(Dict)` 预处理子产线的模型配置参数
- `use_doc_orientation_classify`: `(bool)` 控制是否启用文档方向分类
- `use_doc_unwarping`: `(bool)` 控制是否启用文档扭曲矫正
- `angle`: `(int)` 文档方向分类的预测结果。启用时取值为[0,1,2,3],分别对应[0°,90°,180°,270°];未启用时为-1
- `dt_polys`: `(List[numpy.ndarray])` 文本检测的多边形框列表。每个检测框由4个顶点坐标构成的numpy数组表示,数组shape为(4, 2),数据类型为int16
- `dt_scores`: `(List[float])` 文本检测框的置信度列表
- `text_det_params`: `(Dict[str, Dict[str, int, float]])` 文本检测模块的配置参数
- `limit_side_len`: `(int)` 图像预处理时的边长限制值
- `limit_type`: `(str)` 边长限制的处理方式
- `thresh`: `(float)` 文本像素分类的置信度阈值
- `box_thresh`: `(float)` 文本检测框的置信度阈值
- `unclip_ratio`: `(float)` 文本检测框的膨胀系数
- `text_type`: `(str)` 文本检测的类型,当前固定为"general"
- `textline_orientation_angles`: `(List[int])` 文本行方向分类的预测结果。启用时返回实际角度值(如[0,0,1]),未启用时返回[-1,-1,-1]
- `text_rec_score_thresh`: `(float)` 文本识别结果的过滤阈值
- `rec_texts`: `(List[str])` 文本识别结果列表,仅包含置信度超过`text_rec_score_thresh`的文本
- `rec_scores`: `(List[float])` 文本识别的置信度列表,已按`text_rec_score_thresh`过滤
- `rec_polys`: `(List[numpy.ndarray])` 经过置信度过滤的文本检测框列表,格式同`dt_polys`
- `rec_boxes`: `(numpy.ndarray)` 检测框的矩形边界框数组,shape为(n, 4),dtype为int16。每一行表示一个矩形框的[x_min, y_min, x_max, y_max]坐标
,其中(x_min, y_min)为左上角坐标,(x_max, y_max)为右下角坐标
- 调用`save_to_json()` 方法会将上述内容保存到指定的`save_path`中,如果指定为目录,则保存的路径为`save_path/{your_img_basename}.json`,如果指定为文件,则直接保存到该文件中。由于json文件不支持保存numpy数组,因此会将其中的`numpy.array`类型转换为列表形式。
- 调用`save_to_img()` 方法会将可视化结果保存到指定的`save_path`中,如果指定为目录,则保存的路径为`save_path/{your_img_basename}_ocr_res_img.{your_img_extension}`,如果指定为文件,则直接保存到该文件中。(产线通常包含较多结果图片,不建议直接指定为具体的文件路径,否则多张图会被覆盖,仅保留最后一张图)
* 此外,也支持通过属性获取带结果的可视化图像和预测结果,具体如下:
| 属性 |
属性说明 |
json |
获取预测的 json 格式的结果 |
img |
获取格式为 dict 的可视化图像 |
- `json` 属性获取的预测结果为dict类型的数据,相关内容与调用 `save_to_json()` 方法保存的内容一致。
- `img` 属性返回的预测结果是一个字典类型的数据。其中,键分别为 `ocr_res_img` 和 `preprocessed_img`,对应的值是两个 `Image.Image` 对象:一个用于显示 OCR 结果的可视化图像,另一个用于展示图像预处理的可视化图像。如果没有使用图像预处理子模块,则字典中只包含 `ocr_res_img`。
此外,您可以获取OCR产线配置文件,并加载配置文件进行预测。可执行如下命令将结果保存在 `my_path` 中:
```
paddlex --get_pipeline_config OCR --save_path ./my_path
```
若您获取了配置文件,即可对OCR产线各项配置进行自定义,只需要修改 `create_pipeline` 方法中的 `pipeline` 参数值为产线配置文件路径即可。示例如下:
```python
from paddlex import create_pipeline
pipeline = create_pipeline(pipeline="./my_path/OCR.yaml")
output = pipeline.predict(
input="./general_ocr_002.png",
use_doc_orientation_classify=False,
use_doc_unwarping=False,
use_textline_orientation=False,
)
for res in output:
res.print()
res.save_to_img("./output/")
res.save_to_json("./output/")
```
注: 配置文件中的参数为产线初始化参数,如果希望更改通用OCR产线初始化参数,可以直接修改配置文件中的参数,并加载配置文件进行预测。同时,CLI 预测也支持传入配置文件,`--pipeline` 指定配置文件的路径即可。
## 3. 开发集成/部署
如果通用 OCR 产线可以达到您对产线推理速度和精度的要求,您可以直接进行开发集成/部署。
若您需要将通用 OCR 产线直接应用在您的Python项目中,可以参考 [2.2.2 Python脚本方式](#222-python脚本方式集成)中的示例代码。
此外,PaddleX 也提供了其他三种部署方式,详细说明如下:
🚀 高性能推理:在实际生产环境中,许多应用对部署策略的性能指标(尤其是响应速度)有着较严苛的标准,以确保系统的高效运行与用户体验的流畅性。为此,PaddleX 提供高性能推理插件,旨在对模型推理及前后处理进行深度性能优化,实现端到端流程的显著提速,详细的高性能推理流程请参考[PaddleX高性能推理指南](../../../pipeline_deploy/high_performance_inference.md)。
☁️ 服务化部署:服务化部署是实际生产环境中常见的一种部署形式。通过将推理功能封装为服务,客户端可以通过网络请求来访问这些服务,以获取推理结果。PaddleX 支持用户以低成本实现产线的服务化部署,详细的服务化部署流程请参考[PaddleX服务化部署指南](../../../pipeline_deploy/service_deploy.md)。
下面是API参考和多语言服务调用示例:
API参考
对于服务提供的主要操作:
- HTTP请求方法为POST。
- 请求体和响应体均为JSON数据(JSON对象)。
- 当请求处理成功时,响应状态码为
200,响应体的属性如下:
| 名称 |
类型 |
含义 |
logId |
string |
请求的UUID。 |
errorCode |
integer |
错误码。固定为0。 |
errorMsg |
string |
错误说明。固定为"Success"。 |
result |
object |
操作结果。 |
| 名称 |
类型 |
含义 |
logId |
string |
请求的UUID。 |
errorCode |
integer |
错误码。与响应状态码相同。 |
errorMsg |
string |
错误说明。 |
服务提供的主要操作如下:
获取图像OCR结果。
POST /ocr
| 名称 |
类型 |
含义 |
是否必填 |
image |
string |
服务可访问的图像文件的URL或图像文件内容的Base64编码结果。 |
是 |
inferenceParams |
object |
推理参数。 |
否 |
inferenceParams的属性如下:
| 名称 |
类型 |
含义 |
是否必填 |
maxLongSide |
integer |
推理时,若文本检测模型的输入图像较长边的长度大于maxLongSide,则将对图像进行缩放,使其较长边的长度等于maxLongSide。 |
否 |
- 请求处理成功时,响应体的
result具有如下属性:
| 名称 |
类型 |
含义 |
texts |
array |
文本位置、内容和得分。 |
image |
string |
OCR结果图,其中标注检测到的文本位置。图像为JPEG格式,使用Base64编码。 |
texts中的每个元素为一个object,具有如下属性:
| 名称 |
类型 |
含义 |
poly |
array |
文本位置。数组中元素依次为包围文本的多边形的顶点坐标。 |
text |
string |
文本内容。 |
score |
number |
文本识别得分。 |
result示例如下:
{
"texts": [
{
"poly": [
[
444,
244
],
[
705,
244
],
[
705,
311
],
[
444,
311
]
],
"text": "北京南站",
"score": 0.9
},
{
"poly": [
[
992,
248
],
[
1263,
251
],
[
1263,
318
],
[
992,
315
]
],
"text": "天津站",
"score": 0.5
}
],
"image": "xxxxxx"
}
多语言调用服务示例
Python
import base64
import requests
API_URL = "http://localhost:8080/ocr" # 服务URL
image_path = "./demo.jpg"
output_image_path = "./out.jpg"
# 对本地图像进行Base64编码
with open(image_path, "rb") as file:
image_bytes = file.read()
image_data = base64.b64encode(image_bytes).decode("ascii")
payload = {"image": image_data} # Base64编码的文件内容或者图像URL
# 调用API
response = requests.post(API_URL, json=payload)
# 处理接口返回数据
assert response.status_code == 200
result = response.json()["result"]
with open(output_image_path, "wb") as file:
file.write(base64.b64decode(result["image"]))
print(f"Output image saved at {output_image_path}")
print("\nDetected texts:")
print(result["texts"])
C++
#include <iostream>
#include "cpp-httplib/httplib.h" // https://github.com/Huiyicc/cpp-httplib
#include "nlohmann/json.hpp" // https://github.com/nlohmann/json
#include "base64.hpp" // https://github.com/tobiaslocker/base64
int main() {
httplib::Client client("localhost:8080");
const std::string imagePath = "./demo.jpg";
const std::string outputImagePath = "./out.jpg";
httplib::Headers headers = {
{"Content-Type", "application/json"}
};
// 对本地图像进行Base64编码
std::ifstream file(imagePath, std::ios::binary | std::ios::ate);
std::streamsize size = file.tellg();
file.seekg(0, std::ios::beg);
std::vector<char> buffer(size);
if (!file.read(buffer.data(), size)) {
std::cerr << "Error reading file." << std::endl;
return 1;
}
std::string bufferStr(reinterpret_cast<const char*>(buffer.data()), buffer.size());
std::string encodedImage = base64::to_base64(bufferStr);
nlohmann::json jsonObj;
jsonObj["image"] = encodedImage;
std::string body = jsonObj.dump();
// 调用API
auto response = client.Post("/ocr", headers, body, "application/json");
// 处理接口返回数据
if (response && response->status == 200) {
nlohmann::json jsonResponse = nlohmann::json::parse(response->body);
auto result = jsonResponse["result"];
encodedImage = result["image"];
std::string decodedString = base64::from_base64(encodedImage);
std::vector<unsigned char> decodedImage(decodedString.begin(), decodedString.end());
std::ofstream outputImage(outPutImagePath, std::ios::binary | std::ios::out);
if (outputImage.is_open()) {
outputImage.write(reinterpret_cast<char*>(decodedImage.data()), decodedImage.size());
outputImage.close();
std::cout << "Output image saved at " << outPutImagePath << std::endl;
} else {
std::cerr << "Unable to open file for writing: " << outPutImagePath << std::endl;
}
auto texts = result["texts"];
std::cout << "\nDetected texts:" << std::endl;
for (const auto& text : texts) {
std::cout << text << std::endl;
}
} else {
std::cout << "Failed to send HTTP request." << std::endl;
return 1;
}
return 0;
}
Java
import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.util.Base64;
public class Main {
public static void main(String[] args) throws IOException {
String API_URL = "http://localhost:8080/ocr"; // 服务URL
String imagePath = "./demo.jpg"; // 本地图像
String outputImagePath = "./out.jpg"; // 输出图像
// 对本地图像进行Base64编码
File file = new File(imagePath);
byte[] fileContent = java.nio.file.Files.readAllBytes(file.toPath());
String imageData = Base64.getEncoder().encodeToString(fileContent);
ObjectMapper objectMapper = new ObjectMapper();
ObjectNode params = objectMapper.createObjectNode();
params.put("image", imageData); // Base64编码的文件内容或者图像URL
// 创建 OkHttpClient 实例
OkHttpClient client = new OkHttpClient();
MediaType JSON = MediaType.Companion.get("application/json; charset=utf-8");
RequestBody body = RequestBody.Companion.create(params.toString(), JSON);
Request request = new Request.Builder()
.url(API_URL)
.post(body)
.build();
// 调用API并处理接口返回数据
try (Response response = client.newCall(request).execute()) {
if (response.isSuccessful()) {
String responseBody = response.body().string();
JsonNode resultNode = objectMapper.readTree(responseBody);
JsonNode result = resultNode.get("result");
String base64Image = result.get("image").asText();
JsonNode texts = result.get("texts");
byte[] imageBytes = Base64.getDecoder().decode(base64Image);
try (FileOutputStream fos = new FileOutputStream(outputImagePath)) {
fos.write(imageBytes);
}
System.out.println("Output image saved at " + outputImagePath);
System.out.println("\nDetected texts: " + texts.toString());
} else {
System.err.println("Request failed with code: " + response.code());
}
}
}
}
Go
package main
import (
"bytes"
"encoding/base64"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func main() {
API_URL := "http://localhost:8080/ocr"
imagePath := "./demo.jpg"
outputImagePath := "./out.jpg"
// 对本地图像进行Base64编码
imageBytes, err := ioutil.ReadFile(imagePath)
if err != nil {
fmt.Println("Error reading image file:", err)
return
}
imageData := base64.StdEncoding.EncodeToString(imageBytes)
payload := map[string]string{"image": imageData} // Base64编码的文件内容或者图像URL
payloadBytes, err := json.Marshal(payload)
if err != nil {
fmt.Println("Error marshaling payload:", err)
return
}
// 调用API
client := &http.Client{}
req, err := http.NewRequest("POST", API_URL, bytes.NewBuffer(payloadBytes))
if err != nil {
fmt.Println("Error creating request:", err)
return
}
res, err := client.Do(req)
if err != nil {
fmt.Println("Error sending request:", err)
return
}
defer res.Body.Close()
// 处理接口返回数据
body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println("Error reading response body:", err)
return
}
type Response struct {
Result struct {
Image string `json:"image"`
Texts []map[string]interface{} `json:"texts"`
} `json:"result"`
}
var respData Response
err = json.Unmarshal([]byte(string(body)), &respData)
if err != nil {
fmt.Println("Error unmarshaling response body:", err)
return
}
outputImageData, err := base64.StdEncoding.DecodeString(respData.Result.Image)
if err != nil {
fmt.Println("Error decoding base64 image data:", err)
return
}
err = ioutil.WriteFile(outputImagePath, outputImageData, 0644)
if err != nil {
fmt.Println("Error writing image to file:", err)
return
}
fmt.Printf("Image saved at %s.jpg\n", outputImagePath)
fmt.Println("\nDetected texts:")
for _, text := range respData.Result.Texts {
fmt.Println(text)
}
}
C#
using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json.Linq;
class Program
{
static readonly string API_URL = "http://localhost:8080/ocr";
static readonly string imagePath = "./demo.jpg";
static readonly string outputImagePath = "./out.jpg";
static async Task Main(string[] args)
{
var httpClient = new HttpClient();
// 对本地图像进行Base64编码
byte[] imageBytes = File.ReadAllBytes(imagePath);
string image_data = Convert.ToBase64String(imageBytes);
var payload = new JObject{ { "image", image_data } }; // Base64编码的文件内容或者图像URL
var content = new StringContent(payload.ToString(), Encoding.UTF8, "application/json");
// 调用API
HttpResponseMessage response = await httpClient.PostAsync(API_URL, content);
response.EnsureSuccessStatusCode();
// 处理接口返回数据
string responseBody = await response.Content.ReadAsStringAsync();
JObject jsonResponse = JObject.Parse(responseBody);
string base64Image = jsonResponse["result"]["image"].ToString();
byte[] outputImageBytes = Convert.FromBase64String(base64Image);
File.WriteAllBytes(outputImagePath, outputImageBytes);
Console.WriteLine($"Output image saved at {outputImagePath}");
Console.WriteLine("\nDetected texts:");
Console.WriteLine(jsonResponse["result"]["texts"].ToString());
}
}
Node.js
const axios = require('axios');
const fs = require('fs');
const API_URL = 'http://localhost:8080/ocr'
const imagePath = './demo.jpg'
const outputImagePath = "./out.jpg";
let config = {
method: 'POST',
maxBodyLength: Infinity,
url: API_URL,
data: JSON.stringify({
'image': encodeImageToBase64(imagePath) // Base64编码的文件内容或者图像URL
})
};
// 对本地图像进行Base64编码
function encodeImageToBase64(filePath) {
const bitmap = fs.readFileSync(filePath);
return Buffer.from(bitmap).toString('base64');
}
// 调用API
axios.request(config)
.then((response) => {
// 处理接口返回数据
const result = response.data["result"];
const imageBuffer = Buffer.from(result["image"], 'base64');
fs.writeFile(outputImagePath, imageBuffer, (err) => {
if (err) throw err;
console.log(`Output image saved at ${outputImagePath}`);
});
console.log("\nDetected texts:");
console.log(result["texts"]);
})
.catch((error) => {
console.log(error);
});
PHP
<?php
$API_URL = "http://localhost:8080/ocr"; // 服务URL
$image_path = "./demo.jpg";
$output_image_path = "./out.jpg";
// 对本地图像进行Base64编码
$image_data = base64_encode(file_get_contents($image_path));
$payload = array("image" => $image_data); // Base64编码的文件内容或者图像URL
// 调用API
$ch = curl_init($API_URL);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
// 处理接口返回数据
$result = json_decode($response, true)["result"];
file_put_contents($output_image_path, base64_decode($result["image"]));
echo "Output image saved at " . $output_image_path . "\n";
echo "\nDetected texts:\n";
print_r($result["texts"]);
?>
📱 端侧部署:端侧部署是一种将计算和数据处理功能放在用户设备本身上的方式,设备可以直接处理数据,而不需要依赖远程的服务器。PaddleX 支持将模型部署在 Android 等端侧设备上,详细的端侧部署流程请参考[PaddleX端侧部署指南](../../../pipeline_deploy/edge_deploy.md)。
您可以根据需要选择合适的方式部署模型产线,进而进行后续的 AI 应用集成。
## 4. 二次开发
如果通用 OCR 产线提供的默认模型权重在您的场景中,精度或速度不满意,您可以尝试利用您自己拥有的特定领域或应用场景的数据对现有模型进行进一步的微调,以提升通用 OCR 产线的在您的场景中的识别效果。
### 4.1 模型微调
由于通用OCR产线包含若干模块,模型产线的效果如果不及预期,可能来自于其中任何一个模块。您可以对识别效果差的图片进行分析,进而确定是哪个模块存在问题,并参考以下表格中对应的微调教程链接进行模型微调。
| 情形 |
微调模块 |
微调参考链接 |
| 文本存在漏检 |
文本检测模块 |
链接 |
| 文本内容都不准 |
文本识别模块 |
链接 |
| 垂直或者旋转文本行矫正不准 |
文本行方向分类模块 |
链接 |
| 整图旋转矫正不准 |
文档图像方向分类模块 |
链接 |
| 图像扭曲矫正不准 |
文本图像矫正模块 |
暂不支持微调 |
### 4.2 模型应用
当您使用私有数据集完成微调训练后,可获得本地模型权重文件。
若您需要使用微调后的模型权重,只需对产线配置文件做修改,将微调后模型权重的本地路径替换至产线配置文件中的对应位置即可:
```yaml
SubPipelines:
DocPreprocessor:
...
SubModules:
DocOrientationClassify:
module_name: doc_text_orientation
model_name: PP-LCNet_x1_0_doc_ori
model_dir: null # 替换为微调后的文档图像方向分类模型权重路径
...
SubModules:
TextDetection:
module_name: text_detection
model_name: PP-OCRv4_mobile_det
model_dir: null # 替换为微调后的文本检测模型权重路径
...
TextLineOrientation:
module_name: textline_orientation
model_name: PP-LCNet_x0_25_textline_ori
model_dir: null # 替换为微调后的文本行方向分类模型权重路径
batch_size: 1
TextRecognition:
module_name: text_recognition
model_name: PP-OCRv4_mobile_rec
model_dir: null # 替换为微调后的文本识别模型权重路径
batch_size: 1
```
随后, 参考[2.2 本地体验](#22-本地体验)中的命令行方式或Python脚本方式,加载修改后的产线配置文件即可。
## 5. 多硬件支持
PaddleX 支持英伟达 GPU、昆仑芯 XPU、昇腾 NPU和寒武纪 MLU 等多种主流硬件设备,仅需修改 `--device`参数即可完成不同硬件之间的无缝切换。
例如,您使用昇腾 NPU 进行 OCR 产线的推理,使用的 Python 命令为:
```bash
paddlex --pipeline OCR \
--input general_ocr_002.png \
--use_doc_orientation_classify False \
--use_doc_unwarping False \
--use_textline_orientation False \
--save_path ./output \
--device npu:0
```
若您想在更多种类的硬件上使用通用OCR产线,请参考[PaddleX多硬件使用指南](../../../other_devices_support/multi_devices_use_guide.md)。