简介PaddleOCR 2.0 是一款面向本地文字识别场景的开源光学字符识别工具适合需要从截图、扫描件、PDF转图或拍照文档中提取中英文信息的办公人员与数据录入者解决重复键入与依赖在线接口的问题。资源压缩包以 zip 格式提供整体约 98.84MB页面未列出文件总数与类型明细但功能描述明确覆盖本地单机运行、图片批量识别、延时截图识别、旋转/镜像识别、中英文混排识别及识别区域坐标查看等能力。目前已有 204 人学习/下载适合刚接触 OCR 的入门读者快速获得一套可离线运行的文字提取方案。下载后可直接部署到单机环境无需 GPU 也能通过 CPU 检测完成常见图片字符识别借助批量打开图片文件列表一次可处理多张素材对于方向不对或镜像的图片可直接旋转调整并在输出结果中查看每个识别区域的坐标便于定位错字或做后续数据校验。1. PaddleOCR 2.0为什么两年后依然是产线首选做票据识别的朋友应该都有同感OCR 框架一年换三个真正上了产线、两年没大改的反而是那个「老版本」。PaddleOCR 2.0 就是这样的存在。它是百度飞桨 2021 年开源的 OCR 工具链把检测、方向分类、识别三段式 pipeline 做成了开箱即用中文模型识别精度在当时是独一档训练、导出、部署代码全部开源。到现在很多人纠结是升到新版本还是换 tiny 模型提速但 PaddleOCR 2.0 的稳定性和文档完整度依然让它在中小团队的产线里占着主力位置。这篇笔记从环境搭建、训练闭环、推理加速到踩坑记录把 2.0 完整讲透给准备入坑或已经入坑的朋友一份可直接照做的清单。2. 从安装到跑通第一张图PaddleOCR 2.0 的最小环境与推理命令2.1 环境依赖Python 版本别贪新PaddleOCR 2.0 的第一道坎是 Python 版本。官方文档写的是支持 3.6但我实际跑下来 Python 3.8 最稳。3.9 和 3.10 在 pip 装 paddlepaddle 2.0.x 时经常遇到 wheel 匹配不上或者装上后 import paddle 直接段错误。这是典型的「版本玄学」2.0 发布时 Python 3.9 刚出很多预编译 wheel 只覆盖到 3.8后面补的兼容性版本反而偶尔触到底层内存分配问题。# 用 conda 建独立环境避免污染系统 Python conda create -n paddleocr20 python3.8 -y conda activate paddleocr20 # 安装飞桨框架 CPU 版GPU 版用 paddlepaddle-gpu pip install paddlepaddle2.0.2 -i https://mirror.baidu.com/pypi/simple # 安装 PaddleOCR 2.0 本体2.0.6 是 2.0 系列最后的稳定版 pip install paddleocr2.0.6逻辑说明conda 隔离环境是必须的OCR 框架的底层依赖Protobuf、Shapely、PyMuPDF 等版本要求很拧巴直接装进系统 Python 过半年就会被其他项目搞乱。paddlepaddle2.0.2一定要锁版本2.1 之后飞桨框架的 Python API 有过一轮调整PaddleOCR 2.0 的代码是按 2.0.x 的接口写的用新框架跑旧代码虽然多数能通但没必要冒险。装完先验证import paddle print(paddle.__version__) # 期望输出 2.0.2 print(paddle.is_compiled_with_cuda()) # GPU 版输出 True from paddleocr import PaddleOCR ocr PaddleOCR(use_angle_clsTrue, langch, show_logFalse) result ocr.ocr(test.png, clsTrue)这段代码第一次跑会下载检测、方向分类、识别三个模型总大小约 20 多 MB。如果长时间卡在下载阶段说明服务器网络受限访问模型源慢解决办法在第 5 章讲。2.2 跑通检测识别的最小脚本很多人在 PaddleOCR 2.0 上翻车不是因为模型不对而是看不懂ocr.ocr()返回的嵌套结构。2.0 的返回格式是[[[box, (text, score)], ...], ...]外层 list 对应输入图像内层 list 对应单张图的全部检测框。我习惯写一个摊平函数把结果整理成字典列表方便后续调业务逻辑import json from paddleocr import PaddleOCR ocr PaddleOCR(use_angle_clsTrue, langch, show_logFalse) def parse_ocr_result(result): 把 PaddleOCR 2.0 的返回结果摊平成 list[dict] 每个 dict: {box, text, score} parsed [] for image_lines in result: if image_lines is None: continue for item in image_lines: box item[0] # 4 个点的坐标 [[x1,y1], ...] text, score item[1] # (文本, 置信度) parsed.append({ box: box, text: text, score: float(score) }) return parsed result ocr.ocr(invoice.png, clsTrue) parsed parse_ocr_result(result) for item in parsed: print(f{item[text]} {item[score]:.3f} {item[box]}) with open(ocr_result.json, w, encodingutf-8) as f: json.dump(parsed, f, ensure_asciiFalse, indent2)参数说明use_angle_clsTrue初始化方向分类器强烈建议打开。方向分类器只增加几毫秒推理时间但对手机拍摄、文档扫描这类倾斜图像准确率提升经常超过 5 个百分点。langch指定中文模型如果只做英文识别改成en模型文件更小、速度更快。注意构造函数里的use_angle_cls和ocr()方法里的clsTrue必须成对出现只写一个会在推理时报错或直接跳过方向矫正。有个常见误用有人把use_angle_cls写False然后ocr(..., clsTrue)方向分类器根本没加载推理阶段报错。这两个开关是联动的别拆开。2.3 三个必调推理参数PaddleOCR 2.0 的默认参数能跑通大部分图但产线场景里下面这三个参数几乎必调尤其是长图、低对比度和批量识别场景参数默认值作用调整建议det_limit_side_len960检测阶段图像最长边限制文档图保持 960长图调到 1280rec_batch_num6识别阶段 batch 大小GPU 调到 16CPU 保持 6det_db_thresh0.3检测框置信度阈值复杂背景降到 0.2干净文档提到 0.4ocr PaddleOCR( use_angle_clsTrue, langch, show_logFalse, det_limit_side_len1280, # 长图不截断 rec_batch_num16, # GPU 上提高吞吐 det_db_thresh0.2 # 低对比度文字也能检出 )参数说明det_limit_side_len控制检测前图像的缩放边长默认 960 对 A4 文档足够但超市小票、聊天截图这种长条图不调会把中间内容截断漏检一长串字。rec_batch_num只影响吞吐不影响精度GPU 上从 6 调到 16 能让识别阶段吞吐翻倍CPU 上调高了反而因内存交换变慢。det_db_thresh是 DB 检测算法的二值化阈值默认 0.3遇到浅色字、复杂背景调到 0.2 能捡回漏检但误检也会增多需要配合检测框后处理做过滤。3. 用自有数据训练检测模型与识别模型的完整闭环PaddleOCR 2.0 区别于黑匣子 OCR 服务的最大价值在于训练代码全开源。你拿到的是一个完整的训练框架不是只能调 API 的工具。很多人以为 PaddleOCR 只能跑预训练模型这是最大的误解。从数据标注、YAML 配置、训练命令到模型导出整条链路都可以在本地跑通。而且检测和识别是两个独立模型可以只微调其中一个灵活性很高。3.1 数据标注与格式转换PaddleOCR 官方提供的标注工具是 PPOCRLabel界面类似 labelme安装很简单pip install PPOCRLabel PPOCRLabel --lang ch标注时有两点直接影响训练效果一是检测框要贴合文字边缘偏大偏小都相当于给模型加了噪声二是一张图里的文字要么全标、要么用difficult: true标记漏标的部分会被检测模型当成背景负样本学掉导致模型「主动忽略」那些区域。标注结果是一个Label.txt每行格式为图像绝对路径\t[{transcription: 文本, points: [[x1,y1],[x2,y2],[x3,y3],[x4,y4]], difficult: false}]如果团队之前用 labelme 标注过数据可以直接写脚本转换import json import os def labelme_to_paddleocr(labelme_dir, output_file): 把 labelme 的 json 标注转成 PaddleOCR 训练格式 labelme_dir: 存放 json 标注的目录 output_file: 输出的 Label.txt lines [] for fname in os.listdir(labelme_dir): if not fname.endswith(.json): continue with open(os.path.join(labelme_dir, fname), r, encodingutf-8) as f: data json.load(f) img_name data[imagePath] img_path os.path.abspath(os.path.join(labelme_dir, img_name)) labels [] for shape in data[shapes]: if shape[label] in (背景, ignore): continue points shape[points] if len(points) ! 4: # 多边形点序列不固定排成 左上 右上 右下 左下 xs [p[0] for p in points] ys [p[1] for p in points] points [ [min(xs), min(ys)], [max(xs), min(ys)], [max(xs), max(ys)], [min(xs), max(ys)] ] labels.append({ transcription: shape[label], points: [[int(p[0]), int(p[1])] for p in points], difficult: False }) line f{img_path}\t{json.dumps(labels, ensure_asciiFalse)} lines.append(line) with open(output_file, w, encodingutf-8) as f: f.write(\n.join(lines))逻辑说明labelme 输出的多边形点序是任意的PaddleOCR 2.0 检测训练要求四角点按 左上、右上、右下、左下 的顺序排所以这里取了最小外接矩形的四个顶点。difficult: true的框在检测训练中会被忽略用于标注那种人眼都难分辨的文字。3.2 训练配置与超参数训练检测模型DB 算法用configs/det下的 YAML 配置。命令长但拆开看就是三类参数配置文件、预训练权重、数据集路径。python tools/train.py \ -c configs/det/det_mv3_db.yml \ -o Global.pretrain_weights./pretrain_models/ch_ppocr_mobile_v2.0_det_train/best_accuracy \ Global.save_model_dir./output/det_mv3_db \ Train.dataset.data_dir./train_data/ \ Train.dataset.label_file_path./train_data/Label.txt参数说明Global.pretrain_weights是预训练权重路径2.0 的预训练权重和 1.x 不通用加载会报 shape mismatch。如果只想微调检测就下载检测模型的预训练权重别拿识别模型的去顶。Train.dataset.data_dir和label_file_path建议写绝对路径2.0 对相对路径的解析偶尔会出奇怪的问题。还有两个藏在 YAML 里的关键字段Train.dataset.img_set_dir和Train.dataset.label_file_path是配置展开后的实际字段改了-o之后配置文件里如果还留着旧路径会被-o覆盖。训练开始后看日志里打印的数据路径对不对别埋头跑完一个 epoch 才发现用的是旧数据。识别模型的训练命令类似区别在配置文件和标签格式python tools/train.py \ -c configs/rec/rec_chinese_lite_train_v2.0.yml \ -o Global.pretrain_weights./pretrain_models/ch_ppocr_mobile_v2.0_rec_train/best_accuracy \ Global.character_dict_path./my_dict.txt \ Global.save_model_dir./output/rec_crnn识别训练数据每行是图像绝对路径\t标签文本不需要框坐标因为训练图已经是切好的单行文字图。识别训练里最容易翻车的点是字典文件。默认字典ppocr/utils/ppocr_keys_v1.txt有 6000 多个常用汉字但如果你处理的是医疗单据、物流回执这种有生僻字或特殊符号的业务必须把字典换成自己的并在Global.character_dict_path里指定。字典格式是每行一个字第一行放一个blank占位。如果训练完识别结果全是乱码先检查字典文件最后一行有没有换行符——没换行符的末尾字符经常被读错这是 2.0 的经典老坑。3.3 模型导出与部署训练产出的 checkpoint 不能直接用于PaddleOCR()推理要先导出成推理模型python tools/export_model.py \ -c configs/det/det_mv3_db.yml \ -o Global.checkpoints./output/det_mv3_db/best_accuracy \ Global.save_inference_dir./inference/det_db python tools/export_model.py \ -c configs/rec/rec_chinese_lite_train_v2.0.yml \ -o Global.checkpoints./output/rec_crnn/best_accuracy \ Global.save_inference_dir./inference/rec_crnn导出后每个目录有model.pdmodel、model.pdiparams、model.pdiparams.info三个文件。加载时显式指定模型目录ocr PaddleOCR( det_model_dir./inference/det_db, rec_model_dir./inference/rec_crnn, use_angle_clsFalse, # 没训练方向分类器就关掉 langch )这里有个容易踩的坑同时指定det_model_dir和rec_model_dir时lang参数会失效模型以显式目录为准。换句话说你以为切了langen实际跑的还是你指定的中文模型。4. 推理加速与部署从 CPU 到 GPU 的调优路径4.1 推理引擎与硬件选型PaddleOCR 2.0 的底层推理后端是 Paddle InferenceCPU 上有 MKLDNN 加速GPU 上有 TensorRT 加速。选型逻辑我一般是按 QPS 和延迟分界单机 QPS 需求低于 5直接用 CPUQPS 超过 5 或者单图延迟要压到 100ms 以内才需要上 GPU。这里有个反直觉的结论PaddleOCR 2.0 的中文识别链路在 CPU 上开 MKLDNN 后960 分辨率文档图单张大约 50-80ms并没有很多人以为的那么慢。而 GPU 在 GTX 1650 这类入门卡上跑轻量模型如果图像是 640×480 以下的小图性能反而不如 CPU。模型小到一定程度数据传输和 kernel launch 的开销就盖过了并行计算的红利这也是后来 v6、tiny 这类轻量模型主推 CPU 加速的核心逻辑。4.2 三个加速开关# CPU 推理MKLDNN 是主力加速开关 ocr PaddleOCR( use_angle_clsTrue, langch, enable_mkldnnTrue, # CPU 加速关键开关 mkldnn_cache_capacity10, cpu_threads4 ) # GPU 推理TensorRT 是主力加速开关 ocr PaddleOCR( use_angle_clsTrue, langch, use_gpuTrue, gpu_mem8000, use_tensorrtTrue, enable_mkldnnFalse # GPU 模式下关闭 MKLDNN )参数说明enable_mkldnn只对 CPU 生效默认关。打开后检测和识别两个模型都会走 MKLDNN 算子优化实测中文文档识别速度提升约 2 倍。cpu_threads建议等于物理核心数超过物理核反而因为上下文切换变慢。use_tensorrtTrue在 GPU 上启用 TensorRT 推理首次运行会做模型优化耗时几十秒之后走序列化缓存速度明显提升。gpu_mem是显存预分配量别超过显卡实际显存。特别提醒enable_mkldnn和use_tensorrt不要同时开。两个优化器同时干预同一个算子的情况在 2.0 里是未知行为我见过有人都开了之后推理结果出现 NaN排查半天最后关掉一个就好了。4.3 服务化部署的最小方案PaddleOCR 2.0 自带 hubserving 方案但中小团队我一般建议直接用 Flask 包一层 HTTP 接口理由是大多数需求只是「给业务方一个能传图返回文本的接口」不需要完整的事件驱动服务框架。import base64 import time from flask import Flask, request, jsonify from paddleocr import PaddleOCR app Flask(__name__) # 全局只初始化一次放请求外面 ocr PaddleOCR(use_angle_clsTrue, langch, enable_mkldnnTrue, cpu_threads4) app.route(/ocr, methods[POST]) def ocr_endpoint(): 接收 base64 图片返回文本、坐标和耗时 try: body request.get_json() img_data base64.b64decode(body[image]) img_path /tmp/ocr_input.png with open(img_path, wb) as f: f.write(img_data) start time.time() result ocr.ocr(img_path, clsTrue) elapsed_ms (time.time() - start) * 1000 lines [] for image_lines in result: if image_lines is None: continue for box, (text, score) in image_lines: lines.append({ text: text, score: round(float(score), 4), box: [[int(p[0]), int(p[1])] for p in box] }) return jsonify({code: 0, elapsed_ms: round(elapsed_ms, 1), lines: lines}) except Exception as e: return jsonify({code: 1, error: str(e)}), 400 if __name__ __main__: app.run(host0.0.0.0, port8866, threadedTrue)部署逻辑说明ocr PaddleOCR(...)必须放在请求函数外否则每个请求都重新加载模型延迟会从几十毫秒变成几秒。threadedTrue开启 Flask 多线程PaddleOCR 的 inference 对象在同一进程内多线程调用是安全的但如果用 gunicorn 多 worker每个 worker 会独立加载一份模型内存按模型体积乘以 worker 数估算。实际性能核算按完整三段式链路算不是按单段模型算一张 960×960 文档图CPU MKLDNN 约 50-80msGPU TensorRT 约 20-40ms加上 HTTP 序列化开销单机 CPU 大概能支撑 5-8 QPSGPU 能到 20 QPS 上下。5. 避坑指南PaddleOCR 2.0 最常见的 5 个翻车现场5.1 安装阶段Python 3.9 装不上或者 import 崩现象pip install paddlepaddle提示找不到匹配的版本或者装完后import paddle直接段错误退出。原因PaddleOCR 2.0 发布时期的编译产物主要覆盖 Python 3.6-3.8 和 CUDA 10.1。3.9 之后的兼容性是后补的在某些机器上会触发底层内存分配问题。解决换 Python 3.8 环境重装。别为了迁就现有项目硬用 3.9conda 建个独立环境十分钟的事后面所有依赖都锁在里面出问题直接删掉重建。5.2 训练阶段Loss 一直是 0 或者不收敛现象训练检测模型前几个 iteration 打印的 loss 是 0.0000然后怎么训都没效果。原因学习率过大。PaddleOCR 2.0 的默认学习率是为从零开始训练准备的加载预训练权重之后微调学习率需要调低一个数量级。解决python tools/train.py \ -c configs/det/det_mv3_db.yml \ -o Global.learning_rate0.0005 \ Global.pretrain_weights./pretrain_models/ch_ppocr_mobile_v2.0_det_train/best_accuracy微调我一般用 0.0001 到 0.0005从头训练才用默认的 0.001。改完再看 loss 曲线前 500 个 iteration 应该明显下降。5.3 推理阶段识别结果里有神秘换行符现象识别文本末尾多出一个\n或\t看起来像文本自带换行导致后续入库、搜索、比对全部错位。原因识别模型训练时字典里包含特殊字符模型在序列末尾预测出了不可见字符这属于正常的后处理范围。解决解析结果统一清洗def clean_text(text): return text.replace(\n, ).replace(\t, ).strip()这不是模型 bug但新人容易在这种细节上浪费时间以为是识别错误其实后处理加一行就解决了。5.4 推理阶段GPU 上跑比 CPU 还慢现象把use_gpuTrue打开后单张图延迟反而比 CPU 高特别是小图。原因GPU 推理有显存读写和 kernel launch 开销2.0 自带的轻量模型在入门级 GPU 上加速收益抵不过这些开销。模型小到一定程度CPU MKLDNN 或新版 tiny 模型在 CPU 上跑的方案更划算。解决图像分辨率不大比如单行文字图、小票据截图直接用 CPU MKLDNN只有大图、大批量才值得用 GPU。这个判断可以用一个简单基准测试同一张图分别跑 CPU 和 GPU对比平均延迟别猜。5.5 部署阶段模型初始化卡死超过 30 秒现象PaddleOCR(...)构造函数执行几十秒甚至几分钟看起来像卡死。原因首次初始化会自动检查并下载模型文件。如果服务器网络受限访问模型下载源慢就会一直卡在下载阶段。重启后因为本地缓存已经写了一半可能还会重复卡住。解决在能上网的机器上先把模型下载好按版本和语言放到本地方便加载的目录mkdir -p ~/.paddleocr/2.0.6/ch/det ~/.paddleocr/2.0.6/ch/rec ~/.paddleocr/2.0.6/ch/cls # 把下载好的模型文件分别放进去放好后初始化时会跳过下载流程直接用本地文件。如果初始化后不确定模型读取的具体路径最简单的办法是加一行print(ocr.det_model_dir)把实际路径打出来按输出手动放置模型文件。6. 进阶把检测框拼成段落再从段落里抽出结构化字段6.1 检测框合并的坐标规则PaddleOCR 2.0 输出的是散落的检测框业务上经常需要把它们拼成段落。常见做法是按垂直坐标聚类先按框的中心 y 坐标排序相邻且 y 差小于阈值一般取行高的一半的框视为同一行再按 x 坐标从左到右拼接文本。def merge_boxes_to_lines(parsed, line_threshold_ratio0.5): 按 y 坐标聚类检测框并拼接成行 if not parsed: return [] # 按中心 y 排序 for item in parsed: ys [p[1] for p in item[box]] item[center_y] sum(ys) / 4 item[height] max(ys) - min(ys) parsed.sort(keylambda x: x[center_y]) lines [] current_line [parsed[0]] for item in parsed[1:]: prev current_line[-1] threshold max(prev[height], item[height]) * line_threshold_ratio if abs(item[center_y] - prev[center_y]) threshold: current_line.append(item) else: lines.append(current_line) current_line [item] lines.append(current_line) result_lines [] for line in lines: line.sort(keylambda x: min(p[0] for p in x[box])) result_lines.append({ text: .join(item[text] for item in line), y: round(sum(item[center_y] for item in line) / len(line), 1) }) return result_lines这里的line_threshold_ratio是关键参数票据、文档这类排版整齐的图取 0.5 就很稳如果版面有倾斜可以提高到 0.8但代价是上下两行靠得近时会被错误合并。6.2 从识别结果里抽字段的正则方案我的习惯是PaddleOCR 2.0 负责把图像转成文本结构化字段抽取交给正则和规则不在模型层做。比如发票号、金额、日期这类有固定格式的字段基于合并后的行文本写正则可解释、好维护。import re def extract_key_fields(lines): 从合并行的文本里抽常见字段演示用 text_map {line[text] for line in lines} fields {} # 金额支持千分位和两位小数 for text in text_map: m re.search(r[¥]?\d{1,3}(?:,\d{3})*\.\d{2}, text) if m: fields[amount] m.group() break # 日期支持 2024-01-01 / 2024/01/01 / 2024年1月1日 for text in text_map: m re.search(r\d{4}[-/年]\d{1,2}[-/月]\d{1,2}日?, text) if m: fields[date] m.group() break return fields正则在这个场景里的优势是零成本、可调试字段格式一变改正则就行不用重新标注训练。如果字段是开放文本比如品名、备注那才需要考虑用命名实体识别或基于字典的匹配而不是硬塞给 OCR 模型。我早期做发票识别时习惯把后处理全堆在识别文本上后来发现很多「识别错误」其实是行合并顺序错了、或者清洗规则没覆盖到。PaddleOCR 2.0 只是把图像变成文本的工具工具之外的工程问题占产线工作量的七成以上。这个认知比换任何新模型都值钱希望帮到你。本文还有配套的精品资源点击获取