★ FEATURED ARTICLE 简介该资源是一份面向 PaddleOCR 2.6 初学者的完整操作笔记以检测模型为主线覆盖环境配置、PPOCRLabel 标注、数据集划分、YML 参数调整、训练验证与推理模型导出等完整流程也适合正在搭建 OCR 识别任务、需要快速跑通全流程的开发者参考。文档基于实际项目整理包含多处踩坑提醒例如导出推理模型时 pretrained_model 参数无法直接传入、需将训练后权重写入 YML 文件以及 batch_size 与 eval 验证步数等容易出错的细节。资源为 1 个 docx 文件压缩包大小约 78KB内容紧凑、步骤清晰可直接对照执行。已有 1307 人学习下载对于不想反复查阅官方文档、希望获得中文实操指引的 PaddleOCR 使用者来说是一份省时省力的入门参考。1. 先把 PaddleOCR 2.6 这趟流程透个底说到 OCR 技术PaddleOCR 2.6 这一套几乎成了国内做文字检测加识别绕不开的方案。要做一个票据、卡证或者车牌的识别项目调研一圈下来十有八九都会落到这套代码上。我这回按 PaddleOCR 2.6 的完整流程走了一遍从配环境、用 PPOCRLabel 打标签、切分数据集、改 yml到训练、验证、导出推理模型中间埋了好几个坑。最典型的两个一个是跑 PPOCRLabel 时报缺 yml 模块实际是 PyYAML 没装另一个是 export_model.py 导出时命令行传预训练权重传不进去绕法是把权重写进 yml 文件里。这两处如果没人提前说新手各自卡半天很正常。这篇适合正准备训练自己的检测识别模型、又不想在环境问题上反复折腾的人照着流程走能省下大量试错成本。2. 配置 PaddleOCR 环境虚拟环境、GPU 安装与版本匹配PaddleOCR 2.6 要跑起来核心依赖是 paddlepaddle-gpu、PyYAML、paddleocr 和 paddleclas。顺序装错或者版本没对齐后面训练时 import 就会挂或者界面打不开。这一章把环境从零装干净顺带说清楚每一条命令到底在干什么。2.1 新建虚拟环境避免和项目依赖互相污染我一般会先新开一个虚拟环境名字就叫 PaddleOCR。不要图省事直接装到 base 环境里因为 paddlepaddle-gpu 版本和其他深度学习框架经常打架单独隔离出来后面换版本、删环境都方便。conda create -n PaddleOCR python3.8 -y conda activate PaddleOCR创建时用 python3.8是因为 PaddleOCR 2.6 对 Python 3.8 的兼容性最稳3.9、3.10 也能跑但有些依赖编译容易出幺蛾子。conda create 里的 -y 表示遇到询问直接确认不用手动敲 y。激活成功后进入 PaddleOCR 代码文件所在目录的终端。环境名和代码目录不要求同名但建议把代码固定放在一个清晰路径下比如D:\model\PaddleOCR-release-117\PaddleOCR-release-2.6后边 yml 里的大量路径都要写到这个根目录路径统一后面排查问题会省很多事。2.2 安装 paddlepaddle-gpuCUDA 版本决定了这条命令进入代码目录后执行环境核心安装命令python -m pip install paddlepaddle-gpu -i https://mirror.baidu.com/pypi/simple这里用python -m pip而不是直接pip是为了确保安装到当前虚拟环境自带的 pip 里避免误装到系统 Python。后边-i指定的是百度镜像源国内机器下载速度快不用额外配置网络代理之类的东西。装完 paddlepaddle-gpu先别急着装下一个推荐马上验证一下 GPU 是否真的可用python -c import paddle; paddle.utils.run_check()这条命令会打印当前 paddle 识别到的 CUDA 设备和运行状态。如果输出里显示 GPU 不可用大概率是 paddlepaddle-gpu 版本和本机 CUDA 版本不匹配。常见做法是先执行nvidia-smi看本机 CUDA 版本再到 paddle 官方安装页挑对应版本的命令重新执行一遍。很多人装完不跑检查到训练时才看到device变成 CPU资料白跑那就是反复折腾的起点。接着把一个小依赖装上pip install PyYAML这一步是血泪经验。PaddleOCR 2.6 的 requirements.txt 里没有显式声明 PyYAML但运行 PPOCRLabel 时如果环境里没有 yaml 库会直接抛一个类似module yml not found的报错。很多人看到 “yml” 就以为少了某个配置文件其实只是缺 PyYAML 这个 Python 包。装一下立刻能解决。2.3 安装 PaddleOCR 与 PaddleClas官方包和源码工具的分工再装官方打包好的 PaddleOCR 和分类组件 PaddleClaspip install paddleocr2.6.0.3 pip install paddleclas2.4.3paddleocr 版本加引号并带2.6.0.3是因为从 2.6.0.3 开始官方把常用推理功能打进了 pip 包里后续串联推理直接就能用不带版本限制的话最新版接口可能有变动。paddleclas 是分类组件识别流程里部分能力依赖它版本必须大于等于 2.4.3装低了 import 时可能缺模块。装完 pip 包之后还有一步不能漏进入源码根目录执行pip install -r requirements.txt注意这个 requirements.txt 是源码自带的和 pip 包内部的依赖不是同一份。如果前面只装了 pip 包没在源码目录执行这条后面跑 tools 目录下的训练、导出脚本时可能因为缺少某些子模块直接报错。两个依赖都装齐环境才算完整。组件版本要求用途paddlepaddle-gpu与 CUDA 匹配深度学习计算框架PyYAML任意解析 yml 配置文件paddleocr2.6.0.3OCR 推理与工具链paddleclas2.4.3分类组件识别依赖3. 用 PPOCRLabel 生成标签rec_gt.txt 与 Label.txt 的来龙去脉环境只是第一步。OCR 训练最关键的是数据标注PPOCRLabel 是 PaddleOCR 自带的可视化标注工具负责把图片里的文字框出来生成后续训练要用的两个标签文件。这一章把标注启动、导出和文件格式讲清楚。3.1 启动 PPOCRLabel中文界面与自动预标注进入源码目录下的 PPOCRLabel 子目录先装标注工具自己的依赖cd PPOCRLabel pip install -r requirements.txt这里的 requirements.txt 是标注工具的独立依赖和根目录那份不一样不能跳过。装完后启动标注界面python PPOCRLabel.py --lang ch--lang ch的作用是让界面显示中文同时标注时默认走中文标签体系。第一次启动工具会自动下载用于预标注的检测模型网络不好的话这里会卡几分钟属正常现象等模型下载完再开始操作。标注界面打开后选中图片点“自动标注”工具会用预训练模型先把文字区域框出来你只需要微调框的位置、修正文本框里的内容。这一步的产出质量直接决定后续 rec_gt.txt 里识别文本的准确度所以框歪了要拖正文本错了要改对别为了赶进度把标注文本填错不然模型学出来的也是错的。3.2 导出标记结果识别标签和检测标签分开存标注完一批图后界面上有两个导出动作“导出标记结果”生成 Label.txt“导出识别结果”生成 rec_gt.txt。两个都要点不要只导其中一个。Label.txt 是检测标签每行记录图片路径和一组检测框坐标格式类似图片路径 [{transcription: 发票号码, points: [[x1,y1],[x2,y2],...]}]rec_gt.txt 是识别标签每行记录图片路径和对应的识别文本中间用制表符分隔图片路径 发票号码这两个文件默认保存在 PPOCRLabel 目录下后续划分数据集的两个脚本默认会从当前目录找它们。建议把图片整理到一个固定目录比如OCR/ALL_1206后面对 yml 配置时路径更好写也不容易把图片和标签搞混。4. 划分数据集修改两个脚本让检测集和识别集各就各位PaddleOCR 源码的 PPOCRLabel 目录下提供了两个划分脚本一个管检测数据一个管识别数据。网上很多教程让你自己写脚本其实官方这两个脚本改改参数就能用。这一章把脚本怎么改、生成文件的格式讲清楚。4.1 检测集划分生成 train.txt、val.txt 和 test.txt打开PPOCRLabel/gen_det_train_val_test.py把里面的图片路径、标签文件路径、输出文件的存放位置、划分比例改掉。脚本会根据比例把 Label.txt 里的样本随机打乱分别写进 train.txt、val.txt、test.txt。如果样本量不大可以把验证集比例调小避免训练数据被分走太多导致欠拟合。改完后执行python gen_det_train_val_test.py生成出来的三个 txt 文件每行内容是图片路径加对应的检测框坐标信息。重点在这里后续在 yml 文件里配置 Train 和 Eval 时只需要指定 train.txt 和 val.txt 本身的路径det 数据集的 data_dir 不用再补图片路径。严谨一点说det 脚本生成的图片路径如果带完整目录那 yml 里 data_dir 可以留空如果图片路径写的是相对路径才需要 data_dir 配合。具体看脚本里怎么拼路径训练时报找不到图就回头检查这里。4.2 识别集划分让 rec_train.txt 和 rec_test.txt 跟检测集对齐识别数据的划分用第二个脚本gen_rec_follow_det.py名字里的 “follow_det” 表示跟随检测集划分结果保证同一张图不会一会儿出现在训练集一会儿出现在测试集。修改时同样把标签文件路径、输出路径、划分比例改掉。执行python gen_rec_follow_det.py它会生成 rec_train.txt 和 rec_test.txt。这里有一个坑如果只分训练集和测试集脚本默认可能只生成这两个文件以后想跑 Eval 验证就会因为没有验证标签而直接跳过。我一般会在脚本里加一行输出 rec_val.txt把数据分成三段。这样训练时 Eval 环节有东西可验模型效果如何直接看数值不用靠肉眼猜。识别 txt 里的内容格式同样是“图片路径 识别文本”但这里的图片路径和检测脚本不一样它默认是相对路径。所以 yml 里必须额外配置 data_dir 来补齐根目录。举个例子rec_train.txt 里的图片路径写成crop_img/xxx.jpg实际图片在./OCR/ALL_1206/crop_img下那 yml 里 data_dir 就要指到./OCR/ALL_1206。这个相对路径设计是 PaddleOCR 的常见用法配置 yml 时会反复用到掌握这个拼接逻辑后面基本不会再为路径报错头疼。4.3 划分比例怎么选按数据量定而不是按习惯划分比例没有固定答案我常用的规则是数据量小于 500 张训、验、测按 8:1:1 偏保守验证集可以少一点数据量大于 2000 张按 8:1:1 或 9:0.5:0.5 都可以测试集保留独立的一份别让验证集和测试集混在一起。还要注意一点检测和识别两套划分要用同一个随机种子这样两边数据集对应关系一致训练时才能把检测误差和识别误差对上。5. 配置 YML 与训练验证batch_size、路径与 best_accuracy 的取舍训练配置全部集中在 yml 文件里。PaddleOCR 2.6 的检测配置文件在configs/det/ch_PP-OCRv3/目录下标准文件叫ch_PP-OCRv3_det_cml.yml。不要直接改原文件复制一份出来命名成ch_PP-OCRv3_det_cml_myself.yml以后出了问题还能拿原文件对照。这一章把配置项、训练命令和踩坑记录一次讲透。5.1 最重要的三个配置项pretrained_model、data_dir 和 batch_size用编辑器打开这个 yml重点看三个位置。第一是Global.pretrained_model指定预训练权重路径第一次训练用它加速收敛。第二是Train.dataset和Eval.dataset下的data_dir与label_file_list前者配图片根目录后者配 train.txt 和 val.txt 的路径。第三是Train.loader下的batch_size_per_card。这里有一个前面章节提过的关键点det 模块的 train.txt 路径直接写全图片路径由 txt 文件自己带rec 模块的 rec_train.txt 如果写的是相对路径data_dir 必须配成图片实际所在目录不然训练时读不到图。yml 示例里最常改的部分长这样Global: pretrained_model: ./pretrain_models/best_accuracy save_model_dir: ./output/ch_PP-OCR_v3_det_1206 eval_batch_step: [0, 10] Train: dataset: name: SimpleDataSet data_dir: ./ label_file_list: - ./PPOCRLabel/train.txt Eval: dataset: name: SimpleDataSet data_dir: ./ label_file_list: - ./PPOCRLabel/val.txteval_batch_step: [0, 10]的意思是训练到第 0 个迭代后每 10 步验证一次。这套配置下模型会自动把验证集精度最高的权重保存为 best_accuracy不需要你手动挑。batch_size 不要设置得超过输入训练图或验证图的数量否则数据加载时直接报错尤其是验证集只有几张图的时候batch_size 必须跟着调小。5.2 训练和验证train.py 与 eval.py 的参数传递配置写完后进入 PaddleOCR 根目录启动训练python tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml-c参数指定自己的 yml 文件训练会按配置里的路径加载数据并启动训练。如果临时想换预训练权重不用改 yml用-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可以覆盖 yml 里任意配置项路径用双引号包住防止 Windows 路径里的反斜杠或空格被终端解析出错。验证时用 eval.py注意它不读Global.pretrained_model而是通过Global.checkpoints指定要验证的权重python 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_accuracyWindows 下建议路径里的反斜杠写成正斜杠或者整个路径用双引号包住否则很容易被识别成转义符。验证结束后日志会输出当前权重在验证集上的精度这个数值就是后面判断要不要导出模型的核心依据。5.3 训练踩坑记录batch_size、Eval 间隔与 pretrained_model这里集中写几条实际跑流程碰到的问题按现象、原因、解决三步列出来。现象一训练一启动就报错提示 batch size 超出图片数量。原因是Train.loader.batch_size_per_card配得比训练图片总数还大。解决方法是把 batch_size 调小32 改成 8 或 4。注意检测和识别各有配置块不能只改一处。现象二训练日志里每个 epoch 保存一次权重几个 epoch 下来 output 目录塞了几十个模型文件磁盘空间告急。原因是Global.save_epoch_step和save_model_dir配得过于频繁。解决方法是开启 Eval 并让 Eval 每 10 步验证一次让模型自动保存验证集精度最高的一版权重命名成 best_accuracy。以后导出推理模型、继续训练直接找 best_accuracy 即可几乎不需要保留每个 epoch 的权重文件。现象三pretrained_model 路径写成了相对路径训练日志看起来正常但 loss 下降极慢。原因是权重没加载成功PaddleOCR 对找不到的预训练权重有一定容错不一定会立刻报错。解决方法是训练启动后先看日志前几行有没有出现 Successfully loaded parameters确认预训练权重确实被加载没看到这行就去核实路径。现象四配置文件里路径带中文目录名或 Windows 绝对路径带单反斜杠导致数据加载失败。原因是 YAML 格式里反斜杠会被转义。解决方法是统一用正斜杠分隔路径或者用双引号把整体路径包住。训练和验证都正常后剩下最后一步是导出推理模型。这一步有一个官方文档没写透的坑下一章专说。6. 导出推理模型并串联验证绕开 pretrained_model 传参 Bug训练完成后推理需要导出模型。PaddleOCR 2.6 的导出命令是 export_model.py官方文档给的典型用法是在命令行用-o传Global.pretrained_model和Global.save_inference_dir。按这个做法执行时模型加载的其实还是 yml 里写的预训练权重命令行参数没有真正传进去。绕法很简单把训练好的权重直接写进 yml 文件的Global.pretrained_model字段再跑导出。6.1 导出前先检查 yml 的 pretrained_modelexport_model.py 的参数优先级是读 yml 文件优先命令行-o传参会在这个场景下失效。所以导出前先打开 yml确认Global.pretrained_model指向的是 output 目录下训练好的 best_accuracy而不是官方预训练权重然后执行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 子目录。PaddleOCR 的蒸馏模型导出后真正用于推理的模型放在 Student 目录里配置推理路径时一定要指向它不要指父目录。6.2 串联推理predict_system.py 跑一次完整链路导出完成后用 predict_system.py 做端到端验证。这里的 det_model_dir 用导出的检测 Student 目录识别模型同理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指向识别模型的 Student 目录。跑完后终端会输出每张图的检测框坐标和识别文本同时把可视化结果写到 output 目录。验证模型跑通核心看三点第一终端日志没有报 Load model failed模型文件能被正常读入第二输出结果的检测框坐标和测试图里的文字位置对得上没有全屏框或者漏框第三识别文本顺序合理、没有乱序或漏字。三个都过检测和识别链路就算真的通了。从那次导出翻车之后我每次导出模型都强制自己先检查一遍 yml 里的pretrained_model字段确认它指向的是训练后的权重再动手命令行传参那套只当辅助手段用不再依赖。如果你也在 2.6 版本上做训练和推理建议把确认权重、导出 Student 目录、检查推理输出这三步固化成固定动作能避开大多数导出阶段的黑匣子问题。希望这一整套流程能帮到你少踩几个没必要踩的坑。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
