尧图网站建设 
简介这份资源是面向OCR初学者与算法工程师的PaddleOCR 2.6版本实操教程文档围绕文本检测与识别全流程展开帮助读者快速搭建可复现的训练与推理环境。内容涵盖虚拟环境配置、PPOCRLabel标签生成、检测与识别数据集划分、YML配置文件修改、模型训练与验证、推理模型导出及串联预测等关键环节并针对导出时误加载预训练权重这一常见问题给出了将训练权重直接写入YML的排错思路。资源包为1个docx文档约78KB以图文步骤形式记录命令与参数设置便于对照操作。目前已有1304人学习下载适合需要从零跑通PaddleOCR训练链路、理解检测与识别数据组织方式的读者参考也可作为项目落地前的流程速查手册。1. PaddleOCR 2.6 到底解决了什么从一张发票识别说起手里有一批扫描件发票需要把发票代码、金额、开票日期抠出来入库。用传统 OCR 引擎跑一遍中文识别错字连篇表格线一多直接乱序倾斜几度的图片更是全军覆没。这时候多数人会把目光投向 PaddleOCR——百度飞桨开源的 OCR 工具库2.6 版本是它在 2022 年前后一个相对成熟、文档齐全、社区踩坑记录丰富的版本。它把文本检测、方向分类、文本识别三个模型串成流水线中文场景开箱即用还自带版面分析、表格识别、关键信息抽取的扩展能力。这篇不是官方文档的复读而是一个装过、跑过、被坑过的人把 PaddleOCR 2.6 从环境搭建到推理调参的完整路径讲清楚。适合两类人一类是刚接触 OCR、想用 Python 快速跑通一个中文识别 demo 的新手另一类是已经用过其他 OCR、想评估 PaddleOCR 在自有数据上到底行不行、参数怎么调的工程师。读完你应该能独立完成安装、跑通推理、看懂输出结构、知道哪些参数必须改、哪些坑一定会踩。2. 环境搭建Python、PaddlePaddle 与 PaddleOCR 的版本咬合关系PaddleOCR 2.6 不是一个能随便pip install就完事的包它依赖 PaddlePaddle 框架而框架版本、Python 版本、CUDA 版本三者之间是硬绑定关系。装错一个后面报错能让你怀疑人生。这一章把安装路径拆成 CPU 和 GPU 两条线并给出验证方法。2.1 先定 Python 和 PaddlePaddle 版本再谈 PaddleOCRPaddleOCR 2.6 官方推荐 Python 3.7 到 3.10。Python 3.11 及以上在 2.6 时期支持不完整容易出现paddle包找不到对应 wheel 的情况。所以第一步不是装 PaddleOCR而是确认 Python 版本。# 查看当前 Python 版本必须是 3.7 - 3.10 python --version # 推荐用 conda 建一个干净环境避免和系统包打架 conda create -n paddle26 python3.8 -y conda activate paddle26逻辑说明PaddleOCR 2.6 的依赖里对numpy、opencv-python、shapely等都有版本区间要求系统 Python 里已有的包很容易冲突。用 conda 隔离是最省心的做法。参数上python3.8是兼容性最好的选择3.7 偏旧3.9/3.10 也可以但部分第三方依赖 wheel 较少。接下来装 PaddlePaddle。CPU 版和 GPU 版命令不同GPU 版还要看 CUDA 版本。# CPU 版适合先跑通流程、没有 NVIDIA 显卡的机器 pip install paddlepaddle2.4.2 -i https://mirror.baidu.com/pypi/simple # GPU 版CUDA 11.2 环境常见于 Ubuntu 20.04 驱动 460 pip install paddlepaddle-gpu2.4.2.post112 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html逻辑说明PaddleOCR 2.6 配套的 PaddlePaddle 主流版本是 2.3 到 2.4。这里选 2.4.2 是因为它在 2.6 时期被大量验证过wheel 齐全。post112后缀表示 CUDA 11.2 编译版本如果你本机是 CUDA 10.2 就要换post102CUDA 11.6 换post116。装错 CUDA 版本不会立刻报错而是在推理时提示找不到libcudnn.so或直接回退 CPU这是最常见的翻车点之一。验证 PaddlePaddle 是否装好import paddle # 打印版本确认和安装命令一致 print(paddle.__version__) # 检查 GPU 是否可用CPU 版这里会返回 False print(paddle.is_compiled_with_cuda())如果is_compiled_with_cuda()返回 True 但实际推理还是慢多半是没装对应 CUDA 的 cuDNN或者环境变量LD_LIBRARY_PATH没指向 CUDA 库目录。2.2 安装 PaddleOCR 2.6 并跑通第一张图PaddlePaddle 就绪后PaddleOCR 本身反而简单# 从源码装 2.6 分支保证版本精确 git clone -b release/2.6 https://github.com/PaddlePaddle/PaddleOCR.git cd PaddleOCR pip install -r requirements.txt -i https://mirror.baidu.com/pypi/simple pip install -e .逻辑说明-b release/2.6是关键直接pip install paddleocr拿到的是最新版API 和 2.6 有差异。pip install -e .以可编辑模式安装方便你改源码里的后处理逻辑。requirements.txt里包含shapely、pyclipper等几何计算库检测框后处理离不开它们。跑通第一张图from paddleocr import PaddleOCR # use_angle_clsTrue 开启方向分类处理倒置/旋转文本 # langch 指定中文模型首次运行会自动下载模型到 ~/.paddleocr/ ocr PaddleOCR(use_angle_clsTrue, langch) # 传入图片路径返回结构是 [[[框坐标], (文本, 置信度)], ...] result ocr.ocr(invoice.jpg, clsTrue) for line in result[0]: box line[0] # 四点坐标顺序是左上、右上、右下、左下 text line[1][0] # 识别出的文本 score line[1][1] # 置信度0-1 print(text, score)逻辑说明ocr.ocr()返回的是一个列表外层对应每张图内层是每行文本。clsTrue表示对每个检测框做 0/180 度方向判断发票、扫描件经常有倒置的情况不开这个参数倒置文本会识别成乱码。首次运行会联网下载检测、方向、识别三个模型默认存在用户目录下的.paddleocr文件夹内网机器需要提前把模型文件拷进去并改配置路径。参数上lang支持ch、en、japan、korean等切换语言会换识别模型。use_gpu参数在 2.6 里默认根据环境自动判断也可以显式写use_gpuFalse强制 CPU调试时有用。3. 推理参数怎么调det、cls、rec 三段流水线的关键开关PaddleOCR 的推理是一条三段流水线检测det找出文本框方向分类cls判断是否倒置识别rec把框里的图转成文字。每一段都有独立参数调错一段整条链路都废。这一章把最常改的参数按段拆开讲。3.1 检测阶段det_db_thresh 和 det_db_box_thresh 的区别检测模型输出的是概率图后处理把概率图转成文本框。两个阈值控制这个转换参数作用调大后果调小后果det_db_thresh像素级二值化阈值漏检小字引入噪点框det_db_box_thresh文本框置信度阈值漏检模糊文本误检背景纹理det_db_unclip_ratio文本框扩张比例框变大、粘连框变小、切字ocr PaddleOCR( use_angle_clsTrue, langch, # 像素二值化阈值默认 0.3发票这类干净图可以降到 0.2 det_db_thresh0.3, # 框置信度阈值默认 0.6误检多就提到 0.7 det_db_box_thresh0.6, # 框扩张比例默认 1.5字被切断就提到 1.8 det_db_unclip_ratio1.5, )逻辑说明det_db_thresh决定哪些像素算“有文字”调低能召回淡色小字但背景纹理也会被当成文字。det_db_box_thresh是在框级别过滤一个框里所有像素的平均概率低于它就丢弃。实际调参顺序是先看漏检还是误检漏检降det_db_thresh误检升det_db_box_thresh。det_db_unclip_ratio影响框的松紧表格线密集的场景框太紧会把字切一半适当放大到 1.8 到 2.0。3.2 识别阶段rec_batch_num 和 drop_score 的取舍识别阶段把每个检测框裁出来送进识别模型批量大小和置信度过滤是两个关键参数。ocr PaddleOCR( use_angle_clsTrue, langch, # 识别批大小GPU 显存够就调大默认 6 rec_batch_num16, # 低于这个置信度的结果直接丢弃默认 0.5 drop_score0.5, # 识别输入高度默认 48不要轻易改 rec_image_shape3,48,320, )逻辑说明rec_batch_num是每次送进识别模型的图片数量。GPU 推理时调大能明显提速但显存占用线性增长16 在 8G 显存上比较稳32 可能 OOM。CPU 推理时这个参数影响不大因为瓶颈在单张计算。drop_score是结果过滤低于阈值的识别结果直接不返回。发票场景可以设 0.6 减少错字但手写体场景设太高会丢结果0.3 到 0.5 比较常见。rec_image_shape默认3,48,320表示输入是 3 通道、高 48、宽 320。这个高度是识别模型训练时固定的改了会显著掉点除非你重新训练模型否则不要动。宽度 320 是最大宽度实际会按比例缩放。3.3 方向分类什么时候必须开 cls方向分类模型判断文本是 0 度还是 180 度。开了会增加一次推理速度慢一点但以下场景必须开扫描件、拍照件可能整体倒置文档中有旋转的页眉页脚票据、证件类图片方向不固定# 开启方向分类并设置分类置信度阈值 ocr PaddleOCR( use_angle_clsTrue, langch, # 方向分类阈值默认 0.9低于它不翻转 cls_thresh0.9, )逻辑说明cls_thresh控制翻转的激进程度。调低到 0.7 会让更多框被翻转但可能把正常文本翻错。对于方向明确的场景比如全是正向扫描的 PDF 转图可以关掉use_angle_cls省时间。判断依据很简单如果识别结果里出现大量语义不通的乱码而图片肉眼看是正的多半是方向分类误判把cls_thresh调高。4. 避坑与排查装完跑不通的五个高频问题这一章记录的是我在不同机器上反复遇到的坑每条按现象、原因、解决写。新手照着排查能省掉大量搜索时间。4.1 现象ImportError: libcudnn.so.8 找不到原因装了 GPU 版 PaddlePaddle但系统 CUDA 版本和 wheel 编译版本不匹配或者 cuDNN 没装、没加到LD_LIBRARY_PATH。解决先用nvcc --version和nvidia-smi确认 CUDA 版本再对照 PaddlePaddle wheel 的后缀post112 对应 CUDA 11.2。cuDNN 需要单独下载对应 CUDA 版本的包解压后把lib64目录加到环境变量export LD_LIBRARY_PATH/usr/local/cuda/lib64:/path/to/cudnn/lib64:$LD_LIBRARY_PATH如果一时搞不定先用 CPU 版跑通流程别在环境上耗太久。4.2 现象首次运行卡在下载模型内网直接超时原因PaddleOCR 默认从百度云下载模型内网或无外网环境会卡死。解决在有网的机器上跑一次模型会存到~/.paddleocr/下按det、cls、rec分目录。把整个.paddleocr文件夹拷到目标机器同路径或者改配置文件里的det_model_dir、rec_model_dir、cls_model_dir指向本地路径。配置文件在PaddleOCR/configs/下推理时用--det_model_dir等参数覆盖。4.3 现象识别结果全是乱码或空字符串原因三种可能——图片本身方向倒置但没开 clsrec_image_shape被改过识别模型和语言不匹配比如用ch模型识别英文。解决先开use_angle_clsTrue排除方向问题确认rec_image_shape是默认的3,48,320确认lang和图片语言一致。如果还不行把检测框裁出来单独存图肉眼看框里是不是完整文字框切歪了也会导致识别失败。4.4 现象GPU 显存够但推理速度没比 CPU 快多少原因rec_batch_num太小GPU 利用率上不去或者数据在 CPU 和 GPU 之间频繁拷贝。解决把rec_batch_num从默认 6 提到 16 或 32观察显存占用。另外确认use_gpu确实是 True可以用paddle.is_compiled_with_cuda()和推理时的日志确认。如果图片数量少GPU 的启动开销反而拖慢批量处理才有优势。4.5 现象表格图片识别后文字顺序全乱原因PaddleOCR 2.6 的基础推理只做文本检测和识别不做版面顺序还原。表格里的文字是按检测框位置返回的不是按阅读顺序。解决基础ocr.ocr()不解决阅读顺序问题需要用paddleocr里的PPStructure做版面分析或者自己在后处理里按框的坐标排序先按 y 坐标分行行内按 x 排序。这是很多人误以为 PaddleOCR 能直接输出结构化表格的误区实际上表格识别是另一个模块。5. 从能跑到好用后处理排序与批量推理的两个技巧跑通 demo 只是起点真正落地时两个问题最突出输出顺序不可读以及大批量图片处理效率低。这一章给两个可以直接抄的技巧。5.1 按坐标给识别结果排序还原阅读顺序PaddleOCR 返回的框是四点坐标顺序不保证是阅读顺序。下面这个排序函数按“先上后下、先左后右”重排def sort_boxes(result): 按阅读顺序排序 PaddleOCR 的检测结果 items [] for line in result[0]: box line[0] # 取框的左上角 y 和 x 作为排序依据 y min(p[1] for p in box) x min(p[0] for p in box) items.append((y, x, line[1][0])) # 先按 y 分行行内按 x 排序 items.sort(keylambda t: (round(t[0] / 10), t[1])) return [t[2] for t in items] # 使用 result ocr.ocr(invoice.jpg, clsTrue) ordered_text sort_boxes(result) print(\n.join(ordered_text))逻辑说明round(t[0] / 10)是把 y 坐标按 10 像素分桶同一行内的框 y 值接近分到同一桶后按 x 排序。这个 10 是经验值字号大的图可以调到 20。这个排序对规则文档效果好对多栏排版会失效多栏需要先做栏分割。5.2 批量推理把多张图塞进一次调用PaddleOCR 的ocr()支持传入图片列表内部会循环处理但比逐张调用省去重复的模型加载开销import os # 收集目录下所有图片 img_dir ./invoices img_list [os.path.join(img_dir, f) for f in os.listdir(img_dir) if f.lower().endswith((.jpg, .png, .jpeg))] # 一次性传入列表内部批量处理 results ocr.ocr(img_list, clsTrue) # results 长度和 img_list 一致逐个对应 for img_path, res in zip(img_list, results): print(img_path, len(res[0]) if res else 0)逻辑说明传入列表时PaddleOCR 会复用已加载的模型避免每张图重新初始化。注意返回的results是列表的列表外层对应每张图某张图没检测到文本时对应元素可能是None用之前要判空。批量大小受内存限制几千张图建议分批每批 100 张左右避免一次性占满内存。我自己的习惯是先用 CPU 版在小样本上把参数调好确认识别率达标再切 GPU 版跑全量。环境问题永远比算法问题更耗时间所以装环境时我会把版本号写进一个requirements.txt固定下来换机器直接复现。PaddleOCR 2.6 不是最新版但它的稳定性和社区资料密度对于要快速落地的项目来说反而更省心。希望帮到你。本文还有配套的精品资源点击获取 PaddleOCR 2.6 实战指南：从环境搭建到推理调参的完整路径
简介这份资源是面向OCR初学者与算法工程师的PaddleOCR 2.6版本实操教程文档围绕文本检测与识别全流程展开帮助读者快速搭建可复现的训练与推理环境。内容涵盖虚拟环境配置、PPOCRLabel标签生成、检测与识别数据集划分、YML配置文件修改、模型训练与验证、推理模型导出及串联预测等关键环节并针对导出时误加载预训练权重这一常见问题给出了将训练权重直接写入YML的排错思路。资源包为1个docx文档约78KB以图文步骤形式记录命令与参数设置便于对照操作。目前已有1304人学习下载适合需要从零跑通PaddleOCR训练链路、理解检测与识别数据组织方式的读者参考也可作为项目落地前的流程速查手册。1. PaddleOCR 2.6 到底解决了什么从一张发票识别说起手里有一批扫描件发票需要把发票代码、金额、开票日期抠出来入库。用传统 OCR 引擎跑一遍中文识别错字连篇表格线一多直接乱序倾斜几度的图片更是全军覆没。这时候多数人会把目光投向 PaddleOCR——百度飞桨开源的 OCR 工具库2.6 版本是它在 2022 年前后一个相对成熟、文档齐全、社区踩坑记录丰富的版本。它把文本检测、方向分类、文本识别三个模型串成流水线中文场景开箱即用还自带版面分析、表格识别、关键信息抽取的扩展能力。这篇不是官方文档的复读而是一个装过、跑过、被坑过的人把 PaddleOCR 2.6 从环境搭建到推理调参的完整路径讲清楚。适合两类人一类是刚接触 OCR、想用 Python 快速跑通一个中文识别 demo 的新手另一类是已经用过其他 OCR、想评估 PaddleOCR 在自有数据上到底行不行、参数怎么调的工程师。读完你应该能独立完成安装、跑通推理、看懂输出结构、知道哪些参数必须改、哪些坑一定会踩。2. 环境搭建Python、PaddlePaddle 与 PaddleOCR 的版本咬合关系PaddleOCR 2.6 不是一个能随便pip install就完事的包它依赖 PaddlePaddle 框架而框架版本、Python 版本、CUDA 版本三者之间是硬绑定关系。装错一个后面报错能让你怀疑人生。这一章把安装路径拆成 CPU 和 GPU 两条线并给出验证方法。2.1 先定 Python 和 PaddlePaddle 版本再谈 PaddleOCRPaddleOCR 2.6 官方推荐 Python 3.7 到 3.10。Python 3.11 及以上在 2.6 时期支持不完整容易出现paddle包找不到对应 wheel 的情况。所以第一步不是装 PaddleOCR而是确认 Python 版本。# 查看当前 Python 版本必须是 3.7 - 3.10 python --version # 推荐用 conda 建一个干净环境避免和系统包打架 conda create -n paddle26 python3.8 -y conda activate paddle26逻辑说明PaddleOCR 2.6 的依赖里对numpy、opencv-python、shapely等都有版本区间要求系统 Python 里已有的包很容易冲突。用 conda 隔离是最省心的做法。参数上python3.8是兼容性最好的选择3.7 偏旧3.9/3.10 也可以但部分第三方依赖 wheel 较少。接下来装 PaddlePaddle。CPU 版和 GPU 版命令不同GPU 版还要看 CUDA 版本。# CPU 版适合先跑通流程、没有 NVIDIA 显卡的机器 pip install paddlepaddle2.4.2 -i https://mirror.baidu.com/pypi/simple # GPU 版CUDA 11.2 环境常见于 Ubuntu 20.04 驱动 460 pip install paddlepaddle-gpu2.4.2.post112 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html逻辑说明PaddleOCR 2.6 配套的 PaddlePaddle 主流版本是 2.3 到 2.4。这里选 2.4.2 是因为它在 2.6 时期被大量验证过wheel 齐全。post112后缀表示 CUDA 11.2 编译版本如果你本机是 CUDA 10.2 就要换post102CUDA 11.6 换post116。装错 CUDA 版本不会立刻报错而是在推理时提示找不到libcudnn.so或直接回退 CPU这是最常见的翻车点之一。验证 PaddlePaddle 是否装好import paddle # 打印版本确认和安装命令一致 print(paddle.__version__) # 检查 GPU 是否可用CPU 版这里会返回 False print(paddle.is_compiled_with_cuda())如果is_compiled_with_cuda()返回 True 但实际推理还是慢多半是没装对应 CUDA 的 cuDNN或者环境变量LD_LIBRARY_PATH没指向 CUDA 库目录。2.2 安装 PaddleOCR 2.6 并跑通第一张图PaddlePaddle 就绪后PaddleOCR 本身反而简单# 从源码装 2.6 分支保证版本精确 git clone -b release/2.6 https://github.com/PaddlePaddle/PaddleOCR.git cd PaddleOCR pip install -r requirements.txt -i https://mirror.baidu.com/pypi/simple pip install -e .逻辑说明-b release/2.6是关键直接pip install paddleocr拿到的是最新版API 和 2.6 有差异。pip install -e .以可编辑模式安装方便你改源码里的后处理逻辑。requirements.txt里包含shapely、pyclipper等几何计算库检测框后处理离不开它们。跑通第一张图from paddleocr import PaddleOCR # use_angle_clsTrue 开启方向分类处理倒置/旋转文本 # langch 指定中文模型首次运行会自动下载模型到 ~/.paddleocr/ ocr PaddleOCR(use_angle_clsTrue, langch) # 传入图片路径返回结构是 [[[框坐标], (文本, 置信度)], ...] result ocr.ocr(invoice.jpg, clsTrue) for line in result[0]: box line[0] # 四点坐标顺序是左上、右上、右下、左下 text line[1][0] # 识别出的文本 score line[1][1] # 置信度0-1 print(text, score)逻辑说明ocr.ocr()返回的是一个列表外层对应每张图内层是每行文本。clsTrue表示对每个检测框做 0/180 度方向判断发票、扫描件经常有倒置的情况不开这个参数倒置文本会识别成乱码。首次运行会联网下载检测、方向、识别三个模型默认存在用户目录下的.paddleocr文件夹内网机器需要提前把模型文件拷进去并改配置路径。参数上lang支持ch、en、japan、korean等切换语言会换识别模型。use_gpu参数在 2.6 里默认根据环境自动判断也可以显式写use_gpuFalse强制 CPU调试时有用。3. 推理参数怎么调det、cls、rec 三段流水线的关键开关PaddleOCR 的推理是一条三段流水线检测det找出文本框方向分类cls判断是否倒置识别rec把框里的图转成文字。每一段都有独立参数调错一段整条链路都废。这一章把最常改的参数按段拆开讲。3.1 检测阶段det_db_thresh 和 det_db_box_thresh 的区别检测模型输出的是概率图后处理把概率图转成文本框。两个阈值控制这个转换参数作用调大后果调小后果det_db_thresh像素级二值化阈值漏检小字引入噪点框det_db_box_thresh文本框置信度阈值漏检模糊文本误检背景纹理det_db_unclip_ratio文本框扩张比例框变大、粘连框变小、切字ocr PaddleOCR( use_angle_clsTrue, langch, # 像素二值化阈值默认 0.3发票这类干净图可以降到 0.2 det_db_thresh0.3, # 框置信度阈值默认 0.6误检多就提到 0.7 det_db_box_thresh0.6, # 框扩张比例默认 1.5字被切断就提到 1.8 det_db_unclip_ratio1.5, )逻辑说明det_db_thresh决定哪些像素算“有文字”调低能召回淡色小字但背景纹理也会被当成文字。det_db_box_thresh是在框级别过滤一个框里所有像素的平均概率低于它就丢弃。实际调参顺序是先看漏检还是误检漏检降det_db_thresh误检升det_db_box_thresh。det_db_unclip_ratio影响框的松紧表格线密集的场景框太紧会把字切一半适当放大到 1.8 到 2.0。3.2 识别阶段rec_batch_num 和 drop_score 的取舍识别阶段把每个检测框裁出来送进识别模型批量大小和置信度过滤是两个关键参数。ocr PaddleOCR( use_angle_clsTrue, langch, # 识别批大小GPU 显存够就调大默认 6 rec_batch_num16, # 低于这个置信度的结果直接丢弃默认 0.5 drop_score0.5, # 识别输入高度默认 48不要轻易改 rec_image_shape3,48,320, )逻辑说明rec_batch_num是每次送进识别模型的图片数量。GPU 推理时调大能明显提速但显存占用线性增长16 在 8G 显存上比较稳32 可能 OOM。CPU 推理时这个参数影响不大因为瓶颈在单张计算。drop_score是结果过滤低于阈值的识别结果直接不返回。发票场景可以设 0.6 减少错字但手写体场景设太高会丢结果0.3 到 0.5 比较常见。rec_image_shape默认3,48,320表示输入是 3 通道、高 48、宽 320。这个高度是识别模型训练时固定的改了会显著掉点除非你重新训练模型否则不要动。宽度 320 是最大宽度实际会按比例缩放。3.3 方向分类什么时候必须开 cls方向分类模型判断文本是 0 度还是 180 度。开了会增加一次推理速度慢一点但以下场景必须开扫描件、拍照件可能整体倒置文档中有旋转的页眉页脚票据、证件类图片方向不固定# 开启方向分类并设置分类置信度阈值 ocr PaddleOCR( use_angle_clsTrue, langch, # 方向分类阈值默认 0.9低于它不翻转 cls_thresh0.9, )逻辑说明cls_thresh控制翻转的激进程度。调低到 0.7 会让更多框被翻转但可能把正常文本翻错。对于方向明确的场景比如全是正向扫描的 PDF 转图可以关掉use_angle_cls省时间。判断依据很简单如果识别结果里出现大量语义不通的乱码而图片肉眼看是正的多半是方向分类误判把cls_thresh调高。4. 避坑与排查装完跑不通的五个高频问题这一章记录的是我在不同机器上反复遇到的坑每条按现象、原因、解决写。新手照着排查能省掉大量搜索时间。4.1 现象ImportError: libcudnn.so.8 找不到原因装了 GPU 版 PaddlePaddle但系统 CUDA 版本和 wheel 编译版本不匹配或者 cuDNN 没装、没加到LD_LIBRARY_PATH。解决先用nvcc --version和nvidia-smi确认 CUDA 版本再对照 PaddlePaddle wheel 的后缀post112 对应 CUDA 11.2。cuDNN 需要单独下载对应 CUDA 版本的包解压后把lib64目录加到环境变量export LD_LIBRARY_PATH/usr/local/cuda/lib64:/path/to/cudnn/lib64:$LD_LIBRARY_PATH如果一时搞不定先用 CPU 版跑通流程别在环境上耗太久。4.2 现象首次运行卡在下载模型内网直接超时原因PaddleOCR 默认从百度云下载模型内网或无外网环境会卡死。解决在有网的机器上跑一次模型会存到~/.paddleocr/下按det、cls、rec分目录。把整个.paddleocr文件夹拷到目标机器同路径或者改配置文件里的det_model_dir、rec_model_dir、cls_model_dir指向本地路径。配置文件在PaddleOCR/configs/下推理时用--det_model_dir等参数覆盖。4.3 现象识别结果全是乱码或空字符串原因三种可能——图片本身方向倒置但没开 clsrec_image_shape被改过识别模型和语言不匹配比如用ch模型识别英文。解决先开use_angle_clsTrue排除方向问题确认rec_image_shape是默认的3,48,320确认lang和图片语言一致。如果还不行把检测框裁出来单独存图肉眼看框里是不是完整文字框切歪了也会导致识别失败。4.4 现象GPU 显存够但推理速度没比 CPU 快多少原因rec_batch_num太小GPU 利用率上不去或者数据在 CPU 和 GPU 之间频繁拷贝。解决把rec_batch_num从默认 6 提到 16 或 32观察显存占用。另外确认use_gpu确实是 True可以用paddle.is_compiled_with_cuda()和推理时的日志确认。如果图片数量少GPU 的启动开销反而拖慢批量处理才有优势。4.5 现象表格图片识别后文字顺序全乱原因PaddleOCR 2.6 的基础推理只做文本检测和识别不做版面顺序还原。表格里的文字是按检测框位置返回的不是按阅读顺序。解决基础ocr.ocr()不解决阅读顺序问题需要用paddleocr里的PPStructure做版面分析或者自己在后处理里按框的坐标排序先按 y 坐标分行行内按 x 排序。这是很多人误以为 PaddleOCR 能直接输出结构化表格的误区实际上表格识别是另一个模块。5. 从能跑到好用后处理排序与批量推理的两个技巧跑通 demo 只是起点真正落地时两个问题最突出输出顺序不可读以及大批量图片处理效率低。这一章给两个可以直接抄的技巧。5.1 按坐标给识别结果排序还原阅读顺序PaddleOCR 返回的框是四点坐标顺序不保证是阅读顺序。下面这个排序函数按“先上后下、先左后右”重排def sort_boxes(result): 按阅读顺序排序 PaddleOCR 的检测结果 items [] for line in result[0]: box line[0] # 取框的左上角 y 和 x 作为排序依据 y min(p[1] for p in box) x min(p[0] for p in box) items.append((y, x, line[1][0])) # 先按 y 分行行内按 x 排序 items.sort(keylambda t: (round(t[0] / 10), t[1])) return [t[2] for t in items] # 使用 result ocr.ocr(invoice.jpg, clsTrue) ordered_text sort_boxes(result) print(\n.join(ordered_text))逻辑说明round(t[0] / 10)是把 y 坐标按 10 像素分桶同一行内的框 y 值接近分到同一桶后按 x 排序。这个 10 是经验值字号大的图可以调到 20。这个排序对规则文档效果好对多栏排版会失效多栏需要先做栏分割。5.2 批量推理把多张图塞进一次调用PaddleOCR 的ocr()支持传入图片列表内部会循环处理但比逐张调用省去重复的模型加载开销import os # 收集目录下所有图片 img_dir ./invoices img_list [os.path.join(img_dir, f) for f in os.listdir(img_dir) if f.lower().endswith((.jpg, .png, .jpeg))] # 一次性传入列表内部批量处理 results ocr.ocr(img_list, clsTrue) # results 长度和 img_list 一致逐个对应 for img_path, res in zip(img_list, results): print(img_path, len(res[0]) if res else 0)逻辑说明传入列表时PaddleOCR 会复用已加载的模型避免每张图重新初始化。注意返回的results是列表的列表外层对应每张图某张图没检测到文本时对应元素可能是None用之前要判空。批量大小受内存限制几千张图建议分批每批 100 张左右避免一次性占满内存。我自己的习惯是先用 CPU 版在小样本上把参数调好确认识别率达标再切 GPU 版跑全量。环境问题永远比算法问题更耗时间所以装环境时我会把版本号写进一个requirements.txt固定下来换机器直接复现。PaddleOCR 2.6 不是最新版但它的稳定性和社区资料密度对于要快速落地的项目来说反而更省心。希望帮到你。本文还有配套的精品资源点击获取