PaddleOCR/main/en/version3.x/module_usage/text_recognition

[giscus[bot]]

PaddleOCR/main/en/version3.x/module_usage/text_recognition

Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80+ languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)

https://paddlepaddle.github.io/PaddleOCR/main/en/version3.x/module_usage/text_recognition.html

[DragonPow]

I want training model with new language, have a tutorial step-by-step to do it?

[liuhongen1234567]

Hello, you can refer to the OCR data preparation documentation to annotate data in the new language, and then refer to the text recognition documentation for training, evaluation, and export.

[liuhongen1234567]

Alternatively, if you already have cropped recognition images and recognition labels and do not plan to train the text detection module, you can refer to this document to prepare the recognition data.

[pluszerominus]

Good afternoon, I have completed the PP-OCRv4_server_rec model, exported it to the inference format, and when trying to use the model through the python API (PaddleOCR method), the error "AssertionError: Model name mismatch, please input the correct model dir.." Why can such an error occur? The PP-OCRv4_server_rec model is specified in the yml configuration files.

[liuhongen1234567]

Hello, this is because the default model for PaddleOCR 3.0 is PP-OCRv5_server_rec. For other models, in addition to modifying text_recognition_model_dir, you also need to modify text_recognition_model_name. The correct code is as follows:

from paddleocr import PaddleOCR

ocr = PaddleOCR(
     text_recognition_model_name="PP-OCRv4_server_rec",
     text_recognition_model_dir="export_model_path",
     use_doc_orientation_classify=False,
     use_doc_unwarping=False,
     use_textline_orientation=False,
 ) 
result = ocr.predict("./general_ocr_002.png")
for res in result:
    res.print()
    res.save_to_img("output")
    res.save_to_json("output")

[pluszerominus]

Thanks a lot, it worked

[tieupham-ltp]

Hello, I have trained with my dataset and my custom dictionary file, specifically vi_dict in PP-OCRv5_server_rec, but I couldn't find a way to pass the path to my dictionary file during prediction, like the rec_char_dict_path parameter in OCRv4. How can I use my dictionary file for prediction?
Thank you.

[liuhongen1234567]

Hello, this is a new feature of PaddleOCR 3.0. The dictionary used during training is now stored in the inference.yaml file of the exported model. Therefore, during inference, it will be read from inference.yaml, and there’s no need to set it separately anymore.

[zhangyubo0722]

PaddleOCR 3.1 has been released, featuring the new PP-OCRv5 multilingual text recognition model. It supports 37 languages including French, Spanish, Portuguese, Russian, Korean, and more, achieving an average recognition accuracy improvement of over 30%. Welcome to try it out!

[liuhongen1234567]

Hello, the training data for PaddleOCR is internal and will not be publicly available. If you need to use it, you can upload the data to the OCR no-code pipeline in AI Studio , where there is a fusion factor parameter that allows for training by mixing original data.   鸿飞万里 ***@***.***  

…

------------------ 原始邮件 ------------------ 发件人: "Albert Nathanael ***@***.***>; 发送时间: 2025年7月16日(星期三) 中午11:11 收件人: ***@***.***>; 抄送: ***@***.***>; ***@***.***>; 主题: Re: [PaddlePaddle/PaddleOCR] PaddleOCR/main/en/version3.x/module_usage/text_recognition (Discussion #15712) Hi PaddleOCR team, I want to fine-tune the PP-OCRv5 mobile recognition model with my own scanned document dataset. Is the original training data list (e.g., train_data.txt and images/labels) for PP-OCRv5 mobile-rec publicly available? If not, can you recommend public datasets similar to the ones you used for the Latin (English/Indonesian) model? Thank you! — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you commented.Message ID: ***@***.***>

[Diversi0n]

Hello, thanks for the clarification!

I’m new to PaddleOCR and very interested in fine-tuning the PP-OCRv5 mobile model using my own document dataset. Could you kindly share a tutorial on how to train using AI Studio no-code pipeline with the fusion factor? I’d like to make sure the model’s original knowledge is preserved and strengthened by my data.

Appreciate your help!

[Le-Bao-181003]

I’m currently fine-tuning the PP-OCRv5_mobile_rec model on a custom Japanese dataset that includes both handwritten and printed text. I followed the official PaddleOCR pipeline for training and successfully exported the inference model, which generated the following files in my output folder:
inference/
├── inference.pdiparams
├── inference.pdmodel
├── inference.yml

I then attempted to load this fine-tuned model using the following code:

import cv2
from paddleocr import PaddleOCR
import time

recognition_model = 'PP-OCRv5_mobile_rec_finetune_infer'

ocr = PaddleOCR(
    text_detection_model_name="PP-OCRv5_mobile_det",
    text_recognition_model_name="PP-OCRv5_server_rec",
    text_recognition_model_dir=recognition_model,
)

img_path = "images/crop/Screenshot_2025-07-03_crop_6.jpg"
result = ocr.predict(img_path)

However, I encountered the following error:

ValueError: (InvalidArgument) Type of attribute: strides is not right.
[Hint: Expected attributes.at("strides").dyn_cast<pir::ArrayAttribute>().at(i).isa<pir::Int32Attribute>() == true, but received attributes.at("strides").dyn_cast<pir::ArrayAttribute>().at(i).isa<pir::Int32Attribute>():0 != true:1.] (at paddle\fluid\pir\dialect\operator\ir\pd_op3.cc:24692)

Interestingly, if I replace the model folder with the official inference_model (e.g., the original downloaded version), it works fine.

Could you please advise what might be causing this issue? Is there any incompatibility between the export format and the runtime, or any specific config I need to adjust after fine-tuning?
Thank you so much for your help!

[liuhongen1234567]

Hello, could you provide more details about the environment, for example, the versions of PaddlePaddle, PaddleOCR, and PaddleX?

[hocnt0]

You should re-check the version of the PaddlePaddle library. In my case, I had this error when training with PaddlePaddle version 3.2.2, but I was running the fine-tuned model with version 3.0.0. After updating the Paddle library, the error was gone. I hope this helps someone who encounters this error.

[budian92]

文字识别示例代码中output = model.predict(input="general_ocr_rec_001.png", batch_size=1) 没有关于文本框参数的，需要将det模块识别的文本框结果作为参数传入，参数列表没有这个文本框参数，不知道如何传入

[liuhongen1234567]

您好，这里返回的output是个生成器，需要 for循环遍历才会执行，这里 dt_polys 就是文本框的参数。

示例代码如下：

from paddleocr import TextDetection
model = TextDetection(model_name="PP-OCRv5_server_det")
output = model.predict("general_ocr_001.png", batch_size=1)
for res in output:
    bbox = res["dt_polys"]

[budian92]

这里可能我没表述清楚，现在我先通过TextDetection模块进行文字区域检测，获取对应的dt_polys,会针对dt_polys做些人工检验过滤一些异常后，将dt_polys作为参数传入给TextRecognition进行文字内容识别，这一步文档没说明如何将dt_polys传参给TextRecognition，我试了model = TextDetection(model_name="PP-OCRv5_server_det")
output = model.predict("general_ocr_001.png", batch_size=1，dt_polys=xxxx)，或报错，显示predict无dt_polys参数，这里不清楚如何传参，我需要将文字检测和文字识别作为两步分别处理

[budian92]

上面最后描述打错了：我试了model = TextDetection(model_name="PP-OCRv5_server_det")
output = model.predict("general_ocr_001.png", batch_size=1，dt_polys=xxxx)打错了，应该是model = TextRecognition(model_name="PP-OCRv5_server_det"),在文字识别时不知道如何传参已获取的dt_polys进行文字框内文字内容识别

[liuhongen1234567]

您好，目前文本识别模型不支持直接传入坐标，可以根据 dt_polys 从原始图像中裁剪出 识别区域，再通过input参数直接将识别图片传进去，目前OCR产线也是这么实现的。具体逻辑可以参考 https://github.com/PaddlePaddle/PaddleX/blob/a8ec0bdec40d4108859ebda48e079d2fdcfb5b82/paddlex/inference/pipelines/ocr/pipeline.py#L280

[NikitinaMaria]

Hello. I have trained PP-OCRv5_mobile_rec with my dataset and my custom dictionary file. Then I exported the model using:

python tools/export_model.py -c configs/rec/rec_new.yml \
-o Global.pretrained_model=output/rec_new_v1/latest \
Global.save_inference_dir=output/rec_new_inference \
Global.inference_model=True

But the recognition result differs between uses predict_rec.py and python API:

python3 tools/infer/predict_rec.py --image_dir={img_path} --rec_model_dir=output/rec_new_inference --rec_char_dict_path=new_dict.txt

And

from paddleocr import PaddleOCR

ocr = PaddleOCR(
    text_recognition_model_name="PP-OCRv5_mobile_rec",
    text_recognition_model_dir="rec_new_inference",
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
)
result = ocr.predict(img)

Can you tell me what could have caused this problem?

[liuhongen1234567]

Hello, predict_rec.py is solely for text recognition, while PaddleOCR performs detection first followed by recognition, serving as an end-to-end pipeline. predict_rec.py should correspond to the text recognition module. You can refer to the documentation for more information. https://www.paddleocr.ai/latest/en/version3.x/module_usage/text_recognition.html

[karanpate1]

I fine-tuned the PP-OCRV5 on my custom dataset (containing English alphabets, numerals, and a few symbols).
-> I got a training accuracy of 98% and validation accuracy of 99%.
But I have an issue: when I ran the inference using my fine-tuned model, I am getting shitty results (even on images passed in the training and validation dataset).
-> Can you explain what could be a probable reason?
->i followed all the steps like evaluation and model export as documentation

[karanpate1]

i also ran the inference using exported inference model and also run inference using the tools/infer_rec.py (to check if any thing bad with my model export) but both were struggling with same problem

i dont know how the model was showing 99% accuracy (on training 98%)
with tools/eval.py on my validation data

[karanpate1]

Issue: High Validation Accuracy but Garbage Inference in PP-OCRv5 (Solved)

I fine-tuned PP-OCRv5 on a custom dataset (English alphabets, numerals, and some symbols).

• Training accuracy: 98%
• Validation accuracy: 99%

But when I ran inference (even on images from training/validation sets), the predictions were totally wrong.

I double-checked everything:

• Followed official finetuning + export steps
• Tested with both tools/infer_rec.py and exported inference model
• Same problem: terrible results

At this point, I was stuck because evaluation showed 99% accuracy, but inference was useless.

---

Root Cause

Turns out the problem was due to mismatch in image preprocessing between training and inference.

In my training config PP-OCRv5_mobile_rec.yml:

sampler:
  name: MultiScaleSampler
  scales: [[320, 32], [320, 48], [320, 64]]

So during training, images were dynamically resized to 3 different shapes:

• 3×32×320
• 3×48×320
• 3×64×320

But in my exported inference.yml, the preprocessing looked like this:

PreProcess:
  transform_ops:
  - DecodeImage:
      channel_first: false
      img_mode: BGR
  - MultiLabelEncode:
      gtc_encode: NRTRLabelEncode
  - RecResizeImg:
      image_shape:
      - 3
      - 48
      - 320

Notice the mismatch?

• Training: random multi-scale (32, 48, 64 heights)
• Inference: fixed to 48 height only

That mismatch caused the network to completely fail at inference.

---

✅ Fix

I manually adjusted the inference.yml to try different scales from training.

• With 3×48×320, results were trash.
• With 3×64×320, also trash.
• With 3×32×320, predictions became perfect, matching my training/validation accuracy.

So the fix was:
Set RecResizeImg.image_shape in inference.yml to the same shape(s) used in training.

Final fix:

PreProcess:
  transform_ops:
  - DecodeImage:
      channel_first: false
      img_mode: BGR
  - MultiLabelEncode:
      gtc_encode: NRTRLabelEncode
  - RecResizeImg:
      image_shape:
      - 3
      - 32
      - 320

---

Takeaway

If you’re fine-tuning PP-OCR models with MultiScaleSampler, make sure your inference preprocessing matches your training scales. Otherwise, you’ll see high validation accuracy but garbage results at inference.

---

This should save people from wasting days like I did. 🙃

[liuhongen1234567]

Hello, thank you for your valuable experience. If it's just to test the recognition effect, you should actually use the text recognition module. Using the OCR production line might lead to lower metrics due to the poor performance of PP-OCRv5 in detecting and cropping text areas. Here is a sample code:

from paddleocr import TextRecognition
model = TextRecognition(model_name="PP-OCRv5_server_rec"，model_dir=XXX)
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")

[binhere]

Hi @karanpate1, thank you for your solution. However, I have a couple of questions:

1. When evaluating, how do you set the RecResizeImg? Do you use MultiScaleSampler when evaluating? I see that the default Eval RecResizeImg in the configuration and the PreProcess.RecResizeImg.image_shape in inference.yml are both set to [3, 48, 320]. Because you said your evaluation performance is very high, but the inference is not good.
2. I am training with Vietnamese texts (like English, still have spaces between individual words). Do you include the space " " in the dictionary? And how you configure to predict spaces, in my case, Global.use_space_char: true and Metric.ignore_space: False, right?
3. May I ask you about how you set max_text_length for text having over 25 characters? any followed corresponding setting, such as Global.d2s_train_image_shape, Train.RecConAug.image_shape and Eval.RecResizeImg.image_shape?

[karanpate1]

Hi @karanpate1, thank you for your solution. However, I have a couple of questions:

1. When evaluating, how do you set the RecResizeImg? Do you use MultiScaleSampler when evaluating? I see that the default Eval RecResizeImg in the configuration and the PreProcess.RecResizeImg.image_shape in inference.yml are both set to [3, 48, 320]. Because you said your evaluation performance is very high, but the inference is not good.
2. I am training with Vietnamese texts (like English, still have spaces between individual words). Do you include the space " " in the dictionary? And how you configure to predict spaces, in my case, Global.use_space_char: true and Metric.ignore_space: False, right?
3. May I ask you about how you set max_text_length for text having over 25 characters? any followed corresponding setting, such as Global.d2s_train_image_shape, Train.RecConAug.image_shape and Eval.RecResizeImg.image_shape?

Hi @binhere, thanks for your questions! Here are my answers:

1. During training , the input dimensions were selected dynamically using the MultiScaleSampler — it sampled from three possible shapes:
   3×32×320, 3×48×320, and 3×64×320.
   However, in inference.yml, the RecResizeImg was hardcoded to 3×48×320.
   That mismatch was the reason my exported model gave poor results during inference.
   Once I changed it to 3×32×320, the predictions improved significantly.

   I’m still not sure why evaluation with 3×48×320 worked fine while inference didn’t, but that dimension mismatch was definitely the key issue.

2. Yes, I included spaces in my dictionary.
   Configuration used:

   Global.use_space_char: true
   Metric.ignore_space: false

3. In my case, the text length was quite short, so I didn’t face issues with long text (25+ characters). I didn’t modify any related parameters like max_text_length, Global.d2s_train_image_shape, or RecConAug.image_shape.

I’ve attached txt format of both my PP-OCRv5_server_rec.yml and inference.yml files here for your reference.
inference.txt
PP-OCRv5_server_rec.txt

[binhere]

Hi, I am training a rec model on a new language, but I had a bug. I already change example dataset from paddleocr's document but the same issue still happens:

!python -m paddle.distributed.launch --gpus '0,1' tools/train.py -c /kaggle/working/custom_config.yml
-o Global.pretrained_model=/kaggle/working/en_PP-OCRv5_mobile_rec_pretrained.pdparams

LAUNCH INFO 2025-10-06 09:59:42,584 ------------------------- ERROR LOG DETAIL ------------------------- not matched with loaded params head.gtc_head.tgt_word_prj.weight [384, 442] ! [2025/10/06 09:59:22] ppocr INFO: load pretrain successful from /kaggle/working/en_PP-OCRv5_mobile_rec_pretrained [2025/10/06 09:59:22] ppocr INFO: During the training process, after the 0th iteration, an evaluation is run every 1000 iterations Traceback (most recent call last): File "/kaggle/working/PaddleOCR/tools/train.py", line 272, in <module> main(config, device, logger, vdl_writer, seed) File "/kaggle/working/PaddleOCR/tools/train.py", line 225, in main program.train( File "/kaggle/working/PaddleOCR/tools/program.py", line 356, in train preds = model(images, data=batch[1:]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/usr/local/lib/python3.11/dist-packages/paddle/nn/layer/layers.py", line 1571, in __call__ return self.forward(*inputs, **kwargs) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/usr/local/lib/python3.11/dist-packages/paddle/distributed/parallel.py", line 570, in forward outputs = self._layers(*inputs, **kwargs) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/usr/local/lib/python3.11/dist-packages/paddle/nn/layer/layers.py", line 1571, in __call__ return self.forward(*inputs, **kwargs) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/kaggle/working/PaddleOCR/ppocr/modeling/architectures/base_model.py", line 85, in forward x = self.backbone(x) ^^^^^^^^^^^^^^^^ File "/usr/local/lib/python3.11/dist-packages/paddle/nn/layer/layers.py", line 1571, in __call__ return self.forward(*inputs, **kwargs) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/kaggle/working/PaddleOCR/ppocr/modeling/backbones/rec_lcnetv3.py", line 544, in forward x = self.blocks6(x) ^^^^^^^^^^^^^^^ File "/usr/local/lib/python3.11/dist-packages/paddle/nn/layer/layers.py", line 1571, in __call__ return self.forward(*inputs, **kwargs) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/usr/local/lib/python3.11/dist-packages/paddle/nn/layer/container.py", line 760, in forward input = layer(input) ^^^^^^^^^^^^ File "/usr/local/lib/python3.11/dist-packages/paddle/nn/layer/layers.py", line 1571, in __call__ return self.forward(*inputs, **kwargs) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/kaggle/working/PaddleOCR/ppocr/modeling/backbones/rec_lcnetv3.py", line 390, in forward x = self.pw_conv(x) ^^^^^^^^^^^^^^^ File "/usr/local/lib/python3.11/dist-packages/paddle/nn/layer/layers.py", line 1571, in __call__ return self.forward(*inputs, **kwargs) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/kaggle/working/PaddleOCR/ppocr/modeling/backbones/rec_lcnetv3.py", line 223, in forward out += self.identity(x) TypeError: unsupported operand type(s) for +=: 'int' and 'Tensor' I1006 09:59:41.251125 1466 process_group_nccl.cc:159] ProcessGroupNCCL destruct I1006 09:59:41.450891 1490 tcp_store.cc:292] receive shutdown event and so quit from MasterDaemon run loop LAUNCH INFO 2025-10-06 09:59:42,585 Exit code 1

I followed the GitHub PaddleOCR documents and it says that PaddleOCR source Github v3.2.0 supports PaddlePaddle 3.1.0

I am using Kaggle with the following environments:

!nvidia-smi
NVIDIA-SMI 560.35.03 Driver Version: 560.35.03 CUDA Version: 12.6

!pip install paddlepaddle-gpu==3.1.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/

!git clone -b release/3.2 --single-branch https://github.com/PaddlePaddle/PaddleOCR.git

For training only, I did not `pip install paddleocr==3.2.0. Just clone the source from GitHub only.
My notebook can be found here

I wonder what the most stable version is for training? Are there any solutions for this? Has anyone else met the same issue?

[introvert-rgb]

Hey Hi, This is Anup,
I'm trying finetune PPOCRv5 mobile but I'm not able to find the pretrained model which can be finetuned on my custom dataset. I tried to download it from this site but it gave only inference models and files which gave an error pdparams file not found. Please help me with pretrained model.
Thanks in advance.

[chenxz11]

https://paddlepaddle.github.io/PaddleX/3.2/support_list/models_list.html#_19

[AhSem]

Two questions:

1. Is it possible to differentiate hand-written text from printed text in an image?
2. Is it possible to check font inconsistency? For example, I'm expecting certain kind of font for the text in image, but if I see a different kind of font, PaddleOCR is able to tell it (perhaps by giving a score) ?

[AlifAbdulRauf]

hi @karanpati1, @binhere i want to ask about the same space problem. my finetuning model can't recognize any word that have a space. So any space will be deleted by the model. For example: Quick Start become QuickStart. Thank you

[AlifAbdulRauf]

@karanpate1. Wrong tag

[diasiz1]

Hello. I wanted to fine tune cyrillic rec mobile model in Kaggle. I cloned git repo, installed training dependencies. I used 2 x T4. Also, Ichanged dirs in .yaml config file, and made my custom dict.txt with fewer characters (included my language characters and special signs).

To train, I used this cli command:

!python3 -m paddle.distributed.launch --gpus '0,1'  tools/train.py -c /kaggle/input/config/cyrillic_PP-OCRv5_mobile_rec.yaml \
        -o Global.pretrained_model=/kaggle/working/PaddleOCR/cyrillic_PP-OCRv5_mobile_rec_pretrained.pdparams

In logs I noticed this kind of warning.

[2026/02/04 07:15:56] ppocr WARNING: The shape of model params head.ctc_head.fc.weight [120, 164] not matched with loaded params head.ctc_head.fc.weight [120, 852] !
[2026/02/04 07:15:56] ppocr WARNING: The shape of model params head.ctc_head.fc.bias [164] not matched with loaded params head.ctc_head.fc.bias [852] !
[2026/02/04 07:15:56] ppocr WARNING: The shape of model params head.gtc_head.embedding.embedding.weight [168, 384] not matched with loaded params head.gtc_head.embedding.embedding.weight [856, 384] !
[2026/02/04 07:15:56] ppocr WARNING: The shape of model params head.gtc_head.tgt_word_prj.weight [384, 168] not matched with loaded params head.gtc_head.tgt_word_prj.weight [384, 856] !

And this summary message

----------------------
Error Message Summary:
----------------------
ResourceExhaustedError: 

Out of memory error on GPU 0. Cannot allocate 37.500000MB memory on GPU 0, 14.539917GB memory has been allocated and available memory is only 23.812500MB.

Can someone explain me what I did wrong? What I need to do? Thanks.

[diasiz1]

I solved the problem. It was a too big batch size for T4 gpu.