简介这份PaddleOCR 2.6训练教程面向需要快速上手检测模型训练与推理的OCR开发者围绕检测模型从环境搭建到导出的完整链路展开并融入了标签生成、数据集划分、YML参数配置、训练验证及串联推理等关键环节适合已有基础、希望减少踩坑的读者直接对照操作。内容以1个docx文档承载压缩包仅78KB按步骤记录常用安装命令、脚本参数修改位置以及训练、验证、导出模型的具体命令同时对图片路径设置、batchsize约束和eval频率给出了说明。目前已有1307人学习下载。文档特别指出了export_model时pretrained_model参数传不进去、需将训练权重直接写入YML的常见问题并补充检测与识别模型串联预测示例可帮助读者独立完成从自有数据集标注到最终调用的完整流程是一份实用性较强的OCR入门与进阶操作笔记。1. 为什么 2.6 版本的 PaddleOCR 环境值得单独写一篇做 OCR 方向的人应该都有体会PaddleOCR 的坑从来不在模型本身而在环境。2.6 版本出来之后paddlepaddle-gpu、paddleocr、paddleclas 三个包各自迭代依赖之间稍微错一个版本轻则 import 报错重则训练到一半直接崩掉。我见过不少开发者卡在module yaml has no attribute load这种莫名其妙的问题上最后发现是 PyYAML 没装或者被别的包覆盖了版本。这篇文章是我基于 PaddleOCR 2.6 实际跑通一整套流程后整理的从新建虚拟环境开始一路走到数据标注、数据集划分、YML 配置、训练验证、导出推理模型最后用训练好的权重串联跑预测。整条链路覆盖检测和识别两个模块适合刚接触 PaddleOCR、准备用自有数据集做微调的人也适合之前装过旧版本想迁移到 2.6 的熟手。如果你也在 OCR 环境搭建上反复折腾这篇文章能帮你少踩几个我已经踩过的坑。2. 环境配置从虚拟环境到依赖安装的一次性梳理2.1 新建虚拟环境并克隆代码我不建议直接把 PaddleOCR 装进 base 环境。2.6 版本对 paddlepaddle-gpu 的版本有要求而你的机器上可能有其他项目依赖着不同版本的 Paddle 系列包混在一起很容易出现 CUDA 运行时冲突。所以第一步永远是新建一个独立虚拟环境。conda create -n PaddleOCR python3.8 conda activate PaddleOCRPython 3.8 是 PaddleOCR 2.6 官方测试覆盖较好的版本3.9、3.10 也能跑但有些依赖编译时容易出问题。接下来进入代码文件路径克隆仓库到本地git clone https://github.com/PaddlePaddle/PaddleOCR.git cd PaddleOCR git checkout release/2.6这里我习惯直接切到 release/2.6 分支而不是用默认的 develop 分支。develop 分支的代码更新频繁接口可能和 2.6 文档对不上出了问题你按文档排查时会很痛苦。release/2.6 分支和官方 quickstart 文档是同步的照着做不会出现接口不一致的问题。2.2 安装 paddlepaddle-gpu 与依赖文件GPU 版本的安装使用百度源速度会快很多这是官方 quickstart 里推荐的源也是我实测最稳的方式python -m pip install paddlepaddle-gpu -i https://mirror.baidu.com/pypi/simple注意这里不要省略python -m pip在虚拟环境里直接用pip有时候会安装到全局环境尤其是你配过PYTHONPATH或者有多个 Python 版本时装完会发现 import 还是失败。用python -m pip可以确保装到当前激活的这个 Python 解释器的环境里。安装完后验证一下 GPU 是否正常python -c import paddle; paddle.utils.run_check()正常输出会显示 PaddlePaddle 和 CUDA 的相关信息并提示安装成功。如果报错找不到 CUDA 库先检查环境变量里LD_LIBRARY_PATH是否包含 CUDA 的 lib64 目录这个问题在手动安装 CUDA 而不是用 conda 安装时比较常见。然后安装 requirement.txt 里的依赖pip install -r requirements.txt2.3 PyYAML 缺失的坑和组件包安装这里有一个几乎每个人都会遇到的坑执行完pip install -r requirements.txt后运行 PaddleOCR 相关脚本时直接报ModuleNotFoundError: No module named yaml。原因是 2.6 版本的 requirements.txt 里没有显式列出 PyYAML而 YML 配置文件是 PaddleOCR 的核心配置入口没有这个库根本跑不起来。pip install PyYAML安装后可以用python -c import yaml; print(yaml.__version__)验证。接下来安装 PaddleOCR 的官方打包版和分类组件pip install paddleocr2.6.0.3 pip install paddleclas2.4.3paddleocr2.6.0.3这个版本号值得注意从 2.6.0.3 开始官方把检测、识别、分类的推理逻辑统一封装到了一个包里你在后续串联推理的时候会直接用到。paddleclas是分类组件如果你的业务场景不需要分类可以跳过但 PaddleOCR 的完整链路中它会作为依赖被调用我建议还是装上免得后面报错再回头补。2.4 依赖版本对照与常见问题整个环境装完版本大致长这样组件版本要求用途python3.8 推荐运行环境paddlepaddle-gpu与 CUDA 匹配深度学习框架PyYAML任意新版本解析 YML 配置paddleocr2.6.0.3OCR 推理套件paddleclas2.4.3分类组件环境这块最大的教训是严格按照顺序装。先装 paddlepaddle-gpu再处理 requirements.txt然后才是 paddleocr 和 paddleclas。顺序反了的话paddleocr 可能会因为找不到 paddle 框架的某些模块而安装失败虽然可以事后补救但排查起来费时间。3. 标签生成与数据集划分PPOCRLabel 的完整使用流程3.1 启动 PPOCRLabel 并设置中文模式环境配置好后下一步是给自定义数据集做标注。PaddleOCR 官方提供了配套的标注工具 PPOCRLabel在仓库里的PPOCRLabel目录下。先进入目录安装标注工具的依赖cd PPOCRLabel pip install -r requirements.txt然后启动标注工具python PPOCRLabel.py --lang ch--lang ch是指定中文界面不传的话默认英文。标注界面的基本操作是打开图片目录用鼠标框选出检测框右侧填写对应的文本内容。对于旋转文本可以用滚轮调整框的角度这个功能对发票、证件类图片很实用。标注完成后注意界面上有两个导出按钮一个导出检测结果一个导出识别结果。这两个功能别搞混了检测结果导出的是文本框坐标识别结果导出的是框内文字内容。对应生成的文件分别是Label.txt和rec_gt.txt。3.2 两个标签文件的作用Label.txt是检测任务的标签每一行包含图片路径和检测框坐标信息格式大致是OCR/ALL_1206/img/001.jpg [{transcription: 文本内容, points: [[x1,y1],[x2,y2],[x3,y3],[x4,y4]]}]rec_gt.txt是识别任务的标签格式更简单图片路径加上文本内容。PaddleOCR 的 rec 模型训练只关心「这个图片里是什么字」不关心字的位置所以 rec_gt.txt 不需要坐标信息。生成的标签文件默认在图片目录下如果你把标注结果导出到了其他位置后面配置 YML 时记得对应调整路径这一步很多人会忘。3.3 数据集划分脚本的参数修改训练检测模型和识别模型需要不同的数据划分。官方提供gen_det_train_val_test.py来划分检测数据集先用编辑器打开这个脚本修改输入输出路径参数python gen_det_train_val_test.py脚本会读取标注好的全部数据按比例划分成三份train.txt、val.txt、test.txt。里面有几个关键参数det_label_path指向检测标签文件output_dir是生成文件的输出目录train_ratio、val_ratio、test_ratio是划分比例我一般用 7:1.5:1.5数据量小的话可以用 8:1:1。注意划分完检测数据集后识别数据集的划分不能直接用同一个脚本要改用gen_rec_follow_det.py。因为这个脚本的逻辑是根据检测数据集划分的结果把检测框对应的图像区域裁剪出来生成识别模型的训练数据。python gen_rec_follow_det.py这个脚本执行完会生成rec_train.txt和rec_test.txt同时会把裁剪后的文本行图片保存到指定目录。原作者只分了训练集和测试集如果你需要验证集可以自行在脚本里加一段划分逻辑按照gen_det_train_val_test.py的划分比例复制一份即可。这一步是整个流程里最容易出问题的地方gen_rec_follow_det.py里有一个参数crop_img_dir它决定裁剪后的图片存到哪里。很多人在 YML 配置阶段发现图片路径对不上就是在这里没有统一好目录。我建议把裁剪图片统一放在./OCR/ALL_1206/crop_img这样的路径下后面配置识别模型时直接引用这个相对路径。4. YML 配置详解ch_PP-OCRv3_det_cml_myself.yml 的每一行4.1 复制官方配置并理解核心字段PaddleOCR 2.6 的模型训练全部通过 YML 文件控制官方在configs/det/ch_PP-OCRv3/目录下提供了一系列配置模板。我拿ch_PP-OCRv3_det_cml.yml举例建议你先复制一份再改名保留官方原文件cp configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml.yml configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml打开这个文件你最先看到的是Global段。这一段里最核心的配置是pretrained_model和save_model_dir。pretrained_model指定预训练模型的路径官方下载的预训练权重放在项目根目录的pretrain_models/下。注意这里填的是权重文件的路径前缀不需要带.pdparams后缀PaddleOCR 会自动匹配。还有几个值得关注的字段字段默认值说明epoch_num600总训练轮数save_model_dir./output/训练权重保存目录save_epoch_step10每隔多少轮保存一次权重eval_period10每隔多少轮验证一次4.2 train 和 Eval 的路径配置逻辑这是配置里最容易翻车的部分。检测模型训练用的train.txt里面的图片路径如果是绝对路径那么 YML 里只需要配置label_file_list指定标签文件路径不需要再写图片目录但如果是相对路径就还需要配置data_dir来拼接图片所在的根目录。以检测模块为例train.txt里的图片路径是OCR/ALL_1206/img/001.jpg这是一个相对路径所以 YML 里data_dir需要配置为项目根目录也就是./。PaddleOCR 在读取数据时会把data_dir和标签里的路径拼接成完整路径。识别模块的情况不一样。rec_train.txt里的图片路径对应的是裁剪后的文本行图像比如./OCR/ALL_1206/crop_img/001_0.jpg这里路径本身就带上了./OCR/ALL_1206/crop_img前缀所以 YML 里data_dir可以直接留空或者只填./。判断标准很简单data_dir label中的路径 实际存在的图片路径能拼出来就对了。4.3 batchsize、eval 间隔与训练效率的平衡batchsize在Train和Eval两个子配置里分别设置。一个容易踩的坑是batch_size不能超过输入训练图或验证图的数量。比如你验证集只有 8 张图batch_size却是 16那 eval 阶段就会直接报错终止。小数据集场景下我一般把batch_size设为 4 到 8可以关注 GPU 显存利用率再做调整。eval_period设置为 10 的意思是每 10 步验证一次。别看它叫 period单位是迭代步数而不是 epoch。验证时会计算精度自动保留最高精度的权重存为best_accuracy。这里我建议你对save_epoch_step保持默认或者干脆调大一点因为每几个 epoch 保存一次权重会产生大量中间文件一个 600 轮的训练跑下来能占好几个 GB 的磁盘空间。我一般在配置里把save_epoch_step设为 50同时依赖 eval 机制自动保存最优权重这样最终只需要关心best_accuracy那个文件就够了。YML 配置完成后可以用一个简单的方法验证路径是否正确python tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml如果路径配错了程序会在读取数据阶段报FileNotFoundError或者AssertionError: file not found这时不用等训练跑起来看到这个错误就能去检查data_dir和label_file_list的拼接了。5. 训练、验证与导出推理模型export_model 的预训练权重坑5.1 训练与指定预训练权重的两种方式训练直接跑tools/train.pypython tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml这个命令会从 YML 文件的Global.pretrained_model读取预训练权重路径。如果你需要指定一个不同的预训练权重可以在命令行用-o参数覆盖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参数是 PaddleOCR 提供的命令行覆盖机制格式是配置段.字段名值可以覆盖任意 YML 配置不用改文件。注意命令行覆盖只对当前这次执行生效不会写回 YML 文件。训练过程中日志里每轮会输出loss、lr、elapse等指标loss 持续下降说明训练正常。训练完成后权重会保存在 YML 配置的save_model_dir目录下其中best_accuracy.pdparams是验证精度最高的权重latest.pdparams是最近一步的权重。5.2 用 eval.py 验证指定权重验证阶段使用tools/eval.pypython tools/eval.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml -o Global.checkpointsD:/model/PaddleOCR-release-117/PaddleOCR-release-2.6/output/ch_PP-OCR_v3_det_1206/best_accuracy这里的Global.checkpoints指定用于验证的权重文件路径不带.pdparams后缀。eval.py输出检测模型的精度指标 hmean这个值代表检测和识别综合效果。如果你的数据集和官方数据集差异比较大第一次验证 hmean 低于 0.5 很正常关键看训练过程中有没有逐步提升。另外说明一点训练的最佳权重路径通常是output/xxx/best_accuracy。因为 eval 机制会持续更新保存最优结果所以最终训练完只需要认准best_accuracy这个文件。5.3 导出推理模型容易翻车的传参 bug导出推理模型这一步有个官方文档没强调的坑直接用命令行覆盖Global.pretrained_model导出大概率导出的还是预训练权重而不是你训练好的权重。原教程里也明确提到export_model.py对Global.pretrained_model的传参处理有问题命令行传进去的值不起作用。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-117/PaddleOCR-release-2.6/output/ch_PP-OCR_v3_det_1206/best_accuracy -o Global.save_inference_dir./inference/det_cml_ppocrv3_1206我把这条命令贴出来是想告诉你如果你直接执行它最后导出的模型很可能还是官方预训练权重的行为表现而不是你微调之后的效果。原因是export_model.py内部读取权重的方式和train.py不同命令行覆盖参数没有正确传递到权重加载逻辑里。解决方式很粗暴但有效把你训练好的权重路径直接写进 YML 文件的Global.pretrained_model字段然后再次执行导出命令。这样读取的就是训练好的权重python tools/export_model.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml -o Global.save_inference_dir./inference/det_cml_ppocrv3_1206注意比较这两条命令区别只在于是否用-o覆盖pretrained_model。这个坑我一开始也踩了导出后用测试集预测发现检测效果和预训练模型一模一样最后才发现是权重加载没生效。从那以后我导出前都会先确认 YML 里pretrained_model字段指向的是output/下的训练权重而不是pretrain_models/下的官方权重。5.4 常见问题排查清单以下是这个阶段我遇到过并且有明确解法的问题按「现象 → 原因 → 解决」的顺序梳理现象 1训练时 loss 下降很快但验证精度不涨原因训练集和验证集的分布差异过大或者验证集的标签格式有误。解决检查val.txt的格式和train.txt是否一致特别是坐标点的顺序再看图片是否全部能正常读取。现象 2eval 阶段报batch_size超限原因验证集图片数量小于batch_size。解决把 Eval 配置里的batch_size调小或者往验证集里补充图片。现象 3导出推理模型后预测输出明显不对原因极可能是导出时加载了预训练权重而不是微调权重。解决按 5.3 小节的方式把训练好的权重路径写进 YML 再导出导出的inference目录下应该有inference.pdmodel和inference.pdiparams两个文件。现象 4识别模型和检测模型串联时报模型文件缺失原因检测和识别的推理目录分别设置但predict_system.py默认找的是./inference下特定命名的目录。解决确保--det_model_dir和--rec_model_dir指向能对上或者把导出的模型重命名成官方默认名称。6. 装完怎么验证跑通predict_system.py 串联推理全流程6.1 导出检测和识别两个推理模型验证前的准备工作是把两个模块的推理模型都导出。检测模型按 5.3 小节的方式导出到./inference/det_cml_ppocrv3_1206/目录。识别模型的导出同理识别模块的训练权重在output/下有对应的目录导出命令参考python tools/export_model.py -c configs/rec/ch_PP-OCRv3/ch_PP-OCRv3_rec_distillation.yml -o Global.pretrained_modelD:/model/PaddleOCR-release-117/PaddleOCR-release-2.6/output/rec_ppocr_v3_distillation_1206/best_accuracy -o Global.save_inference_dir./inference/rec_ppocr_v3_distillation_1206导出完成后检查inference/det_cml_ppocrv3_1206/和inference/rec_ppocr_v3_distillation_1206/目录下是否都生成了推理模型文件。识别模型如果使用了蒸馏训练方式模型文件中可能区分Student和Teacher两个子目录串联时使用Student版本即可教师模型只用于训练阶段。6.2 串联预测命令与结果验证一切就绪后用官方提供的predict_system.py做端到端验证。这个脚本会依次执行文本检测、方向分类、文本识别三个步骤输入一张图片输出检测框和识别文字python tools/infer/predict_system.py --image_dirD:/model/PaddleOCR-release-117/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几个参数的说明--image_dir可以是单张图片路径也可以是一个目录目录下所有图片都会被批量处理--det_model_dir指向检测模型的单模型目录。注意如果你的导出目录下直接就是推理模型文件就不需要加/Student后缀--rec_model_dir指向识别模型的目录规则同上分类模型的--cls_model_dir如果没配置默认会用官方在线的分类模型权重建议也导出本地模型并指定路径避免依赖外网下载执行完成后控制台会逐张打印检测框坐标和识别结果。我用一个简单标准判断是否跑通测试集里选取文字清晰、背景简单的图片如果识别文本和真实内容一致率能达到 90% 以上说明全流程没问题。另外predict_system.py支持--save_result和--output参数把可视化结果保存到本地目录生成带框标注的图片。我会把这些可视化图片打开快速扫一遍看检测框是否贴合文字区域这是判断模型推断效果最直观的方式。从那以后我每次装完一套 OCR 环境都强制自己走一遍「标注 → 划分 → 训练 → 导出 → 串联预测」的完整流程而不是只跑通训练就结束。因为真正判断环境是否可用的标准是最后的推理链路能否输出正确结果。这个流程走完后面再迁移到其他机器、换数据集都能顺着这条路快速复现。希望这篇基于 2.6 版本的安装记录能帮你把 PaddleOCR 跑通少走几步弯路。本文还有配套的精品资源点击获取 
长河君 · 2026/10/16 13:27:07 · 阅读 1.2k PaddleOCR 2.6环境配置与模型训练全流程实战指南
简介这份PaddleOCR 2.6训练教程面向需要快速上手检测模型训练与推理的OCR开发者围绕检测模型从环境搭建到导出的完整链路展开并融入了标签生成、数据集划分、YML参数配置、训练验证及串联推理等关键环节适合已有基础、希望减少踩坑的读者直接对照操作。内容以1个docx文档承载压缩包仅78KB按步骤记录常用安装命令、脚本参数修改位置以及训练、验证、导出模型的具体命令同时对图片路径设置、batchsize约束和eval频率给出了说明。目前已有1307人学习下载。文档特别指出了export_model时pretrained_model参数传不进去、需将训练权重直接写入YML的常见问题并补充检测与识别模型串联预测示例可帮助读者独立完成从自有数据集标注到最终调用的完整流程是一份实用性较强的OCR入门与进阶操作笔记。1. 为什么 2.6 版本的 PaddleOCR 环境值得单独写一篇做 OCR 方向的人应该都有体会PaddleOCR 的坑从来不在模型本身而在环境。2.6 版本出来之后paddlepaddle-gpu、paddleocr、paddleclas 三个包各自迭代依赖之间稍微错一个版本轻则 import 报错重则训练到一半直接崩掉。我见过不少开发者卡在module yaml has no attribute load这种莫名其妙的问题上最后发现是 PyYAML 没装或者被别的包覆盖了版本。这篇文章是我基于 PaddleOCR 2.6 实际跑通一整套流程后整理的从新建虚拟环境开始一路走到数据标注、数据集划分、YML 配置、训练验证、导出推理模型最后用训练好的权重串联跑预测。整条链路覆盖检测和识别两个模块适合刚接触 PaddleOCR、准备用自有数据集做微调的人也适合之前装过旧版本想迁移到 2.6 的熟手。如果你也在 OCR 环境搭建上反复折腾这篇文章能帮你少踩几个我已经踩过的坑。2. 环境配置从虚拟环境到依赖安装的一次性梳理2.1 新建虚拟环境并克隆代码我不建议直接把 PaddleOCR 装进 base 环境。2.6 版本对 paddlepaddle-gpu 的版本有要求而你的机器上可能有其他项目依赖着不同版本的 Paddle 系列包混在一起很容易出现 CUDA 运行时冲突。所以第一步永远是新建一个独立虚拟环境。conda create -n PaddleOCR python3.8 conda activate PaddleOCRPython 3.8 是 PaddleOCR 2.6 官方测试覆盖较好的版本3.9、3.10 也能跑但有些依赖编译时容易出问题。接下来进入代码文件路径克隆仓库到本地git clone https://github.com/PaddlePaddle/PaddleOCR.git cd PaddleOCR git checkout release/2.6这里我习惯直接切到 release/2.6 分支而不是用默认的 develop 分支。develop 分支的代码更新频繁接口可能和 2.6 文档对不上出了问题你按文档排查时会很痛苦。release/2.6 分支和官方 quickstart 文档是同步的照着做不会出现接口不一致的问题。2.2 安装 paddlepaddle-gpu 与依赖文件GPU 版本的安装使用百度源速度会快很多这是官方 quickstart 里推荐的源也是我实测最稳的方式python -m pip install paddlepaddle-gpu -i https://mirror.baidu.com/pypi/simple注意这里不要省略python -m pip在虚拟环境里直接用pip有时候会安装到全局环境尤其是你配过PYTHONPATH或者有多个 Python 版本时装完会发现 import 还是失败。用python -m pip可以确保装到当前激活的这个 Python 解释器的环境里。安装完后验证一下 GPU 是否正常python -c import paddle; paddle.utils.run_check()正常输出会显示 PaddlePaddle 和 CUDA 的相关信息并提示安装成功。如果报错找不到 CUDA 库先检查环境变量里LD_LIBRARY_PATH是否包含 CUDA 的 lib64 目录这个问题在手动安装 CUDA 而不是用 conda 安装时比较常见。然后安装 requirement.txt 里的依赖pip install -r requirements.txt2.3 PyYAML 缺失的坑和组件包安装这里有一个几乎每个人都会遇到的坑执行完pip install -r requirements.txt后运行 PaddleOCR 相关脚本时直接报ModuleNotFoundError: No module named yaml。原因是 2.6 版本的 requirements.txt 里没有显式列出 PyYAML而 YML 配置文件是 PaddleOCR 的核心配置入口没有这个库根本跑不起来。pip install PyYAML安装后可以用python -c import yaml; print(yaml.__version__)验证。接下来安装 PaddleOCR 的官方打包版和分类组件pip install paddleocr2.6.0.3 pip install paddleclas2.4.3paddleocr2.6.0.3这个版本号值得注意从 2.6.0.3 开始官方把检测、识别、分类的推理逻辑统一封装到了一个包里你在后续串联推理的时候会直接用到。paddleclas是分类组件如果你的业务场景不需要分类可以跳过但 PaddleOCR 的完整链路中它会作为依赖被调用我建议还是装上免得后面报错再回头补。2.4 依赖版本对照与常见问题整个环境装完版本大致长这样组件版本要求用途python3.8 推荐运行环境paddlepaddle-gpu与 CUDA 匹配深度学习框架PyYAML任意新版本解析 YML 配置paddleocr2.6.0.3OCR 推理套件paddleclas2.4.3分类组件环境这块最大的教训是严格按照顺序装。先装 paddlepaddle-gpu再处理 requirements.txt然后才是 paddleocr 和 paddleclas。顺序反了的话paddleocr 可能会因为找不到 paddle 框架的某些模块而安装失败虽然可以事后补救但排查起来费时间。3. 标签生成与数据集划分PPOCRLabel 的完整使用流程3.1 启动 PPOCRLabel 并设置中文模式环境配置好后下一步是给自定义数据集做标注。PaddleOCR 官方提供了配套的标注工具 PPOCRLabel在仓库里的PPOCRLabel目录下。先进入目录安装标注工具的依赖cd PPOCRLabel pip install -r requirements.txt然后启动标注工具python PPOCRLabel.py --lang ch--lang ch是指定中文界面不传的话默认英文。标注界面的基本操作是打开图片目录用鼠标框选出检测框右侧填写对应的文本内容。对于旋转文本可以用滚轮调整框的角度这个功能对发票、证件类图片很实用。标注完成后注意界面上有两个导出按钮一个导出检测结果一个导出识别结果。这两个功能别搞混了检测结果导出的是文本框坐标识别结果导出的是框内文字内容。对应生成的文件分别是Label.txt和rec_gt.txt。3.2 两个标签文件的作用Label.txt是检测任务的标签每一行包含图片路径和检测框坐标信息格式大致是OCR/ALL_1206/img/001.jpg [{transcription: 文本内容, points: [[x1,y1],[x2,y2],[x3,y3],[x4,y4]]}]rec_gt.txt是识别任务的标签格式更简单图片路径加上文本内容。PaddleOCR 的 rec 模型训练只关心「这个图片里是什么字」不关心字的位置所以 rec_gt.txt 不需要坐标信息。生成的标签文件默认在图片目录下如果你把标注结果导出到了其他位置后面配置 YML 时记得对应调整路径这一步很多人会忘。3.3 数据集划分脚本的参数修改训练检测模型和识别模型需要不同的数据划分。官方提供gen_det_train_val_test.py来划分检测数据集先用编辑器打开这个脚本修改输入输出路径参数python gen_det_train_val_test.py脚本会读取标注好的全部数据按比例划分成三份train.txt、val.txt、test.txt。里面有几个关键参数det_label_path指向检测标签文件output_dir是生成文件的输出目录train_ratio、val_ratio、test_ratio是划分比例我一般用 7:1.5:1.5数据量小的话可以用 8:1:1。注意划分完检测数据集后识别数据集的划分不能直接用同一个脚本要改用gen_rec_follow_det.py。因为这个脚本的逻辑是根据检测数据集划分的结果把检测框对应的图像区域裁剪出来生成识别模型的训练数据。python gen_rec_follow_det.py这个脚本执行完会生成rec_train.txt和rec_test.txt同时会把裁剪后的文本行图片保存到指定目录。原作者只分了训练集和测试集如果你需要验证集可以自行在脚本里加一段划分逻辑按照gen_det_train_val_test.py的划分比例复制一份即可。这一步是整个流程里最容易出问题的地方gen_rec_follow_det.py里有一个参数crop_img_dir它决定裁剪后的图片存到哪里。很多人在 YML 配置阶段发现图片路径对不上就是在这里没有统一好目录。我建议把裁剪图片统一放在./OCR/ALL_1206/crop_img这样的路径下后面配置识别模型时直接引用这个相对路径。4. YML 配置详解ch_PP-OCRv3_det_cml_myself.yml 的每一行4.1 复制官方配置并理解核心字段PaddleOCR 2.6 的模型训练全部通过 YML 文件控制官方在configs/det/ch_PP-OCRv3/目录下提供了一系列配置模板。我拿ch_PP-OCRv3_det_cml.yml举例建议你先复制一份再改名保留官方原文件cp configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml.yml configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml打开这个文件你最先看到的是Global段。这一段里最核心的配置是pretrained_model和save_model_dir。pretrained_model指定预训练模型的路径官方下载的预训练权重放在项目根目录的pretrain_models/下。注意这里填的是权重文件的路径前缀不需要带.pdparams后缀PaddleOCR 会自动匹配。还有几个值得关注的字段字段默认值说明epoch_num600总训练轮数save_model_dir./output/训练权重保存目录save_epoch_step10每隔多少轮保存一次权重eval_period10每隔多少轮验证一次4.2 train 和 Eval 的路径配置逻辑这是配置里最容易翻车的部分。检测模型训练用的train.txt里面的图片路径如果是绝对路径那么 YML 里只需要配置label_file_list指定标签文件路径不需要再写图片目录但如果是相对路径就还需要配置data_dir来拼接图片所在的根目录。以检测模块为例train.txt里的图片路径是OCR/ALL_1206/img/001.jpg这是一个相对路径所以 YML 里data_dir需要配置为项目根目录也就是./。PaddleOCR 在读取数据时会把data_dir和标签里的路径拼接成完整路径。识别模块的情况不一样。rec_train.txt里的图片路径对应的是裁剪后的文本行图像比如./OCR/ALL_1206/crop_img/001_0.jpg这里路径本身就带上了./OCR/ALL_1206/crop_img前缀所以 YML 里data_dir可以直接留空或者只填./。判断标准很简单data_dir label中的路径 实际存在的图片路径能拼出来就对了。4.3 batchsize、eval 间隔与训练效率的平衡batchsize在Train和Eval两个子配置里分别设置。一个容易踩的坑是batch_size不能超过输入训练图或验证图的数量。比如你验证集只有 8 张图batch_size却是 16那 eval 阶段就会直接报错终止。小数据集场景下我一般把batch_size设为 4 到 8可以关注 GPU 显存利用率再做调整。eval_period设置为 10 的意思是每 10 步验证一次。别看它叫 period单位是迭代步数而不是 epoch。验证时会计算精度自动保留最高精度的权重存为best_accuracy。这里我建议你对save_epoch_step保持默认或者干脆调大一点因为每几个 epoch 保存一次权重会产生大量中间文件一个 600 轮的训练跑下来能占好几个 GB 的磁盘空间。我一般在配置里把save_epoch_step设为 50同时依赖 eval 机制自动保存最优权重这样最终只需要关心best_accuracy那个文件就够了。YML 配置完成后可以用一个简单的方法验证路径是否正确python tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml如果路径配错了程序会在读取数据阶段报FileNotFoundError或者AssertionError: file not found这时不用等训练跑起来看到这个错误就能去检查data_dir和label_file_list的拼接了。5. 训练、验证与导出推理模型export_model 的预训练权重坑5.1 训练与指定预训练权重的两种方式训练直接跑tools/train.pypython tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml这个命令会从 YML 文件的Global.pretrained_model读取预训练权重路径。如果你需要指定一个不同的预训练权重可以在命令行用-o参数覆盖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参数是 PaddleOCR 提供的命令行覆盖机制格式是配置段.字段名值可以覆盖任意 YML 配置不用改文件。注意命令行覆盖只对当前这次执行生效不会写回 YML 文件。训练过程中日志里每轮会输出loss、lr、elapse等指标loss 持续下降说明训练正常。训练完成后权重会保存在 YML 配置的save_model_dir目录下其中best_accuracy.pdparams是验证精度最高的权重latest.pdparams是最近一步的权重。5.2 用 eval.py 验证指定权重验证阶段使用tools/eval.pypython tools/eval.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml -o Global.checkpointsD:/model/PaddleOCR-release-117/PaddleOCR-release-2.6/output/ch_PP-OCR_v3_det_1206/best_accuracy这里的Global.checkpoints指定用于验证的权重文件路径不带.pdparams后缀。eval.py输出检测模型的精度指标 hmean这个值代表检测和识别综合效果。如果你的数据集和官方数据集差异比较大第一次验证 hmean 低于 0.5 很正常关键看训练过程中有没有逐步提升。另外说明一点训练的最佳权重路径通常是output/xxx/best_accuracy。因为 eval 机制会持续更新保存最优结果所以最终训练完只需要认准best_accuracy这个文件。5.3 导出推理模型容易翻车的传参 bug导出推理模型这一步有个官方文档没强调的坑直接用命令行覆盖Global.pretrained_model导出大概率导出的还是预训练权重而不是你训练好的权重。原教程里也明确提到export_model.py对Global.pretrained_model的传参处理有问题命令行传进去的值不起作用。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-117/PaddleOCR-release-2.6/output/ch_PP-OCR_v3_det_1206/best_accuracy -o Global.save_inference_dir./inference/det_cml_ppocrv3_1206我把这条命令贴出来是想告诉你如果你直接执行它最后导出的模型很可能还是官方预训练权重的行为表现而不是你微调之后的效果。原因是export_model.py内部读取权重的方式和train.py不同命令行覆盖参数没有正确传递到权重加载逻辑里。解决方式很粗暴但有效把你训练好的权重路径直接写进 YML 文件的Global.pretrained_model字段然后再次执行导出命令。这样读取的就是训练好的权重python tools/export_model.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml -o Global.save_inference_dir./inference/det_cml_ppocrv3_1206注意比较这两条命令区别只在于是否用-o覆盖pretrained_model。这个坑我一开始也踩了导出后用测试集预测发现检测效果和预训练模型一模一样最后才发现是权重加载没生效。从那以后我导出前都会先确认 YML 里pretrained_model字段指向的是output/下的训练权重而不是pretrain_models/下的官方权重。5.4 常见问题排查清单以下是这个阶段我遇到过并且有明确解法的问题按「现象 → 原因 → 解决」的顺序梳理现象 1训练时 loss 下降很快但验证精度不涨原因训练集和验证集的分布差异过大或者验证集的标签格式有误。解决检查val.txt的格式和train.txt是否一致特别是坐标点的顺序再看图片是否全部能正常读取。现象 2eval 阶段报batch_size超限原因验证集图片数量小于batch_size。解决把 Eval 配置里的batch_size调小或者往验证集里补充图片。现象 3导出推理模型后预测输出明显不对原因极可能是导出时加载了预训练权重而不是微调权重。解决按 5.3 小节的方式把训练好的权重路径写进 YML 再导出导出的inference目录下应该有inference.pdmodel和inference.pdiparams两个文件。现象 4识别模型和检测模型串联时报模型文件缺失原因检测和识别的推理目录分别设置但predict_system.py默认找的是./inference下特定命名的目录。解决确保--det_model_dir和--rec_model_dir指向能对上或者把导出的模型重命名成官方默认名称。6. 装完怎么验证跑通predict_system.py 串联推理全流程6.1 导出检测和识别两个推理模型验证前的准备工作是把两个模块的推理模型都导出。检测模型按 5.3 小节的方式导出到./inference/det_cml_ppocrv3_1206/目录。识别模型的导出同理识别模块的训练权重在output/下有对应的目录导出命令参考python tools/export_model.py -c configs/rec/ch_PP-OCRv3/ch_PP-OCRv3_rec_distillation.yml -o Global.pretrained_modelD:/model/PaddleOCR-release-117/PaddleOCR-release-2.6/output/rec_ppocr_v3_distillation_1206/best_accuracy -o Global.save_inference_dir./inference/rec_ppocr_v3_distillation_1206导出完成后检查inference/det_cml_ppocrv3_1206/和inference/rec_ppocr_v3_distillation_1206/目录下是否都生成了推理模型文件。识别模型如果使用了蒸馏训练方式模型文件中可能区分Student和Teacher两个子目录串联时使用Student版本即可教师模型只用于训练阶段。6.2 串联预测命令与结果验证一切就绪后用官方提供的predict_system.py做端到端验证。这个脚本会依次执行文本检测、方向分类、文本识别三个步骤输入一张图片输出检测框和识别文字python tools/infer/predict_system.py --image_dirD:/model/PaddleOCR-release-117/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几个参数的说明--image_dir可以是单张图片路径也可以是一个目录目录下所有图片都会被批量处理--det_model_dir指向检测模型的单模型目录。注意如果你的导出目录下直接就是推理模型文件就不需要加/Student后缀--rec_model_dir指向识别模型的目录规则同上分类模型的--cls_model_dir如果没配置默认会用官方在线的分类模型权重建议也导出本地模型并指定路径避免依赖外网下载执行完成后控制台会逐张打印检测框坐标和识别结果。我用一个简单标准判断是否跑通测试集里选取文字清晰、背景简单的图片如果识别文本和真实内容一致率能达到 90% 以上说明全流程没问题。另外predict_system.py支持--save_result和--output参数把可视化结果保存到本地目录生成带框标注的图片。我会把这些可视化图片打开快速扫一遍看检测框是否贴合文字区域这是判断模型推断效果最直观的方式。从那以后我每次装完一套 OCR 环境都强制自己走一遍「标注 → 划分 → 训练 → 导出 → 串联预测」的完整流程而不是只跑通训练就结束。因为真正判断环境是否可用的标准是最后的推理链路能否输出正确结果。这个流程走完后面再迁移到其他机器、换数据集都能顺着这条路快速复现。希望这篇基于 2.6 版本的安装记录能帮你把 PaddleOCR 跑通少走几步弯路。本文还有配套的精品资源点击获取