简介：基于飞桨（PaddlePaddle）的中文OCR轻量化工具库，以8.6M超小总模型实现高效文字检测与识别，面向嵌入式、移动端及服务端中文场景，解决中英文混合、数字组合及竖排文本识别难题。压缩包包含702个文件，涵盖Python脚本、图片样本、Markdown说明、YAML配置文件及C++/Java扩展等，合计约58.45MB，源码与预训练模型齐备，便于快速部署与二次开发。已有1119人学习下载。资源内置完整PaddleOCR-release-2.1工程，提供RNN、LSTM、CRNN、Transformer等多种训练算法示例、微调脚本及清晰目录结构，适合机器学习初学者理解OCR原理，也适合开发者直接调用API实现身份证、地址等场景识别，并根据业务数据进一步优化模型精度。
1. 8.6M的轻量中文OCR：这个数字是怎么来的，又为什么值得动手
基于飞桨生态的这套OCR工具库，卖点都写在标题里：总模型只有8.6M，Python调用，中文识别开箱即用。这个数字在选型会议上很有说服力，但真落地之后你才会理解，它说的是模型本身很轻，不是整个运行环境很轻——真正决定项目能不能跑起来的，是CPU推理耗时、缓存目录里那几百兆的框架轮子和一张复杂图片上的识别率。
我接手过不少识别项目：发票、截图、说明书翻拍、聊天记录取证，图片里中文识别率翻车的情况并不少见。这套工具库能覆盖的场景很明确：文字清晰、排版相对规整的文档和截图；不适合艺术字、严重透视畸变和低照度拍摄。这篇笔记按我自己的落地习惯写：说清8.6M的体积是什么，给最小可跑代码、四个必调参数、五个踩坑记录，最后补一条让结果可直接入库的后处理技巧。适合正在做选型、或者刚装上还没跑通第一张图的人。
2. 三段式架构与8.6M的体积口径：检测、方向分类、识别各管什么
2.1 检测：先回答“文字在哪一行”
OCR的第一步永远不是认字，而是找字。检测模型解决的是“图片上哪些区域有文字”的问题，输出是一组文本框坐标，每一框对应一行或一个独立语块。这套轻量模型里检测部分遵循的是DB思路：对特征图做可微二值化，把“预测为文字的概率图”转换成“文字区域掩码”，再通过轮廓提取得到四边形框。这个环节决定了后续识别模型看什么内容，框少了会漏字，框多了会把背景纹理也送进识别器。
检测模型能做到这么小的主要原因，是通道数和分辨率都做了压缩。代价是对模糊文字、印章压字和复杂底纹的鲁棒性变差，这属于模型体积换速度的典型取舍。如果图片里文字清晰、背景干净，这个检测模型的表现会非常稳定；如果检测框本身飘了，后面怎么调识别参数都救不回来。所以遇到识别结果不对，我第一个动作永远是先把检测框可视化看一下，而不是急着改识别阈值。
2.2 方向分类：为什么中文场景需要这一路
方向分类是这个三段式流程里最容易被忽略、又最值钱的一环。它本质上是一个极轻量的分类网络，判断当前图像是否需要旋转90度或180度。手机拍单据、随手扫码拍纸质文档时，图片经常是旋转过的，方向分类器会先把图像摆正，再交给检测和识别，从源头减少误判。
初始化时对应的开关是use_angle_cls=True，调用识别时再配一个cls=True，两个配对出现才生效。如果你的图片来源是程序截图、固定摄像头俯拍，方向永远是正的，可以考虑关掉方向分类器，每张图省下几毫秒推理时间。竖排中文古文书、侧拍的立牌和招牌，这个组件的作用就很明显了，建议保留。要注意的是：方向分类并不会逐行判断方向，它看的是整张图的大方向，所以一张图里混着正的和倒的文本时，还是得靠检测框粒度做后处理。
2.3 识别与8.6M的真实口径
识别模型解决“画出来的框里是什么字”。通用技术路线是先经卷积网络提取视觉特征，再用序列建模把特征梳理成字符序列，最后通过CTC一类解码输出每个字符在字典里的索引。模型输出不是文字本身，而是字典下标，这就是为什么模型目录里通常还附着一个字典文件，运行时靠它把索引换回中文。字典体积从几百KB到1MB不等，它属于运行时资源，不属于模型权重口径。
标题里的8.6M，我倾向于理解为检测、方向分类、识别三个模型推理权重的合计体积，不同小版本里单个模型的尺寸略有出入，所以8.6M是个约数口径。它不包括飞桨运行库本身，也不包括字典、内置字体和后处理脚本。装进你环境的paddlepaddle基础轮子是几百兆级别的，所以“8.6M”在部署语境下的真实含义是：模型权重小，低配设备上放得下，换到GPU里也几乎不占显存。判断生产环境要不要选它，不该只盯着8.6M，而是看推理耗时和内存占用。
| 组件 | 负责的事 | 可否关闭 | 关闭后的影响 |
|---|---|---|---|
| 检测 | 找出所有文本框 | 不建议关 | 识别没有输入 |
| 方向分类 | 纠正整图旋转 | 可以关 | 倒置/竖排图识别率明显下降 |
| 识别 | 把框转成文字 | 不可以 | 没有文本输出 |
3. 用Python跑通最小可用方案：安装、初始化与第一张图的识别
3.1 环境准备与推理后端选型
先装底层计算库，再装OCR套件，顺序反了也能装，但容易装出依赖冲突。最稳的做法是给项目单独建一个虚拟环境，里面只装这套依赖，避免和公司的其他深度学习项目互相污染。CPU场景直接装CPU版底层库即可，GPU场景要装对应的GPU版本，并且不要把CPU版和GPU版混装在一起。
# CPU版，适合绝大多数调试场景 pip install paddlepaddle # GPU版本地安装后，再用下面命令确认是否能正确调用显卡 python -c "import paddle; paddle.utils.run_check()"装完底层库再装OCR依赖库，pip install paddleocr即可。第一次初始化时会自动下载检测、方向分类、识别三个模型到用户目录的缓存文件夹里，这个过程会真实连接外部模型托管地址，网络状态差的时候会显得像卡死，后面避坑章会专门讲。装好后不要一上来就调参，先用默认参数跑一张清晰的截图，确认流程能走通，再进入调参阶段。
3.2 最小识别代码：识别一张本地图片并拿到文本和置信度
下面这段是跑通流程的最小代码，几乎每次我都会先拿它验证环境。代码里做了注释，方便逐行对照。
from paddleocr import PaddleOCR # 初始化一次，全局复用，不要在每次请求里重复创建 ocr = PaddleOCR( use_angle_cls=True, # 启用方向分类器，自动纠正旋转图片 lang="ch", # 使用中文识别模型 show_log=False, # 关闭调试日志，保持终端干净 ) # 识别单张图片；cls=True 和上面的 use_angle_cls 配套使用 result = ocr.ocr("sample.jpg", cls=True) # result 的第一项对应第一张图，每行包含文本框和识别结果 for line in result[0]: box = line[0] # 文本框四个角坐标 text, score = line[1] # 识别文本与置信度 print(f"{score:.3f}\t{text}")use_angle_cls=True决定初始化时是否加载方向分类模型，cls=True决定本次调用是否执行方向判断，两个开关少一个，方向纠正就不生效。lang="ch"指定加载中文模型，识别英文混排时一般也够用，但纯英文场景建议单独试英文模型，速度和准确率都更合适。result[0]的每一项都是[box, (text, score)]结构，box是四角坐标列表，score是模型置信度，范围在0到1之间。如果result[0]是空列表，说明检测或识别环节没有产出结果，这通常不是代码写错，而是参数或图片本身的问题。
3.3 批量识别目录下的图片：路径、日志与错误处理
单张跑通后，下一步就是把一张张处理变成一批批处理。批量脚本有几个工程细节值得注意：文件后缀要过滤、单张失败不能拖垮整个目录、中文路径在部分环境里会造成读图异常。下面这段是我常用的批处理骨架。
from pathlib import Path ocr = PaddleOCR(use_angle_cls=True, lang="ch", show_log=False) for img_path in Path("./imgs").glob("*"): # 只处理常见图片格式，避免把临时文件也送进识别 if img_path.suffix.lower() not in (".jpg", ".jpeg", ".png", ".bmp"): continue try: result = ocr.ocr(str(img_path), cls=True) lines = result[0] if result and result[0] else [] for _, (text, score) in lines: print(f"{img_path.name}\t{score:.3f}\t{text}") except Exception as e: # 记录失败文件，继续处理后续图片 print(f"失败: {img_path.name} -> {e}")Path.glob("*")会匹配目录下所有文件，通过suffix.lower()过滤后缀，把非图片文件挡在门外。单张图片解码失败、模型推理异常都不应该中断整个目录，所以用try/except包住每一张的处理逻辑，失败信息打印出来，后续再用这些日志复盘。路径方面，我一般会把中文文件名改成拼音或英文序号再跑批处理，少一个变量，多一份省心。
4. 从能跑到能用：四个关键参数和两类预处理边界
4.1 四个必调的识别参数与适用场景
跑通只是第一步，真实图片永远不会像样例图那么干净。这套工具库把推理参数暴露在构造器里，大部分问题靠四个参数就能解决。参数调起来有点玄学成分，因为效果和图片内容强相关，同一个参数在这一批图上有效，换一批图可能反而变差，所以调参要一次只动一个，不要同时改三四个值。
from paddleocr import PaddleOCR # 带核心参数的初始化示例，按需取值，不要照抄 ocr = PaddleOCR( lang="ch", use_angle_cls=True, det_db_thresh=0.3, # 文本框检测阈值，0.3~0.5 之间常见 det_limit_side_len=1280, # 输入图像最长边，大图可适当调大 rec_batch_num=6, # 每批识别行数，CPU 上建议 4~8 show_log=False, )det_db_thresh是检测阶段的置信度阈值，控制“一个区域算不算文字框”。调低能召回更多模糊文字框，但会把底纹、水印、复杂背景一起框进来；调高则只保留确信的文字区域，代价是漏检。低对比度扫描件和手机翻拍，我一般从0.3往下探；高清截图反而可以上调到0.4以上，让检测结果更干净。
det_limit_side_len控制送入检测模型的图像最长边。默认值在960附近，超过这个边长的图片会被等比缩小，避免显存和内存溢出。分辨率高、文字小的图片如果被缩小，小字就糊成一片，检测框直接消失。遇到这类图，我会先把这个值调到1280再测试，观察内存占用能接受就继续往上加。它不是越大越好，调大后推理耗时会明显上升，内存也可能告急。
rec_batch_num是识别阶段每批处理的行数。检测出几十行文字后，识别模型会分批处理，批次越大吞吐越高，但显存和内存占用也水涨船高。GPU上可以开到16到32，CPU上我一般维持4到8，超过这个范围往往只是让CPU风扇转得更响，速度提升很有限。
文本置信度阈值建议保留在默认位置，不要一上来就调。它过滤的是“识别结果可信度低”的行，调高了会把正确结果一起扔掉，调低了又放进一堆乱码。合理的做法是先把低于阈值的行打印出来人工看一遍，判断是对还是错，再决定阈值方向。
4.2 长图与多栏文本：什么时候该改预处理而不是改参数
参数调不出效果时，问题往往在图片本身。反色文字、印章压字、倾斜角度大、分辨率超高这四类场景，改模型参数不如改预处理。反色图指的是深色底浅色字，检测模型是拿自然场景图训练出来的，对这种图经常一整片框不出来，常见做法是先做像素取反，再进OCR。
印章压字在发票和合同识别里非常常见，红色印章和黑色文字叠在一起，检测框可能把两者框成一体，识别结果里掺进印章纹理。预处理层面先做颜色通道分离，取出红色通道作为掩膜，或者对图做去红处理，通常比调阈值有效得多。倾斜超过一定角度时，整行文字在检测器眼里是斜的，方向分类器只做整图纠正，没法逐行拉平，所以在送入OCR前先把图片做透视矫正会更可靠。
超长截图是另一个高频场景，一张聊天记录长图可能横跨几千像素。直接把整图送进模型，det_limit_side_len会把图像压缩到看不见小字。更实用的做法是把长图按高度切片，每片800到1000像素，重叠少量区域防切断行，再逐片识别。这里有个判断标准：如果同一张图在两种不同预处理下结果差异很大，问题就在预处理，不在参数。
4.3 CPU上的加速项与GPU确认
CPU环境里一个常见困惑是“为什么别人的GPU跑得飞快，我的CPU版本慢得像PPT”。模型本身不大，但框架在CPU上的算子效率和GPU完全不同。CPU上能做的优化比较有限，但有一件事值得检查：初始化时留意是否支持MKL-DNN或类似算子加速选项，有就打开，能在Intel系CPU上获得可感知的加速。旧版本里习惯传use_gpu=True的地方，新版本往往改成自动检测了，遇到这个参数直接不传即可。
GPU环境要确认框架确实在用显卡。很多项目翻车在“装了GPU框架却没装GPU版底层库”，或者“两个版本底层库同时存在导致加载错乱”。验证手段很直接：
python -c "import paddle; paddle.utils.run_check()"输出里能明确看到设备类型和健康状态。如果输出显示CPU而不是GPU，优先检查安装包是否纯净。GPU推理还有一个容易被忽视的点：模型加载和预处理本身有不少时间花在CPU到显存的拷贝上，小图识别时这部分开销占比很高，所以不要期待GPU在任何图上都比CPU快一个数量级。
5. 避坑指南：中文OCR落地最容易踩的5个坑
5.1 首次运行卡在模型下载
现象：代码看起来在运行，日志停留在下载模型阶段，进度条不动，等很久也没结果，第一次跑很容易误判成死循环或代码问题。我也是第一次跑这类工具时盯着终端看了五分钟才反应过来它是在联网下模型。
原因：初始化时框架自动下载检测、方向分类、识别三个模型到用户目录，文件总共几十兆，但下载源有时不稳定，网络环境差就会出现长时间停滞。
解决：先确认模型已经完整落盘，再去用户目录下找缓存文件夹。如果有残缺文件就清掉重新下载。离线环境更省心的做法是部署前在有网机器上跑一次完整流程，把缓存目录整体拷走，部署时通过构造器里的det_model_dir、rec_model_dir、cls_model_dir指定本地模型路径，避免每次启动都尝试联网。提前把模型缓存好，是所有离线部署场景的后悔药。
5.2 GPU装了却还在用CPU
现象：明明按GPU方式装的环境，跑推理时风扇不转、耗时很长，日志或性能监控显示计算发生在CPU上。这个问题在多人共用的开发机上特别常见。
原因：最常见的是环境里同时存在CPU版底层库和GPU版底层库，导入时加载到了CPU版本；其次是GPU版底层库对应的CUDA运行环境不匹配，框架自动回退到CPU。
解决：卸载CPU版依赖只保留GPU版，然后重新执行paddle.utils.run_check()确认设备信息。如果确认失败，优先检查CUDA相关运行库是否完整。不要在没确认设备状态的情况下盲目调参，否则一切优化都作用在CPU路径上，白费力气。
5.3 多行文本顺序乱
现象：一张从上到下排列的截图，识别结果是逐行输出的，但顺序完全随机，有时是后一行先输出，有时是同一行文字被拆成多段混排。直接入库时数据乱得没法用。
原因：OCR输出的顺序由检测置信度或内部处理顺序决定，不等于阅读顺序。人类按“从上到下、从左到右”读，模型并不关心顺序。
解决：在后处理里按文本框坐标自己排序，取每行框的平均Y值做初步分组，同组内再按X值排序，这个技巧最后一章会给出完整代码。这里先强调一点：任何接数据库或对接业务系统的项目，都必须自己做一次坐标排序，不能信任OCR接口返回的原始顺序。
5.4 明明有文字，结果却返回空
现象：图片里肉眼能看清楚的中文，OCR返回空列表，或者打印出来的文本全是无意义字符。我第一次在合同扫描件上遇到时，第一反应是模型没加载对。
原因：检测阈值和识别阈值设置过高，把轻微模糊、低对比度的文字全滤掉了；或者图片本身是反色的；又或者输入分辨率太低，文字在模型眼里就是一团噪点。
解决：先看单张图在默认参数下的置信度分布，如果大部分行置信度低于0.3，通常是图片质量问题，优先做预处理；如果检测框根本没出现，就往下调det_db_thresh。反色图做像素取反，模糊图先做锐化和放大。这个问题的核心是：空结果往往不是模型坏了，而是输入和参数不匹配。
5.5 服务里反复初始化，内存一路涨
现象：接口初次调用正常，连续调用几十次后内存占用持续上升，最后响应变慢甚至崩溃。这个问题在Web服务里很典型，每次请求都new了一个新的OCR实例。
原因：每次初始化都会加载模型、分配推理资源，对象生命期结束后资源没有完全释放。反复创建销毁实例既慢又浪费内存。
解决：把OCR实例设计成全局单例，进程启动时初始化一次，之后所有请求共用。多线程并发调用时还要注意推理接口本身是否线程安全，不确定的情况下用锁或队列把请求串行化，或者在主线程预热一次再对外服务。内存涨不回去，大概率是实例没复用，而不是框架泄漏。
6. 让结果可直接交付：按坐标重排阅读顺序并保留置信度
坐标准重排是OCR落地里最不起眼、收益却最明显的后处理。识别接口返回的行顺序不可依赖，而业务系统需要的往往是“像人一样从左到右、从上到下读出来的文本块”。下面这段代码把每行文本按坐标排序，并给置信度偏低的行打上复核标记，保证交付给下游的不是一堆乱序字符串。
def render_readable(result, y_bucket=20): lines = result[0] if result and result[0] else [] items = [] for box, (text, score) in lines: xs = [pt[0] for pt in box] ys = [pt[1] for pt in box] items.append({ "text": text, "score": score, "x_min": min(xs), # 行内最左侧坐标 "y_mean": sum(ys) / len(ys), # 行的平均高度 }) # 按“行位于哪个高度区间”分组，区间内再按从左到右排 items.sort(key=lambda it: (round(it["y_mean"] / y_bucket), it["x_min"])) return items items = render_readable(result) for it in items: flag = "" if it["score"] >= 0.7 else " [需复核]" print(f"{it['score']:.3f}\t{it['text']}{flag}")排序逻辑的关键是round(y_mean / y_bucket)这个表达式。它把图片高度切成若干个20像素的横条，每行文本按自己的平均Y值落入对应的横条，同横条内的行再按x_min从左到右排。这样做的效果是：同一行文字即使检测框上下有小幅抖动，也会被归到同一个高度区间，不会因为Y坐标差两个像素就上下颠倒。
y_bucket不是固定不变的，它应该随图片分辨率浮动。高清大图里一行文字可能有40像素高，20像素的桶会把一行切成上下两段；扫描件里一行只有15像素高，桶太大会把上下两行混在一起。我一般会先看检测框的平均高度，取它的一半作为桶大小，这样对不同分辨率的图都能自适应。这个后处理让OCR结果从“一堆文本”变成“一块可读文本”，配合置信度复核标记，已经足够直接写入结构化数据了。
我现在养成的习惯是：任何一个新场景，先拿五张有代表性的图跑默认参数，把每行文本和置信度打印出来看一遍，而不是上来就调参。置信度低往往不是调用参能解决的，它更多是在提醒我图片预处理还有问题。这个习惯帮我省下了大量翻车时间，也让我对模型边界心里有数。希望帮到你。
本文还有配套的精品资源，点击获取
