MindOCR¶

简介¶

MindOCR是一个基于MindSpore 框架开发的OCR开源工具箱，集成系列主流文字检测识别的算法、模型，并提供易用的训练和推理工具，可以帮助用户快速开发和应用业界SoTA文本检测、文本识别模型，如DBNet/DBNet++和CRNN/SVTR，满足图像文档理解的需求。

主要特性

模块化设计: MindOCR将OCR任务解耦成多个可配置模块，用户只需修改几行代码，就可以轻松地在定制化的数据和模型上配置训练、评估的全流程；
高性能: MindOCR提供的预训练权重和训练方法可以使其达到OCR任务上具有竞争力的表现；
易用性: MindOCR提供易用工具帮助在真实世界数据中进行文本的检测和识别。

以下是对应的“mindocr”版本和支持 Mindspore 版本。

mindocr	mindspore
main	master
0.4	2.3.0/2.3.1
0.3	2.2.10
0.1	1.8

安装教程¶

MindSpore相关环境准备¶

MindOCR基于MindSpore AI框架开发，并适配以下框架版本。模型训练场景：

mindspore [安装] 请按照mindocr分支安装对应版本MindSpore。
python >= 3.7
openmpi 4.0.3 (用于分布式训练与验证) [安装]

Lite推理环境准备请参考离线推理环境准备。

包依赖¶

pip install -r requirements.txt

通过源文件安装（推荐）¶

git clone https://github.com/mindspore-lab/mindocr.git
cd mindocr
pip install -e .

使用 -e 代表可编辑模式，可以帮助解决潜在的模块导入问题。

通过docker安装¶

详情

目前提供的docker，环境信息如下 - 操作系统版本：Euler2.8 - CANN版本：7.0 - Python版本：3.9 - MindSpore 版本：2.2.10 - MindSpore Lite 版本：2.2.10 使用docker安装，根据以下步骤： 1. 下载docker - 910：

docker pull swr.cn-central-221.ovaijisuan.com/mindocr/mindocr_dev_910_ms_2_2_10_cann7_0_py39:v1

- 910*:

docker pull swr.cn-central-221.ovaijisuan.com/mindocr/mindocr_dev_ms_2_2_10_cann7_0_py39:v1

2. 新建容器

docker_name="temp_mindocr"
# 910
image_name="swr.cn-central-221.ovaijisuan.com/mindocr/mindocr_dev_910_ms_2_2_10_cann7_0_py39:v1"
# 910*
image_name="swr.cn-central-221.ovaijisuan.com/mindocr/mindocr_dev_ms_2_2_10_cann7_0_py39:v1"

docker run --privileged --name ${docker_name} \
    --tmpfs /tmp \
    --tmpfs /run \
    -v /sys/fs/cgroup:/sys/fs/cgroup:ro \
    --device=/dev/davinci1 \
    --device=/dev/davinci2 \
    --device=/dev/davinci3 \
    --device=/dev/davinci4 \
    --device=/dev/davinci5 \
    --device=/dev/davinci6 \
    --device=/dev/davinci7 \
    --device=/dev/davinci_manager \
    --device=/dev/hisi_hdc \
    --device=/dev/devmm_svm \
    -v /etc/localtime:/etc/localtime \
    -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    --shm-size 800g \
    --cpus 96 \
    --security-opt seccomp=unconfined \
    --network=bridge -itd ${image_name} bash

3. 进入容器

# 设置docker id
container_id="your docker id"
docker exec -it --user root $container_id bash

4. 设置环境变量进入容器后，设置环境变量：

source env_setup.sh

通过PyPI安装¶

pip install mindocr

由于此项目正在积极开发中，从PyPI安装的版本目前已过期，我们将很快更新，敬请期待。

快速开始¶

1. 文字检测和识别示例¶

安装完MindOCR后，我们就很方便地进行任意图像的文本检测和识别，如下。

python tools/infer/text/predict_system.py --image_dir {path_to_img or dir_to_imgs} \
                                          --det_algorithm DB++  \
                                          --rec_algorithm CRNN  \
                                          --visualize_output True

运行结束后，结果将被默认保存在./inference_results路径，可视化结果如下：

文本检测、识别结果可视化

可以看到图像中的文字块均被检测出来并正确识别。更详细的用法介绍，请参考推理教程。

2. 模型训练、评估与推理-快速指南¶

使用tools/train.py脚本可以进行OCR模型训练，该脚本可支持文本检测和识别模型训练。

python tools/train.py --config {path/to/model_config.yaml}

--config 参数用于指定yaml文件的路径，该文件定义要训练的模型和训练策略，包括数据处理流程、优化器、学习率调度器等。

MindOCR在configs文件夹中提供系列SoTA的OCR模型及其训练策略，用户可以快速将其适配到自己的任务或数据集上，参考例子如下

# train text detection model DBNet++ on icdar15 dataset
python tools/train.py --config configs/det/dbnet/dbpp_r50_icdar15.yaml

# train text recognition model CRNN on icdar15 dataset
python tools/train.py --config configs/rec/crnn/crnn_icdar15.yaml

使用tools/eval.py 脚本可以评估已训练好的模型，如下所示：

python tools/eval.py \
    --config {path/to/model_config.yaml} \
    --opt eval.dataset_root={path/to/your_dataset} eval.ckpt_load_path={path/to/ckpt_file}

使用tools/infer/text/predict_system.py 脚本可进行模型的在线推理，如下所示：

python tools/infer/text/predict_system.py --image_dir {path_to_img or dir_to_imgs} \
                                          --det_algorithm DB++  \
                                          --rec_algorithm CRNN  \
                                          --visualize_output True

更多使用方法，请参考使用教程中的模型训练、推理章节。

3. 模型离线推理¶

你可以在MindOCR中对 MindOCR原生模型 或 第三方模型（如PaddleOCR、MMOCR等）进行MindSpore Lite推理。详情请参考模型离线推理教程。

使用教程¶

模型列表¶

文本检测

DBNet (AAAI'2020)
DBNet++ (TPAMI'2022)
PSENet (CVPR'2019)
EAST(CVPR'2017)

文本识别

版面分析

YOLOv8 (Ultralytics Inc.)

关键信息抽取

LayoutXLM (arXiv'2021)
LayoutLMv3 (arXiv'2022)

表格识别

TableMaster (arXiv'2021)

OCR大模型

Vary (arXiv'2023)

关于以上模型的具体训练方法和结果，请参见configs下各模型子目录的readme文档。

MindSpore Lite模型推理的支持列表，请参见MindOCR原生模型推理支持列表和第三方模型推理支持列表（如PaddleOCR）。

数据集列表¶

MindOCR提供了数据格式转换工具，以支持不同格式的OCR数据集，支持用户自定义的数据集。当前已在模型训练评估中验证过的公开OCR数据集如下。

通用OCR数据集

Born-Digital Images [download]
CASIA-10K [download]
CCPD [download]
Chinese Text Recognition Benchmark [paper] [download]
COCO-Text [download]
CTW [download]
ICDAR2015 [paper] [download]
ICDAR2019 ArT [download]
LSVT [download]
MLT2017 [paper] [download]
MSRA-TD500 [paper] [download]
MTWI-2018 [download]
RCTW-17 [download]
ReCTS [download]
SCUT-CTW1500 [paper] [download]
SROIE [download]
SVT [download]
SynText150k [paper] [download]
SynthText [paper] [download]
TextOCR [download]
Total-Text [paper] [download]

版面分析数据集

PublayNet [paper] [download]

关键信息抽取数据集

XFUND [paper] [download]

表格识别数据集

PubTabNet [paper] [download]

我们会在更多的数据集上进行模型训练和验证。该列表将持续更新。

常见问题¶

关于配置环境、使用mindocr遇到的高频问题，可以参考常见问题。

重要信息¶

更新日志¶

详细

2023/04/01 1. 增加新模型
- 关键信息抽取LayoutLMv3
2024/03/20 1. 增加新模型
- OCR大模型Vary-toy，支持基于通义千问1.8B LLM的检测和OCR功能
2023/12/25 1. 增加新模型
- 表格识别TableMaster 2. 添加更多基准数据集及其结果
- PubTabNet
2023/12/14 1. 增加新模型
- 关键信息抽取LayoutXLM
- 关键信息抽取VI-LayoutXLM
- 文本检测PP-OCRv3 DBNet和文本识别PP-OCRv3 SVTR，支持在线推理和微调训练 2. 添加更多基准数据集及其结果
- XFUND 3. 昇腾910硬件多规格支持：DBNet ResNet-50、DBNet++ ResNet-50、CRNN VGG7、SVTR-Tiny、FCENet、ABINet
2023/11/28 1. 增加支持PP-OCRv4模型离线推理
- 文本检测 [PP-OCRv4 DBNet(https://github.com/mindspore-lab/mindocr/blob/main/deploy/py_infer/src/configs/det/ppocr/ch_PP-OCRv4_det_cml.yaml)和文本识别 [PP-OCRv4 CRNN(https://github.com/mindspore-lab/mindocr/blob/main/deploy/py_infer/src/configs/rec/ppocr/ch_PP-OCRv4_rec_distillation.yaml)，支持离线推理 2. 修复第三方模型离线推理bug
2023/11/17 1. 增加新模型
- 版面分析YOLOv8 2. 添加更多基准数据集及其结果
- PublayNet
2023/07/06 1. 增加新模型
- 文本识别 RobustScanner
2023/07/05 1. 增加新模型
- 文本识别 VISIONLAN
2023/06/29 1. 新增2个SoTA模型
- 文本检测 FCENet
- 文本识别 MASTER
2023/06/07 1. 增加新模型
- 文本检测 PSENet
- 文本检测 EAST
- 文本识别 SVTR 2. 添加更多基准数据集及其结果
- totaltext
- mlt2017
- chinese_text_recognition 3. 增加断点续训(resume training)功能，可在训练意外中断时使用。如需使用，请在配置文件中model字段下增加resume参数，允许传入具体路径resume: /path/to/train_resume.ckpt或者通过设置resume: True来加载在ckpt_save_dir下保存的trian_resume.ckpt 4. 改进检测模块的后处理部分：默认情况下，将检测到的文本多边形重新缩放到原始图像空间，可以通过在eval.dataset.output_columns列表中增加"shape_list"实现。 5. 重构在线推理以支持更多模型，详情请参见README.md 。
2023/05/15 1. 增加新模型
- 文本检测 DBNet++
- 文本识别 CRNN-Seq2Seq
- 在SynthText数据集上预训练的DBNet 2. 添加更多基准数据集及其结果
- SynthText, MSRA-TD500, CTW1500
- DBNet的更多基准结果可以在此找到. 3. 添加用于保存前k个checkpoint的checkpoint manager并改进日志。 4. Python推理代码重构。 5. Bug修复：对大型数据集使用平均损失meter，在AMP训练中对ctcloss禁用pred_cast_fp32，修复存在无效多边形的错误。
2023/05/04 1. 支持加载自定义的预训练checkpoint，通过在yaml配置中将model-pretrained设置为checkpoint url或本地路径来使用。 2. 支持设置执行包括旋转和翻转在内的数据增强操作的概率。 3. 为模型训练添加EMA功能，可以通过在yaml配置中设置train-ema（默认值：False）和train-ema_decay来启用。 4. 参数修改：num_columns_to_net -> net_input_column_index: 输入网络的columns数量改为输入网络的columns索引 5. 参数修改：num_columns_of_labels -> label_column_index: 用索引替换数量，以表示label的位置。
2023/04/21 1. 添加参数分组以支持训练中的正则化。用法：在yaml config中添加grouping_strategy参数以选择预定义的分组策略，或使用no_weight_decay_params参数选择要从权重衰减中排除的层（例如，bias、norm）。示例可参考configs/rec/crn/crnn_icdar15.yaml 2. 添加梯度累积，支持大批量训练。用法：在yaml配置中添加gradient_accumulation_steps，全局批量大小=batch_size * devices * gradient_aaccumulation_steps。示例可参考configs/rec/crn/crnn_icdar15.yaml 3. 添加梯度裁剪，支持训练稳定。通过在yaml配置中将grad_clip设置为True来启用。
2023/03/23 1. 增加dynamic loss scaler支持, 且与drop overflow update兼容。如需使用, 请在配置文件中增加loss_scale字段并将type参数设为dynamic，参考例子请见configs/rec/crnn/crnn_icdar15.yaml
2023/03/20 1. 参数名修改：output_keys -> output_columns；num_keys_to_net -> num_columns_to_net； 2. 更新数据流程。

2023/03/13 1. 增加系统测试和CI工作流； 2. 增加modelarts平台适配器，使得支持在OpenI平台上训练，在OpenI平台上训练需要以下步骤：

  i)   在OpenI云平台上创建一个训练任务；
  ii)  在网页上关联数据集，如ic15_mindocr；
  iii) 增加 `config` 参数，在网页的UI界面配置yaml文件路径，如'/home/work/user-job-dir/V0001/configs/rec/test.yaml'；
  iv)  在网页的UI界面增加运行参数`enable_modelarts`并将其设置为True；
  v)   填写其他项并启动训练任务。

如何贡献¶

我们欢迎包括问题单和PR在内的所有贡献，来让MindOCR变得更好。

请参考CONTRIBUTING.md作为贡献指南，请按照Model Template and Guideline的指引贡献一个适配所有接口的模型，多谢合作。

许可¶

本项目遵从Apache License 2.0开源许可。

引用¶

如果本项目对您的研究有帮助，请考虑引用：

@misc{MindSpore OCR 2023,
    title={{MindSpore OCR }:MindSpore OCR Toolbox},
    author={MindSpore Team},
    howpublished = {\url{https://github.com/mindspore-lab/mindocr/}},
    year={2023}
}