PaddleOCR 文字检测模型训练实战：基于 ICDAR2015 的完整训练、评估与部署指南-育师

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/PaddleOCR

PaddleOCR 的文字检测（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 下载预训练 Backbone

PaddleOCR 检测模型目前支持 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.txt

pretrained_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.5；
Neck.name: DBFPN：FPN 特征金字塔增强模块，输出 256 通道；
Head.name: DBHead：DB 检测头，k: 50是二值化阈值相关的放大系数。

2.3 Loss、Optimizer 与 PostProcess

Loss: 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.5

DBLoss采用 DiceLoss 作为主损失，配合alpha、beta权重与ohem_ratio在线难例挖掘比例；
优化器默认 Adam，初始学习率 0.001，L2 正则系数为 0（可在-o参数中随时调整）；
DBPostProcess是 DB 算法的后处理模块，其核心参数thresh（二值化阈值）、box_thresh（框置信度阈值）、unclip_ratio（框外扩比例）在 ppocr/postprocess/db_postprocess.py 中实现，源码中unclip_ratio默认值为 2.0，box_thresh默认值为 0.7，配置文件按数据集特点做了针对性调整。后处理流程先通过cv2.findContours提取二值图轮廓，再用pyclipper按unclip_ratio外扩多边形得到最终文本框。

2.4 Metric：评估指标

Metric: name: DetMetric main_indicator: hmean

PaddleOCR 计算三个检测核心指标：Precision（精确率）、Recall（召回率）、Hmean（F-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.5～3 倍）增强；
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 ID）：

python3 -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.0001：

python3 tools/train.py -c configs/det/det_mv3_db.yml -o Optimizer.base_lr=0.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并实现forward：

import 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_type（det/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_amp=True Global.scale_loss=1024.0 Global.use_dynamic_loss_scaling=True

Global.use_amp=True：开启自动混合精度；
Global.scale_loss=1024.0：初始损失缩放系数，防止 FP16 梯度下溢；
Global.use_dynamic_loss_scaling=True：启用动态损失缩放。

从 tools/train.py 的源码可以看出，开启 AMP 后还会为 CUDA 设置FLAGS_cudnn_batchnorm_spatial_persistent等标志位，并使用paddle.amp.GradScaler管理缩放；amp_level默认O2，amp_dtype默认float16。

注意：文本检测模型使用 AMP 时可能遇到训练不收敛问题，建议参考 PaddleOCR 官方 discussions 中的临时解决方案（如将部分算子加入黑名单）进行调整。

3.5 分布式训练（多机多卡）

多机多卡训练时，通过--ips设置机器 IP 列表，通过--gpus设置使用的 GPU ID：

python3 -m paddle.distributed.launch --ips="xx.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/CPU：Windows 平台与 Linux 略有不同：

只支持单卡训练与预测，指定 GPU 训练需设置set CUDA_VISIBLE_DEVICES=0；
DataLoader 只支持单进程模式，需要将num_workers设置为 0。

macOS：不支持 GPU 模式，需在配置文件中将use_gpu设为False，其余训练评估预测命令与 Linux GPU 完全相同。

Linux DCU：DCU 设备上运行需要设置环境变量export HIP_VISIBLE_DEVICES=0,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_thresh=0.6 PostProcess.unclip_ratio=2.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_algorithm="DB" --det_model_dir="./output/det_db_inference/" --image_dir="./doc/imgs/" --use_gpu=True

如果是其他检测算法，如 EAST，需将det_algorithm修改为对应算法名（默认为 DB）：

python3 tools/infer/predict_det.py --det_algorithm="EAST" --det_model_dir="./output/det_db_inference/" --image_dir="./doc/imgs/" --use_gpu=True

更多推理超参数（如--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 库？

A：EAST 算法的后处理依赖 lanms（Locality-Aware NMS）库，执行pip3 install lanms-nova安装即可。

7. 总结

本文以 ICDAR2015 数据集为例，完整覆盖了 PaddleOCR 检测模型的训练闭环：从数据集与预训练 Backbone 准备，到det_mv3_db.yml配置文件的逐段解析，再到单卡/多卡训练、断点续训、Backbone 自定义、AMP 混合精度、分布式训练与知识蒸馏，最后完成指标评估、效果可视化、inference 模型导出与部署推理。

理解整个流程的关键在于把握两条主线：一是"四段式"组网结构（transforms → backbones → necks → heads），它决定了自定义网络模块的接入方式；二是训练与推理的预处理/后处理一致性，它是排除精度落差问题的核心排查思路。掌握这两点，你就能在 PaddleOCR 上灵活训练并落地自己的检测模型。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

PaddleOCR 文字检测模型训练实战：基于 ICDAR2015 的完整训练、评估与部署指南