General OCR pipeline Usage Guide¶

1. Introduction to the OCR pipeline¶

OCR (Optical Character Recognition) is a technology that converts text in images into editable text. It is widely used in document digitization, information extraction, and data processing. OCR can recognize printed text, handwritten text, and even certain types of fonts and symbols.

The General OCR pipeline is designed to solve text recognition tasks, extracting text information from images and outputting it in text form. This pipeline integrates the well-known end-to-end OCR series systems, PP-OCRv3 and PP-OCRv4, supporting recognition of over 80 languages. Additionally, it includes functions for image orientation correction and distortion correction. Based on this pipeline, precise text content prediction at the millisecond level on CPUs can be achieved, covering a wide range of applications including general, manufacturing, finance, and transportation sectors. The pipeline also provides flexible deployment options, supporting calls in various programming languages on multiple hardware platforms. Moreover, it offers the capability for secondary development, allowing you to train and optimize on your own dataset. The trained models can also be seamlessly integrated.

The General OCR pipeline includes mandatory text detection and text recognition modules, as well as optional document image orientation classification, text image correction, and text line orientation classification modules. The document image orientation classification and text image correction modules are integrated as a document preprocessing sub-line into the General OCR pipeline. Each module contains multiple models, and you can choose the model based on the benchmark test data below.

If you prioritize model accuracy, choose a high-accuracy model; if you prioritize inference speed, choose a faster inference model; if you care about model storage size, choose a smaller model.

Document Image Orientation Classification Module (Optional):

Model	Model Download Link	Top-1 Acc (%)	GPU Inference Time (ms) [Normal Mode / High-Performance Mode]	CPU Inference Time (ms) [Normal Mode / High-Performance Mode]	Model Storage Size (M)	Introduction
PP-LCNet_x1_0_doc_ori	Inference Model/Training Model	99.06	2.31 / 0.43	3.37 / 1.27	7	A document image classification model based on PP-LCNet_x1_0, with four categories: 0 degrees, 90 degrees, 180 degrees, and 270 degrees.

Text Image Correction Module (Optional):

Model	Model Download Link	CER	Model Storage Size (M)	Introduction
UVDoc	Inference Model/Training Model	0.179	30.3 M	High-precision text image correction model

Text Detection Module:

Model	Model Download Link	Detection Hmean (%)	GPU Inference Time (ms) [Normal Mode / High-Performance Mode]	CPU Inference Time (ms) [Normal Mode / High-Performance Mode]	Model Storage Size (M)	Introduction
PP-OCRv4_server_det	Inference Model/Training Model	82.56	83.34 / 80.91	442.58 / 442.58	109	The server-side text detection model of PP-OCRv4, with higher accuracy, suitable for deployment on high-performance servers
PP-OCRv4_mobile_det	Inference Model/Training Model	77.35	8.79 / 3.13	51.00 / 28.58	4.7	The mobile text detection model of PP-OCRv4, with higher efficiency, suitable for deployment on edge devices
PP-OCRv3_mobile_det	Inference Model/Training Model	78.68	8.44 / 2.91	27.87 / 27.87	2.1	The mobile text detection model of PP-OCRv3, with higher efficiency, suitable for deployment on edge devices
PP-OCRv3_server_det	Inference Model/Training Model	80.11	65.41 / 13.67	305.07 / 305.07	102.1	The server-side text detection model of PP-OCRv3, with higher accuracy, suitable for deployment on high-performance servers

Text Recognition Module:

Model	Model Download Link	Recognition Avg Accuracy (%)	GPU Inference Time (ms) [Normal Mode / High-Performance Mode]	CPU Inference Time (ms) [Normal Mode / High-Performance Mode]	Model Storage Size (M)	Introduction
PP-OCRv4_server_rec_doc	Inference Model/Training Model	81.53	6.65 / 2.38	32.92 / 32.92	74.7 M	PP-OCRv4_server_rec_doc is trained on a mixed dataset of more Chinese document data and PP-OCR training data based on PP-OCRv4_server_rec. It has added the ability to recognize some traditional Chinese characters, Japanese, and special characters, and can support the recognition of more than 15,000 characters. In addition to improving the text recognition capability related to documents, it also enhances the general text recognition capability.
PP-OCRv4_mobile_rec	Inference Model/Training Model	78.74	4.82 / 1.20	16.74 / 4.64	10.6 M	The lightweight recognition model of PP-OCRv4 has high inference efficiency and can be deployed on various hardware devices, including edge devices.
PP-OCRv4_server_rec	Inference Model/Training Model	80.61	6.58 / 2.43	33.17 / 33.17	71.2 M	The server-side model of PP-OCRv4 offers high inference accuracy and can be deployed on various types of servers.
en_PP-OCRv4_mobile_rec	Inference Model/Training Model	70.39	4.81 / 0.75	16.10 / 5.31	6.8 M	The ultra-lightweight English recognition model, trained based on the PP-OCRv4 recognition model, supports the recognition of English letters and numbers.

❗ The above list features the 4 core models that the text recognition module primarily supports. In total, this module supports 18 models. The complete list of models is as follows:

👉Model List Details

* Chinese Recognition Model

Model	Model Download Link	Recognition Avg Accuracy(%)	GPU Inference Time (ms) [Normal Mode / High-Performance Mode]	CPU Inference Time (ms) [Normal Mode / High-Performance Mode]	Model Storage Size (M)	Introduction
PP-OCRv4_server_rec_doc	Inference Model/Training Model	81.53	6.65 / 2.38	32.92 / 32.92	74.7 M	PP-OCRv4_server_rec_doc is trained on a mixed dataset of more Chinese document data and PP-OCR training data based on PP-OCRv4_server_rec. It has added the recognition capabilities for some traditional Chinese characters, Japanese, and special characters. The number of recognizable characters is over 15,000. In addition to the improvement in document-related text recognition, it also enhances the general text recognition capability.
PP-OCRv4_mobile_rec	Inference Model/Training Model	78.74	4.82 / 1.20	16.74 / 4.64	10.6 M	The lightweight recognition model of PP-OCRv4 has high inference efficiency and can be deployed on various hardware devices, including edge devices.
PP-OCRv4_server_rec	Inference Model/Trained Model	80.61	6.58 / 2.43	33.17 / 33.17	71.2 M	The server-side model of PP-OCRv4 offers high inference accuracy and can be deployed on various types of servers.
PP-OCRv3_mobile_rec	Inference Model/Training Model	72.96	5.87 / 1.19	9.07 / 4.28	9.2 M	PP-OCRv3’s lightweight recognition model is designed for high inference efficiency and can be deployed on a variety of hardware devices, including edge devices.

Model	Model Download Link	Recognition Avg Accuracy(%)	GPU Inference Time (ms) [Normal Mode / High-Performance Mode]	CPU Inference Time (ms) [Normal Mode / High-Performance Mode]	Model Storage Size (M)	Introduction
ch_SVTRv2_rec	Inference Model/Training Model	68.81	8.08 / 2.74	50.17 / 42.50	73.9 M	SVTRv2 is a server text recognition model developed by the OpenOCR team of Fudan University's Visual and Learning Laboratory (FVL). It won the first prize in the PaddleOCR Algorithm Model Challenge - Task One: OCR End-to-End Recognition Task. The end-to-end recognition accuracy on the A list is 6% higher than that of PP-OCRv4.

Model	Model Download Link	Recognition Avg Accuracy(%)	GPU Inference Time (ms) [Normal Mode / High-Performance Mode]	CPU Inference Time (ms) [Normal Mode / High-Performance Mode]	Model Storage Size (M)	Introduction
ch_RepSVTR_rec	Inference Model/Training Model	65.07	5.93 / 1.62	20.73 / 7.32	22.1 M	The RepSVTR text recognition model is a mobile text recognition model based on SVTRv2. It won the first prize in the PaddleOCR Algorithm Model Challenge - Task One: OCR End-to-End Recognition Task. The end-to-end recognition accuracy on the B list is 2.5% higher than that of PP-OCRv4, with the same inference speed.

* English Recognition Model

Model	Model Download Link	Recognition Avg Accuracy(%)	GPU Inference Time (ms) [Normal Mode / High-Performance Mode]	CPU Inference Time (ms) [Normal Mode / High-Performance Mode]	Model Storage Size (M)	Introduction
en_PP-OCRv4_mobile_rec	Inference Model/Training Model	70.39	4.81 / 0.75	16.10 / 5.31	6.8 M	The ultra-lightweight English recognition model trained based on the PP-OCRv4 recognition model supports the recognition of English and numbers.
en_PP-OCRv3_mobile_rec	Inference Model/Training Model	70.69	5.44 / 0.75	8.65 / 5.57	7.8 M	The ultra-lightweight English recognition model trained based on the PP-OCRv3 recognition model supports the recognition of English and numbers.

* Multilingual Recognition Model

Model	Model Download Link	Recognition Avg Accuracy(%)	GPU Inference Time (ms) [Normal Mode / High-Performance Mode]	CPU Inference Time (ms) [Normal Mode / High-Performance Mode]	Model Storage Size (M)	Introduction
korean_PP-OCRv3_mobile_rec	Inference Model/Training Model	60.21	5.40 / 0.97	9.11 / 4.05	8.6 M	The ultra-lightweight Korean recognition model trained based on the PP-OCRv3 recognition model supports the recognition of Korean and numbers.
japan_PP-OCRv3_mobile_rec	Inference Model/Training Model	45.69	5.70 / 1.02	8.48 / 4.07	8.8 M	The ultra-lightweight Japanese recognition model trained based on the PP-OCRv3 recognition model supports the recognition of Japanese and numbers.
chinese_cht_PP-OCRv3_mobile_rec	Inference Model/Training Model	82.06	5.90 / 1.28	9.28 / 4.34	9.7 M	The ultra-lightweight Traditional Chinese recognition model trained based on the PP-OCRv3 recognition model supports the recognition of Traditional Chinese and numbers.
te_PP-OCRv3_mobile_rec	Inference Model/Training Model	95.88	5.42 / 0.82	8.10 / 6.91	7.8 M	The ultra-lightweight Telugu recognition model trained based on the PP-OCRv3 recognition model supports the recognition of Telugu and numbers.
ka_PP-OCRv3_mobile_rec	Inference Model/Training Model	96.96	5.25 / 0.79	9.09 / 3.86	8.0 M	The ultra-lightweight Kannada recognition model trained based on the PP-OCRv3 recognition model supports the recognition of Kannada and numbers.
ta_PP-OCRv3_mobile_rec	Inference Model/Training Model	76.83	5.23 / 0.75	10.13 / 4.30	8.0 M	The ultra-lightweight Tamil recognition model trained based on the PP-OCRv3 recognition model supports the recognition of Tamil and numbers.
latin_PP-OCRv3_mobile_rec	Inference Model/Training Model	76.93	5.20 / 0.79	8.83 / 7.15	7.8 M	The ultra-lightweight Latin recognition model trained based on the PP-OCRv3 recognition model supports the recognition of Latin script and numbers.
arabic_PP-OCRv3_mobile_rec	Inference Model/Training Model	73.55	5.35 / 0.79	8.80 / 4.56	7.8 M	The ultra-lightweight Arabic script recognition model trained based on the PP-OCRv3 recognition model supports the recognition of Arabic script and numbers.
cyrillic_PP-OCRv3_mobile_rec	Inference Model/Training Model	94.28	5.23 / 0.76	8.89 / 3.88	7.9 M	The ultra-lightweight cyrillic alphabet recognition model trained based on the PP-OCRv3 recognition model supports the recognition of cyrillic letters and numbers.
devanagari_PP-OCRv3_mobile_rec	Inference Model/Training Model	96.44	5.22 / 0.79	8.56 / 4.06	7.9 M	The ultra-lightweight Devanagari script recognition model trained based on the PP-OCRv3 recognition model supports the recognition of Devanagari script and numbers.

Text Line Orientation Classification Module (Optional):

Model	Model Download Link	Top-1 Acc (%)	GPU Inference Time (ms) [Normal Mode / High-Performance Mode]	CPU Inference Time (ms) [Normal Mode / High-Performance Mode]	Model Storage Size (M)	Introduction
PP-LCNet_x0_25_textline_ori	Inference Model/ Training Model	95.54	-	-	0.32	A text line orientation classification model based on PP-LCNet_x0_25, with two categories: 0 degrees and 180 degrees.

Test Environment Description:

Performance Test Environment
Test Dataset:
- Text Image Rectification Model: DocUNet.
- Text Detection Model: A self-built Chinese dataset using PaddleOCR, covering multiple scenarios such as street scenes, web images, documents, and handwriting, with 500 images for detection.
- Chinese Recognition Model: A self-built Chinese dataset using PaddleOCR, covering multiple scenarios such as street scenes, web images, documents, and handwriting, with 11,000 images for text recognition.
- ch_SVTRv2_rec: Evaluation set A for "OCR End-to-End Recognition Task" in the PaddleOCR Algorithm Model Challenge.
- ch_RepSVTR_rec: Evaluation set B for "OCR End-to-End Recognition Task" in the PaddleOCR Algorithm Model Challenge.
- English Recognition Model: A self-built English dataset using PaddleX.
- Multilingual Recognition Model: A self-built multilingual dataset using PaddleX.
- Text Line Orientation Classification Model: A self-built dataset using PaddleX, covering various scenarios such as ID cards and documents, containing 1000 images.
Hardware Configuration:
- GPU: NVIDIA Tesla T4
- CPU: Intel Xeon Gold 6271C @ 2.60GHz
- Other Environments: Ubuntu 20.04 / cuDNN 8.6 / TensorRT 8.5.2.2
Inference Mode Description

Mode	GPU Configuration	CPU Configuration	Acceleration Technology Combination
Normal Mode	FP32 Precision / No TRT Acceleration	FP32 Precision / 8 Threads	PaddleInference
High-Performance Mode	Optimal combination of pre-selected precision types and acceleration strategies	FP32 Precision / 8 Threads	Pre-selected optimal backend (Paddle/OpenVINO/TRT, etc.)

2. Quick Start¶

All model pipelines provided by PaddleX can be quickly experienced. You can experience the effect of the general OCR pipeline on the community platform, or you can use the command line or Python locally to experience the effect of the general OCR pipeline.

2.1 Online Experience¶

You can experience the general OCR pipeline online by recognizing the demo images provided by the official platform, for example:

If you are satisfied with the performance of the pipeline, you can directly integrate and deploy it. You can choose to download the deployment package from the cloud, or refer to the methods in Section 2.2 Local Experience for local deployment. If you are not satisfied with the effect, you can fine-tune the models in the pipeline using your private data. If you have local hardware resources for training, you can start training directly on your local machine; if not, the Star River Zero-Code platform provides a one-click training service. You don't need to write any code—just upload your data and start the training task with one click.

2.2 Local Experience¶

❗ Before using the general OCR pipeline locally, please ensure that you have completed the installation of the PaddleX wheel package according to the PaddleX Installation Guide.

2.2.1 Command Line Experience¶

You can quickly experience the OCR pipeline with a single command. Use the test image, and replace --input with the local path for prediction.

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

For details on the relevant parameter descriptions, please refer to the parameter descriptions in 2.2.2 Python Script Integration.

After running, the results will be printed to the terminal as follows:

{'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)}}

The explanation of the running result parameters can refer to the result interpretation in 2.2.2 Python Script Integration.

The visualized results are saved under save_path, and the OCR visualization results are as follows:

2.2.2 Python Script Integration¶

The above command line is for quick experience and effect checking. Generally, in a project, integration through code is often required. You can complete the quick inference of the pipeline with just a few lines of code. The inference code is as follows:

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/")

In the above Python script, the following steps are executed:

(1) The OCR pipeline object is instantiated via create_pipeline(), with specific parameter descriptions as follows:

Parameter	Description	Type	Default Value
`pipeline`	The name of the pipeline or the path to the pipeline configuration file. If it is a pipeline name, it must be supported by PaddleX.	`str`	`None`
`config`	Specific configuration information for the pipeline (if set simultaneously with the `pipeline`, it takes precedence over the `pipeline`, and the pipeline name must match the `pipeline`).	`dict[str, Any]`	`None`
`device`	The device used for pipeline inference. It supports specifying specific GPU card numbers, such as "gpu:0", other hardware card numbers, such as "npu:0", or CPU, such as "cpu".	`str`	`gpu:0`
`use_hpip`	Whether to enable high-performance inference. This is only available if the pipeline supports high-performance inference.	`bool`	`False`

(2) The predict() method of the OCR pipeline object is called to perform inference. This method returns a generator. Below are the parameters and their descriptions for the predict() method:

Parameter	Description	Type	Options	Default Value
`input`	Data to be predicted, supports multiple input types (required).	`Python Var\|str\|list`	Python Var: Image data represented by `numpy.ndarray` str: Local path of an image file or PDF file, e.g., `/root/data/img.jpg`; URL link, e.g., network URL of an image file or PDF file: example; local directory, which must contain images to be predicted, e.g., `/root/data/` (prediction of PDF files in directories is currently not supported; PDF files must specify the exact file path) List: Elements of the list must be of the above types, e.g., `[numpy.ndarray, numpy.ndarray]`, `["/root/data/img1.jpg", "/root/data/img2.jpg"]`, `["/root/data1", "/root/data2"]`	`None`
`device`	The device used for inference.	`str\|None`	CPU: Use CPU for inference, e.g., `cpu` GPU: Use the first GPU for inference, e.g., `gpu:0` NPU: Use the first NPU for inference, e.g., `npu:0` XPU: Use the first XPU for inference, e.g., `xpu:0` MLU: Use the first MLU for inference, e.g., `mlu:0` DCU: Use the first DCU for inference, e.g., `dcu:0` None: If set to `None`, the default value from the pipeline initialization will be used. During initialization, the local GPU 0 will be used if available; otherwise, the CPU will be used.	`None`
`use_doc_orientation_classify`	Whether to use the document orientation classification module.	`bool\|None`	bool: `True` or `False` None: If set to `None`, the default value from the pipeline initialization will be used, which is `True`	`None`
`use_doc_unwarping`	Whether to use the document unwarping module.	`bool\|None`	bool: `True` or `False` None: If set to `None`, the default value from the pipeline initialization will be used, which is `True`	`None`
`use_textline_orientation`	Whether to use the text line orientation classification module.	`bool\|None`	bool: `True` or `False` None: If set to `None`, the default value from the pipeline initialization will be used, which is `True`	`None`
`text_det_limit_side_len`	The limit on the side length of the image for text detection.	`int\|None`	int: Any integer greater than `0` None: If set to `None`, the default value from the pipeline initialization will be used, which is `960`	`None`
`text_det_limit_type`	The type of limit on the side length of the image for text detection.	`str\|None`	str: Supports `min` and `max`. `min` ensures that the shortest side of the image is not less than `det_limit_side_len`, while `max` ensures that the longest side is not greater than `limit_side_len` None: If set to `None`, the default value from the pipeline initialization will be used, which is `max`	`None`
`text_det_thresh`	The detection pixel threshold. Pixels with scores greater than this threshold in the output probability map will be considered as text pixels.	`float\|None`	float: Any floating-point number greater than `0` None: If set to `None`, the default value from the pipeline initialization will be used, which is `0.3`	`None`
`text_det_box_thresh`	The detection box threshold. A detection result will be considered as a text region if the average score of all pixels within the bounding box is greater than this threshold.	`float\|None`	float: Any floating-point number greater than `0` None: If set to `None`, the default value from the pipeline initialization will be used, which is `0.6`	`None`
`text_det_unclip_ratio`	The text detection expansion ratio. The larger this value, the larger the expanded area.	`float\|None`	float: Any floating-point number greater than `0` None: If set to `None`, the default value from the pipeline initialization will be used, which is `2.0`	`None`
`text_rec_score_thresh`	The text recognition score threshold. Text results with scores greater than this threshold will be retained.	`float\|None`	float: Any floating-point number greater than `0` None: If set to `None`, the default value from the pipeline initialization will be used, which is `0.0` (i.e., no threshold)	`None`

(3) Process the prediction results. The prediction result for each sample is of type dict, and supports operations such as printing, saving as an image, and saving as a json file:

Method	Description	Parameter	Parameter Type	Parameter Description	Default Value
`print()`	Print the result to the terminal	`format_json`	`bool`	Whether to format the output content using `JSON` indentation	`True`
		`indent`	`int`	Specify the indentation level to beautify the output `JSON` data, making it more readable. This is only effective when `format_json` is `True`	4
		`ensure_ascii`	`bool`	Control whether non-`ASCII` characters are escaped to `Unicode`. When set to `True`, all non-`ASCII` characters will be escaped; `False` retains the original characters. This is only effective when `format_json` is `True`	`False`
`save_to_json()`	Save the result as a JSON file	`save_path`	`str`	The file path for saving. When a directory is specified, the saved file name will match the input file name	None
		`indent`	`int`	Specify the indentation level to beautify the output `JSON` data, making it more readable. This is only effective when `format_json` is `True`	4
		`ensure_ascii`	`bool`	Control whether non-`ASCII` characters are escaped to `Unicode`. When set to `True`, all non-`ASCII` characters will be escaped; `False` retains the original characters. This is only effective when `format_json` is `True`	`False`
`save_to_img()`	Save the result as an image file	`save_path`	`str`	The file path for saving, supporting both directory and file paths	None

Calling the print() method will print the result to the terminal. The printed content is explained as follows:
- input_path: (str) The input path of the image to be predicted
- page_index: (Union[int, None]) If the input is a PDF file, this indicates the current page number of the PDF. Otherwise, it is None
- model_settings: (Dict[str, bool]) The model parameters required for the pipeline configuration
  - use_doc_preprocessor: (bool) Controls whether to enable the document preprocessing sub-line
  - use_textline_orientation: (bool) Controls whether to enable text line orientation classification
- doc_preprocessor_res: (Dict[str, Union[str, Dict[str, bool], int]]) The output result of the document preprocessing sub-line. This exists only when use_doc_preprocessor=True
  - input_path: (Union[str, None]) The image path accepted by the preprocessing sub-line. When the input is numpy.ndarray, it is saved as None
  - model_settings: (Dict) The model configuration parameters for the preprocessing sub-line
    - use_doc_orientation_classify: (bool) Controls whether to enable document orientation classification
    - use_doc_unwarping: (bool) Controls whether to enable document unwarping
  - angle: (int) The prediction result of document orientation classification. When enabled, it takes values [0,1,2,3], corresponding to [0°,90°,180°,270°]; when disabled, it is -1
- dt_polys: (List[numpy.ndarray]) A list of polygon boxes for text detection. Each detection box is represented by a numpy array of 4 vertex coordinates, with a shape of (4, 2) and data type int16
- dt_scores: (List[float]) A list of confidence scores for text detection boxes
- text_det_params: (Dict[str, Dict[str, int, float]]) The configuration parameters for the text detection module
  - limit_side_len: (int) The side length limit value for image preprocessing
  - limit_type: (str) The processing method for side length limits
  - thresh: (float) The confidence threshold for text pixel classification
  - box_thresh: (float) The confidence threshold for text detection boxes
  - unclip_ratio: (float) The expansion ratio for text detection boxes
  - text_type: (str) The type of text detection, currently fixed as "general"
- textline_orientation_angles: (List[int]) The prediction results for text line orientation classification. When enabled, it returns actual angle values (e.g., [0,0,1]); when disabled, it returns [-1,-1,-1]
- text_rec_score_thresh: (float) The filtering threshold for text recognition results
- rec_texts: (List[str]) A list of text recognition results, containing only texts with confidence scores above text_rec_score_thresh
- rec_scores: (List[float]) A list of confidence scores for text recognition, filtered by text_rec_score_thresh
- rec_polys: (List[numpy.ndarray]) A list of text detection boxes filtered by confidence score, in the same format as dt_polys
- rec_boxes: (numpy.ndarray) An array of rectangular bounding boxes for detection boxes, with a shape of (n, 4) and dtype int16. Each row represents the [x_min, y_min, x_max, y_max] coordinates of a rectangle, where (x_min, y_min) is the top-left corner and (x_max, y_max) is the bottom-right corner
Calling the save_to_json() method will save the above content to the specified save_path. If a directory is specified, the saved path will be save_path/{your_img_basename}_res.json. If a file is specified, it will be saved directly to that file. Since JSON files do not support saving numpy arrays, the numpy.array type will be converted to a list format.
Calling the save_to_img() method will save the visualization results to the specified save_path. If a directory is specified, the saved path will be save_path/{your_img_basename}_ocr_res_img.{your_img_extension}. If a file is specified, it will be saved directly to that file. (Since the pipeline usually contains multiple result images, it is not recommended to specify a specific file path directly, as multiple images will be overwritten and only the last image will be retained)
Additionally, it also supports obtaining the visualization image with results and the prediction results through attributes, as follows:

Attribute	Description
`json`	Get the prediction results in `json` format
`img`	Get the visualization image in `dict` format

The prediction results obtained through the json attribute are of type dict, and the content is consistent with the data saved by calling the save_to_json() method.
The prediction results returned by the img attribute are of type dict. The keys are ocr_res_img and preprocessed_img, and the corresponding values are two Image.Image objects: one for displaying the visualization image of OCR results, and the other for showing the visualization image of image preprocessing. If the image preprocessing sub-module is not used, the dictionary will only contain ocr_res_img.

Additionally, you can obtain the OCR pipeline configuration file and load the configuration file for prediction. You can execute the following command to save the results in my_path:

paddlex --get_pipeline_config OCR --save_path ./my_path

If you have obtained the configuration file, you can customize the configurations of the OCR pipeline. You just need to modify the pipeline parameter value in the create_pipeline method to the path of the pipeline configuration file. The example is as follows:

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/")

Note: The parameters in the configuration file are initialization parameters for the pipeline. If you want to change the general OCR pipeline initialization parameters, you can directly modify the parameters in the configuration file and load the configuration file for prediction. In addition, CLI prediction also supports passing in a configuration file, just specify the path of the configuration file with --pipeline.

3. Development Integration/Deployment¶

If the general OCR pipeline meets your requirements for inference speed and accuracy, you can proceed with development integration/deployment directly.

If you need to apply the general OCR pipeline directly in your Python project, you can refer to the example code in 2.2.2 Python Script Method.

In addition, PaddleX also provides three other deployment methods, which are detailed as follows:

🚀 High-Performance Inference: In actual production environments, many applications have strict performance requirements for deployment strategies, especially response speed, to ensure efficient system operation and smooth user experience. To this end, PaddleX provides a high-performance inference plugin, which aims to deeply optimize the performance of model inference and pre/post-processing, significantly speeding up the end-to-end process. For detailed high-performance inference procedures, please refer to the PaddleX High-Performance Inference Guide.

☁️ Serving: Serving is a common deployment strategy in real-world production environments. By encapsulating inference functions into services, clients can access these services via network requests to obtain inference results. PaddleX supports various solutions for serving pipelines. For detailed pipeline serving procedures, please refer to the PaddleX Pipeline Serving Guide.

Below are the API reference and multi-language service invocation examples for the basic serving solution:

API Reference

For the main operations provided by the service:

The HTTP request method is POST.
Both the request body and response body are JSON data (JSON objects).
When the request is processed successfully, the response status code is 200, and the attributes of the response body are as follows:

Name	Type	Meaning
`logId`	`string`	The UUID of the request.
`errorCode`	`integer`	Error code. Fixed as `0`.
`errorMsg`	`string`	Error message. Fixed as `"Success"`.
`result`	`object`	The result of the operation.

When the request is not processed successfully, the attributes of the response body are as follows:

Name	Type	Meaning
`logId`	`string`	The UUID of the request.
`errorCode`	`integer`	Error code. Same as the response status code.
`errorMsg`	`string`	Error message.

The main operations provided by the service are as follows:

infer

Obtain OCR results from images.

POST /ocr

The attributes of the request body are as follows:

Name	Type	Meaning	Required
`file`	`string`	The URL of an image or PDF file accessible by the server, or the Base64-encoded content of the file. For PDF files exceeding 10 pages, only the first 10 pages will be used.	Yes
`fileType`	`integer` \| `null`	The type of the file. `0` for PDF files, `1` for image files. If this attribute is missing, the file type will be inferred from the URL.	No
`useDocOrientationClassify`	`boolean` \| `null`	Refer to the `use_doc_orientation_classify` parameter description in the pipeline `predict` method.	No
`useDocUnwarping`	`boolean` \| `null`	Refer to the `use_doc_unwarping` parameter description in the pipeline `predict` method.	No
`useTextlineOrientation`	`boolean` \| `null`	Refer to the `use_textline_orientation` parameter description in the pipeline `predict` method.	No
`textDetLimitSideLen`	`integer` \| `null`	Refer to the `text_det_limit_side_len` parameter description in the pipeline `predict` method.	No
`textDetLimitType`	`string` \| `null`	Refer to the `text_det_limit_type` parameter description in the pipeline `predict` method.	No
`textDetThresh`	`number` \| `null`	Refer to the `text_det_thresh` parameter description in the pipeline `predict` method.	No
`textDetBoxThresh`	`number` \| `null`	Refer to the `text_det_box_thresh` parameter description in the pipeline `predict` method.	No
`textDetUnclipRatio`	`number` \| `null`	Refer to the `text_det_unclip_ratio` parameter description in the pipeline `predict` method.	No
`textRecScoreThresh`	`number` \| `null`	Refer to the `text_rec_score_thresh` parameter description in the pipeline `predict` method.	No

When the request is processed successfully, the response body has the following properties for result:

Name	Type	Description
`ocrResults`	`object`	OCR results. The array length is 1 (for image input) or the smaller of the document page count and 10 (for PDF input). For PDF input, each element in the array represents the processing result for each page of the PDF file.
`dataInfo`	`object`	Information about the input data.

Each element in ocrResults is an object with the following properties:

Name	Type	Description
`prunedResult`	`object`	The simplified version of the `res` field in the JSON representation generated by the `predict` method of the production object, with the `input_path` field removed.
`ocrImage`	`string` \| `null`	The OCR result image, which marks the detected text positions. The image is in JPEG format and encoded in Base64.
`docPreprocessingImage`	`string` \| `null`	The visualization result image. The image is in JPEG format and encoded in Base64.
`inputImage`	`string` \| `null`	The input image. The image is in JPEG format and encoded in Base64.

Multi-language Service Call Example

Python

import base64
import requests

API_URL = "http://localhost:8080/ocr"
file_path = "./demo.jpg"

with open(file_path, "rb") as file:
    file_bytes = file.read()
    file_data = base64.b64encode(file_bytes).decode("ascii")

payload = {"file": file_data, "fileType": 1}

response = requests.post(API_URL, json=payload)

assert response.status_code == 200
result = response.json()["result"]
for i, res in enumerate(result["ocrResults"]):
    print(res["prunedResult"])
    ocr_img_path = f"ocr_{i}.jpg"
    with open(ocr_img_path, "wb") as f:
        f.write(base64.b64decode(res["ocrImage"]))
    print(f"Output image saved at {ocr_img_path}")

📱 Edge Deployment: Edge deployment is a method of placing computing and data processing capabilities directly on user devices, allowing them to process data locally without relying on remote servers. PaddleX supports deploying models on edge devices such as Android. For detailed instructions, please refer to the PaddleX Edge Deployment Guide. You can choose the appropriate deployment method based on your needs to integrate the model pipeline into your AI applications.

4. Secondary Development¶

If the default model weights provided by the General OCR pipeline do not meet your requirements in terms of accuracy or speed, you can attempt to fine-tune the existing models using your own domain-specific or application-specific data to improve the recognition performance of the General OCR pipeline in your scenario.

4.1 Model Fine-Tuning¶

Since the General OCR pipeline consists of several modules, the unsatisfactory performance of the pipeline may originate from any one of these modules. You can analyze the images with poor recognition results to identify which module is problematic and refer to the corresponding fine-tuning tutorial links in the table below for model fine-tuning.

Scenario	Fine-Tuning Module	Fine-Tuning Reference Link
Text is missed in detection	Text Detection Module	Link
Text content is inaccurate	Text Recognition Module	Link
Vertical or rotated text line correction is inaccurate	Text Line Orientation Classification Module	Link
Whole-image rotation correction is inaccurate	Document Image Orientation Classification Module	Link
Image distortion correction is inaccurate	Text Image Correction Module	Fine-tuning not supported yet

4.2 Model Application¶

After fine-tuning with your private dataset, you will obtain the local model weight files.

If you need to use the fine-tuned model weights, simply modify the pipeline configuration file by replacing the local paths of the fine-tuned model weights into the corresponding positions in the configuration file:

SubPipelines:
  DocPreprocessor:
    ...
    SubModules:
      DocOrientationClassify:
        module_name: doc_text_orientation
        model_name: PP-LCNet_x1_0_doc_ori
        model_dir: null # Replace with the path to the fine-tuned document image orientation classification model weights.
    ...

SubModules:
  TextDetection:
    module_name: text_detection
    model_name: PP-OCRv4_mobile_det
    model_dir: null # Replace with the path to the fine-tuned text detection model weights.
    ...
  TextLineOrientation:
    module_name: textline_orientation
    model_name: PP-LCNet_x0_25_textline_ori
    model_dir: null  # Replace with the path to the fine-tuned textline orientation classification model weights.
    batch_size: 1
  TextRecognition:
    module_name: text_recognition
    model_name: PP-OCRv4_mobile_rec
    model_dir: null  # Replace with the path to the fine-tuned text recognition model weights.
    batch_size: 1

Subsequently, refer to the command-line or Python script methods in 2.2 Local Experience to load the modified pipeline configuration file.

5. Multi-Hardware Support¶

PaddleX supports a variety of mainstream hardware devices, including NVIDIA GPUs, Kunlunxin XPUs, Ascend NPUs, and Cambricon MLUs. Simply modify the --device parameter to seamlessly switch between different hardware devices.

For example, if you are using an NVIDIA GPU for OCR pipeline inference, the Python command is:

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

Of course, you can also specify the hardware device when calling create_pipeline() or predict() in a Python script.

If you want to use the General OCR pipeline on more types of hardware, please refer to the PaddleX Multi-Hardware Usage Guide.