简介这份资源是面向深度学习OCR入门与进阶开发者的PaddleOCR 2.6版本实操教程文档针对环境配置繁琐、标签生成与数据集划分流程不清、YML参数配置易出错等常见痛点提供从零跑通检测与识别全流程的参考方案。资源包内共1个docx文档压缩包约78KB以图文步骤形式组织内容便于按章节检索与对照操作。教程覆盖虚拟环境搭建、PPOCRLabel自动标注与标签导出、检测与识别数据集划分脚本、YML文件关键参数配置、模型训练与验证命令、推理模型导出及串联预测等环节并特别记录了export_model加载预训练权重失效的排错思路提示需将训练后权重直接写入YML的pretrained_model字段。目前已有1304人学习下载适合希望快速掌握PaddleOCR 2.6训练部署流程、减少踩坑时间的中高级开发者参考。1. 从装环境到跑通推理PaddleOCR 2.6 这套流程到底值不值得跟如果你手上有一批中文票据、表格或者工业铭牌图片想自己训一个检测识别模型又不想从零搭训练框架PaddleOCR 2.6 大概率是你绕不开的一个版本。它把检测、识别、方向分类三个模块拆得比较清楚配置文件是 yml训练入口是tools/train.py推理入口是tools/infer/predict_system.py整条链路是通的。但真正上手你会发现官方 quickstart 只告诉你「怎么装」没告诉你「标签怎么串、数据集怎么切、yml 里哪些字段必须改、导出推理模型为什么会加载错权重」。这篇笔记就是把我自己从零跑通 2.6 版本的过程拆开包括 PPOCRLabel 标注、检测集和识别集的联动划分、yml 参数落点、训练验证命令以及那个导出模型时Global.pretrained_model传不进去的坑。适合已经会 Python、装过 CUDA 环境、想拿自己数据微调检测或识别模型的从业者纯新手建议先把虚拟环境和 pip 装包跑顺再往下看。2. 环境配置与 PPOCRLabel 标注把依赖装对把标签生成对2.1 虚拟环境与依赖安装的先后顺序PaddleOCR 2.6 对环境比较敏感尤其是 paddlepaddle-gpu 和 paddleocr 这两个包的版本要对齐。我一般会新建一个干净的虚拟环境避免和系统里已有的 paddle 冲突。进入代码目录的终端后按下面顺序装# 新建并激活虚拟环境名字随意这里叫 PaddleOCR python -m venv PaddleOCR # Windows 下激活 PaddleOCR\Scripts\activate # Linux/macOS 下激活 source PaddleOCR/bin/activate # 先装 GPU 版 paddlepaddle走百度镜像会快很多 python -m pip install paddlepaddle-gpu -i https://mirror.baidu.com/pypi/simple # 装项目根目录下的依赖 pip install -r requirements.txt # 补一个容易漏的 PyYAML不装后面读 yml 会直接报 module yaml 找不到 pip install PyYAML # 装官方打包好的 paddleocr版本要 2.6.0.3 pip install paddleocr2.6.0.3 # 分类组件做方向分类或者后续串联推理会用到 pip install paddleclas2.4.3这里有几个参数点值得说清楚。paddlepaddle-gpu不指定版本时默认拉最新但 PaddleOCR 2.6 对应的 paddle 版本建议在 2.4 左右如果你装完 import paddle 报 CUDA 相关错误先python -c import paddle; paddle.utils.run_check()看输出。requirements.txt里有些包是训练和标注共用的比如 shapely、pyclipper装的时候如果卡在编译优先用镜像源。PyYAML这个包名字是 yaml但 pip 包名是 PyYAML很多人第一次跑tools/train.py报ModuleNotFoundError: No module named yaml就是漏了它。提示如果你用的是 Windows虚拟环境激活命令是PaddleOCR\Scripts\activate不是source别照搬 Linux 命令。2.2 PPOCRLabel 标注与标签文件生成环境装好后下一步是标注。PaddleOCR 自带的 PPOCRLabel 是一个半自动标注工具能先跑一遍检测和识别你只需要修正框和文字比纯手拉框快很多。进入 PPOCRLabel 目录后cd PPOCRLabel pip install -r requirements.txt # 启动中文标注界面 python PPOCRLabel.py --lang ch启动后界面里可以打开图片文件夹点「自动标注」它会调用内置模型先出一版结果你逐张修正。标注完成后通过菜单导出标记结果和识别结果会在输出目录生成两个关键文件Label.txt是检测标签格式是图片路径\t[{transcription: 文字, points: [[x1,y1],...]}]rec_gt.txt是识别标签格式是图片路径\t文字。这两个文件是后面划分数据集和配 yml 的基础路径一定要记清楚。这里有个容易翻车的点PPOCRLabel 导出的Label.txt里图片路径可能是相对路径也可能是绝对路径取决于你打开文件夹的方式。后面gen_det_train_val_test.py读这个文件时如果路径对不上生成的 train.txt 里图片路径就是错的训练时直接报找不到图。我一般会在导出后先head Label.txt看一眼路径格式确认是相对还是绝对再决定脚本里怎么拼。3. 数据集划分与 yml 配置检测集和识别集怎么联动3.1 检测数据集划分脚本的参数落点PPOCRLabel 目录下有两个划分脚本gen_det_train_val_test.py负责按检测标签划分gen_rec_follow_det.py负责让识别集跟着检测集走。先改检测划分脚本# gen_det_train_val_test.py 里主要改这几个参数 # 输入PPOCRLabel 导出的 Label.txt # 输出train.txt / val.txt / test.txt # 划分比例一般 8:1:1 或 7:2:1 train_ratio 0.8 val_ratio 0.1 test_ratio 0.1 # 标签文件路径指向你导出的 Label.txt label_file Label.txt # 输出目录 output_dir ./执行后会生成train.txt、val.txt、test.txt每个文件里每行是图片路径\t标注json。这里的关键是划分比例要和你实际数据量匹配如果总共只有几百张图test 集太小评估没意义可以只分 train 和 val把 test 合并进 val。3.2 识别集跟随检测集划分识别集不能自己随机分否则会出现同一张图在检测训练集里、却在识别测试集里的数据泄漏。gen_rec_follow_det.py就是解决这个问题的# gen_rec_follow_det.py 里主要改这几个参数 # 输入rec_gt.txt识别标签和上一步生成的 train.txt / val.txt / test.txt # 输出rec_train.txt / rec_test.txt # 注意识别集划分是跟着检测集的图片列表走的 det_train_file train.txt det_val_file val.txt det_test_file test.txt rec_label_file rec_gt.txt output_dir ./执行后生成rec_train.txt和rec_test.txt。如果你只分了训练和测试脚本里可以自己改把 val 合并进 train 或 test。这一步的逻辑是先按检测集的图片列表筛选识别标签保证同一张图不会跨集。很多人忽略这一步直接对 rec_gt.txt 随机划分训出来的识别模型在测试集上虚高实际部署就露馅。3.3 yml 配置文件的关键字段以configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml为例复制一份官方配置改名后重点改这几处# 预训练模型路径不写就从零训写了就是微调 Global: pretrained_model: ./pretrain_models/ch_PP-OCRv3_det_train/best_accuracy # 训练集和验证集配置 Train: dataset: data_dir: ./OCR/ALL_1206/ # 图片根目录 label_file_list: - ./train.txt # 只需要指定 train.txt 路径 Eval: dataset: data_dir: ./OCR/ALL_1206/ label_file_list: - ./val.txt # batch size 不能超过训练图或验证图的数量 Train: loader: batch_size_per_card: 8 num_workers: 4 # 评估间隔10 步验证一次保存最高精度权重 Eval: loader: batch_size_per_card: 8几个参数说明pretrained_model指向官方预训练权重目录微调时必填从零训就注释掉。data_dir是图片根目录label_file_list里只写 train.txt 路径因为 train.txt 里每行已经带了图片相对路径PaddleOCR 会自动拼data_dir 图片路径。识别模块的 yml 里rec_train.txt里的图片路径可能是crop_img/xxx.jpg这种所以data_dir要补成./OCR/ALL_1206/让实际路径变成./OCR/ALL_1206/crop_img/xxx.jpg。batch_size_per_card如果设成 16 但训练集只有 10 张图会直接报错这个值必须小于等于数据集数量。Eval里设 10 步验证一次它会自动保存 best_accuracy不需要再设每几个 epoch 存一次否则 output 目录会堆满权重文件占存储。注意yml 里缩进是空格不能用 Tab改完最好用python -c import yaml; yaml.safe_load(open(xxx.yml))验证一下格式。4. 训练、验证与导出推理命令怎么敲权重怎么接4.1 训练与指定预训练权重训练命令本身不复杂关键是-o覆盖参数的用法# 基础训练用 yml 里配的 pretrained_model python tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml # 临时更换预训练权重-o 覆盖 Global.pretrained_model python tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml \ -o Global.pretrained_modelpretrain_models/best_accuracy-c指定配置文件-o是覆盖 yml 里的字段格式是Global.xxx值。训练过程中 output 目录会按 yml 里save_model_dir生成权重best_accuracy 是验证集精度最高的那个。如果训练 loss 一直不降先看 pretrained_model 路径对不对再看学习率是不是太大检测任务一般 0.001 起步。4.2 验证指定权重验证时要显式指定用哪个权重否则默认加载 yml 里的配置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_accuracyGlobal.checkpoints指向不带后缀的权重前缀PaddleOCR 会自动找.pdparams。验证输出的 precision、recall、hmean 是检测任务的核心指标hmean 低于 0.8 基本说明标注质量或数据量有问题。4.3 导出推理模型的坑导出推理模型这一步有个血泪经验直接敲官方命令Global.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.pretrained_modelD:/model/.../best_accuracy \ -o Global.save_inference_dir./inference/det_cml_ppocrv3_1206正确做法是直接把训练后的权重路径写进 yml 的pretrained_model字段再执行导出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_1206python tools/export_model.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml导出后会生成inference/det_cml_ppocrv3_1206/Student/inference.pdmodel和inference.pdiparams。识别模型同理导出目录里会有 Student 子目录串联推理时 det_model_dir 和 rec_model_dir 都要指到 Student 这一层。4.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--image_dir可以是单张图也可以是文件夹--det_model_dir和--rec_model_dir分别指向检测和识别的推理模型目录。跑完会在./inference_results/下生成带框和文字的图片。如果结果框位置对但文字乱检查识别模型的字典文件ppocr_keys_v1.txt是否和训练时一致。5. 避坑与排查这几处翻车点我替你踩过了5.1 报 No module named yaml现象装完 requirements.txt 后跑训练直接报ModuleNotFoundError: No module named yaml。 原因requirements.txt 里没有把 PyYAML 列进去或者装的时候被跳过。 解决pip install PyYAML装完python -c import yaml确认不报错。5.2 训练报图片路径找不到现象train.py 启动后报FileNotFoundError路径里出现重复拼接或缺失目录。 原因data_dir和 label 文件里的图片路径拼接后对不上常见于识别集rec_train.txt里是crop_img/xxx.jpg但data_dir没补到正确层级。 解决打开 train.txt 看第一行图片路径再手动拼data_dir 该路径确认文件真实存在。识别任务的data_dir要指到 crop_img 的上一级。5.3 batch_size 超过数据集数量现象训练一开始就报batch_size_per_card相关错误或者 loss 直接 NaN。 原因yml 里 batch_size 设成 16但训练集只有 10 张图。 解决把batch_size_per_card改成小于等于数据集数量小数据集建议 2 或 4配合梯度累积。5.4 导出推理模型加载错权重现象导出命令执行成功但推理结果和训练时验证结果差很多。 原因export_model.py的-o Global.pretrained_model覆盖不生效实际加载的是 yml 里原来的预训练权重。 解决把训练后的 best_accuracy 路径直接写进 yml 的pretrained_model再执行导出不要依赖命令行-o。5.5 验证时 checkpoints 路径写错现象eval.py 报找不到权重文件。 原因Global.checkpoints写成了带.pdparams后缀的完整文件名或者路径里用了反斜杠在 Linux 下不识别。 解决Global.checkpoints只写到权重前缀不带后缀路径统一用正斜杠Windows 下也建议用/。6. 进阶技巧用蒸馏配置和评估曲线判断模型是否值得上线PaddleOCR 2.6 的ch_PP-OCRv3_det_cml.yml本身就是一个蒸馏配置Student 和 Teacher 两个模型一起训导出时只取 Student。如果你数据量不大直接用这个配置微调比单模型更容易收敛。我一般会在训练时盯两个东西一是Eval输出的 hmean 曲线二是导出推理后拿测试集跑一遍predict_system.py对比训练日志里的精度。如果推理精度比验证精度低超过 5 个点大概率是导出权重接错了回去检查 yml 里的pretrained_model。另一个实用技巧是识别模型的字典对齐。训练时用的ppocr_keys_v1.txt如果和推理时predict_system.py默认加载的字典不一致识别结果会变成乱码。我习惯在导出识别模型后把训练用的字典文件复制到推理模型目录并在predict_system.py里显式指定--rec_char_dict_path。这样即使换机器部署也不会因为字典路径问题翻车。评估检测模型时不要只看 hmean还要看 recall。如果 recall 明显低于 precision说明漏检多可能是标注框太松或者训练轮次不够。识别模型则看准确率如果某些字符总是错检查训练集里这类字符的样本量必要时用 PPOCRLabel 补标。从那以后我每次导出推理模型都强制走一遍「yml 写死权重 → 导出 → 测试集推理 → 对比验证精度」这个流程不再偷懒用命令行-o覆盖。希望帮到你。本文还有配套的精品资源点击获取