简介面向OCR初学者及需要自定义训练任务的开发者这份资料基于PaddleOCR 2.6版本梳理了一套完整的实操流程内容覆盖深度学习环境配置、依赖安装、PPOCRLabel工具标注、识别与检测标签生成、数据集按检测结果划分、YML文件核心参数调整以及模型训练、验证、推理导出和串联预测等环节几乎涵盖了从零搭建OCR项目的全部步骤。资源包内为一份docx文档大小仅78KB文字精炼、层次分明便于对照步骤逐步操作。教程里特别指出了实际项目中的常见坑例如导出推理模型时预训练权重参数无法直接传入、需要手动改写配置文件中对应的路径评估时如何设置步数以自动保存最优权重批大小不能超过训练或验证图片数量等这些经验能显著缩短调试时间。目前该资源已有1307人学习是上手PaddleOCR自定义流程的高密度中文参考资料。1. 把 PaddleOCR 2.6 训练流程跑通先从一本正经的“大致教程”里挑出真正能用的东西手头攒了一批票据截图和翻拍文档通用 OCR 引擎识别率上不去最直接的解法就是用 PaddleOCR 2.6 自己训一套检测 识别模型。PaddleOCR 自带 PPOCRLabel 标注工具、训练脚本和蒸馏模型库只要数据整理得当从零开始跑通“标注 → 划分 → 训练 → 导出 → 串联推理”这条路是可行的。这套教程的价值不在于命令多全而在于它替你踩过了环境安装、标注格式、路径映射和权重导出这几个最容易翻车的环节。适合手里已经有了一批待识别图片需要自己训练模型来提升准确率的工程师和研究者。接下来我把整个流程拆开每一步该怎么走、参数怎么填、坑在哪里一次说清。2. 从零配置 PaddleOCR 2.6 环境装库顺序就是第一道坑2.1 虚拟环境与 GPU 版飞桨的安装顺序实际动手前先明确一个原则PaddleOCR 在 2.6 版本里已经要求依赖飞桨的 Python 包而 GPU 版飞桨的安装必须放在 PaddleOCR 之前。很多用户一上来就pip install paddleocr等到跑训练时报paddle not installed或者版本不匹配再回头补装又发现已经把环境搞乱了。我一般会新开一个虚拟环境专门命名成PaddleOCR避免和兄弟项目互相污染。# 创建并激活虚拟环境Windows / Linux 通用 python -m venv PaddleOCR # Windows: PaddleOCR\Scripts\activate # Linux: source PaddleOCR/bin/activate # 先装 GPU 版飞桨走百度镜像速度有保障 python -m pip install paddlepaddle-gpu -i https://mirror.baidu.com/pypi/simple这段命令的逻辑是先解决底层深度学习框架因为 PaddleOCR 的安装包会检测飞桨版本并拉取对应依赖。如果先装 PaddleOCR 再装飞桨paddleocr的依赖解析可能锁定一个基础版本后续升级 GPU 版会破坏环境一致性。镜像源这里用了百度的 PyPI 镜像国内网络环境下明显比默认源稳定尤其是 Paddle 系列这样的大包。参数说明paddlepaddle-gpu默认安装的是当前飞桨稳定的 GPU 版本如果你的显卡是旧型号建议到飞桨官网按 CUDA 版本选择对应的安装命令这里不展开。装完可以用python -c import paddle; print(paddle.__version__)验证输出带版本号就说明底层没问题。2.2 requirements.txt 与 PyYAML 缺失的处理飞桨就绪后接着装项目本身的依赖。PaddleOCR 仓库下有一个requirements.txt直接执行即可。但这步有一个几乎每个新人都要撞上的坑安装过程提示缺少 module ‘yml’。# 安装项目依赖 pip install -r requirements.txt # 缺失 module yml 时补装 PyYAML pip install PyYAML逻辑说明PaddleOCR 的配置文件全部是 YAML 格式解析依赖PyYAML而该库在某些 Python 版本下不会自动被paddleocr拉起来属于典型的依赖缺失。requirements.txt里一般不会写死PyYAML因为飞桨本体有间接依赖但环境隔离后解析链可能断裂所以手动补一次最稳。参数说明先执行requirements.txt再补PyYAML不要反过来。如果装 PyYAML 在前pip install -r可能把它升级或覆盖到不兼容版本。2.3 安装 PaddleOCR 与 paddleclas一个负责识别一个负责分类模型训练前需要装两个核心 Python 包PaddleOCR 和 paddleclas。# 官方打包的 PaddleOCR2.6 系列均适用 pip install paddleocr2.6.0.3 # 分类组件后续训练分类模型时会用到 pip install paddleclas2.4.3这里有两个容易被忽略的点。第一paddleocr2.6.0.3加引号是因为符号在 shell 里有重定向含义不加引号命令会解析错误第二paddleclas是走蒸馏和分类任务时的依赖即使当前只做检测识别也建议装上否则个别工具脚本会在运行时才报缺失。装完可以把三个包版本打印出来确认主体环境没问题再往下走。2.4 验证环境跑一次官方自带的小推理环境装好不代表真能用我的习惯是先用官方预训练模型做一次快速推理排除 CUDA 或模型下载问题。# verify_env.py # 运行示例python verify_env.py import paddle from paddleocr import PaddleOCR print(paddle version:, paddle.__version__) # 这里不传 det_model_dir / rec_model_dirPaddleOCR 2.6 会自动下载官方模型 ocr PaddleOCR(use_angle_clsTrue, langch) result ocr.ocr(https://paddleocr.bj.bcebos.com/dygraph_v2.0/demo/0001.jpg, clsTrue) print(初步推理完成识别段落数, len(result))这段代码的核心作用不是让你立刻上手预测而是验证三件事飞桨的 CUDA 调用是否正常、PaddleOCR 的模型下载链路是否通畅、中文识别管道能否完整跑通。如果result返回空列表优先检查图片路径和网络如果报 CUDA 错误回到飞桨版本与显卡驱动的匹配上排查。参数说明use_angle_clsTrue启用了方向分类器适合文本方向不固定的图片langch指定中文模型。实际训练场景里这两个参数不用特别关注验证完环境就可以停了。3. 标签生成与数据集划分先分清检测集和识别集再动手3.1 用 PPOCRLabel 生成检测标签和识别标签数据标注是整套流程里最耗时却最容易出错的地方。PaddleOCR 2.6 仓库里带了标注工具PPOCRLabel它同时输出检测和识别两套标签这一步很关键因为后续训练检测模型和训练识别模型用的是不同的标注文件。# 进入标注工具目录 cd PPOCRLabel # 安装标注工具额外依赖 pip install -r requirements.txt # 启动中文版标注界面 python PPOCRLabel.py --lang ch代码说明PPOCRLabel.py --lang ch会启动一个图形界面你可以在里面框选文字区域并自动转成文本框然后通过“自动标注”功能调用官方 OCR 模型预打标。标注完成后点击“导出标记结果”和“识别结果”会生成两个文件Label.txt检测标签记录每个文本框的坐标和rec_gt.txt识别标签记录每个文本框对应的文字内容。参数说明--lang ch指定界面语言为中文和识别语言无关。真正的语言选择在模型训练配置里这里只需要让界面顺手。标注框的四个坐标是左上、右上、右下、左下导出的Label.txt格式为“图片路径 四组坐标 转义文本”每行一条记录。这里要重点提示很多人标完Label.txt就把rec_gt.txt忘了跑识别训练时报“找不到数据”再回头找才发现识别标签根本没导出。两个文件必须都生成缺一不可。3.2 划分检测集gen_det_train_val_test.py 的参数含义标注完成后数据还在一个大目录里需要划分成训练集、验证集和测试集。PaddleOCR 的PPOCRLabel目录下提供了两个现成脚本分工明确先划分检测集再基于检测集划分识别集。# 用文本编辑器打开 gen_det_train_val_test.py按需修改以下内容 # 核心参数通常有 # image_dir: 原始图片所在目录 # label_dir: Label.txt 所在目录 # train_ratio: 训练集比例默认 0.7 # val_ratio: 验证集比例默认 0.2 # test_ratio: 测试集比例默认 0.1 # 修改后执行 python PPOCRLabel/gen_det_train_val_test.py逻辑说明这个脚本会读取Label.txt按比例随机把样本拆成三份并生成train.txt、val.txt、test.txt。每个.txt文件里每一行是“图片路径 对应检测标注”。注意train.txt只存相对路径或绝对路径加标注后续训练配置里不用再去拼接图片目录因为标注信息里已经包含了图片路径。参数说明三个比例加起来必须等于 1否则脚本会报错。数据量不大时我建议训练集 0.8、验证集 0.1、测试集 0.1因为 OCR 模型吃数据验证集太大反而浪费训练样本。如果你的场景只有上千张图片更极端一点可以训练集 0.9验证集 0.05测试集 0.05但测试集至少要保证有几十张否则评估指标没有意义。3.3 划分识别集gen_rec_follow_det.py 的关联拆分识别数据集不能独立划分必须跟着检测集走。原因是识别模型训练时输入的是一张“被裁剪出来的文本行图片”这些图片由检测标注框裁剪而来。如果识别集的划分和检测集不一致会出现同一张原始图片的一部分文本在训练集、一部分在验证集造成数据泄露。# 打开 gen_rec_follow_det.py重点修改以下参数 # det_train_list: 上一步生成的 train.txt 路径 # det_val_list: 上一步生成的 val.txt 路径 # det_test_list: 上一步生成的 test.txt 路径 # crop_save_dir: 裁剪后的文本行图片保存目录例如 ./crop_img # 修改后执行 python PPOCRLabel/gen_rec_follow_det.py脚本做的事情是读取检测划分文件用检测框坐标把原图裁剪成文本小图保存到crop_save_dir并生成新的标注文件。由于我实际只做了训练集和测试集的划分没有单独保留验证集所以脚本生成的rec_train.txt和rec_test.txt已经够用了如果你想加验证集可以在脚本输出逻辑里多写一份rec_val.txt只要保证和val.txt来自同一批检测框坐标即可。参数说明crop_save_dir最好用一个独立目录并且和训练配置文件里的data_dir保持一致。这里容易出现路径错位比如脚本把裁剪图保存到了./OCR/ALL_1206/crop_img但训练配置里data_dir写成了./OCR/ALL_1206/crop_img2那rec_train.txt里的相对路径就全部失效。4. 训练 YML 配置与常见问题排查预训练权重和路径填对一半就能跑4.1 从官方配置改出你自己的训练文件所有训练参数都集中在 YAML 文件里。PaddleOCR 2.6 的检测模型推荐看configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml.yml这个文件本身是给蒸馏训练用的包含学生模型和教师模型两段配置。自己训练时不建议直接改原文件而是复制一份出来改成ch_PP-OCRv3_det_cml_myself.yml避免原文件被改坏后无法回退。# configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml Global: pretrained_model: ./pretrain_models/best_accuracy save_model_dir: ./output/ch_PP-OCR_v3_det_1206/ save_epoch_step: 50 eval_batch_step: [0, 10] cal_metric_during_train: True Architecture: model_type: det algorithm: DB Backbone: name: PPLCNetV3 Head: name: DBHead k: 50 Loss: name: DBLoss eps: 1.0e-6 Optimizer: name: Adam beta1: 0.9 beta2: 0.999 lr: name: Cosine learning_rate: 0.001 Train: dataset: name: SimpleDataSet data_dir: ./OCR/ALL_1206/ label_file_list: ./train.txt loader: batch_size_per_card: 16 num_workers: 8 Eval: dataset: name: SimpleDataSet data_dir: ./OCR/ALL_1206/ label_file_list: ./val.txt loader: batch_size_per_card: 8 num_workers: 4这份配置最核心的字段就三个Global.pretrained_model、Train.dataset.label_file_list、Eval.dataset.label_file_list。pretrained_model指向初始化权重训练早期用官方权重收敛更快label_file_list指向前面生成的train.txt和val.txt。特别注意data_dir不是图片目录而是标注列表中相对路径的基准目录。如果train.txt里每一行写的是相对路径训练时 PaddleOCR 会把data_dir拼接上去最终定位图片真的存在。4.2 路径映射规律train.txt 与 rec_train.txt 的差异处理这里要区分检测训练和识别训练的路径规则。检测模块的train.txt里面写的是完整图片相对路径通常长这样./OCR/ALL_1206/images/0001.jpg [{points: [[x1,y1],[x2,y2],[x3,y3],[x4,y4]], ...}]这种情况下你只需要在配置里指定label_file_list: ./train.txt图片路径靠data_dir自动拼接。因为相对路径里已经包含了图片子目录data_dir可以只写到公共根目录比如./OCR/ALL_1206/。识别模块则不一样。前面gen_rec_follow_det.py生成的rec_train.txt每一行一般是这样的结构crop_img/0001_0.jpg 文本内容这里crop_img是裁剪图片的保存子目录但如果你把data_dir写成./OCR/ALL_1206/拼接出来就是./OCR/ALL_1206/crop_img/0001_0.jpg而实际图片确实存放在这个位置。所以识别模块的配置必须补足data_dir到能覆盖实际图片路径的位置。我一般会把识别配置的data_dir写成./OCR/ALL_1206/这样既能覆盖crop_img子目录也方便后续路径调整。判断规律可以总结成一句话看标注文件里第一列路径相对于哪个目录成立data_dir就指向那个目录。不要想当然地把所有图片路径都写成绝对路径那样换机器就要重改配置相对路径加data_dir才是可迁移方案。4.3 常见问题排查batchsize、eval 步数与权重保存策略训练配置里最容易踩坑的有三个参数batchsize、eval 间隔和权重保存频率。第一batchsize 不能超过训练集或验证集的图片总数。这个“不能超过”不是软性警告是硬性报错。PaddleOCR 在加载数据时会用total_batch_size batch_size_per_card * device_num去除数据总量如果余数为 0 还好说但如果总样本数不足一个 batch训练直接崩掉。比如你的验证集只有 60 张图batch_size_per_card写成 16那一个 batch 都凑不满脚本会报“No data”或者 EOF 错误。所以配 batchsize 前先数一遍train.txt和val.txt的行数保证行数至少为 batchsize 的两到三倍。第二eval_batch_step: [0, 10]表示训练到第 0 步开始评估之后每隔 10 步验证一次。PaddleOCR 的 eval 阶段会自动保留当前最高精度的权重文件名为best_accuracy。这里要特别说明不要频繁设置save_epoch_step每几个 epoch 保存一次因为训练过程中会生成大量中间权重每个权重文件几百 MB 起步磁盘很快就被塞满。默认做法是只靠 eval 选出最高精度权重保存训练结束后用best_accuracy作为最终成果。第三Global.pretrained_model在训练过程中不要随意修改。如果你先从官方权重开始训练跑到一半想接着自己的best_accuracy继续可以单独用命令行参数覆盖不用动 YAML 文件。但如果 YAML 里同时写了pretrained_model和训练路径PaddleOCR 的加载逻辑是优先从pretrained_model初始化这会导致你之前的训练成果被官方权重盖掉。这一点在下一章展开。5. 训练、验证到导出推理模型参数传递的坑与端到端预测5.1 训练命令与中途更换预训练权重配置没问题后执行训练命令python tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml这条命令会按照 YAML 里的配置启动训练。如果你中途训练中断想用当前的best_accuracy继续跑可以用参数覆盖预训练权重python tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml \ -o Global.pretrained_modelpretrain_models/best_accuracy逻辑说明-o参数用于在命令行覆盖 YAML 里的任意字段优先级高于文件配置。一般用在不想改配置文件的场景。但如果 YAML 里已经写了pretrained_model指向官方权重而且你用的是训练中断恢复那么直接用-o覆盖依然是从官方权重重新开始而不是接着之前的训练进度。PaddleOCR 判断“是否恢复训练”的标准是检查输出目录里有没有latest.pdopt和latest.pdparams而不是看pretrained_model。参数说明pretrain_models/best_accuracy路径不要加.pdparams后缀PaddleOCR 会自动补齐。如果你把完整文件名写进去反而会报找不到权重文件。5.2 验证命令与指定权重评估训练结束后评估模型精度有两种方式直接跑 eval 脚本指定Global.checkpoints或者在训练过程中看日志里的 eval 指标。单独验证指定权重时命令长这样python tools/eval.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml \ -o Global.checkpointsD:/model/PaddleOCR-release-2.6/output/ch_PP-OCR_v3_det_1206/best_accuracy这条命令的关键参数是Global.checkpoints它指向要验证的权重文件的公共前缀也就是“不带.pdparams的文件路径”。PaddleOCR 会加载best_accuracy.pdparams和best_accuracy.pdopt如果只存在前者也能正常评估。验证脚本会输出 precision、recall、hmean 三项指标这三项都在 0.8 以上基本可以放心导出。5.3 export_model.py 导出推理模型的常见坑导出推理模型这一步我遇到过最隐蔽的坑直接命令行传Global.pretrained_model不会生效导出的模型仍然加载的是 YAML 里配置的预训练权重而不是你指定的训练成果。# 表面看起来没问题的写法实际会踩坑 python tools/export_model.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml \ -o Global.pretrained_modelD:/model/PaddleOCR-release-2.6/output/ch_PP-OCR_v3_det_1206/best_accuracy \ -o Global.save_inference_dir./inference/det_cml_ppocrv3_1206这里-o Global.pretrained_model并没有真正覆盖 YAML 文件里的值因为export_model.py在解析命令行参数时对Global.pretrained_model的处理逻辑与train.py不同。表现形式是导出的推理模型尺寸异常小或者预测结果明显不对。解决办法是把训练后的权重直接写进 YAML 文件的pretrained_model字段再执行导出命令# 修改 ch_PP-OCRv3_det_cml_myself.yml Global: pretrained_model: D:/model/PaddleOCR-release-2.6/output/ch_PP-OCR_v3_det_1206/best_accuracy save_inference_dir: ./inference/det_cml_ppocrv3_1206# 修改后再导出这次加载的就是你训练好的权重 python tools/export_model.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml导出完成后save_inference_dir目录下会生成inference.pdmodel、inference.pdiparams等文件。但如果你走的是蒸馏训练导出目录里可能还有Student和Teacher两个子目录。实际部署时要用Student目录因为教师模型只负责训练阶段的蒸馏指导不参与推理。5.4 用 predict_system.py 串联检测与识别模型训练完检测模型后如果识别模型也是你自己训练的需要先按同样流程导出识别推理模型再用串联脚本做端到端预测python tools/infer/predict_system.py \ --image_dirD:/model/PaddleOCR-release-2.6/OCR/ALL_1206/test \ --det_model_dir./inference/det_cml_ppocrv3_1206/Student \ --rec_model_dir./inference/rec_ppocr_v3_distillation_1206/Student这条命令把检测和识别两个推理模型串在一起predict_system.py先跑检测模型把图片里的文本区域框出来再裁剪框内图像送给识别模型最终输出文字行和置信度。--image_dir可以传一个目录也可以传单张图片路径。推理结果会保存到output目录下同时打印在终端里。参数说明--det_model_dir指向导出后的检测模型目录--rec_model_dir指向识别模型目录。如果目录下同时存在Student和Teacher只填Student即可。--image_dir传目录时脚本会遍历目录下所有常见格式的图片文件。从那以后每次导出推理模型我都强制走一遍“先看 YAML 里的 pretrained_model 是不是训练成果路径再跑 export_model.py”的流程。命令行-o传参在这个场景下不值得信赖与其查报错不如直接改文件。这套流程跑完检测模型和识别模型都能稳定导出并端到端预测后续微调也只是在数据和路径上做文章。希望帮到你。本文还有配套的精品资源点击获取
简介面向OCR初学者及需要自定义训练任务的开发者这份资料基于PaddleOCR 2.6版本梳理了一套完整的实操流程内容覆盖深度学习环境配置、依赖安装、PPOCRLabel工具标注、识别与检测标签生成、数据集按检测结果划分、YML文件核心参数调整以及模型训练、验证、推理导出和串联预测等环节几乎涵盖了从零搭建OCR项目的全部步骤。资源包内为一份docx文档大小仅78KB文字精炼、层次分明便于对照步骤逐步操作。教程里特别指出了实际项目中的常见坑例如导出推理模型时预训练权重参数无法直接传入、需要手动改写配置文件中对应的路径评估时如何设置步数以自动保存最优权重批大小不能超过训练或验证图片数量等这些经验能显著缩短调试时间。目前该资源已有1307人学习是上手PaddleOCR自定义流程的高密度中文参考资料。1. 把 PaddleOCR 2.6 训练流程跑通先从一本正经的“大致教程”里挑出真正能用的东西手头攒了一批票据截图和翻拍文档通用 OCR 引擎识别率上不去最直接的解法就是用 PaddleOCR 2.6 自己训一套检测 识别模型。PaddleOCR 自带 PPOCRLabel 标注工具、训练脚本和蒸馏模型库只要数据整理得当从零开始跑通“标注 → 划分 → 训练 → 导出 → 串联推理”这条路是可行的。这套教程的价值不在于命令多全而在于它替你踩过了环境安装、标注格式、路径映射和权重导出这几个最容易翻车的环节。适合手里已经有了一批待识别图片需要自己训练模型来提升准确率的工程师和研究者。接下来我把整个流程拆开每一步该怎么走、参数怎么填、坑在哪里一次说清。2. 从零配置 PaddleOCR 2.6 环境装库顺序就是第一道坑2.1 虚拟环境与 GPU 版飞桨的安装顺序实际动手前先明确一个原则PaddleOCR 在 2.6 版本里已经要求依赖飞桨的 Python 包而 GPU 版飞桨的安装必须放在 PaddleOCR 之前。很多用户一上来就pip install paddleocr等到跑训练时报paddle not installed或者版本不匹配再回头补装又发现已经把环境搞乱了。我一般会新开一个虚拟环境专门命名成PaddleOCR避免和兄弟项目互相污染。# 创建并激活虚拟环境Windows / Linux 通用 python -m venv PaddleOCR # Windows: PaddleOCR\Scripts\activate # Linux: source PaddleOCR/bin/activate # 先装 GPU 版飞桨走百度镜像速度有保障 python -m pip install paddlepaddle-gpu -i https://mirror.baidu.com/pypi/simple这段命令的逻辑是先解决底层深度学习框架因为 PaddleOCR 的安装包会检测飞桨版本并拉取对应依赖。如果先装 PaddleOCR 再装飞桨paddleocr的依赖解析可能锁定一个基础版本后续升级 GPU 版会破坏环境一致性。镜像源这里用了百度的 PyPI 镜像国内网络环境下明显比默认源稳定尤其是 Paddle 系列这样的大包。参数说明paddlepaddle-gpu默认安装的是当前飞桨稳定的 GPU 版本如果你的显卡是旧型号建议到飞桨官网按 CUDA 版本选择对应的安装命令这里不展开。装完可以用python -c import paddle; print(paddle.__version__)验证输出带版本号就说明底层没问题。2.2 requirements.txt 与 PyYAML 缺失的处理飞桨就绪后接着装项目本身的依赖。PaddleOCR 仓库下有一个requirements.txt直接执行即可。但这步有一个几乎每个新人都要撞上的坑安装过程提示缺少 module ‘yml’。# 安装项目依赖 pip install -r requirements.txt # 缺失 module yml 时补装 PyYAML pip install PyYAML逻辑说明PaddleOCR 的配置文件全部是 YAML 格式解析依赖PyYAML而该库在某些 Python 版本下不会自动被paddleocr拉起来属于典型的依赖缺失。requirements.txt里一般不会写死PyYAML因为飞桨本体有间接依赖但环境隔离后解析链可能断裂所以手动补一次最稳。参数说明先执行requirements.txt再补PyYAML不要反过来。如果装 PyYAML 在前pip install -r可能把它升级或覆盖到不兼容版本。2.3 安装 PaddleOCR 与 paddleclas一个负责识别一个负责分类模型训练前需要装两个核心 Python 包PaddleOCR 和 paddleclas。# 官方打包的 PaddleOCR2.6 系列均适用 pip install paddleocr2.6.0.3 # 分类组件后续训练分类模型时会用到 pip install paddleclas2.4.3这里有两个容易被忽略的点。第一paddleocr2.6.0.3加引号是因为符号在 shell 里有重定向含义不加引号命令会解析错误第二paddleclas是走蒸馏和分类任务时的依赖即使当前只做检测识别也建议装上否则个别工具脚本会在运行时才报缺失。装完可以把三个包版本打印出来确认主体环境没问题再往下走。2.4 验证环境跑一次官方自带的小推理环境装好不代表真能用我的习惯是先用官方预训练模型做一次快速推理排除 CUDA 或模型下载问题。# verify_env.py # 运行示例python verify_env.py import paddle from paddleocr import PaddleOCR print(paddle version:, paddle.__version__) # 这里不传 det_model_dir / rec_model_dirPaddleOCR 2.6 会自动下载官方模型 ocr PaddleOCR(use_angle_clsTrue, langch) result ocr.ocr(https://paddleocr.bj.bcebos.com/dygraph_v2.0/demo/0001.jpg, clsTrue) print(初步推理完成识别段落数, len(result))这段代码的核心作用不是让你立刻上手预测而是验证三件事飞桨的 CUDA 调用是否正常、PaddleOCR 的模型下载链路是否通畅、中文识别管道能否完整跑通。如果result返回空列表优先检查图片路径和网络如果报 CUDA 错误回到飞桨版本与显卡驱动的匹配上排查。参数说明use_angle_clsTrue启用了方向分类器适合文本方向不固定的图片langch指定中文模型。实际训练场景里这两个参数不用特别关注验证完环境就可以停了。3. 标签生成与数据集划分先分清检测集和识别集再动手3.1 用 PPOCRLabel 生成检测标签和识别标签数据标注是整套流程里最耗时却最容易出错的地方。PaddleOCR 2.6 仓库里带了标注工具PPOCRLabel它同时输出检测和识别两套标签这一步很关键因为后续训练检测模型和训练识别模型用的是不同的标注文件。# 进入标注工具目录 cd PPOCRLabel # 安装标注工具额外依赖 pip install -r requirements.txt # 启动中文版标注界面 python PPOCRLabel.py --lang ch代码说明PPOCRLabel.py --lang ch会启动一个图形界面你可以在里面框选文字区域并自动转成文本框然后通过“自动标注”功能调用官方 OCR 模型预打标。标注完成后点击“导出标记结果”和“识别结果”会生成两个文件Label.txt检测标签记录每个文本框的坐标和rec_gt.txt识别标签记录每个文本框对应的文字内容。参数说明--lang ch指定界面语言为中文和识别语言无关。真正的语言选择在模型训练配置里这里只需要让界面顺手。标注框的四个坐标是左上、右上、右下、左下导出的Label.txt格式为“图片路径 四组坐标 转义文本”每行一条记录。这里要重点提示很多人标完Label.txt就把rec_gt.txt忘了跑识别训练时报“找不到数据”再回头找才发现识别标签根本没导出。两个文件必须都生成缺一不可。3.2 划分检测集gen_det_train_val_test.py 的参数含义标注完成后数据还在一个大目录里需要划分成训练集、验证集和测试集。PaddleOCR 的PPOCRLabel目录下提供了两个现成脚本分工明确先划分检测集再基于检测集划分识别集。# 用文本编辑器打开 gen_det_train_val_test.py按需修改以下内容 # 核心参数通常有 # image_dir: 原始图片所在目录 # label_dir: Label.txt 所在目录 # train_ratio: 训练集比例默认 0.7 # val_ratio: 验证集比例默认 0.2 # test_ratio: 测试集比例默认 0.1 # 修改后执行 python PPOCRLabel/gen_det_train_val_test.py逻辑说明这个脚本会读取Label.txt按比例随机把样本拆成三份并生成train.txt、val.txt、test.txt。每个.txt文件里每一行是“图片路径 对应检测标注”。注意train.txt只存相对路径或绝对路径加标注后续训练配置里不用再去拼接图片目录因为标注信息里已经包含了图片路径。参数说明三个比例加起来必须等于 1否则脚本会报错。数据量不大时我建议训练集 0.8、验证集 0.1、测试集 0.1因为 OCR 模型吃数据验证集太大反而浪费训练样本。如果你的场景只有上千张图片更极端一点可以训练集 0.9验证集 0.05测试集 0.05但测试集至少要保证有几十张否则评估指标没有意义。3.3 划分识别集gen_rec_follow_det.py 的关联拆分识别数据集不能独立划分必须跟着检测集走。原因是识别模型训练时输入的是一张“被裁剪出来的文本行图片”这些图片由检测标注框裁剪而来。如果识别集的划分和检测集不一致会出现同一张原始图片的一部分文本在训练集、一部分在验证集造成数据泄露。# 打开 gen_rec_follow_det.py重点修改以下参数 # det_train_list: 上一步生成的 train.txt 路径 # det_val_list: 上一步生成的 val.txt 路径 # det_test_list: 上一步生成的 test.txt 路径 # crop_save_dir: 裁剪后的文本行图片保存目录例如 ./crop_img # 修改后执行 python PPOCRLabel/gen_rec_follow_det.py脚本做的事情是读取检测划分文件用检测框坐标把原图裁剪成文本小图保存到crop_save_dir并生成新的标注文件。由于我实际只做了训练集和测试集的划分没有单独保留验证集所以脚本生成的rec_train.txt和rec_test.txt已经够用了如果你想加验证集可以在脚本输出逻辑里多写一份rec_val.txt只要保证和val.txt来自同一批检测框坐标即可。参数说明crop_save_dir最好用一个独立目录并且和训练配置文件里的data_dir保持一致。这里容易出现路径错位比如脚本把裁剪图保存到了./OCR/ALL_1206/crop_img但训练配置里data_dir写成了./OCR/ALL_1206/crop_img2那rec_train.txt里的相对路径就全部失效。4. 训练 YML 配置与常见问题排查预训练权重和路径填对一半就能跑4.1 从官方配置改出你自己的训练文件所有训练参数都集中在 YAML 文件里。PaddleOCR 2.6 的检测模型推荐看configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml.yml这个文件本身是给蒸馏训练用的包含学生模型和教师模型两段配置。自己训练时不建议直接改原文件而是复制一份出来改成ch_PP-OCRv3_det_cml_myself.yml避免原文件被改坏后无法回退。# configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml Global: pretrained_model: ./pretrain_models/best_accuracy save_model_dir: ./output/ch_PP-OCR_v3_det_1206/ save_epoch_step: 50 eval_batch_step: [0, 10] cal_metric_during_train: True Architecture: model_type: det algorithm: DB Backbone: name: PPLCNetV3 Head: name: DBHead k: 50 Loss: name: DBLoss eps: 1.0e-6 Optimizer: name: Adam beta1: 0.9 beta2: 0.999 lr: name: Cosine learning_rate: 0.001 Train: dataset: name: SimpleDataSet data_dir: ./OCR/ALL_1206/ label_file_list: ./train.txt loader: batch_size_per_card: 16 num_workers: 8 Eval: dataset: name: SimpleDataSet data_dir: ./OCR/ALL_1206/ label_file_list: ./val.txt loader: batch_size_per_card: 8 num_workers: 4这份配置最核心的字段就三个Global.pretrained_model、Train.dataset.label_file_list、Eval.dataset.label_file_list。pretrained_model指向初始化权重训练早期用官方权重收敛更快label_file_list指向前面生成的train.txt和val.txt。特别注意data_dir不是图片目录而是标注列表中相对路径的基准目录。如果train.txt里每一行写的是相对路径训练时 PaddleOCR 会把data_dir拼接上去最终定位图片真的存在。4.2 路径映射规律train.txt 与 rec_train.txt 的差异处理这里要区分检测训练和识别训练的路径规则。检测模块的train.txt里面写的是完整图片相对路径通常长这样./OCR/ALL_1206/images/0001.jpg [{points: [[x1,y1],[x2,y2],[x3,y3],[x4,y4]], ...}]这种情况下你只需要在配置里指定label_file_list: ./train.txt图片路径靠data_dir自动拼接。因为相对路径里已经包含了图片子目录data_dir可以只写到公共根目录比如./OCR/ALL_1206/。识别模块则不一样。前面gen_rec_follow_det.py生成的rec_train.txt每一行一般是这样的结构crop_img/0001_0.jpg 文本内容这里crop_img是裁剪图片的保存子目录但如果你把data_dir写成./OCR/ALL_1206/拼接出来就是./OCR/ALL_1206/crop_img/0001_0.jpg而实际图片确实存放在这个位置。所以识别模块的配置必须补足data_dir到能覆盖实际图片路径的位置。我一般会把识别配置的data_dir写成./OCR/ALL_1206/这样既能覆盖crop_img子目录也方便后续路径调整。判断规律可以总结成一句话看标注文件里第一列路径相对于哪个目录成立data_dir就指向那个目录。不要想当然地把所有图片路径都写成绝对路径那样换机器就要重改配置相对路径加data_dir才是可迁移方案。4.3 常见问题排查batchsize、eval 步数与权重保存策略训练配置里最容易踩坑的有三个参数batchsize、eval 间隔和权重保存频率。第一batchsize 不能超过训练集或验证集的图片总数。这个“不能超过”不是软性警告是硬性报错。PaddleOCR 在加载数据时会用total_batch_size batch_size_per_card * device_num去除数据总量如果余数为 0 还好说但如果总样本数不足一个 batch训练直接崩掉。比如你的验证集只有 60 张图batch_size_per_card写成 16那一个 batch 都凑不满脚本会报“No data”或者 EOF 错误。所以配 batchsize 前先数一遍train.txt和val.txt的行数保证行数至少为 batchsize 的两到三倍。第二eval_batch_step: [0, 10]表示训练到第 0 步开始评估之后每隔 10 步验证一次。PaddleOCR 的 eval 阶段会自动保留当前最高精度的权重文件名为best_accuracy。这里要特别说明不要频繁设置save_epoch_step每几个 epoch 保存一次因为训练过程中会生成大量中间权重每个权重文件几百 MB 起步磁盘很快就被塞满。默认做法是只靠 eval 选出最高精度权重保存训练结束后用best_accuracy作为最终成果。第三Global.pretrained_model在训练过程中不要随意修改。如果你先从官方权重开始训练跑到一半想接着自己的best_accuracy继续可以单独用命令行参数覆盖不用动 YAML 文件。但如果 YAML 里同时写了pretrained_model和训练路径PaddleOCR 的加载逻辑是优先从pretrained_model初始化这会导致你之前的训练成果被官方权重盖掉。这一点在下一章展开。5. 训练、验证到导出推理模型参数传递的坑与端到端预测5.1 训练命令与中途更换预训练权重配置没问题后执行训练命令python tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml这条命令会按照 YAML 里的配置启动训练。如果你中途训练中断想用当前的best_accuracy继续跑可以用参数覆盖预训练权重python tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml \ -o Global.pretrained_modelpretrain_models/best_accuracy逻辑说明-o参数用于在命令行覆盖 YAML 里的任意字段优先级高于文件配置。一般用在不想改配置文件的场景。但如果 YAML 里已经写了pretrained_model指向官方权重而且你用的是训练中断恢复那么直接用-o覆盖依然是从官方权重重新开始而不是接着之前的训练进度。PaddleOCR 判断“是否恢复训练”的标准是检查输出目录里有没有latest.pdopt和latest.pdparams而不是看pretrained_model。参数说明pretrain_models/best_accuracy路径不要加.pdparams后缀PaddleOCR 会自动补齐。如果你把完整文件名写进去反而会报找不到权重文件。5.2 验证命令与指定权重评估训练结束后评估模型精度有两种方式直接跑 eval 脚本指定Global.checkpoints或者在训练过程中看日志里的 eval 指标。单独验证指定权重时命令长这样python tools/eval.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml \ -o Global.checkpointsD:/model/PaddleOCR-release-2.6/output/ch_PP-OCR_v3_det_1206/best_accuracy这条命令的关键参数是Global.checkpoints它指向要验证的权重文件的公共前缀也就是“不带.pdparams的文件路径”。PaddleOCR 会加载best_accuracy.pdparams和best_accuracy.pdopt如果只存在前者也能正常评估。验证脚本会输出 precision、recall、hmean 三项指标这三项都在 0.8 以上基本可以放心导出。5.3 export_model.py 导出推理模型的常见坑导出推理模型这一步我遇到过最隐蔽的坑直接命令行传Global.pretrained_model不会生效导出的模型仍然加载的是 YAML 里配置的预训练权重而不是你指定的训练成果。# 表面看起来没问题的写法实际会踩坑 python tools/export_model.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml \ -o Global.pretrained_modelD:/model/PaddleOCR-release-2.6/output/ch_PP-OCR_v3_det_1206/best_accuracy \ -o Global.save_inference_dir./inference/det_cml_ppocrv3_1206这里-o Global.pretrained_model并没有真正覆盖 YAML 文件里的值因为export_model.py在解析命令行参数时对Global.pretrained_model的处理逻辑与train.py不同。表现形式是导出的推理模型尺寸异常小或者预测结果明显不对。解决办法是把训练后的权重直接写进 YAML 文件的pretrained_model字段再执行导出命令# 修改 ch_PP-OCRv3_det_cml_myself.yml Global: pretrained_model: D:/model/PaddleOCR-release-2.6/output/ch_PP-OCR_v3_det_1206/best_accuracy save_inference_dir: ./inference/det_cml_ppocrv3_1206# 修改后再导出这次加载的就是你训练好的权重 python tools/export_model.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml导出完成后save_inference_dir目录下会生成inference.pdmodel、inference.pdiparams等文件。但如果你走的是蒸馏训练导出目录里可能还有Student和Teacher两个子目录。实际部署时要用Student目录因为教师模型只负责训练阶段的蒸馏指导不参与推理。5.4 用 predict_system.py 串联检测与识别模型训练完检测模型后如果识别模型也是你自己训练的需要先按同样流程导出识别推理模型再用串联脚本做端到端预测python tools/infer/predict_system.py \ --image_dirD:/model/PaddleOCR-release-2.6/OCR/ALL_1206/test \ --det_model_dir./inference/det_cml_ppocrv3_1206/Student \ --rec_model_dir./inference/rec_ppocr_v3_distillation_1206/Student这条命令把检测和识别两个推理模型串在一起predict_system.py先跑检测模型把图片里的文本区域框出来再裁剪框内图像送给识别模型最终输出文字行和置信度。--image_dir可以传一个目录也可以传单张图片路径。推理结果会保存到output目录下同时打印在终端里。参数说明--det_model_dir指向导出后的检测模型目录--rec_model_dir指向识别模型目录。如果目录下同时存在Student和Teacher只填Student即可。--image_dir传目录时脚本会遍历目录下所有常见格式的图片文件。从那以后每次导出推理模型我都强制走一遍“先看 YAML 里的 pretrained_model 是不是训练成果路径再跑 export_model.py”的流程。命令行-o传参在这个场景下不值得信赖与其查报错不如直接改文件。这套流程跑完检测模型和识别模型都能稳定导出并端到端预测后续微调也只是在数据和路径上做文章。希望帮到你。本文还有配套的精品资源点击获取
