拓冰网站定制 
简介这份资源是面向OCR初学者与算法工程师的PaddleOCR 2.6版本实操教程文档围绕文本检测与识别全流程展开帮助读者快速搭建可复现的训练与推理环境。压缩包内共1个docx文件约78KB以图文笔记形式系统梳理了环境配置、标签生成、数据集划分、YML参数配置、模型训练验证及推理导出等关键环节并针对导出模型时预训练权重加载异常等常见问题给出了排错思路。内容覆盖PPOCRLabel标注、检测与识别数据集联动划分、ch_PP-OCRv3配置文件修改、batchsize与eval策略设置等具体细节适合希望从零跑通PaddleOCR训练链路、理解检测与识别模块衔接逻辑的读者参考。目前已有1304人学习下载可作为版本迁移与工程落地的对照笔记。1. PaddleOCR 2.6 到底能干什么从一张歪斜发票说起手里有一批用手机拍的发票角度歪、光线差、背景还带水印丢给传统 OCR 接口识别出来的文字顺序全乱金额和税额串行。这种场景下PaddleOCR 2.6 是我近两年反复回头用的方案。它把检测、方向分类、识别三段串成一条流水线中文场景的准确率在开源方案里属于第一梯队而且 2.6 这个版本把推理和训练脚本整理得比较规整新手照着跑不容易翻车。这篇教程面向两类人一类是刚接触 OCR、想在自己电脑上把 PaddleOCR 2.6 跑起来看到结果的另一类是用过旧版本、想搞清楚 2.6 的模型选型、参数配置和部署差异的。我会从环境搭建讲到推理、训练、部署把每一步的命令、参数含义和踩过的坑都摊开。整套流程不需要 GPU 也能跑通推理训练部分我会说明显存门槛。读完你应该能独立完成一次从安装到出结果的完整链路。2. 环境搭建Python、PaddlePaddle 与 PaddleOCR 的版本咬合PaddleOCR 2.6 不是一个能脱离 PaddlePaddle 单独存在的包它依赖飞桨框架的底层算子。很多人第一次装就卡在版本不匹配上报一堆libpaddle找不到或者undefined symbol的错。这一章把安装顺序和版本对应关系讲清楚。2.1 先定 Python 和 PaddlePaddle 版本PaddleOCR 2.6 官方验证过的组合是 Python 3.7 到 3.10PaddlePaddle 2.4 或 2.5。我一般用 Python 3.8 配 PaddlePaddle 2.5 的 CPU 版稳定且依赖冲突少。如果你有 NVIDIA 显卡装 GPU 版之前先确认 CUDA 版本PaddlePaddle 2.5 对应 CUDA 11.2 到 11.7cuDNN 8.2 以上。用 conda 建一个干净环境别在 base 里折腾conda create -n paddleocr26 python3.8 -y conda activate paddleocr26逻辑说明单独建环境是为了隔离依赖PaddleOCR 会拉入 opencv、shapely、pyclipper 等一堆包混装容易和系统里已有的 numpy 版本打架。参数上-n指定环境名python3.8锁死解释器版本避免 conda 自动选到 3.11 导致后续 wheel 包找不到。装 PaddlePaddle CPU 版python -m pip install paddlepaddle2.5.2 -i https://pypi.tuna.tsinghua.edu.cn/simple如果你要 GPU 版把包名换成paddlepaddle-gpu2.5.2并且确认本机 CUDA 版本匹配。装完立刻验证python -c import paddle; paddle.utils.run_check()看到PaddlePaddle is installed successfully才算过。这一步不过后面全是白搭。2.2 装 PaddleOCR 2.6 并验证推理链路PaddleOCR 的包名就是paddleocr但 PyPI 上的版本更新和 GitHub 仓库不完全同步。要精确拿到 2.6我建议从源码装git clone -b release/2.6 https://github.com/PaddlePaddle/PaddleOCR.git cd PaddleOCR python -m pip install -r requirements.txt python -m pip install -e .逻辑说明-b release/2.6切到 2.6 分支保证代码和文档一致。-e .是可编辑安装改源码后不用重装调试阶段方便。requirements.txt里锁了 shapely、scikit-image 等版本别跳过。装完跑一个最小推理from paddleocr import PaddleOCR # use_angle_clsTrue 开启方向分类处理倒置或旋转文本 # langch 指定中文模型首次运行会自动下载权重 ocr PaddleOCR(use_angle_clsTrue, langch) result ocr.ocr(test_invoice.jpg, clsTrue) for line in result[0]: print(line[1][0], line[1][1]) # 文本内容, 置信度逻辑说明PaddleOCR()初始化时会加载检测、方向分类、识别三个模型。use_angle_clsTrue对歪斜文本很关键代价是多一次推理。ocr()返回的是嵌套列表result[0]是第一张图的结果每个元素是[坐标框, (文本, 置信度)]。参数clsTrue表示启用方向分类如果图片都是正向的可以设 False 提速。首次运行会从云端下载模型到~/.paddleocr/目录网络不通就手动下载放到对应路径。这一步能出结果说明环境没问题了。3. 推理参数怎么调检测、识别、方向分类三段拆开看PaddleOCR 2.6 的推理不是黑匣子三个模型各有各的参数。默认配置能应付大部分场景但遇到密集小字、长文本或者特殊字体就得动手调。这一章把关键参数和调整逻辑讲透。3.1 检测模型控制文本框的粒度和合并检测阶段用的是 DB 算法输出文本区域的热力图再转成框。影响结果的核心参数有三个det_db_thresh、det_db_box_thresh、det_db_unclip_ratio。det_db_thresh热力图二值化阈值默认 0.3。调低会保留更多弱边缘适合浅色文字调高会过滤噪点但可能漏掉淡字。det_db_box_thresh文本框置信度阈值默认 0.6。低于这个值的框被丢弃。密集小字场景可以降到 0.4。det_db_unclip_ratio文本框扩张比例默认 1.5。调大让框更宽松适合文字贴得近的情况调小让框更紧适合文字稀疏。在代码里这样改ocr PaddleOCR( use_angle_clsTrue, langch, det_db_thresh0.3, det_db_box_thresh0.5, det_db_unclip_ratio1.8 )逻辑说明这三个参数是联动的。比如发票上金额和税额挨得近默认 1.5 的扩张比例可能让两个框粘连识别时串行。把unclip_ratio降到 1.2 再配合box_thresh降到 0.5能分开。反过来如果文字被切碎成单字就调大unclip_ratio。3.2 识别模型影响准确率的几个开关识别阶段用的是 CRNN 加 CTC 解码。2.6 默认的中文识别模型对常规印刷体够用但有几个参数值得关注。rec_batch_num控制识别时的批大小默认 6。GPU 上可以调到 16 或 32 提速CPU 上保持默认或降到 1 避免内存爆。rec_image_shape默认是3, 48, 320表示输入识别的图像高 48、宽 320。如果识别长文本经常截断可以改成3, 48, 640但模型需要支持动态宽度2.6 的识别模型是支持的。ocr PaddleOCR( use_angle_clsTrue, langch, rec_batch_num16, rec_image_shape3,48,640, drop_score0.5 )逻辑说明drop_score是识别结果的置信度过滤阈值默认 0.5低于这个值的文本会被丢弃。如果发现有些正确结果被过滤了降到 0.3如果结果里混入大量乱码升到 0.7。rec_image_shape改宽后长文本识别更完整但显存占用增加需要权衡。3.3 方向分类什么时候开什么时候关use_angle_cls开启后会多加载一个方向分类模型判断文本是 0 度还是 180 度。对于扫描件、截图这类正向图片关掉能省 20% 到 30% 的推理时间。对于手机拍摄、可能倒置的图片必须开。方向分类的阈值参数是cls_thresh默认 0.9。意思是分类置信度超过 0.9 才判定为 180 度并旋转。如果图片里既有正向又有倒置文本这个阈值可以降到 0.8让更多文本被纠正但可能误转正向文本。ocr PaddleOCR( use_angle_clsTrue, langch, cls_thresh0.8 )逻辑说明方向分类模型只处理 0 度和 180 度不处理 90 度旋转。如果你的图片是横拍的需要先用 OpenCV 旋转再送入 OCR。这是很多人误以为方向分类能解决所有旋转问题的坑。4. 训练自己的模型数据准备、配置修改与断点续训预训练模型在通用场景够用但遇到特定字体、手写体或者行业术语识别率会掉。PaddleOCR 2.6 支持检测和识别模型的微调这一章讲怎么用自己的数据训练。4.1 数据标注格式与转换检测模型训练需要标注文本框坐标识别模型需要标注文本内容。PaddleOCR 用的是自己的格式检测是图片路径\t{transcription: 文本, points: [[x1,y1],[x2,y2],[x3,y3],[x4,y4]]}识别是图片路径\t文本内容。如果你用 LabelImg 或 PPOCRLabel 标注导出后需要转换。PPOCRLabel 是 PaddleOCR 自带的标注工具直接输出兼容格式python PPOCRLabel/PPOCRLabel.py --lang ch逻辑说明PPOCRLabel 启动后可以自动预标注人工修正后导出Label.txt和rec_gt.txt。检测训练用Label.txt识别训练用rec_gt.txt。注意导出的路径是相对路径训练前确认工作目录正确。4.2 修改配置文件的关键字段PaddleOCR 2.6 的配置文件在configs/目录下检测用ch_ppocr_server_v2.0_det.yml识别用ch_ppocr_server_v2.0_rec.yml。需要改的字段字段含义建议值Global.use_gpu是否用 GPU有卡 True无卡 FalseGlobal.epoch_num训练轮数检测 500识别 300Global.save_model_dir模型保存路径自定义Train.dataset.data_dir数据根目录指向你的数据Train.dataset.label_file_list标注文件列表训练集 txtTrain.loader.batch_size_per_card单卡批大小显存 8G 设 8Optimizer.lr.name学习率策略微调用 CosineOptimizer.lr.learning_rate初始学习率微调设 0.0001改完配置后启动训练python tools/train.py -c configs/rec/ch_ppocr_server_v2.0_rec.yml \ -o Global.pretrained_model./pretrain_models/ch_ppocr_server_v2.0_rec_train/best_accuracy逻辑说明-c指定配置文件-o覆盖配置里的字段。Global.pretrained_model指向预训练权重微调必须加载否则从零训练收敛慢且效果差。路径指向的是不带.pdparams后缀的前缀。4.3 断点续训与评估指标训练中断后用Global.checkpoints恢复python tools/train.py -c configs/rec/ch_ppocr_server_v2.0_rec.yml \ -o Global.checkpoints./output/rec/iter_epoch_50逻辑说明checkpoints指向保存的检查点前缀会恢复优化器状态和迭代数。注意和pretrained_model的区别前者是续训后者是微调起点。评估识别模型用python tools/eval.py -c configs/rec/ch_ppocr_server_v2.0_rec.yml \ -o Global.checkpoints./output/rec/best_accuracy关注acc和norm_edit_dis两个指标。acc是整句准确率norm_edit_dis是归一化编辑距离后者对长文本更敏感。如果acc高但norm_edit_dis低说明短文本识别好、长文本有问题需要检查rec_image_shape是否够宽。5. 避坑与排查装不上、跑不动、结果乱怎么办这一章记录我实际踩过的坑每条按现象、原因、解决写。新手遇到问题先在这里对号入座。5.1 安装后 import paddle 报 undefined symbol现象import paddle时报undefined symbol: _ZNK5paddle...之类的错。原因PaddlePaddle 的 wheel 包和本机 glibc 或 CUDA 版本不匹配。常见于在 CentOS 7 上装 GPU 版或者 CUDA 版本和 paddle 编译版本不一致。解决先ldd看缺哪个库。CPU 版换用paddlepaddle2.4.2试试这个版本对老系统兼容好。GPU 版确认 CUDA 版本用nvcc --version查然后去 PaddlePaddle 官网找对应 wheel。实在不行用 Docker官方镜像paddlepaddle/paddle:2.5.2-gpu-cuda11.2-cudnn8省去环境折腾。5.2 首次运行卡在下载模型现象ocr.ocr()调用后长时间无输出最后报连接超时。原因模型权重从云端下载网络不通或速度慢。解决手动下载。检测模型、识别模型、方向分类模型分别在 PaddleOCR 的模型库页面能找到下载链接。下载后放到~/.paddleocr/whl/det/ch/、~/.paddleocr/whl/rec/ch/、~/.paddleocr/whl/cls/对应目录解压后确认文件名和代码里期望的一致。代码里模型路径可以通过det_model_dir、rec_model_dir、cls_model_dir参数指定指向本地目录即可跳过下载。5.3 识别结果顺序错乱现象输出的文本顺序和图片里的阅读顺序不一致金额跑到税额后面。原因PaddleOCR 默认按检测框的坐标排序先上后下、先左后右。但遇到多栏排版或者表格这个排序会乱。解决拿到result后自己重排。按box的左上角 y 坐标聚类同一行的按 x 排序。简单做法是设一个 y 阈值比如 10 像素y 差小于阈值的算同一行。复杂表格建议先做版面分析把表格区域切出来单独识别。5.4 GPU 显存不足现象推理时报Out of memory或者训练时 batch size 设大了直接崩。原因rec_batch_num或batch_size_per_card超过显存容量。解决推理时把rec_batch_num降到 1 到 4rec_image_shape保持默认。训练时batch_size_per_card从 8 开始试8G 显存一般能跑 84G 显存设 2 或 4。还可以开Global.use_amp混合精度训练省显存但需要 GPU 支持。5.5 训练 loss 不下降现象训练几十轮后 loss 还在高位震荡评估准确率不涨。原因学习率太大、预训练权重没加载、或者标注数据有问题。解决先确认pretrained_model路径正确加载成功日志里会打印load pretrain model。学习率微调场景设 0.0001从零训练设 0.001。检查标注文件里有没有空文本或者坐标越界用tools/check_label.py可以校验。如果数据量少于 1000 张考虑冻结 backbone 只训练 head。6. 部署与提速从 Python 脚本到服务化的一条实用路径训练和推理跑通后下一步是把它变成能对外提供服务的接口。PaddleOCR 2.6 支持导出 ONNX 和 Paddle Inference 格式后者在服务端部署更常见。这一章讲导出、加速和验证。6.1 导出 Paddle Inference 模型PaddleOCR 提供了导出脚本把训练好的权重转成推理格式python tools/export_model.py -c configs/rec/ch_ppocr_server_v2.0_rec.yml \ -o Global.pretrained_model./output/rec/best_accuracy \ Global.save_inference_dir./inference/rec_model逻辑说明save_inference_dir下会生成inference.pdmodel和inference.pdiparams两个文件。前者是网络结构后者是权重。导出后可以用 Paddle Inference 的 Python API 加载比直接调PaddleOCR类少一层封装推理速度快 10% 到 20%。6.2 用 Paddle Inference 加载并推理import paddle.inference as paddle_infer import numpy as np import cv2 # 配置推理引擎 config paddle_infer.Config(./inference/rec_model/inference.pdmodel, ./inference/rec_model/inference.pdiparams) config.disable_gpu() # 有 GPU 改成 enable_use_gpu(100, 0) config.enable_mkldnn() # CPU 上开 MKLDNN 加速 predictor paddle_infer.create_predictor(config) # 预处理resize 到 3x48x320归一化 img cv2.imread(word.jpg) img cv2.resize(img, (320, 48)) img img.astype(float32) / 255.0 img (img - 0.5) / 0.5 img img.transpose(2, 0, 1)[np.newaxis, ...] # 推理 input_names predictor.get_input_names() input_handle predictor.get_input_handle(input_names[0]) input_handle.copy_from_cpu(img) predictor.run() output_names predictor.get_output_names() output_handle predictor.get_output_handle(output_names[0]) output output_handle.copy_to_cpu() print(output.shape)逻辑说明enable_mkldnn()在 Intel CPU 上开启指令集加速实测能快 30% 左右。预处理必须和训练时一致归一化参数是(img/255 - 0.5) / 0.5尺寸是3,48,320。输出是 CTC 解码前的 logits还需要接一个解码器转成文本。解码逻辑在ppocr/postprocess/rec_postprocess.py里可以直接复用CTCLabelDecode类。6.3 服务化时的并发与批处理单条推理延迟在 CPU 上约 50 到 100 毫秒QPS 上不去。服务化时用批处理把多条请求攒成一个 batch 送进去吞吐能翻几倍。PaddleOCR 的rec_batch_num就是干这个的但那是内部批处理。对外服务建议用消息队列攒批比如每 10 毫秒或攒够 16 条触发一次推理。验证方法用ab或wrk压测对比开批处理和不开的 QPS。我一般会先跑一个基线记录单条延迟和吞吐再逐步调rec_batch_num和攒批窗口找到延迟和吞吐的平衡点。这个平衡点因硬件而异没有万能参数。最后说个习惯每次改完配置或者换模型我都会拿同一批测试图跑一遍把结果存下来和上次对比。OCR 的效果波动有时候很玄学同一张图两次运行结果可能差一个字没有基线对比根本发现不了。这个习惯帮我省了很多后悔药。希望帮到你。本文还有配套的精品资源点击获取 PaddleOCR 2.6 实战指南：从环境搭建到部署的完整教程
简介这份资源是面向OCR初学者与算法工程师的PaddleOCR 2.6版本实操教程文档围绕文本检测与识别全流程展开帮助读者快速搭建可复现的训练与推理环境。压缩包内共1个docx文件约78KB以图文笔记形式系统梳理了环境配置、标签生成、数据集划分、YML参数配置、模型训练验证及推理导出等关键环节并针对导出模型时预训练权重加载异常等常见问题给出了排错思路。内容覆盖PPOCRLabel标注、检测与识别数据集联动划分、ch_PP-OCRv3配置文件修改、batchsize与eval策略设置等具体细节适合希望从零跑通PaddleOCR训练链路、理解检测与识别模块衔接逻辑的读者参考。目前已有1304人学习下载可作为版本迁移与工程落地的对照笔记。1. PaddleOCR 2.6 到底能干什么从一张歪斜发票说起手里有一批用手机拍的发票角度歪、光线差、背景还带水印丢给传统 OCR 接口识别出来的文字顺序全乱金额和税额串行。这种场景下PaddleOCR 2.6 是我近两年反复回头用的方案。它把检测、方向分类、识别三段串成一条流水线中文场景的准确率在开源方案里属于第一梯队而且 2.6 这个版本把推理和训练脚本整理得比较规整新手照着跑不容易翻车。这篇教程面向两类人一类是刚接触 OCR、想在自己电脑上把 PaddleOCR 2.6 跑起来看到结果的另一类是用过旧版本、想搞清楚 2.6 的模型选型、参数配置和部署差异的。我会从环境搭建讲到推理、训练、部署把每一步的命令、参数含义和踩过的坑都摊开。整套流程不需要 GPU 也能跑通推理训练部分我会说明显存门槛。读完你应该能独立完成一次从安装到出结果的完整链路。2. 环境搭建Python、PaddlePaddle 与 PaddleOCR 的版本咬合PaddleOCR 2.6 不是一个能脱离 PaddlePaddle 单独存在的包它依赖飞桨框架的底层算子。很多人第一次装就卡在版本不匹配上报一堆libpaddle找不到或者undefined symbol的错。这一章把安装顺序和版本对应关系讲清楚。2.1 先定 Python 和 PaddlePaddle 版本PaddleOCR 2.6 官方验证过的组合是 Python 3.7 到 3.10PaddlePaddle 2.4 或 2.5。我一般用 Python 3.8 配 PaddlePaddle 2.5 的 CPU 版稳定且依赖冲突少。如果你有 NVIDIA 显卡装 GPU 版之前先确认 CUDA 版本PaddlePaddle 2.5 对应 CUDA 11.2 到 11.7cuDNN 8.2 以上。用 conda 建一个干净环境别在 base 里折腾conda create -n paddleocr26 python3.8 -y conda activate paddleocr26逻辑说明单独建环境是为了隔离依赖PaddleOCR 会拉入 opencv、shapely、pyclipper 等一堆包混装容易和系统里已有的 numpy 版本打架。参数上-n指定环境名python3.8锁死解释器版本避免 conda 自动选到 3.11 导致后续 wheel 包找不到。装 PaddlePaddle CPU 版python -m pip install paddlepaddle2.5.2 -i https://pypi.tuna.tsinghua.edu.cn/simple如果你要 GPU 版把包名换成paddlepaddle-gpu2.5.2并且确认本机 CUDA 版本匹配。装完立刻验证python -c import paddle; paddle.utils.run_check()看到PaddlePaddle is installed successfully才算过。这一步不过后面全是白搭。2.2 装 PaddleOCR 2.6 并验证推理链路PaddleOCR 的包名就是paddleocr但 PyPI 上的版本更新和 GitHub 仓库不完全同步。要精确拿到 2.6我建议从源码装git clone -b release/2.6 https://github.com/PaddlePaddle/PaddleOCR.git cd PaddleOCR python -m pip install -r requirements.txt python -m pip install -e .逻辑说明-b release/2.6切到 2.6 分支保证代码和文档一致。-e .是可编辑安装改源码后不用重装调试阶段方便。requirements.txt里锁了 shapely、scikit-image 等版本别跳过。装完跑一个最小推理from paddleocr import PaddleOCR # use_angle_clsTrue 开启方向分类处理倒置或旋转文本 # langch 指定中文模型首次运行会自动下载权重 ocr PaddleOCR(use_angle_clsTrue, langch) result ocr.ocr(test_invoice.jpg, clsTrue) for line in result[0]: print(line[1][0], line[1][1]) # 文本内容, 置信度逻辑说明PaddleOCR()初始化时会加载检测、方向分类、识别三个模型。use_angle_clsTrue对歪斜文本很关键代价是多一次推理。ocr()返回的是嵌套列表result[0]是第一张图的结果每个元素是[坐标框, (文本, 置信度)]。参数clsTrue表示启用方向分类如果图片都是正向的可以设 False 提速。首次运行会从云端下载模型到~/.paddleocr/目录网络不通就手动下载放到对应路径。这一步能出结果说明环境没问题了。3. 推理参数怎么调检测、识别、方向分类三段拆开看PaddleOCR 2.6 的推理不是黑匣子三个模型各有各的参数。默认配置能应付大部分场景但遇到密集小字、长文本或者特殊字体就得动手调。这一章把关键参数和调整逻辑讲透。3.1 检测模型控制文本框的粒度和合并检测阶段用的是 DB 算法输出文本区域的热力图再转成框。影响结果的核心参数有三个det_db_thresh、det_db_box_thresh、det_db_unclip_ratio。det_db_thresh热力图二值化阈值默认 0.3。调低会保留更多弱边缘适合浅色文字调高会过滤噪点但可能漏掉淡字。det_db_box_thresh文本框置信度阈值默认 0.6。低于这个值的框被丢弃。密集小字场景可以降到 0.4。det_db_unclip_ratio文本框扩张比例默认 1.5。调大让框更宽松适合文字贴得近的情况调小让框更紧适合文字稀疏。在代码里这样改ocr PaddleOCR( use_angle_clsTrue, langch, det_db_thresh0.3, det_db_box_thresh0.5, det_db_unclip_ratio1.8 )逻辑说明这三个参数是联动的。比如发票上金额和税额挨得近默认 1.5 的扩张比例可能让两个框粘连识别时串行。把unclip_ratio降到 1.2 再配合box_thresh降到 0.5能分开。反过来如果文字被切碎成单字就调大unclip_ratio。3.2 识别模型影响准确率的几个开关识别阶段用的是 CRNN 加 CTC 解码。2.6 默认的中文识别模型对常规印刷体够用但有几个参数值得关注。rec_batch_num控制识别时的批大小默认 6。GPU 上可以调到 16 或 32 提速CPU 上保持默认或降到 1 避免内存爆。rec_image_shape默认是3, 48, 320表示输入识别的图像高 48、宽 320。如果识别长文本经常截断可以改成3, 48, 640但模型需要支持动态宽度2.6 的识别模型是支持的。ocr PaddleOCR( use_angle_clsTrue, langch, rec_batch_num16, rec_image_shape3,48,640, drop_score0.5 )逻辑说明drop_score是识别结果的置信度过滤阈值默认 0.5低于这个值的文本会被丢弃。如果发现有些正确结果被过滤了降到 0.3如果结果里混入大量乱码升到 0.7。rec_image_shape改宽后长文本识别更完整但显存占用增加需要权衡。3.3 方向分类什么时候开什么时候关use_angle_cls开启后会多加载一个方向分类模型判断文本是 0 度还是 180 度。对于扫描件、截图这类正向图片关掉能省 20% 到 30% 的推理时间。对于手机拍摄、可能倒置的图片必须开。方向分类的阈值参数是cls_thresh默认 0.9。意思是分类置信度超过 0.9 才判定为 180 度并旋转。如果图片里既有正向又有倒置文本这个阈值可以降到 0.8让更多文本被纠正但可能误转正向文本。ocr PaddleOCR( use_angle_clsTrue, langch, cls_thresh0.8 )逻辑说明方向分类模型只处理 0 度和 180 度不处理 90 度旋转。如果你的图片是横拍的需要先用 OpenCV 旋转再送入 OCR。这是很多人误以为方向分类能解决所有旋转问题的坑。4. 训练自己的模型数据准备、配置修改与断点续训预训练模型在通用场景够用但遇到特定字体、手写体或者行业术语识别率会掉。PaddleOCR 2.6 支持检测和识别模型的微调这一章讲怎么用自己的数据训练。4.1 数据标注格式与转换检测模型训练需要标注文本框坐标识别模型需要标注文本内容。PaddleOCR 用的是自己的格式检测是图片路径\t{transcription: 文本, points: [[x1,y1],[x2,y2],[x3,y3],[x4,y4]]}识别是图片路径\t文本内容。如果你用 LabelImg 或 PPOCRLabel 标注导出后需要转换。PPOCRLabel 是 PaddleOCR 自带的标注工具直接输出兼容格式python PPOCRLabel/PPOCRLabel.py --lang ch逻辑说明PPOCRLabel 启动后可以自动预标注人工修正后导出Label.txt和rec_gt.txt。检测训练用Label.txt识别训练用rec_gt.txt。注意导出的路径是相对路径训练前确认工作目录正确。4.2 修改配置文件的关键字段PaddleOCR 2.6 的配置文件在configs/目录下检测用ch_ppocr_server_v2.0_det.yml识别用ch_ppocr_server_v2.0_rec.yml。需要改的字段字段含义建议值Global.use_gpu是否用 GPU有卡 True无卡 FalseGlobal.epoch_num训练轮数检测 500识别 300Global.save_model_dir模型保存路径自定义Train.dataset.data_dir数据根目录指向你的数据Train.dataset.label_file_list标注文件列表训练集 txtTrain.loader.batch_size_per_card单卡批大小显存 8G 设 8Optimizer.lr.name学习率策略微调用 CosineOptimizer.lr.learning_rate初始学习率微调设 0.0001改完配置后启动训练python tools/train.py -c configs/rec/ch_ppocr_server_v2.0_rec.yml \ -o Global.pretrained_model./pretrain_models/ch_ppocr_server_v2.0_rec_train/best_accuracy逻辑说明-c指定配置文件-o覆盖配置里的字段。Global.pretrained_model指向预训练权重微调必须加载否则从零训练收敛慢且效果差。路径指向的是不带.pdparams后缀的前缀。4.3 断点续训与评估指标训练中断后用Global.checkpoints恢复python tools/train.py -c configs/rec/ch_ppocr_server_v2.0_rec.yml \ -o Global.checkpoints./output/rec/iter_epoch_50逻辑说明checkpoints指向保存的检查点前缀会恢复优化器状态和迭代数。注意和pretrained_model的区别前者是续训后者是微调起点。评估识别模型用python tools/eval.py -c configs/rec/ch_ppocr_server_v2.0_rec.yml \ -o Global.checkpoints./output/rec/best_accuracy关注acc和norm_edit_dis两个指标。acc是整句准确率norm_edit_dis是归一化编辑距离后者对长文本更敏感。如果acc高但norm_edit_dis低说明短文本识别好、长文本有问题需要检查rec_image_shape是否够宽。5. 避坑与排查装不上、跑不动、结果乱怎么办这一章记录我实际踩过的坑每条按现象、原因、解决写。新手遇到问题先在这里对号入座。5.1 安装后 import paddle 报 undefined symbol现象import paddle时报undefined symbol: _ZNK5paddle...之类的错。原因PaddlePaddle 的 wheel 包和本机 glibc 或 CUDA 版本不匹配。常见于在 CentOS 7 上装 GPU 版或者 CUDA 版本和 paddle 编译版本不一致。解决先ldd看缺哪个库。CPU 版换用paddlepaddle2.4.2试试这个版本对老系统兼容好。GPU 版确认 CUDA 版本用nvcc --version查然后去 PaddlePaddle 官网找对应 wheel。实在不行用 Docker官方镜像paddlepaddle/paddle:2.5.2-gpu-cuda11.2-cudnn8省去环境折腾。5.2 首次运行卡在下载模型现象ocr.ocr()调用后长时间无输出最后报连接超时。原因模型权重从云端下载网络不通或速度慢。解决手动下载。检测模型、识别模型、方向分类模型分别在 PaddleOCR 的模型库页面能找到下载链接。下载后放到~/.paddleocr/whl/det/ch/、~/.paddleocr/whl/rec/ch/、~/.paddleocr/whl/cls/对应目录解压后确认文件名和代码里期望的一致。代码里模型路径可以通过det_model_dir、rec_model_dir、cls_model_dir参数指定指向本地目录即可跳过下载。5.3 识别结果顺序错乱现象输出的文本顺序和图片里的阅读顺序不一致金额跑到税额后面。原因PaddleOCR 默认按检测框的坐标排序先上后下、先左后右。但遇到多栏排版或者表格这个排序会乱。解决拿到result后自己重排。按box的左上角 y 坐标聚类同一行的按 x 排序。简单做法是设一个 y 阈值比如 10 像素y 差小于阈值的算同一行。复杂表格建议先做版面分析把表格区域切出来单独识别。5.4 GPU 显存不足现象推理时报Out of memory或者训练时 batch size 设大了直接崩。原因rec_batch_num或batch_size_per_card超过显存容量。解决推理时把rec_batch_num降到 1 到 4rec_image_shape保持默认。训练时batch_size_per_card从 8 开始试8G 显存一般能跑 84G 显存设 2 或 4。还可以开Global.use_amp混合精度训练省显存但需要 GPU 支持。5.5 训练 loss 不下降现象训练几十轮后 loss 还在高位震荡评估准确率不涨。原因学习率太大、预训练权重没加载、或者标注数据有问题。解决先确认pretrained_model路径正确加载成功日志里会打印load pretrain model。学习率微调场景设 0.0001从零训练设 0.001。检查标注文件里有没有空文本或者坐标越界用tools/check_label.py可以校验。如果数据量少于 1000 张考虑冻结 backbone 只训练 head。6. 部署与提速从 Python 脚本到服务化的一条实用路径训练和推理跑通后下一步是把它变成能对外提供服务的接口。PaddleOCR 2.6 支持导出 ONNX 和 Paddle Inference 格式后者在服务端部署更常见。这一章讲导出、加速和验证。6.1 导出 Paddle Inference 模型PaddleOCR 提供了导出脚本把训练好的权重转成推理格式python tools/export_model.py -c configs/rec/ch_ppocr_server_v2.0_rec.yml \ -o Global.pretrained_model./output/rec/best_accuracy \ Global.save_inference_dir./inference/rec_model逻辑说明save_inference_dir下会生成inference.pdmodel和inference.pdiparams两个文件。前者是网络结构后者是权重。导出后可以用 Paddle Inference 的 Python API 加载比直接调PaddleOCR类少一层封装推理速度快 10% 到 20%。6.2 用 Paddle Inference 加载并推理import paddle.inference as paddle_infer import numpy as np import cv2 # 配置推理引擎 config paddle_infer.Config(./inference/rec_model/inference.pdmodel, ./inference/rec_model/inference.pdiparams) config.disable_gpu() # 有 GPU 改成 enable_use_gpu(100, 0) config.enable_mkldnn() # CPU 上开 MKLDNN 加速 predictor paddle_infer.create_predictor(config) # 预处理resize 到 3x48x320归一化 img cv2.imread(word.jpg) img cv2.resize(img, (320, 48)) img img.astype(float32) / 255.0 img (img - 0.5) / 0.5 img img.transpose(2, 0, 1)[np.newaxis, ...] # 推理 input_names predictor.get_input_names() input_handle predictor.get_input_handle(input_names[0]) input_handle.copy_from_cpu(img) predictor.run() output_names predictor.get_output_names() output_handle predictor.get_output_handle(output_names[0]) output output_handle.copy_to_cpu() print(output.shape)逻辑说明enable_mkldnn()在 Intel CPU 上开启指令集加速实测能快 30% 左右。预处理必须和训练时一致归一化参数是(img/255 - 0.5) / 0.5尺寸是3,48,320。输出是 CTC 解码前的 logits还需要接一个解码器转成文本。解码逻辑在ppocr/postprocess/rec_postprocess.py里可以直接复用CTCLabelDecode类。6.3 服务化时的并发与批处理单条推理延迟在 CPU 上约 50 到 100 毫秒QPS 上不去。服务化时用批处理把多条请求攒成一个 batch 送进去吞吐能翻几倍。PaddleOCR 的rec_batch_num就是干这个的但那是内部批处理。对外服务建议用消息队列攒批比如每 10 毫秒或攒够 16 条触发一次推理。验证方法用ab或wrk压测对比开批处理和不开的 QPS。我一般会先跑一个基线记录单条延迟和吞吐再逐步调rec_batch_num和攒批窗口找到延迟和吞吐的平衡点。这个平衡点因硬件而异没有万能参数。最后说个习惯每次改完配置或者换模型我都会拿同一批测试图跑一遍把结果存下来和上次对比。OCR 的效果波动有时候很玄学同一张图两次运行结果可能差一个字没有基线对比根本发现不了。这个习惯帮我省了很多后悔药。希望帮到你。本文还有配套的精品资源点击获取