diff --git a/docs/ppocr/model_train/recognition.en.md b/docs/ppocr/model_train/recognition.en.md index bc630575ae..4918faf879 100644 --- a/docs/ppocr/model_train/recognition.en.md +++ b/docs/ppocr/model_train/recognition.en.md @@ -5,13 +5,89 @@ typora-copy-images-to: images # Text Recognition +This article provides a comprehensive guide for the PaddleOCR text recognition task, covering the entire workflow including data preparation, model training, fine-tuning, evaluation, and prediction, with detailed explanations for each phase. + ## 1. Data Preparation -### 1.1 DataSet Preparation +### 1.1. Prepare the Dataset + +PaddleOCR supports two data formats: + +- `lmdb`: Used for training with datasets stored in LMDB format (LMDBDataSet); +- `General Data`: Used for training with datasets stored in text files (SimpleDataSet); + +The default storage path for training data is `PaddleOCR/train_data`. If you already have a dataset on your disk, simply create a symbolic link to the dataset directory: + +```bash +# Linux and macOS +ln -sf /train_data/dataset +# Windows +mklink /d /train_data/dataset +``` + +### 1.2. Custom Dataset + +Here, we will use a general dataset as an example to explain how to prepare the dataset: + +- Training Dataset -To prepare datasets, refer to [ocr_datasets](../../datasets/datasets.en.md) . +It is recommended to place the training images in the same folder and record the image paths and labels in a txt file (`rec_gt_train.txt`). The content of the txt file should be as follows: -PaddleOCR provides label files for training the icdar2015 dataset, which can be downloaded in the following ways: +**Note:** In the txt file, please use `\t` to separate the image path and the label. Using any other separator will cause errors during training. + +```text +" Image Filename Image Label " + +train_data/rec/train/word_001.jpg Simple and reliable +train_data/rec/train/word_002.jpg Making the complex world simpler with technology +... +``` + +The final structure of the training dataset should look like this: + +```text +|-train_data + |-rec + |- rec_gt_train.txt + |- train + |- word_001.png + |- word_002.jpg + |- word_003.jpg + | ... +``` + +In addition to the single-image-per-line format described above, PaddleOCR also supports training on data augmented offline. To avoid sampling the same sample multiple times in the same batch, we can list image paths with the same label on one line. During training, PaddleOCR will randomly select one image from the list. The corresponding format of the label file is as follows: + +```text +["11.jpg", "12.jpg"] Simple and reliable +["21.jpg", "22.jpg", "23.jpg"] Making the complex world simpler with technology +3.jpg ocr +``` + +In the above example, both "11.jpg" and "12.jpg" have the same label `Simple and reliable`. During training, one of these images will be randomly chosen for training. + +- Validation Dataset + +Similarly to the training dataset, the validation dataset should also provide a folder containing all the images (test) and a `rec_gt_test.txt` file. The structure of the validation dataset is as follows: + +```text +|-train_data + |-rec + |- rec_gt_test.txt + |- test + |- word_001.jpg + |- word_002.jpg + |- word_003.jpg + | ... +``` + +### 1.3. Data Download + +- ICDAR2015 + +If you don't have a dataset locally, you can download the [ICDAR2015](http://rrc.cvc.uab.es/?ch=4&com=downloads) dataset from the official website for quick testing. You can also refer to [DTRB](https://github.com/clovaai/deep-text-recognition-benchmark#download-lmdb-dataset-for-traininig-and-evaluation-from-here) to download the LMDB formatted dataset needed for benchmarking. + +If you're using the public ICDAR2015 dataset, PaddleOCR provides a label file for training the ICDAR2015 dataset. You can download it as follows: ```bash linenums="1" # Training set label @@ -32,14 +108,14 @@ The data format is as follows, (a) is the original picture, (b) is the Ground Tr ![img](./images/icdar_rec.png) -- Multilingual dataset +- Multilingual Datasets The multi-language model training method is the same as the Chinese model. The training data set is 100w synthetic data. A small amount of fonts and test data can be downloaded using the following two methods. - [Baidu Netdisk](https://pan.baidu.com/s/1bS_u207Rm7YbY33wOECKDA) ,Extraction code:frgi. - [Google drive](https://drive.google.com/file/d/18cSWX7wXSy4G0tbKJ0d9PuIaiwRLHpjA/view) -### 1.2 Dictionary +### 1.4. Dictionary Finally, a dictionary ({word_dict_name}.txt) needs to be provided so that when the model is trained, all the characters that appear can be mapped to the dictionary index. @@ -56,36 +132,28 @@ n In `word_dict.txt`, there is a single word in each line, which maps characters and numeric indexes together, e.g "and" will be mapped to [2 5 1] -PaddleOCR has built-in dictionaries, which can be used on demand. - -`ppocr/utils/ppocr_keys_v1.txt` is a Chinese dictionary with 6623 characters. - -`ppocr/utils/ic15_dict.txt` is an English dictionary with 36 characters - -`ppocr/utils/dict/french_dict.txt` is a French dictionary with 118 characters - -`ppocr/utils/dict/japan_dict.txt` is a Japanese dictionary with 4399 characters - -`ppocr/utils/dict/korean_dict.txt` is a Korean dictionary with 3636 characters - -`ppocr/utils/dict/german_dict.txt` is a German dictionary with 131 characters - -`ppocr/utils/en_dict.txt` is a English dictionary with 96 characters +PaddleOCR includes several built-in dictionaries that can be used as needed: -The current multi-language model is still in the demo stage and will continue to optimize the model and add languages. **You are very welcome to provide us with dictionaries and fonts in other languages**, -If you like, you can submit the dictionary file to [dict](../../ppocr/utils/dict) and we will thank you in the Repo. +- `ppocr/utils/ppocr_keys_v1.txt`: A Chinese dictionary containing 6623 characters. +- `ppocr/utils/ic15_dict.txt`: An English dictionary containing 36 characters. +- `ppocr/utils/dict/french_dict.txt`: A French dictionary containing 118 characters. +- `ppocr/utils/dict/japan_dict.txt`: A Japanese dictionary containing 4399 characters. +- `ppocr/utils/dict/korean_dict.txt`: A Korean dictionary containing 3636 characters. +- `ppocr/utils/dict/german_dict.txt`: A German dictionary containing 131 characters. +- `ppocr/utils/en_dict.txt`: An English dictionary containing 96 characters. -To customize the dict file, please modify the `character_dict_path` field in `configs/rec/rec_icdar15_train.yml` . +Currently, the multilingual models are still in the demo stage, and we are continuously improving the models and adding new languages. **We highly welcome you to provide dictionaries and fonts for other languages**. If you are willing, you can submit your dictionary files to the [dict](../../ppocr/utils/dict) directory, and we will credit you in the repo. +To customize the dict file, please modify the `character_dict_path` field in `configs/rec/rec_icdar15_train.yml`. -- Custom dictionary +- Custom Dictionary If you need to customize dic file, please add character_dict_path field in configs/rec/rec_icdar15_train.yml to point to your dictionary path. And set character_type to ch. -### 1.4 Add Space Category +### 1.5. Add Space Category -If you want to support the recognition of the `space` category, please set the `use_space_char` field in the yml file to `True`. +To support recognition of the "space" category, set the `use_space_char` field in the YAML file to `True`. -### 1.5 Data Augmentation +### 1.6. Data Augmentation PaddleOCR provides a variety of data augmentation methods. All the augmentation methods are enabled by default. @@ -93,11 +161,11 @@ The default perturbation methods are: cvtColor, blur, jitter, Gasuss noise, rand Each disturbance method is selected with a 40% probability during the training process. For specific code implementation, please refer to: [rec_img_aug.py](../../ppocr/data/imaug/rec_img_aug.py) -## 2.Training +## 2. Training -PaddleOCR provides training scripts, evaluation scripts, and prediction scripts. In this section, the CRNN recognition model will be used as an example: +PaddleOCR provides training scripts, evaluation scripts, and prediction scripts. This section will take the PP-OCRv3 English recognition model as an example: -### 2.1 Start Training +### 2.1. Start Training First download the pretrain model, you can download the trained model to finetune on the icdar2015 data: @@ -247,7 +315,7 @@ class MyBackbone(nn.Layer): return y ``` -3. Import the added module in the [ppocr/modeling/backbones/\__init\__.py](../../ppocr/modeling/backbones/__init__.py) file. +3. Import the added module in the [ppocr/modeling/backbones/\__init\__.py](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppocr/modeling/backbones/__init__.py) file. After adding the four-part modules of the network, you only need to configure them in the configuration file to use, such as: @@ -259,9 +327,9 @@ After adding the four-part modules of the network, you only need to configure th **NOTE**: More details about replace Backbone and other mudule can be found in [doc](../../algorithm/add_new_algorithm.en.md). -### 2.4 Mixed Precision Training +### 2.4. Mixed Precision Training -If you want to speed up your training further, you can use [Auto Mixed Precision Training](https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/01_paddle2.0_introduction/basic_concept/amp_cn.html), taking a single machine and a single gpu as an example, the commands are as follows: +If you want to speed up your training further, you can use [Auto Mixed Precision Training](https://www.paddlepaddle.org.cn/documentation/docs/en/guides/performance_improving/amp_en.html), taking a single machine and a single gpu as an example, the commands are as follows: ```bash linenums="1" python3 tools/train.py -c configs/rec/rec_icdar15_train.yml \ @@ -269,7 +337,7 @@ python3 tools/train.py -c configs/rec/rec_icdar15_train.yml \ Global.use_amp=True Global.scale_loss=1024.0 Global.use_dynamic_loss_scaling=True ``` -### 2.5 Distributed Training +### 2.5. Distributed Training During multi-machine multi-gpu training, use the `--ips` parameter to set the used machine IP address, and the `--gpus` parameter to set the used GPU ID: @@ -278,13 +346,16 @@ python3 -m paddle.distributed.launch --ips="xx.xx.xx.xx,xx.xx.xx.xx" --gpus '0,1 -o Global.pretrained_model=./pretrain_models/rec_mv3_none_bilstm_ctc_v2.0_train ``` -**Note:** (1) When using multi-machine and multi-gpu training, you need to replace the ips value in the above command with the address of your machine, and the machines need to be able to ping each other. (2) Training needs to be launched separately on multiple machines. The command to view the ip address of the machine is `ifconfig`. (3) For more details about the distributed training speedup ratio, please refer to [Distributed Training Tutorial](../blog/distributed_training.en.md). +**Note:** +1. When using multi-machine and multi-gpu training, you need to replace the ips value in the above command with the address of your machine, and the machines need to be able to ping each other. +2. Training needs to be launched separately on multiple machines. The command to view the ip address of the machine is `ifconfig`. +3. For more details about the distributed training speedup ratio, please refer to [Distributed Training Tutorial](../blog/distributed_training.en.md). -### 2.6 Training with Knowledge Distillation +### 2.6. Training with Knowledge Distillation Knowledge distillation is supported in PaddleOCR for text recognition training process. For more details, please refer to [doc](../model_compress/knowledge_distillation.en.md). -### 2.7 Multi-language Training +### 2.7. Multi-Language Model Training Currently, the multi-language algorithms supported by PaddleOCR are: @@ -358,7 +429,7 @@ In actual use, it is recommended to load the official pre-trained model and fine ## 3. Evaluation and Test -### 3.1 Evaluation +### 3.1. Evaluation The model parameters during training are saved in the `Global.save_model_dir` directory by default. When evaluating indicators, you need to set `Global.checkpoints` to point to the saved parameter file. The evaluation dataset can be set by modifying the `Eval.dataset.label_file_list` field in the `configs/rec/PP-OCRv3/en_PP-OCRv3_rec.yml` file. @@ -426,17 +497,19 @@ infer_img: doc/imgs_words/ch/word_1.jpg result: ('韩国小馆', 0.997218) ``` -## 4. Inference +### 4. Model Export and Prediction -The inference model (the model saved by `paddle.jit.save`) is generally a solidified model saved after the model training is completed, and is mostly used to give prediction in deployment. +**Inference Model** (saved using `paddle.jit.save`) -The model saved during the training process is the checkpoints model, which saves the parameters of the model and is mostly used to resume training. +The inference model is a "frozen" version of the model, where both the model structure and model parameters are saved in a file. It is typically used for prediction and deployment scenarios. +In contrast, the **checkpoint model** only saves the model's parameters and is mostly used for training resumption, etc. Compared to the checkpoint model, the inference model also includes the model structure information, which makes it more efficient for deployment, inference acceleration, and flexible integration with systems. -Compared with the checkpoints model, the inference model will additionally save the structural information of the model. Therefore, it is easier to deploy because the model structure and model parameters are already solidified in the inference model file, and is suitable for integration with actual systems. - -The recognition model is converted to the inference model in the same way as the detection, as follows: +The process of converting a recognition model to an inference model is similar to the detection model conversion, as shown below: ```bash linenums="1" +# Enable old IR mode +export FLAGS_enable_pir_api=0 + # -c Set the training algorithm yml configuration file # -o Set optional parameters # Global.pretrained_model parameter Set the training model address to be converted without adding the file suffix .pdmodel, .pdopt or .pdparams. @@ -456,16 +529,31 @@ inference/en_PP-OCRv3_rec/ └── inference.pdmodel # The program file of recognition model ``` -- Text recognition model Inference using custom characters dictionary +**Note**: If you need to store the model in the new IR mode (i.e., `.json` format), use the following command to switch to the new IR mode: + +```bash +export FLAGS_enable_pir_api=1 +python3 tools/export_model.py -c configs/rec/PP-OCRv3/en_PP-OCRv3_rec.yml -o Global.pretrained_model=./pretrain_models/en_PP-OCRv3_rec_train/best_accuracy Global.save_inference_dir=./inference/en_PP-OCRv3_rec/ +``` - If the text dictionary is modified during training, when using the inference model to predict, you need to specify the dictionary path used by `--rec_char_dict_path` +Once successful, you will have two files in the directory: - ```bash linenums="1" - python3 tools/infer/predict_rec.py --image_dir="./doc/imgs_words_en/word_336.png" --rec_model_dir="./your inference model" --rec_image_shape="3, 32, 100" --rec_char_dict_path="your text dict path" - ``` +```text +inference/en_PP-OCRv3_rec/ + ├── inference.pdiparams # Model parameter file for the inference model + └── inference.json # Program file for the inference model +``` + +### Custom Model Inference + +If you modified the text dictionary during training, you must specify the path to the custom dictionary when using the inference model for prediction. For more information about configuring and explaining inference hyperparameters, refer to the [Inference Hyperparameters Explanation Tutorial](../blog/inference_args.md). + +```bash linenums="1" +python3 tools/infer/predict_rec.py --image_dir="./doc/imgs_words_en/word_336.png" --rec_model_dir="./your_inference_model" --rec_image_shape="3, 48, 320" --rec_char_dict_path="your_text_dict_path" +``` -## 5. FAQ +### 5. FAQ -Q1: After the training model is transferred to the inference model, the prediction effect is inconsistent? +**Q1:** Why is the prediction result inconsistent after converting a trained model to an inference model? -**A**: There are many such problems, and the problems are mostly caused by inconsistent preprocessing and postprocessing parameters when the trained model predicts and the preprocessing and postprocessing parameters when the inference model predicts. You can compare whether there are differences in preprocessing, postprocessing, and prediction in the configuration files used for training. +**A**: This is a common issue. It typically arises due to differences in the preprocessing and postprocessing parameters used during training and inference. To troubleshoot, check whether the preprocessing, postprocessing, and prediction settings in the configuration file used for training match those used during inference. diff --git a/docs/ppocr/model_train/recognition.md b/docs/ppocr/model_train/recognition.md index 0d531c593c..9049c926d2 100644 --- a/docs/ppocr/model_train/recognition.md +++ b/docs/ppocr/model_train/recognition.md @@ -344,7 +344,7 @@ class MyBackbone(nn.Layer): return y ``` -3. 在 [ppocr/modeling/backbones/\_*init\_*.py](../../ppocr/modeling/backbones/__init__.py)文件内导入添加的`MyBackbone`模块，然后修改配置文件中Backbone进行配置即可使用，格式如下: +3. 在 [ppocr/modeling/backbones/\_*init\_*.py](https://github.com/PaddlePaddle/PaddleOCR/blob/main/ppocr/modeling/backbones/__init__.py)文件内导入添加的`MyBackbone`模块，然后修改配置文件中Backbone进行配置即可使用，格式如下: ```yaml linenums="1" Backbone: @@ -356,7 +356,7 @@ args1: args1 ### 2.4. 混合精度训练 -如果您想进一步加快训练速度，可以使用[自动混合精度训练](https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/01_paddle2.0_introduction/basic_concept/amp_cn.html)， 以单机单卡为例，命令如下： +如果您想进一步加快训练速度，可以使用[自动混合精度训练](https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/performance_improving/amp_cn.html)， 以单机单卡为例，命令如下： ```bash linenums="1" python3 tools/train.py -c configs/rec/PP-OCRv3/en_PP-OCRv3_rec.yml \ @@ -534,6 +534,9 @@ inference 模型（`paddle.jit.save`保存的模型） 识别模型转inference模型与检测的方式相同，如下： ```bash linenums="1" +# 开启旧 IR 模式 +export FLAGS_enable_pir_api=0 + # -c 后面设置训练算法的yml配置文件 # -o 配置可选参数 # Global.pretrained_model 参数设置待转换的训练模型地址，不用添加文件后缀 .pdmodel，.pdopt或.pdparams。 @@ -553,6 +556,21 @@ inference/en_PP-OCRv3_rec/ └── inference.pdmodel # 识别inference模型的program文件 ``` +**注意：** 如果需要以新 IR 模式（`FLAGS_enable_pir_api=1`）存储 `.json` 文件，请执行以下命令切换到新 IR 模式： + +```bash linenums="1" +export FLAGS_enable_pir_api=1 +python3 tools/export_model.py -c configs/rec/PP-OCRv3/en_PP-OCRv3_rec.yml -o Global.pretrained_model=./pretrain_models/en_PP-OCRv3_rec_train/best_accuracy Global.save_inference_dir=./inference/en_PP-OCRv3_rec/ +``` + +转换成功后，在目录下有三个文件： + +```text linenums="1" +inference/en_PP-OCRv3_rec/ + ├── inference.pdiparams # 识别inference模型的参数文件 + └── inference.json # 识别inference模型的program文件 +``` + - 自定义模型推理 如果训练时修改了文本的字典，在使用inference模型预测时，需要通过`--rec_char_dict_path`指定使用的字典路径，更多关于推理超参数的配置与解释，请参考：[模型推理超参数解释教程](../blog/inference_args.md)。 diff --git a/docs/ppstructure/quick_start.en.md b/docs/ppstructure/quick_start.en.md index 773964f787..d21ed9c90b 100644 --- a/docs/ppstructure/quick_start.en.md +++ b/docs/ppstructure/quick_start.en.md @@ -10,28 +10,33 @@ comments: true > If you do not have a Python environment, please refer to [Environment Preparation](../ppocr/environment.en.md). -- If you have CUDA 9 or CUDA 10 installed on your machine, please run the following command to install +- PaddlePaddle with CUDA 11.8 ```bash linenums="1" - python3 -m pip install paddlepaddle-gpu -i https://mirror.baidu.com/pypi/simple + python3 -m pip install paddlepaddle-gpu -i https://www.paddlepaddle.org.cn/packages/stable/cu118/ ``` -- If you have no available GPU on your machine, please run the following command to install the CPU version +- PaddlePaddle with CUDA 12.3 ```bash linenums="1" - python3 -m pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple + python3 -m pip install paddlepaddle-gpu -i https://www.paddlepaddle.org.cn/packages/stable/cu123/ ``` -For more software version requirements, please refer to the instructions in [Installation Document](https://www.paddlepaddle.org.cn/install/quick) for operation. +- If your machine does not have an available GPU, please run the following command to install the CPU version + + ```bash linenums="1" + python3 -m pip install paddlepaddle -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ + ``` + +For more software version requirements, please refer to the instructions in the [Installation Document](https://www.paddlepaddle.org.cn/en/install/quick). ### 1.2 Install PaddleOCR Whl Package ```bash linenums="1" -# Install paddleocr, version 2.6 is recommended -pip3 install "paddleocr>=2.6.0.3" +python3 -m pip install paddleocr # Install the image direction classification dependency package paddleclas (if you do not use the image direction classification, you can skip it) -pip3 install paddleclas>=2.4.3 +python3 -m pip install paddleclas ``` ## 2. Quick Use @@ -41,6 +46,8 @@ pip3 install paddleclas>=2.4.3 #### 2.1.1 image orientation + layout analysis + table recognition ```bash linenums="1" +# Temporarily disable the new IR feature +export FLAGS_enable_pir_api=0 paddleocr --image_dir=ppstructure/docs/table/1.png --type=structure --image_orientation=true ``` @@ -64,9 +71,9 @@ paddleocr --image_dir=ppstructure/docs/table/table.jpg --type=structure --layout #### 2.1.5 Key Information Extraction -Key information extraction does not currently support use by the whl package. For detailed usage tutorials, please refer to: [inference document](./infer_deploy/python_infer.en.md). +Key information extraction does not currently support use by the whl package. For detailed usage tutorials, please refer to: [Key Information Extraction](../ppocr/model_train/kie.en.md). -#### 2.1.6 layout recovery(PDF to Word) +#### 2.1.6 layout recovery Two layout recovery methods are provided, For detailed usage tutorials, please refer to: [Layout Recovery](./model_train/recovery_to_doc.en.md). diff --git a/docs/ppstructure/quick_start.md b/docs/ppstructure/quick_start.md index 7d9851eb82..ae1507f768 100644 --- a/docs/ppstructure/quick_start.md +++ b/docs/ppstructure/quick_start.md @@ -10,16 +10,22 @@ comments: true > > 如果您没有基础的Python运行环境，请参考[运行环境准备](../ppocr/environment.md)。 -- 您的机器安装的是CUDA9或CUDA10，请运行以下命令安装 +- CUDA11.8 的 PaddlePaddle ```bash linenums="1" - python3 -m pip install paddlepaddle-gpu -i https://mirror.baidu.com/pypi/simple + python3 -m pip install paddlepaddle-gpu -i https://www.paddlepaddle.org.cn/packages/stable/cu118/ + ``` + +- CUDA12.3 的 PaddlePaddle + + ```bash linenums="1" + python3 -m pip install paddlepaddle-gpu -i https://www.paddlepaddle.org.cn/packages/stable/cu123/ ``` - 您的机器是CPU，请运行以下命令安装 ```bash linenums="1" - python3 -m pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple + python3 -m pip install paddlepaddle -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ ``` 更多的版本需求，请参照[飞桨官网安装文档](https://www.paddlepaddle.org.cn/install/quick)中的说明进行操作。 @@ -27,11 +33,10 @@ comments: true ### 1.2 安装PaddleOCR whl包 ```bash linenums="1" -# 安装 paddleocr，推荐使用2.6版本 -pip3 install "paddleocr>=2.6.0.3" +python3 -m pip install paddleocr # 安装 图像方向分类依赖包paddleclas（如不需要图像方向分类功能，可跳过） -pip3 install paddleclas>=2.4.3 +python3 -m pip install paddleclas ``` ## 2. 便捷使用 @@ -41,6 +46,8 @@ pip3 install paddleclas>=2.4.3 #### 2.1.1 图像方向分类+版面分析+表格识别 ```bash linenums="1" +# 暂时关闭新 IR 功能 +export FLAGS_enable_pir_api=0 paddleocr --image_dir=ppstructure/docs/table/1.png --type=structure --image_orientation=true ```