PaddleOCR 文字检测模型训练实战基于 ICDAR2015 的完整训练、评估与部署指南【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCRPaddleOCR 的文字检测Text Detection模块负责在图像中定位文本所在区域是整个 OCR 流程检测 → 方向分类 → 识别的第一环。本文以 ICDAR2015 数据集为例基于docs/version2.x/ppocr/model_train/detection.md的核心内容结合仓库源码系统讲解检测模型的训练、断点续训、Backbone 更换、混合精度与分布式训练、知识蒸馏、评估与预测、模型导出与部署的完整流程并深入剖析配置文件与底层调用链帮助你从零掌握 PaddleOCR 检测模型的全生命周期。1. 训练前的准备工作数据集与预训练模型1.1 准备数据集PaddleOCR 检测模型训练需要格式为图像路径 多边形标注框的数据集。以 ICDAR2015 为例其组织方式与标注格式说明可参考 ocr_datasets.md。默认的配置文件假定数据位于./train_data/icdar2015/text_localization/目录下并包含训练与测试两个标注文件详见下文配置文件解析。检测任务与识别任务的关键区别在于检测的标注是任意四边形的四个顶点坐标而非文本内容模型学习的是哪里是文字而不是文字是什么。1.2 下载预训练 BackbonePaddleOCR 检测模型目前支持 MobileNetV3 与 ResNet_vd 系列两种经典 Backbone从当前仓库 ppocr/modeling/backbones 目录看检测侧还已扩展支持 ResNet、ResNet_SAST、PPLCNet 等更多选择。训练时建议加载在 ImageNet 上预训练的权重以加速收敛、提升精度。下载命令如下cd PaddleOCR/ # 根据backbone的不同选择下载对应的预训练模型 # 下载MobileNetV3的预训练模型 wget -P ./pretrain_models/ https://paddleocr.bj.bcebos.com/pretrained/MobileNetV3_large_x0_5_pretrained.pdparams # 或下载ResNet18_vd的预训练模型 wget -P ./pretrain_models/ https://paddleocr.bj.bcebos.com/pretrained/ResNet18_vd_pretrained.pdparams # 或下载ResNet50_vd的预训练模型 wget -P ./pretrain_models/ https://paddleocr.bj.bcebos.com/pretrained/ResNet50_vd_ssld_pretrained.pdparams也可以根据需求使用 PaddleClas 中的模型更换 backbone对应预训练权重可在 PaddleClas 仓库主页找到下载链接。2. 配置文件深度解析以det_mv3_db.yml为例训练的核心入口是 configs/det/det_mv3_db.yml它完整定义了检测训练所需的全部组件。理解这份配置是掌握训练流程的关键下面对关键段落逐层拆解。2.1 Global训练全局参数Global: use_gpu: true use_xpu: false use_mlu: false epoch_num: 1200 log_smooth_window: 20 print_batch_step: 10 save_model_dir: ./output/db_mv3/ save_epoch_step: 1200 eval_batch_step: [0, 2000] # 每2000个iter执行一次评估 cal_metric_during_train: False pretrained_model: ./pretrain_models/MobileNetV3_large_x0_5_pretrained checkpoints: save_inference_dir: use_visualdl: False infer_img: doc/imgs_en/img_10.jpg save_res_path: ./output/det_db/predicts_db.txtpretrained_model预训练权重路径不含.pdparams后缀用于首次训练checkpoints断点权重路径用于恢复训练优先级高于pretrained_model见下文 2.2 节eval_batch_step: [0, 2000]从第 0 个 iter 开始每 2000 个 iter 在验证集上评估一次epoch_num: 1200训练总轮数DB 类检测模型通常需要较大轮数才能收敛到理想精度。2.2 Architecture网络组网Architecture: model_type: det algorithm: DB Transform: Backbone: name: MobileNetV3 scale: 0.5 model_name: large Neck: name: DBFPN out_channels: 256 Head: name: DBHead k: 50这里体现了 PaddleOCR四段式组网哲学。数据在模型中按顺序流经transforms → backbones → necks → heads四个部分分别对应 ppocr/modeling 下的四个目录├── architectures # 网络的组网代码 ├── transforms # 网络的图像变换模块 ├── backbones # 网络的特征提取模块 ├── necks # 网络的特征增强模块 └── heads # 网络的输出模块algorithm: DB选用可微二值化Differentiable Binarization检测算法Backbone.name: MobileNetV3特征提取网络scale: 0.5表示通道缩放系数为 0.5Neck.name: DBFPNFPN 特征金字塔增强模块输出 256 通道Head.name: DBHeadDB 检测头k: 50是二值化阈值相关的放大系数。2.3 Loss、Optimizer 与 PostProcessLoss: name: DBLoss balance_loss: true main_loss_type: DiceLoss alpha: 5 beta: 10 ohem_ratio: 3 Optimizer: name: Adam beta1: 0.9 beta2: 0.999 lr: learning_rate: 0.001 regularizer: name: L2 factor: 0 PostProcess: name: DBPostProcess thresh: 0.3 box_thresh: 0.6 max_candidates: 1000 unclip_ratio: 1.5DBLoss采用 DiceLoss 作为主损失配合alpha、beta权重与ohem_ratio在线难例挖掘比例优化器默认 Adam初始学习率 0.001L2 正则系数为 0可在-o参数中随时调整DBPostProcess是 DB 算法的后处理模块其核心参数thresh二值化阈值、box_thresh框置信度阈值、unclip_ratio框外扩比例在 ppocr/postprocess/db_postprocess.py 中实现源码中unclip_ratio默认值为 2.0box_thresh默认值为 0.7配置文件按数据集特点做了针对性调整。后处理流程先通过cv2.findContours提取二值图轮廓再用pyclipper按unclip_ratio外扩多边形得到最终文本框。2.4 Metric评估指标Metric: name: DetMetric main_indicator: hmeanPaddleOCR 计算三个检测核心指标Precision精确率、Recall召回率、HmeanF-Score主指标为hmean。其底层实现在 ppocr/metrics/det_metric.py通过DetectionIoUEvaluator将预测多边形与标注多边形做 IoU 匹配后汇总统计。2.5 Train / Eval数据流与增强策略训练集与评估集的数据管线差异是检测精度的重要来源。训练阶段采用图像解码 → 标签编码 → 数据增强 → 随机裁剪 → 生成 DB 标签图的管线Train: dataset: name: SimpleDataSet data_dir: ./train_data/icdar2015/text_localization/ label_file_list: - ./train_data/icdar2015/text_localization/train_icdar2015_label.txt transforms: - DecodeImage: img_mode: BGR channel_first: False - DetLabelEncode: - IaaAugment: augmenter_args: - { type: Fliplr, args: { p: 0.5 } } - { type: Affine, args: { rotate: [-10, 10] } } - { type: Resize, args: { size: [0.5, 3] } } - EastRandomCropData: size: [640, 640] max_tries: 50 keep_ratio: true - MakeBorderMap: shrink_ratio: 0.4 thresh_min: 0.3 thresh_max: 0.7 - MakeShrinkMap: shrink_ratio: 0.4 min_text_size: 8 - NormalizeImage: scale: 1./255. mean: [0.485, 0.456, 0.406] std: [0.229, 0.224, 0.225] order: hwc - ToCHWImage: - KeepKeys: keep_keys: [image, threshold_map, threshold_mask, shrink_map, shrink_mask] loader: shuffle: True drop_last: False batch_size_per_card: 16 num_workers: 8 use_shared_memory: True训练阶段的关键点IaaAugment基于 imgaug 的水平翻转概率 0.5、旋转-10°10°、随机缩放0.53 倍增强EastRandomCropData随机裁剪 640×640 区域模拟不同尺度的文本MakeBorderMap/MakeShrinkMap这是 DB 算法特有的标签生成环节分别生成概率图shrink map与阈值图border map二者共同监督网络输出KeepKeys指定的threshold_map、shrink_map等即为送入模型的监督信号。评估阶段则使用固定尺寸缩放保证与论文评测口径一致Eval: dataset: name: SimpleDataSet data_dir: ./train_data/icdar2015/text_localization/ label_file_list: - ./train_data/icdar2015/text_localization/test_icdar2015_label.txt transforms: - DecodeImage: img_mode: BGR channel_first: False - DetLabelEncode: - DetResizeForTest: image_shape: [736, 1280] - NormalizeImage: scale: 1./255. mean: [0.485, 0.456, 0.406] std: [0.229, 0.224, 0.225] order: hwc - ToCHWImage: - KeepKeys: keep_keys: [image, shape, polys, ignore_tags] loader: shuffle: False drop_last: False batch_size_per_card: 1 # must be 1 num_workers: 8 use_shared_memory: True注意DetResizeForTest将图像 resize 到 [736, 1280]高×宽这与论文保持一致而推理阶段的默认 resize 策略不同见 FAQ 部分这是训练与推理效果不一致问题的根源所在。3. 开始训练3.1 启动训练如果您安装的是 CPU 版本请将配置文件中的use_gpu字段修改为false。单机单卡训练 mv3_db 模型python3 tools/train.py -c configs/det/det_mv3_db.yml \ -o Global.pretrained_model./pretrain_models/MobileNetV3_large_x0_5_pretrained单机多卡训练通过--gpus参数设置 GPU IDpython3 -m paddle.distributed.launch --gpus 0,1,2,3 tools/train.py -c configs/det/det_mv3_db.yml \ -o Global.pretrained_model./pretrain_models/MobileNetV3_large_x0_5_pretrained上述指令中-c选择训练使用的 det_mv3_db.yml 配置文件-o用于在不修改 yml 文件的前提下覆盖任意训练参数。例如调整学习率为 0.0001python3 tools/train.py -c configs/det/det_mv3_db.yml -o Optimizer.base_lr0.0001关于配置文件各字段的完整解释请参考 config.md。底层调用链tools/train.py依次完成build_dataloader构建训练/验证 DataLoader→build_post_process→build_model组装 Architecture→build_loss→build_optimizer→build_metric→load_model加载预训练/断点权重→program.train进入训练循环。其中 AMP、EMA、SyncBN 等高级特性也在此处按配置自动启用源码见 tools/train.py。3.2 断点训练恢复训练训练意外中断时可通过Global.checkpoints指定要加载的模型路径恢复训练python3 tools/train.py -c configs/det/det_mv3_db.yml -o Global.checkpoints./your/trained/model注意Global.checkpoints的优先级高于Global.pretrained_model。即同时指定两个参数时优先加载Global.checkpoints指定的模型若其路径有误才回退加载Global.pretrained_model指定的模型。权重加载逻辑见 ppocr/utils/save_load.py 中的load_model实现。3.3 更换 Backbone 训练PaddleOCR 将网络划分为四部分transforms、backbones、necks、heads代码分别位于 ppocr/modeling 下。如果要更换的 Backbone 在 PaddleOCR 中已有实现如ResNet_vd、PPLCNet等完整清单见 ppocr/modeling/backbones/init.py 中build_backbone的support_dict直接修改配置文件中Backbone部分的参数即可Backbone: name: ResNet_vd depth: 50 # 其余参数以具体实现为准如果要使用全新的 Backbone按以下三步操作在 ppocr/modeling/backbones 文件夹下新建文件如my_backbone.py在my_backbone.py内添加网络定义需继承paddle.nn.Layer并实现forwardimport paddle import paddle.nn as nn import paddle.nn.functional as F class MyBackbone(nn.Layer): def __init__(self, *args, **kwargs): super(MyBackbone, self).__init__() # your init code self.conv nn.xxxx def forward(self, inputs): # your network forward y self.conv(inputs) return y在 ppocr/modeling/backbones/init.py 中导入新增的MyBackbone模块然后在配置文件的Backbone中引用Backbone: name: MyBackbone args1: args1从build_backbone的源码看注册机制是按model_typedet/rec/cls/e2e/kie/table分别维护support_dict白名单并断言name必须存在于白名单中因此新 Backbone 必须完成注册才能被加载。如果要更换网络的其他模块Neck、Head、Loss 等参考 add_new_algorithm.md 的完整流程。3.4 混合精度训练AMP为加快训练速度可使用 PaddlePaddle 自动混合精度训练。单机单卡示例python3 tools/train.py -c configs/det/det_mv3_db.yml \ -o Global.pretrained_model./pretrain_models/MobileNetV3_large_x0_5_pretrained \ Global.use_ampTrue Global.scale_loss1024.0 Global.use_dynamic_loss_scalingTrueGlobal.use_ampTrue开启自动混合精度Global.scale_loss1024.0初始损失缩放系数防止 FP16 梯度下溢Global.use_dynamic_loss_scalingTrue启用动态损失缩放。从 tools/train.py 的源码可以看出开启 AMP 后还会为 CUDA 设置FLAGS_cudnn_batchnorm_spatial_persistent等标志位并使用paddle.amp.GradScaler管理缩放amp_level默认O2amp_dtype默认float16。注意文本检测模型使用 AMP 时可能遇到训练不收敛问题建议参考 PaddleOCR 官方 discussions 中的临时解决方案如将部分算子加入黑名单进行调整。3.5 分布式训练多机多卡多机多卡训练时通过--ips设置机器 IP 列表通过--gpus设置使用的 GPU IDpython3 -m paddle.distributed.launch --ipsxx.xx.xx.xx,xx.xx.xx.xx --gpus 0,1,2,3 tools/train.py -c configs/det/det_mv3_db.yml \ -o Global.pretrained_model./pretrain_models/MobileNetV3_large_x0_5_pretrained注意事项需将命令中的ips替换为实际机器地址机器之间需要能够相互 ping 通训练时需要在每台机器上分别启动同样的命令查看本机 IP 可使用ifconfig更多分布式训练的性能优势与原理参考 distributed_training.md。3.6 知识蒸馏训练PaddleOCR 支持基于知识蒸馏的检测模型训练更多内容参考 knowledge_distillation.md。注意知识蒸馏训练目前只支持 PP-OCR 使用的DB和CRNN算法。3.7 其他训练环境Windows GPU/CPUWindows 平台与 Linux 略有不同只支持单卡训练与预测指定 GPU 训练需设置set CUDA_VISIBLE_DEVICES0DataLoader 只支持单进程模式需要将num_workers设置为 0。macOS不支持 GPU 模式需在配置文件中将use_gpu设为False其余训练评估预测命令与 Linux GPU 完全相同。Linux DCUDCU 设备上运行需要设置环境变量export HIP_VISIBLE_DEVICES0,1,2,3其余训练评估预测命令与 Linux GPU 完全相同。3.8 模型微调实际使用过程中建议加载官方提供的预训练模型在自己的数据集中进行微调以获得更好的领域适配效果。检测模型的微调方法包括学习率调整策略、数据规模建议等参考 finetune.md。4. 模型评估与预测4.1 指标评估训练中模型参数默认保存在Global.save_model_dir目录下det_mv3_db.yml中为./output/db_mv3/。评估时需要设置Global.checkpoints指向保存的参数文件python3 tools/eval.py -c configs/det/det_mv3_db.yml -o Global.checkpoints{path/to/weights}/best_accuracy评估脚本 tools/eval.py 会复用配置文件中的Eval数据集与PostProcess、Metric定义在验证集上计算 Precision、Recall、Hmean 三个指标并打印。从 ppocr/metrics/det_metric.py 的实现可以看到DetMetric通过DetectionIoUEvaluator.evaluate_image逐图比对预测多边形与 GT 多边形最终汇总得到整体指标。4.2 测试单张图像的检测效果python3 tools/infer_det.py -c configs/det/det_mv3_db.yml -o Global.infer_img./doc/imgs_en/img_10.jpg Global.pretrained_model./output/det_db/best_accuracy测试 DB 模型时可动态调整后处理阈值检测框会被绘制并以黄色多边形可视化保存python3 tools/infer_det.py -c configs/det/det_mv3_db.yml -o Global.infer_img./doc/imgs_en/img_10.jpg Global.pretrained_model./output/det_db/best_accuracy PostProcess.box_thresh0.6 PostProcess.unclip_ratio2.0注box_thresh、unclip_ratio是DB 后处理参数其他检测模型如 EAST、SAST不支持。tools/infer_det.py的推理逻辑值得留意见 tools/infer_det.py它会复用配置Eval.dataset.transforms中的数据预处理算子跳过含Label的算子支持对单张图片、图片文件夹乃至每行一个路径的 txt 文件进行批量检测检测结果以图像路径 JSON 格式的四边形点集逐行写入Global.save_res_path指定的文件并同步绘制可视化结果。4.3 测试文件夹下所有图像python3 tools/infer_det.py -c configs/det/det_mv3_db.yml -o Global.infer_img./doc/imgs_en/ Global.pretrained_model./output/det_db/best_accuracy只需将Global.infer_img指向目录即可脚本会自动遍历目录下所有支持的图像格式。5. 模型导出与推理部署5.1 checkpoint 模型与 inference 模型的区别inference 模型paddle.jit.save保存将模型结构与参数固化在文件中多用于预测部署场景推理速度与集成灵活性更优checkpoints 模型训练过程中保存只包含模型参数多用于恢复训练。与 checkpoints 模型相比inference 模型额外保存了模型的结构信息在预测部署、加速推理上性能优越适合实际系统集成。5.2 检测模型转 inference 模型# 加载配置文件det_mv3_db.yml从output/det_db目录下加载best_accuracy模型inference模型保存在./output/det_db_inference目录下 python3 tools/export_model.py -c configs/det/det_mv3_db.yml -o Global.pretrained_model./output/det_db/best_accuracy Global.save_inference_dir./output/det_db_inference/导出入口为 tools/export_model.py底层调用 ppocr/utils/export_model.py 中的export(config)完成结构与权重的固化。5.3 inference 模型预测DB 检测模型 inference 模型预测python3 tools/infer/predict_det.py --det_algorithmDB --det_model_dir./output/det_db_inference/ --image_dir./doc/imgs/ --use_gpuTrue如果是其他检测算法如 EAST需将det_algorithm修改为对应算法名默认为 DBpython3 tools/infer/predict_det.py --det_algorithmEAST --det_model_dir./output/det_db_inference/ --image_dir./doc/imgs/ --use_gpuTrue更多推理超参数如--det_limit_side_len、--det_limit_type等的配置与解释参考 inference_args.md。6. FAQ训练与推理常见问题Q1训练模型转 inference 模型之后预测效果不一致A此类问题出现较多根源多是trained model 预测时的预处理、后处理参数与 inference model 预测时的预处理、后处理参数不一致。以det_mv3_db.yml训练的模型为例排查步骤如下检查 trained model 预处理Eval段的DetResizeForTest与 inference model 的预测预处理 是否一致。算法在评估时输入图像大小会影响精度训练 icdar15 配置中将图像 resize 到 [736, 1280] 以与论文保持一致而 inference 预测时只有一套默认参数考虑到预测速度默认将图像最长边限制为 960进行 resize。训练与 inference 的预处理算子实现均位于 ppocr/data/imaug/operators.py。检查 trained model 后处理PostProcess段的thresh、box_thresh、unclip_ratio与 inference 后处理参数 是否一致。Q2训练 EAST 模型提示找不到 lanms 库AEAST 算法的后处理依赖 lanmsLocality-Aware NMS库执行pip3 install lanms-nova安装即可。7. 总结本文以 ICDAR2015 数据集为例完整覆盖了 PaddleOCR 检测模型的训练闭环从数据集与预训练 Backbone 准备到det_mv3_db.yml配置文件的逐段解析再到单卡/多卡训练、断点续训、Backbone 自定义、AMP 混合精度、分布式训练与知识蒸馏最后完成指标评估、效果可视化、inference 模型导出与部署推理。理解整个流程的关键在于把握两条主线一是四段式组网结构transforms → backbones → necks → heads它决定了自定义网络模块的接入方式二是训练与推理的预处理/后处理一致性它是排除精度落差问题的核心排查思路。掌握这两点你就能在 PaddleOCR 上灵活训练并落地自己的检测模型。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考