PaddleOCR 的检测模型训练说难不难说简单也不简单。上篇聊过安装和基本调用大部分人跑通官方 demo 之后都会想同一件事我手里这批图片有自己的排版风格官方模型识别文字不够准能不能自己训练一个检测模型让模型把我场景里的文字区域都框对这篇文章就在“PaddleOCR 检测模型训练”这条主线上做完整拆解数据怎么准备、配置文件怎么改、训练命令怎么跑、训练完怎么评估和导出以及我在实操中踩过的几个坑。适合已经跑通 PaddleOCR 基础流程、准备训练自定义检测模型的朋友也适合第一次尝试模型训练的新手按步骤跟着做基本都能跑起来。1. 检测模型在PaddleOCR里的定位与训练思路1.1 检测模型到底在解决什么问题一个完整的 OCR 系统通常分两段先检测后识别。检测模型负责在图片中找到文字所在的区域输出一个或多个四边形框识别模型再对每个框内的图像做字符转换。PaddleOCR 的官方预训练检测模型对常规印刷体、屏幕截图、清晰扫描件表现很好但对特殊场景往往力不从心。我手头做过一个模拟项目X需要检测产品铭牌上环形排列的字符官方模型把字符区域框得歪歪扭扭甚至把背景纹理误检成文字。原因不复杂预训练模型主要基于常规文本行数据训练对弯曲文本、艺术字、印章、低对比度文字的适应性有限。这种情况下跑再强的识别模型都没用因为检测框本身就不准识别阶段拿到的输入是错的。所以检测模型训练聚焦的核心问题不是“这些字符怎么读”而是“文字区域在哪里、边界该画在哪里”。检测框的精度直接决定识别效果框偏了识别模型会截到半个字符框松了识别模型会把背景噪声当文字读框漏了文字直接消失。很多项目里重新训练检测模型比训练识别模型带来的整体收益更明显原因就在这里。DBDifferentiable Binarization是 PaddleOCR 检测模型中最常用的算法之一它的思路很直观模型先输出一个概率图表示每个像素属于文字区域的置信度再用一个可微分的二值化操作把概率图转成文字区域掩码最后从掩码里提取出文本行的最小外接四边形。训练时损失函数由三部分组成概率图损失、阈值图损失和二值化图损失。理解这个原理有助于后面分析训练日志比如 loss 里包含多个子项某个子项异常大就能大致猜到是哪部分学得不好。1.2 从数据到部署的整体训练链路检测模型训练可以拆成七个环节每个环节都有对应产出环节主要工作输出物数据采集收集真实场景图片覆盖光照、角度、排版变化原始图片集标注给文字区域画框记录顶点坐标标注文件格式转换转成 PaddleOCR 检测训练要求的 txt 格式train/val 标注文件配置修改指定模型结构、数据集路径、超参数yaml 配置文件训练在 GPU 上执行训练脚本训练权重评估在验证集上计算 precision、recall、hmean指标报告导出部署转成推理模型并接入预测推理模型文件很多人第一次接触训练链路喜欢直接跳到“训练”这一步下载一个预训练模型就开始跑。这个思路不是不行但如果数据格式错了、配置路径错了训练可能白跑几小时甚至一晚上。我建议第一次做检测训练时先把这条链路完整走一遍不要跳步。等经验多了再考虑跳过某些环节比如用官方预训练模型先做预标注来辅助人工标注那是后话。在这条链路里数据采集和标注是整个项目的地基。后面所有环节都是在地基上盖楼。后续章节我会把每个环节的常见细节和注意事项展开讲这里先记住一个总原则数据质量永远比模型结构更重要。模型结构可以换参数可以调但标注错了模型学到的就是错误的目标再怎么调参也救不回来。2. 训练数据准备标注格式与生成方法2.1 PaddleOCR检测标注格式拆解PaddleOCR 的检测训练标注文件是纯文本格式每一行对应一张图片格式如下图像路径 坐标点1 坐标点2 坐标点3 坐标点4 标签其中每个坐标点用英文逗号拼接的“x,y”表示点与点之间用空格分隔四个点按顺时针顺序排列。标签字段可以是任意内容但必须存在检测训练阶段不使用标签内容所以通常用“*”或“###”占位。例如train/images/001.jpg 100,120 180,120 180,180 100,180 *这行表示图片 001.jpg 中有一个文字框四个顶点分别是左上、右上、右下、左下坐标都在像素坐标系下。如果文字区域是任意四边形比如倾斜文本只需要把四个顶点按顺序写出来即可。PaddleOCR 检测训练支持任意四点构成的四边形但注意不是任意多边形四点框足够覆盖绝大多数场景。有个细节容易被忽略坐标顺序必须一致。训练过程中数据加载器会根据顶点顺序做一些几何变换比如透视变换、仿射变换。如果顺序乱几何关系就乱了轻则 loss 波动重则模型输出框直接扭曲。标注工具导出顺序不一定符合要求写转换脚本时一定要把顺序调整好。坐标是否需要归一化不需要。PaddleOCR 的数据加载器会在内部做归一化处理标注文件里直接写原图像素坐标即可。但坐标必须在图像范围内越界的坐标可能导致后处理时产生非法框或者训练时出现数值异常。我处理这种问题的做法是解析标注时检查坐标范围越界的点直接裁剪到图像边界如果多个点越界则跳过这张图。2.2 数据目录划分与标注质量检查训练数据和验证数据建议分开存放目录结构可以这样dataset/ ├── train/ │ ├── images/ │ │ ├── 001.jpg │ │ └── 002.jpg │ └── label.txt └── val/ ├── images/ └── label.txttrain.txt 和 val.txt 是 PaddleOCR 真正读取的标注文件。在配置文件里data_dir 指向 images 的上级目录label_file_path 指向对应的 txt 文件。如果图片路径写的是相对 data_dir 的相对路径txt 里的图像路径也要保持一致不要写错层级。训练集和验证集的比例常规用 8:2 或 9:1。划分时要按图片而不是按标注框混排避免同一张图同时出现在训练和验证里。验证集要有代表性尽量包含光照差、角度偏、模糊等难例而不是只挑简单的图片否则评估结果会虚高真实场景一用就崩。数据准备好之后强烈建议做一次可视化检查。我一般写一个几十行的 Python 脚本读取标注文件用 OpenCV 把框画到原图上另存为 preview 目录然后快速翻阅。重点看框是否紧贴文字、是否有漏标、是否有框内容明显不符合文字区域。这个步骤只花十几分钟但能避免训练一晚上后才发现数据有问题。标注工具方面开源的图形标注工具基本都能满足需求导出格式可能不是 PaddleOCR 直接支持的格式。比如有些工具导出的是“图片路径 角度 中心点 宽高”的旋转矩形格式这种格式需要转换。转换时要注意旋转矩形的旋转方向、中心点坐标、宽高和角度要转换成四个顶点的像素坐标并且保证顶点顺序符合 PaddleOCR 要求的顺时针。如果你对转换脚本不熟可以先画一两个样例验证确认转换后的框在原图上位置准确再批量处理。2.3 数据增强与样本均衡实践PaddleOCR 配置文件里内置了不少数据增强算子比如随机旋转、随机缩放、随机裁剪、颜色抖动、模糊、反转等等。数据增强能让模型对光照、角度、颜色变化更鲁棒也可以缓解数据量不足的问题。但刚开始不要全部打开先把所有增强关闭或者只留基础项跑通流程再说。等确认训练、评估正常再逐步打开增强观察结果变化。数据量少时增强的作用尤其明显。我在某个模拟项目X里只有三百多张标注图打开随机旋转 ±10 度、随机亮度对比度调整、随机裁剪之后验证集 hmean 从 0.75 提升到 0.82。注意随机旋转角度不能太大否则会把本身是横排文字的数据旋转成竖排引入错误的学习方向。另外随机裁剪如果裁掉了大量文字区域模型会不断学习不完整的文字框反而导致检测框不稳。如果你的场景里有很多大面积空白或者图片中只有少数区域有文字建议在训练集中加入一些没有文字的图片作为负样本。负样本能帮助模型学习“这里没有文字”的判断减少误检。PaddleOCR 对纯背景图片的标注方式不同版本支持程度不一样更稳妥的方法是调整后处理里的 box_thresh 参数让模型输出候选框更少这个后面会讲。这里要给一个明确建议标注文字框时框的边缘要尽量贴近文字的外边界。尤其是中文汉字笔画多如果框松了背景会被大量包含进框里模型学到的特征就会混合背景噪声。标注工具可以通过放大图片精细调整虽然费时间但值得。标注质量差的数据不仅会拖慢收敛速度还会让最终检测框普遍偏离文字后期调 unclip_ratio 也很难完全补偿。3. 配置文件详解读懂并修改训练配置3.1 配置文件结构全解析PaddleOCR 的训练入口是 tools/train.py需要传入一个 yaml 配置文件。官方仓库中检测模型的配置一般在 configs/det 目录下不同版本文件名略有差异。配置文件逻辑上分成几个大段常用字段如下Global: epoch_num: 200 save_model_dir: ./output/det_custom pretrained_model: ./pretrain/best_accuracy use_gpu: true Architecture: model_type: det algorithm: DB Backbone: name: ... Neck: name: ... Head: name: ... Loss: name: DBLoss balance_loss: true Optimizer: name: Adam lr: 0.001 ... Train: dataset: name: SimpleDataSet data_dir: dataset label_file_path: dataset/train.txt loader: batch_size_per_card: 8 Eval: dataset: name: SimpleDataSet data_dir: dataset label_file_path: dataset/val.txt初次接触这个文件不要慌记住一个原则改配置时按“训练流程”来找而不是按代码结构来记。训练流程需要知道训练多少轮、保存到哪里、用什么模型、用什么损失函数、数据从哪里读。对应到配置就是 Global、Architecture、Loss、Optimizer 和 Train/Eval 数据集。其余字段比如 PostProcess、Metric在评估和导出时会用到训练阶段保持默认就可以。Architecture 部分里的 model_type 要写成 detalgorithm 一般对应 DB 或 SAST 等检测算法。自定义训练场景中Backbone 的选择决定了特征提取能力。PaddleOCR 里的 Backbone 常见有 MobileNetV3、ResNet50 等。简单理解MobileNetV3 轻快适合移动端ResNet50 更重特征表达能力更强但训练和推理都更慢。如果你数据量不大用 MobileNetV3 做微调往往性价比更高。3.2 关键超参数调整逻辑超参数里最常调的是 epoch_num、batch_size、学习率和输入尺寸。epoch_num 取决于数据规模和是否加载预训练。从零开始训练数据量几百张一般要 300 轮以上用官方预训练模型微调50~100 轮通常足够。判断模型有没有收敛可以看训练日志里验证集 hmean 是否稳定而不是盯着训练 loss。batch_size 受显存限制常见 4、8、16。batch_size 小梯度噪声大学习率要相应调低batch_size 大训练更稳但显存占用高。学习率是最敏感的参数。PaddleOCR 默认的 Adam 优化器配 0.001~0.01 的初始学习率在加载预训练模型时通常能正常收敛。但如果从零开始训练或者数据标注噪声较大建议把学习率降到 0.0001 左右先用小学习率跑通再逐步调大。配置里一般还会配合余弦退火或 step 衰减让学习率在训练后期变小收敛更稳定。输入尺寸DB 检测模型默认把训练图片 resize 到一个固定尺寸常见 640×640。图片分辨率高、文字面积小需要更大输入尺寸才能保留细节比如 960 或 1280但输入尺寸越大显存占用和训练时间就越高。如果是快速验证流程先用 640 跑通再根据效果考虑加大。这里还有一个经验如果图片是长条形比如票据固定 resize 成正方形会严重压缩横向细节可以优先选择支持动态尺寸或按比例缩放的配置。3.3 预训练模型的选择与加载PaddleOCR 提供多种检测预训练模型按体积和精度分 mobile 和 server 两类。mobile 模型小、速度更快适合 CPU 或移动端部署server 模型精度更高、参数量更大适合服务器 GPU 部署。选择依据是最终部署环境而不是训练时的显卡性能。下载预训练权重后在配置里设置Global.pretrained_model: ./pretrain/det_server/best_accuracyPaddleOCR 加载的预训练权重是整模型权重包含 Backbone、Neck、Head 的参数相当于把模型“预热”到一个较好的初始状态。这样做最大的好处是收敛快、少踩坑。我对比过加载预训练模型后训练 50 轮效果比从零开始训 200 轮还好。加载预训练有两个常见误区。一是路径写错pretrained_model 应该指到具体的 .pdparams 文件而不是目录二是和 checkpoints 混用。pretrained_model 是在开始训练时初始化参数checkpoints 是恢复上一次训练的状态。从零开始微调用 pretrained_model中断后续训用 checkpoints二者不要同时设置。4. 训练实操命令行、日志与恢复4.1 标准训练命令与参数覆盖进入 PaddleOCR 仓库根目录执行python tools/train.py -c configs/det/ch_PP-OCRv3_det_cml.yml \ -o Global.epoch_num200 \ -o Global.save_model_dir./output/det_custom \ -o Global.pretrained_model./pretrain/det_server/best_accuracy \ -o Train.dataset.data_dir./dataset \ -o Train.dataset.label_file_path./dataset/train.txt \ -o Train.loader.batch_size_per_card8 \ -o Eval.dataset.data_dir./dataset \ -o Eval.dataset.label_file_path./dataset/val.txt这里 -c 指定基础配置文件-o 覆盖配置项作用等价于修改 yaml。用 -o 的好处是可以在不同实验之间快速切换参数而不污染原始配置文件。注意点号路径必须和 yaml 层级一致。如果字段名写错不会立刻崩溃但配置不会生效等发现模型表现不对再排查就很麻烦。所以建议第一次运行时设置一个小 epoch 数确定配置生效后再正式跑。如果机器有多张 GPU可以使用python -m paddle.distributed.launch --gpus 0,1 tools/train.py -c ...多卡训练时batch_size_per_card 是单卡 batch size总 batch size 等于单卡乘以卡数。经验法则是总 batch size 翻倍学习率也可以翻倍或略微调高但具体效果要根据验证集指标判断。如果你只有一张显卡不要强行开多卡单卡训练照样能出好模型只是时间慢一些。4.2 训练日志怎么看训练过程中控制台会输出类似日志epoch: 3, iter: 200, loss: 2.135, lr: 0.001000loss 是当前 step 的总损失。DB 损失通常包含几个子项比如概率图损失、阈值图损失、二值化图损失。整体 loss 变化趋势比绝对值更有意义。正常情况前几百个 iter loss 快速下降之后进入缓慢下降阶段。如果 loss 一开始就是 nan或者连续几千 iter 不下降先怀疑数据和配置不要盲目调学习率。除 loss 外训练过程中会周期性在验证集上评估。日志类似precision: 0.832, recall: 0.785, hmean: 0.808hmean 是精度和召回率的调和平均相当于 F1 分数最能代表检测效果。评估频率由配置里的 eval_batch_step 控制一般每隔几百个 step 评估一次。如果数据量小可以把这个值调小比如 200这样能更早发现过拟合。我这里说“发现过拟合”指的是训练 loss 还在降低但验证集 hmean 不再上升或者开始下降。一旦出现这种情况后续训练基本不会带来收益可以提前停止然后考虑增强数据或调小模型。4.3 中断恢复与保存管理训练会自动把权重保存到 Global.save_model_dir 指定的目录。不同版本保存文件命名略有不同常见的是 best_accuracy.pdparams 和 latest.pdparams以及对应的优化器状态文件。best_accuracy 是验证集 hmean 最高的模型latest 是最近一个保存点。训练中断后继续不要用 pretrained_model要用-o Global.checkpoints./output/det_custom/latestcheckpoints 会加载模型权重、优化器状态和学习率调度状态做到无缝续训。如果只是加载权重而不加载优化器学习率重新开始训练曲线可能波动效果不一定好。保存频率由 save_epoch_step 控制。如果你设置每 1 个 epoch 保存一次200 轮会生成 200 份权重如果输入图片分辨率高这些文件会占不少磁盘空间。建议训练稳定后把保存间隔改大比如 5 或 10只保留 best_accuracy 和 latest其余定期清理。另外如果你在多个实验之间切换要特别注意 save_model_dir 不要复用同一个目录否则后一次训练会覆盖前一次的 best_accuracy最后你都不知道这个权重到底是在哪组配置下训出来的。5. 模型评估、导出推理与串联使用5.1 评估指标与评估脚本训练完成后用验证集评估最佳模型python tools/eval.py -c configs/det/ch_PP-OCRv3_det_cml.yml \ -o Global.pretrained_model./output/det_custom/best_accuracy \ -o Eval.dataset.data_dir./dataset \ -o Eval.dataset.label_file_path./dataset/val.txt评估脚本会计算三个指标。precision 是模型检测出的所有框中真正属于文字框的比例recall 是真实文字框中被模型成功检测出的比例hmean 是两者的调和平均。公式上 hmean 2 * precision * recall / (precision recall)如果两个指标有一个低hmean 都会被拉下来。不同业务对 precision 和 recall 的偏好不一样。合同票据类应用更怕漏识可以允许 precision 略低自动录入系统更怕误识需要优先保证 precision。这个权衡可以通过调整后处理参数实现也可以根据场景重新设计验证集。建议评估时同时记录三个指标而不是只记 hmean方便后面对比。比如你的 hmean 没变但 precision 从 0.8 变成 0.9、recall 从 0.9 变成 0.8业务效果可能完全不同。5.2 推理模型导出与预测训练产出的权重包含优化器状态等训练信息不适合直接部署。用 export_model.py 导出python tools/export_model.py -c configs/det/ch_PP-OCRv3_det_cml.yml \ -o Global.pretrained_model./output/det_custom/best_accuracy \ -o Global.save_inference_dir./inference/det_custom导出后目录里有 inference.pdmodel、inference.pdiparams、inference.pdiparams.info 等文件。inference.pdmodel 描述网络结构inference.pdiparams 存储权重。之后可以用 predict_det.py 单独测试python tools/infer/predict_det.py \ --image_dir./test_images \ --det_model_dir./inference/det_custom \ --use_gpuTrue如果检测结果不理想可以先对单张图可视化检查框的位置和置信度。注意导出的推理模型不能再用于继续训练要继续训练时还是用训练目录里的 best_accuracy。如果想在推理时调整后处理参数predict_det.py 或 PaddleOCR API 里一般都有 det_db_unclip_ratio、det_db_box_thresh 这类参数可以直接传入不需要重新导出模型。5.3 检测和识别模型如何串联在实际 OCR 流程中检测模型和识别模型是串行执行的。PaddleOCR 的 Python API 支持分别指定检测、识别、方向分类模型路径from paddleocr import PaddleOCR ocr PaddleOCR( det_model_dir./inference/det_custom, rec_model_dir./inference/rec_custom, use_angle_clsTrue )如果 rec_model_dir 不指定默认使用官方识别模型。检测模型用自定义模型识别模型用官方模型这种组合最常见。但要注意检测框的风格会影响识别效果。比如你的检测框很紧经常只框到文字主体官方识别模型在训练数据里见过各种框通常能适应如果检测框特别松把很多背景包进去了官方识别模型可能把背景噪声识别成符号这时候就需要重新训练识别模型。如果识别也需要自定义通常建议把检测和识别模型都训练好后再串联测试。单独替换一个模型另一个模型的行为需要重新适配。串联测试时可以用 OCR 接口直接输入图片查看最终识别文本也可以分步调用检测和识别模型定位问题出在哪一步。比如检测框正常但识别结果错问题在识别检测框已经歪掉那就要回到检测模型这边优化。6. 常见问题排查与避坑经验6.1 标注问题导致训练异常训练检测模型遇到的绝大多数问题都出在标注数据上。常见的有坐标点数不对比如四个点写成五个坐标顺序混乱导致框交叉坐标越界标签为空图片路径错误。排查方法很简单写一个小脚本遍历标注文件的每一行依次检查图片是否存在、坐标数量是否是 8 个数字、每个坐标是否在图像尺寸范围内、标签是否为空。然后再随机抽取部分图片把框画出来人工确认。某次我遇到 loss 先降后突然升高最后定位到是一张标注图里框的顶点顺序错了概率图在训练时无法对齐损失直接上升。这类问题不靠脚本很难发现。还有一个容易忽略的问题不同图片的尺寸差异很大时如果配置文件里的训练尺寸固定为 640×640模型会把大图和小图都拉伸到这个尺寸。某些极端的长宽比会造成文字区域严重变形。这种情况下不是数据标注错了而是数据预处理策略不合适可以考虑使用 PaddleOCR 里支持动态输入尺寸的配置或者把图片按比例缩放到最长边 960 而不是强行拉伸。6.2 显存不足的实用解法GPU 显存不足是最常见的训练报错。解决办法按优先级排列降低 batch_size_per_card从 16 降到 8再降到 4。降低输入尺寸从 640 降到 512 或者 480。开启混合精度训练减少显存占用。使用多卡训练把显存压力分散到多张卡。降低 batch size 后如果训练不稳定可以把学习率按比例降低比如 batch size 减半学习率也减半。开启混合精度时要注意配置里是否有相应的开关名字在旧版本可能叫 use_fp16新版本可能是 AMP 相关字段以官方文档为准。还有一个临时手段关闭验证集的频繁评估有时 eval 也会占一部分显存训练后期再做评估可以缓解。6.3 检测效果不好的调优方向训练结束但效果不理想先别急着重新标注。按顺序排查验证集 hmean 高但真实场景差验证集和业务场景分布不一致需要收集更多真实场景图片进验证集。检测框偏大调低后处理 unclip_ratio比如从 1.5 调到 1.2。检测框偏小调高 unclip_ratio。漏检多调低 box_thresh让更多低置信度框被保留。误检多调高 box_thresh过滤掉低置信度框。后处理参数调完如果还不行回到数据和模型层面。数据方面增加难例样本模型方面可以换更大的 backbone 或更深的 Neck。但要注意大模型不一定会带来大提升尤其在数据量少的情况下。很多场景里微调后处理参数比换模型更见效。我见过有人反复换模型结构最后发现是 unclip_ratio 设置得太大检测框全都外扩了一圈识别自然不准。所以调优顺序应该是先简单后复杂先调参数再改数据最后才换模型。6.4 训练前一定要做的三件事最后分享一个我自己的习惯算是踩过不少次坑后总结出的检查清单。第一正式训练前先跑 10 个 iter确认能正常输出日志、loss 数值正常、能保存模型文件。这一步能过滤掉大部分配置和数据问题。第二训练前把标注文件可视化一遍不要只检查语法。语法对不代表语义对框离文字太远、框只框住半个字模型学起来很痛苦。第三每次实验记录下数据集版本、配置文件、预训练权重、超参数、验证集 hmean。训练检测模型通常要迭代很多轮不记录的话过两天就分不清哪个配置是哪个结果调优全凭记忆效率很低。如果你准备训练检测模型我特别建议把上面的检查清单过一遍。这几点都不是高深技巧但价值比任何调参技巧都大。训练检测模型最花时间的往往不是 GPU 等待而是反复的数据问题排查。把数据检查做在前面后面就顺了。
