简介：面向希望基于 PaddleOCR 2.6 快速上手文本检测与识别训练的开发者和初学者，提供从零开始的实操教程，教程以 Word 文档形式整理，包内共 1 个 docx 文件，整体大小约 78KB。内容按环境配置、依赖安装、PPOCRLabel 标签标注、数据集划分、YML 配置、模型训练与验证、推理模型导出等阶段循序渐进，命令和步骤清晰，基本覆盖了自定义 OCR 模型训练的完整链路。除了基础流程，文档还重点解释了训练与验证目录的路径设置、batchsize 限制、按验证精度自动保存最优权重等细节，并记录了导出推理模型时 pretrained_model 参数不生效的常见问题，给出了将训练权重直接写入 YML 配置文件的解决方法，能有效减少踩坑。已有 1304 人浏览学习，适合正在入门 OCR、准备基于 PaddleOCR 训练自定义检测或识别模型的读者参考。
1. 为什么 PaddleOCR 2.6 版本仍是落地首选
PaddleOCR 2.6 是飞桨团队在 2022 年发布的稳定分支，虽然现在社区早就在聊 3.x，但真做生产项目时，很多老牌图像处理系统和数据中台场景里，2.6 版本依旧是上线率最高的那个。原因不复杂：这个版本把检测、方向分类、识别三件套拆得清清楚楚，接口签名不再频繁变动，对 PyTorch 模型转换、ONNX 导出、PyInstaller 打包都有成熟的解法。对于 5 年以上的工程师来说，选 2.6 不是为了追新，而是为了省心。下面直接从零搭建环境、跑通第一行识别代码，再逐步把模型参数、乱码问题和打包部署的坑填平。
2. 从 Python 版本到依赖：PaddleOCR 2.6 环境搭建的完整路径
2.1 conda 环境与 Python 版本选择
PaddleOCR 2.6 官方要求 Python 3.6 到 3.10 都能用，但实际测试下来，Python 3.8 和 3.9 是最稳的组合，因为后续的 onnxruntime、pyinstaller、opencv-python 在这两个版本上的预编译轮子最齐全。我一般会用一个独立的 conda 环境来隔离依赖，避免和项目里已有的机器学习库发生版本冲突。
conda create -n paddle python=3.9 -y conda activate paddle创建环境的命令不需要加额外参数，python=3.9 会直接拉取当前 conda 源里可用的 3.9 最新补丁版本。激活后，建议先升级 pip 和 setuptools，因为过旧的 setuptools 会导致部分依赖的 wheel 在安装时被判定为不支持当前平台。
python -m pip install --upgrade pip setuptools wheel然后安装 PaddlePaddle 基础框架。这里要特别注意 CPU 和 GPU 版本的选择：如果你的机器只有 CPU，就安装 CPU 版；如果有 N 卡且 CUDA 版本是 11.2 或更高，就装 GPU 版。下面是两种常见方式。
# CPU 版本 pip install paddlepaddle==2.6.1 -i https://mirror.baidu.com/pypi/simple # GPU 版本（CUDA 11.7 的示例，按自己环境调整） pip install paddlepaddle-gpu==2.6.1.post117 -i https://mirror.baidu.com/pypi/simple使用百度镜像源能明显加快下载速度，但要注意镜像源只对 pip 生效，conda 创建环境时不会使用这个源。安装完成后，可以用下面的 Python 代码验证框架是否正常。
import paddle print(paddle.__version__) print(paddle.is_compiled_with_cuda())如果is_compiled_with_cuda()返回 False，说明装的是 CPU 版，或者 GPU 版和当前 CUDA 驱动不匹配。这时不要急着换版本，先检查nvidia-smi驱动支持的 CUDA 版本，再决定是否重新安装。
2.2 安装 PaddleOCR 2.6 及配套依赖
框架就绪后，接着安装 PaddleOCR 本体。这里建议直接指定版本号，避免 pip 自动拉到 3.x 导致接口不一致。
pip install paddleocr==2.6.1 -i https://mirror.baidu.com/pypi/simple安装过程中，pip 会自动拉取 opencv-python、shapely、pyclipper、numpy 等依赖。需要注意，PaddleOCR 2.6 对 numpy 的版本要求是 1.21 到 1.24 之间，如果后面安装 pyinstaller 时把 numpy 升级到 1.26，就会出现数据格式错误。最稳妥的做法是，装完 PaddleOCR 后再执行一次紧固定位。
pip install numpy==1.24.4 -i https://mirror.baidu.com/pypi/simple另外，如果你需要在服务端部署或者做并发请求，建议同时安装 shapely 的二进制版本，而不是源码编译版。源码版在个别 Linux 环境下会导致多边形计算报错，具体表现是文字框坐标出现负数或不闭合。
pip install shapely==2.0.1安装完成后，建议在命令行里跑一次paddleocr -h，确认paddleocr命令能正常调用，再进入下一节的代码实战。如果报缺失库，先看错误信息里是ModuleNotFoundError还是编译错误，前者一般是缺 pip 包装，后者通常是 C 库冲突。
3. 一行代码跑通检测、方向分类与识别
3.1 最小识别脚本：PaddleOCR 2.6 的训练推理接口
PaddleOCR 2.6 提供了一体化的 Python 调用方式，不需要手动加载三个模型。下面的代码就是最常用的最小实现，它会自动下载默认的中文轻量模型到~/.paddleocr/目录。
from paddleocr import PaddleOCR ocr = PaddleOCR(use_angle_cls=True, lang='ch', show_log=False) result = ocr.ocr('demo.jpg', cls=True) for item in result: for line in item: print(line)PaddleOCR类的构造函数里，use_angle_cls=True表示启用方向分类器。这个参数在手机拍摄、扫描件角度偏移的场景下必须打开，否则识别文本时会把倒置或旋转 90 度的文字直接判读为乱码。lang='ch'指定中文模型，加载时会自动下载检测、方向分类、识别三个模型。show_log=False可以关闭推理过程中的调试日志，避免在批处理时刷屏。
ocr.ocr('demo.jpg', cls=True)的第一个参数支持图片路径、numpy 数组和 bytes 数据。返回格式是两层列表：外层对应每张图，内层对应每个文字框。每一行的数据结构是[框坐标, (识别文本, 置信度)]，所以上面的打印结果会是一个四元组加一个元组。
3.2 带坐标输出的解析方法
实际业务中往往需要把文字框坐标和识别内容分开处理，比如做答题卡识别、票据信息抽取。下面的代码演示如何把结果转成字典结构。
from paddleocr import PaddleOCR ocr = PaddleOCR(use_angle_cls=True, lang='ch', show_log=False) result = ocr.ocr('invoice.jpg', cls=True) parsed = [] if result and result[0]: for box, (text, confidence) in result[0]: parsed.append({ 'box': box, 'text': text, 'confidence': float(confidence) }) for item in parsed: print(item)这里需要注意，result[0]在无文字区域时会返回None，所以要先判断再遍历，否则会抛TypeError。坐标box是四个点组成的列表，每个点又是[x, y]两个值。它遵循的是顺时针顺序，可以和 OpenCV 的polylines函数直接配合画框。
3.3 图片预处理对识别效果的影响
2.6 版本的模型虽然效果好，但也不是万能。现场操作时，给模型喂一张亮度过高、文字阴影明显的图片，结果往往还不如先做一次灰度化和二值化。我一般会在调用 OCR 前，先用 OpenCV 做一次自适应阈值处理，但要注意不能把二值化后的图片直接交给识别器，因为训练数据里包含彩图和灰度图，二值化后的纹理信息丢失太多反而降低精度。
import cv2 from paddleocr import PaddleOCR def preprocess(image_path, output_path): img = cv2.imread(image_path) gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) thresh = cv2.adaptiveThreshold( gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 31, 10 ) cv2.imwrite(output_path, thresh) return output_path ocr = PaddleOCR(use_angle_cls=True, lang='ch', show_log=False) result = ocr.ocr(preprocess('dark_text.jpg', 'temp.jpg'), cls=True)这里ADAPTIVE_THRESH_GAUSSIAN_C是用邻域高斯加权和减去常数 C 作为阈值，31是邻域大小，必须是奇数。对于文字阴影严重的场景，这个值比全局二值化稳定得多。当然，如果原图本身是清晰的白底黑字，就不要做任何预处理，直接走原图反而更快。
4. 参数调优与模型替换：PaddleOCR 2.6 的高阶控制
4.1 检测、分类、识别三个模块的独立开关
PaddleOCR 2.6 的一个核心设计是检测、方向分类、识别三者可以分开控制。默认的构造参数里，det=True, cls=True, rec=True表示三个模型全部启用。如果做纯的固定版式截图识别，可以选择关闭方向分类器，减少一次前向推理时间。
ocr_fast = PaddleOCR( use_angle_cls=False, lang='ch', det=True, rec=True, show_log=False )关闭方向分类器后，推理速度能提升约 15% 到 20%，但代价是输入的图片必须保证文字方向正确。对于自动化脚本抓取的网页截图或合同 PDF 转图，这个优化是安全的；对于手机随手拍的发票，就不要省这一步。
还可以单独关闭检测模块，直接给识别器喂一张已经裁剪好的单行文字图片。这种方式适合处理只有一行文字的证件号码、银行卡号等场景。
ocr_rec_only = PaddleOCR(use_angle_cls=False, lang='ch', det=False, rec=True, show_log=False) result = ocr_rec_only.ocr('single_line.png', cls=False)注意，当det=False时，ocr.ocr返回的结果格式也会变化，不再有框坐标，而是直接返回识别文本和置信度。这个改版容易让人困惑，官方文档里没有在显眼位置说明。如果你在调用时发现解析结果维度不对，先检查是不是关闭了检测模块。
4.2 常用推理参数表
下面这张表总结了 2.6 版本里最容易影响结果的几个参数，对应构造器和ocr.ocr方法中的字段。
| 参数名 | 所属对象 | 默认值 | 作用 | 推荐调整方式 |
|---|---|---|---|---|
use_angle_cls | 构造器 | True | 是否启用方向分类 | 图片方向固定时设 False 提速 |
det_limit_side_len | 构造器 | 960 | 检测阶段最长边尺寸 | 大图长边超过 960 时按比例缩放 |
det_db_thresh | 构造器 | 0.3 | 检测二值化阈值 | 低阈值能找更多弱文字框 |
det_db_box_thresh | 构造器 | 0.6 | 文本框过滤阈值 | 高阈值能过滤噪声框 |
rec_batch_num | 构造器 | 6 | 识别批大小 | 显存不足时调小到 1 或 2 |
drop_score | ocr.ocr | 0.5 | 置信度过滤 | 票据场景可提高到 0.7 |
cls | ocr.ocr | 按构造器 | 本次调用是否分类 | 特殊情况单独覆盖构造器设置 |
以det_limit_side_len为例，这个参数控制在检测阶段把输入图片缩放到的最大边长。如果一张扫描件是 4000 像素宽，模型会先压缩到 960 再检测，但识别阶段会按原始坐标映射，所以最终的框坐标依然是原始尺寸。需要提高小字识别率时，可以把值调到 1280，但显存占用会明显增加。
4.3 替换官方模型为自定义模型
企业项目里很少直接使用默认的轻量模型，因为场景太特殊，比如识别印章里的篆体字、工厂铭牌上的点阵数字。PaddleOCR 2.6 支持直接替换三个模块的模型路径，不需要改代码。
ocr_custom = PaddleOCR( det_model_dir='./models/det_infer/', rec_model_dir='./models/rec_infer/', cls_model_dir='./models/cls_infer/', use_angle_cls=True, lang='ch', show_log=False )这里的模型目录必须是 PaddleOCR 的推理格式目录，包含inference.pdmodel和inference.pdiparams两个文件。如果你的模型是从训练好的权重通过paddleocr/tools/export_model.py导出的，直接指向导出目录即可。如果只有model.pdparams训练权重，需要先走一遍导出流程，否则会报参数形状不匹配的错误。
替换模型时，最容易碰到的问题是字典文件不匹配。默认中文模型的字典是 6623 个字符，如果你的识别模型使用了自定义字典，需要把rec_char_dict_path参数也指向对应字典文件。不然识别结果显示的都是“口”字或空字符，和文字乱码表现相似。
5. 乱码、内存爆炸与 PyInstaller 打包：PaddleOCR 2.6 的三大拦路虎
5.1 识别结果乱码的真正原因
很多新手把 PaddleOCR 识别出来的“口口口”称为乱码，但其实多数时候不是模型错，而是字体或编码问题。首先排查图像本身有没有乱码，这是最常见的原因。用 OpenCV 读入图片时，如果原图本身是带颜色的花体字，OCR 会输出不可读字符。这时优先做灰度化和降噪，而不是调模型。
另一个高频原因是lang参数和模型文件不匹配。如果你指定lang='en'却装了中文模型，识别结果就是一堆无意义的英文组合。当你在同一台机器上切换过多个语言模型后，最好用ocr = PaddleOCR(lang='ch')重新初始化，而不是复用之前的实例，因为模型缓存的加载逻辑在某些版本下有 bug。
最后要确认控制台的输出环境是否支持中文。PyCharm 的默认编码可能是GBK，而标准输出中文本就是 UTF-8，这会导致打印时显示乱码但实际识别是正常的。验证方法很简单：把结果写入文件后用文本编辑器打开，如果文件里是正确的，那就是控制台编码问题，不是 OCR 问题。
import json with open('result.json', 'w', encoding='utf-8') as f: json.dump(parsed, f, ensure_ascii=False, indent=2)5.2 PyInstaller 打包时常见的依赖遗漏
pyinstaller打包 PaddleOCR 程序是个老问题，核心在于隐式导入的模块不会被自动收集。最常见的报错是缺少paddleocr包内的模型配置文件和数字库，或者缺少paddle的第三方 C 扩展。
我建议的打包命令是把 PaddleOCR 相关的包全部用--collect-all收进来，同时排除不必要的大文件以减少体积。
pyinstaller --onefile \ --name ocr_tool \ --collect-all paddleocr \ --collect-all paddle \ --collect-all shapely \ --collect-all pyclipper \ --hidden-import=imghdr \ --exclude-module matplotlib \ main.py这里的--collect-all paddleocr会把包内所有.json、.txt、.pdmodel配置一并打进 dist 目录，避免运行时找不到默认模型配置。shapely和pyclipper这两个库在 Linux 下经常链接动态库，--collect-all能自动带上.so文件。打包完成后，需要在没有安装 Python 的干净机器上测试，因为很多依赖只在开发环境里存在。
如果你的程序在打包后启动就闪退，先用终端在 dist 目录手动运行./ocr_tool，然后看最后的 Traceback。90% 的错误指向ModuleNotFoundError: No module named 'xxx'，这时候把对应模块加到--hidden-import后重新打包即可。
5.3 内存占用过高与显存释放
2.6 版本的检测模型在 CPU 上运行会占用 1.5GB 到 2GB 内存，这还不包括图片加载的临时缓冲。处理大图时，如果det_limit_side_len配置得过高，内存峰值可能直接翻倍。更危险的是，GPU 版的显存并不会在ocr.ocr调用结束后自动释放，多次调用后显存会逐渐涨满。
遇到显存泄漏，可以显式清理飞桨的内存池。
import paddle ocr = PaddleOCR(use_angle_cls=True, lang='ch', show_log=False) # 每处理一批后调用 result = ocr.ocr('batch1.jpg', cls=True) paddle.device.cuda.empty_cache()empty_cache()的作用是释放飞桨内部缓存但没有归还给驱动，实际显存可能依然被占用，但在下一批推理时不会继续累积。真正彻底释放显存的办法是重启进程，或者用子进程方式单独处理 OCR，任务结束就销毁子进程。
6. 用 PaddleOCR 2.6 搭一个 Web 服务并处理批量图片
到了实际应用层，我经常被问到如何把 OCR 放到一个 HTTP 服务里。这里有现成的手段：2.6 版本的PaddleOCR实例本身不是线程安全的，直接塞进 Flask 里多线程处理会导致 CPU 资源抢占和模型预测崩溃。最稳妥的方案是用multiprocessing创建独立的 OCR worker 进程，主进程只做任务分发。
from multiprocessing import process from paddleocr import PaddleOCR def worker(input_queue, output_queue): ocr = PaddleOCR(use_angle_cls=True, lang='ch', show_log=False) while True: img_path = input_queue.get() if img_path is None: break result = ocr.ocr(img_path, cls=True) output_queue.put(result) if __name__ == '__main__': q_in = Queue() q_out = Queue() p = Process(target=worker, args=(q_in, q_out)) p.start() q_in.put('test.jpg') print(q_out.get()) q_in.put(None) p.join()这个模式可以扩展到四个进程，每个进程一个PaddleOCR实例，相当于四倍吞吐。实际测试中，CPU 机器上 2 个进程收益最明显，超过 4 个进程会开始受硬盘读取速度限制。注意不要把同一个PaddleOCR对象传给子进程，因为飞桨模型不能跨进程共享。
如果你只是想做离线批量识别，直接在 for 循环里复用同一个PaddleOCR对象是允许的，而且比反复初始化快一个数量级。
ocr = PaddleOCR(use_angle_cls=True, lang='ch', show_log=False) image_files = ['a.jpg', 'b.jpg', 'c.jpg'] for filename in image_files: result = ocr.ocr(filename, cls=True) print(f"{filename}: {result[0] if result else 'no text'}")需要说明的是，ocr.ocr在批量场景下会自动对图片做预处理，但每张图片独立推理的结果并不会自动保存在内存里，所以要及时写入文件，避免列表过大导致内存溢出。这里推荐把文本结果和坐标一起写入 JSON，方便后续对接 ERP 系统或知识检索引擎。
本文还有配套的精品资源，点击获取
