简介面向想要快速上手深度学习OCR训练的开发者与初学者这份docx教程梳理了PaddleOCR 2.6版本从环境搭建到模型推理的完整操作流程涵盖GPU版框架安装、PyYAML与分类组件配置以及使用PPOCRLabel标注生成识别与检测标签的方法。文中还讲解了数据集划分、YML文件中预训练模型路径、批大小、验证路径等关键参数的设置思路。资源共1个docx文件包体仅78KB内容按环境配置、标签生成、数据划分、训练验证、推理导出等阶段组织并配有训练、验证、导出及串联预测的命令示例适合正在搭建检测模型或准备微调训练的动手型读者对照参考。目前已有1307人浏览学习笔记特别提示了导出推理模型时预训练权重传参失效、需直接写入YML文件的常见坑这些实战细节能帮助读者少走弯路。1. PaddleOCR 2.6 的完整闭环不只看预训练模型还要自己训练微调很多人把 OCR 当成一个开箱即用的工具——装个预训练模型传张图识别不准就换模型。但到了具体场景比如票据、工单、某个业务系统的截图预训练模型往往撑不住必须用自己的数据微调检测和识别两个模型。PaddleOCR 2.6 把这条路从环境到推理串成了完整闭环标注、划分数据集、改配置、训练、验证、导出推理模型、串联预测。这篇文章按我实际跑通一套流程的顺序讲适合已经入过深度学习、有标注数据但没理顺训练链路的人新手照着命令走也能复现熟手重点看中间的参数边界和导出那个隐藏 bug。2. 环境配置不是一次 pip install虚拟环境、镜像源与版本对应2.1 从零搭一套可复现的 PaddleOCR 环境我习惯先把虚拟环境建好再装依赖避免把系统 Python 弄乱。PaddleOCR 2.6 完整流程依赖仓库里的tools/、configs/、PPOCRLabel/目录所以建议直接拉 release/2.6 分支的代码然后在仓库根目录下操作。常见的做法是用 conda 建独立环境conda create -n PaddleOCR python3.9 -y conda activate PaddleOCR python -m pip install paddlepaddle-gpu -i https://pypi.tuna.tsinghua.edu.cn/simple pip install pyyaml pip install paddleocr2.6.0.3 pip install paddleclas2.4.3这里的安装顺序有讲究。paddlepaddle-gpu是深度学习计算底座它和paddleocr的版本有对应关系。如果先装paddleocr再回头补 GPU 版 paddle版本不匹配时容易出现算子找不到或 CUDA 加载失败。pyyaml是配置文件解析依赖这个包很基础但经常被漏掉漏装时会报No module named yml我在 2.6 环境里见过好几次这个报错装完就能解决。paddleocr2.6.0.3是官方打好包的 pip 库直接提供预测接口后面串联推理时可以直接调用。paddleclas2.4.3是分类组件PPOCRLabel 自动标注时会用它判断文本方向。如果网络状况不太好-i参数可以换成延迟更低的国内 pypi 镜像核心是装完一定要做一次自检python -c import paddle; paddle.utils.run_check()出现PaddlePaddle is installed successfully说明 GPU 版 paddle 已经能正常调用 CUDA。这一步最好不要跳后面训练时如果发现实际在 CPU 上跑日志里能看到明显偏慢回头查安装最省时间。2.2 版本对应关系与常见安装翻车点PaddleOCR 2.6 有两个容易混淆的概念一个是 GitHub 上的完整工程仓库包含训练、验证、导出、标注全套脚本另一个是pip install paddleocr装的 Python 包只带预测接口不带tools/train.py。训练微调必须用仓库代码直接用 pip 包跑python tools/train.py会报找不到模块。我一开始也在这个地方卡过后来固定从仓库根目录跑训练相关命令pip 包只用来做快速预测。各组件版本与用途可以按下面这个对应关系梳理组件版本要求作用paddlepaddle-gpu与本地 CUDA 匹配深度学习运行时训练和推理的计算底座paddleocr2.6.0.3官方打包 OCR 预测库含检测识别方向分类paddleclas2.4.3文本方向分类PPOCRLabel 自动标注依赖PyYAML任意较新版本解析训练用 yml 配置文件paddlepaddle-gpu的安装需要注意本地 CUDA 版本装之前用nvidia-smi查一下驱动支持的 CUDA 版本再选择对应标签的安装包。虚拟环境里 Python 版本推荐 3.9PaddleOCR 2.6 分支对 3.8 到 3.10 都兼容但 3.9 遇到问题最少。如果装完paddleocr后想确认版本可以用pip show paddleocr paddleclas查看避免装到旧版的坑。3. 数据准备的核心PPOCRLabel 自动标注与两套划分脚本3.1 PPOCRLabel检测和识别标签是两份不同的产物数据准备是 OCR 微调里最耗时的一步。PPOCRLabel 是官方配套的标注工具进入仓库的 PPOCRLabel 目录装依赖后启动图形界面cd PPOCRLabel pip install -r requirements.txt python PPOCRLabel.py --lang ch--lang ch是让界面显示中文从文件菜单打开图片目录后右侧会自动跑一遍检测和识别的预标注结果。预标注由预训练模型完成人工只需要修正框的位置和文字内容效率比纯手工标注高很多。标注完点击导出会生成rec_gt.txt和Label.txt两个文件。rec_gt.txt是识别标签每行格式为“图片路径 Tab 转义后的文本”给识别模型训练用。Label.txt是检测标签每行格式为“图片路径 Tab 检测框四点坐标 文本内容 难度标记”给检测模型训练用。两份产物内容完全不同后面配置训练时要分别指定不能混用。标注质量直接决定模型上限框歪一点、文字漏几个字收敛后精度就上不去这一环节值得花时间。3.2 划分数据集检测和识别要分开划分别共用一份 train.txt标注完不能直接开训。官方仓库里带了两个划分脚本gen_det_train_val_test.py负责检测数据集划分gen_rec_follow_det.py负责让识别数据集跟随检测的划分结果。先把两个脚本用编辑器打开修改头部路径常量和划分比例再依次执行python PPOCRLabel/gen_det_train_val_test.py python PPOCRLabel/gen_rec_follow_det.py第一个脚本生成train.txt、val.txt、test.txt里面对应的是标注全图路径和检测框信息。第二个脚本生成rec_train.txt、rec_test.txt指向标注工具自动裁剪出来的文字区域小图。为什么识别要跟随检测划分因为识别模型的输入是检测框裁剪出来的小图如果两套数据各自随机划分训练集和测试集中的裁剪图可能来自同一张原图评估结果会虚高看不出来真实水平。这里引出一个贯穿后续配置的关键规则检测数据的图片路径已经写死在train.txt里所以 YML 配置里只填train.txt的路径就行识别数据的裁剪图片路径是相对的需要在配置里单独补data_dir指向实际存放裁剪图的目录。这个“检测填 txt 路径、识别补 data_dir”的差别是新手配置最容易翻车的地方。划分完可以用wc -l查看生成的 txt 行数确认跟标注数量对得上。4. YML 配置与训练pretrained_model、eval_step 和 batchsize 怎么设4.1 照着官方检测配置改出自己的 YML官方configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml.yml是带蒸馏结构的检测配置。我通常拷贝一份改成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: 100 eval_batch_step: [0, 10] cal_metric_during_train: true Train: dataset: data_dir: ./ label_file_list: [./train.txt] batch_size_per_card: 8 drop_last: true num_workers: 4 Eval: dataset: data_dir: ./ label_file_list: [./val.txt] batch_size_per_card: 4 drop_last: false这里几个参数值得细说。pretrained_model是训练起点可以初始指向官方预训练权重也可以像我一样在中途指向自己训出来的best_accuracy继续训练。batch_size_per_card与显卡显存相关显存不够就调小。eval_batch_step: [0, 10]的意思是前 0 步开始每 10 个训练 step 做一次验证每次验证后自动保留精度最高的best_accuracy权重。save_epoch_step是每隔多少 epoch 保存一次权重不必设得太小否则权重文件堆满磁盘。ch_PP-OCRv3_det_cml.yml是 CML 蒸馏结构训练时同时优化 Teacher 和 Student导出推理时选 Student。识别配置同理官方configs/rec/ch_PP-OCRv3/ch_PP-OCRv3_rec_distillation.yml里改法一致只是标签文件要换成rec_train.txt和rec_test.txt并且需要额外指定data_dir为裁剪图的存放目录。4.2 启动训练日志里看什么Loss 降到多少算能用配置改好后从仓库根目录执行python tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml如果要临时换预训练权重继续训练可以用-o参数覆盖 YML 里的配置python tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml -o Global.pretrained_modelpretrain_models/best_accuracy启动后先看日志里的 device 信息确认是 GPU 训练再离开。训练过程中主要看 loss 变化检测模型 loss 能稳步下降即可不必过分纠结绝对数值最终以验证集上的精确率、召回率和 Hmean 为准。如果遇到显存溢出把batch_size_per_card调小batchsize 过大不仅会 OOM还会影响 BatchNorm 层的统计。验证参照官方评测命令执行python tools/eval.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml -o Global.checkpointsD:/models/ch_PP-OCR_v3_det_1206/best_accuracy训练结束后会在output目录下找到best_accuracy权重目录。识别模型的训练流程与检测完全一致把配置换成识别那份 yml 即可两边都训完才能做串联推理。5. 训练链路里绕不开的坑五条实测踩坑记录5.1 batchsize 大于训练图数量启动就报错现象训练命令跑起来后快速报 IndexError或者数据加载进度一直不动。原因batch_size_per_card设置过大超过了训练集总张数配合drop_last: true后数据集被丢弃为空。解决调小 batchsize同时核对train.txt的行数和路径是否真实存在路径写错也会导致读不到数据。5.2 eval 太频繁权重文件把磁盘塞满现象训练一晚上output 目录多出几十 GB 权重最后不知道该用哪个。原因save_epoch_step设得太小每个 epoch 都存一份完整权重。解决优先依靠eval_batch_step让脚本自动保留best_accuracy把save_epoch_step设大或者干脆不依赖定期保存的权重。5.3 验证时指定了 checkpoints 却不生效现象eval.py用-o Global.checkpoints.../best_accuracy跑完精度还是初始值。原因多配置文件场景下命令行-o参数的覆盖优先级低于 YML 内部某些字段。解决直接把Global.checkpoints写进 YML 文件再执行验证或者确认命令行传的路径指向具体的权重文件而不是整个权重文件夹。5.4 识别准确率怎么调都上不去现象训练 loss 收敛了串联推理时文字还是错一堆。原因rec_gt.txt里的特殊字符没有正确转义或者标注时把空格、标点删了导致模型字典对不上。解决打开rec_gt.txt抽查文本内容确认与字典文件一致长尾特殊字符要么补进字典要么在标注阶段清洗掉。5.5 pip 装的 paddleocr 和仓库 tools 脚本混用现象装完paddleocrpip 包直接跑python tools/train.py报找不到模块。原因仓库里的 tools 脚本依赖仓库内部源码路径pip 包不带完整训练脚本。解决训练、验证、导出统一从 release/2.6 仓库根目录跑pip 包只用于快速预测不要混着用。6. 导出推理模型的隐藏 bugpretrained_model 失效与串联预测6.1 先改 YML 再导出绕过 pretrained_model 传参失效我踩过的最大一个坑在导出环节。直接执行下面的命令命令行里的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:/models/ch_PP-OCR_v3_det_1206/best_accuracy -o Global.save_inference_dir./inference/det_cml_ppocrv3_1206原因是对export_model.py来说-o方式覆盖pretrained_model不生效。正确做法是把训练后的权重直接写死在 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导出完成后inference/det_cml_ppocrv3_1206目录下会有Student和Teacher两个子目录推理时用Student目录即可里面是inference.pdmodel和inference.pdiparams两个文件。识别模型导出方式相同。6.2 用 predict_system.py 把检测和识别串起来两个模型都导出后用官方推理脚本串联python tools/infer/predict_system.py \ --image_dirD:/data/OCR/ALL_1206/test \ --det_model_dir./inference/det_cml_ppocrv3_1206/Student \ --rec_model_dir./inference/rec_ppocr_v3_distillation_1206/Student \ --save_res_path./output/predict_result--det_model_dir和--rec_model_dir分别指向检测和识别的导出目录脚本会先让检测模型拿到文本框再裁剪出文字区域送给识别模型最后在保存路径下生成带框带文字的可视化图。第一次跑建议先拿一两张图验证确认框的位置和文字识别没问题再整目录推理。从那以后我每次导出前都强制检查一遍 YML 里的pretrained_model是否指向训练后的权重再确认 Student 目录下两个文件都在这套流程就很少再翻车了。希望帮到你。本文还有配套的精品资源点击获取