简介：一份基于PyQt5与PaddleOCR实现文字识别的Python项目源码，定位为毕业设计、课程大作业或项目初期立项演示的优质范例，主要面向计算机、人工智能、物联网等专业的在校学生和开发者，帮助解决图形界面下快速完成图片文字提取与编辑的实际需求。项目将GUI交互与OCR识别能力深度融合，涵盖图像导入、画布标注、亮度对比度调节、文字识别、结果编辑与列表管理等完整流程，并包含工具栏、颜色对话框、文件预览等实用组件，代码分层清晰，便于阅读和二次开发。压缩包共80个文件，大小约4.37MB，核心为24个Python源码，另有界面UI/XML文件、PNG/JPG图标素材、配置文件与说明文档，还附带演示动图和示例图片，可直观了解运行效果。目前已有42人学习下载，对希望快速上手PyQt5桌面应用开发或PaddleOCR集成实践的读者，是一份完整且具参考价值的示例。
1. 为什么毕业设计选 PyQt5 + PaddleOCR 而不是 Tkinter + Tesseract
OCR 类的毕业设计和课程大作业，最常见的完成形态是 Flask 接口配一个上传框，识别完把 JSON 渲染到页面上就算交差。这个项目不一样的地方在于，它的核心是一个带标注工作流的桌面应用：PyQt5 负责界面和鼠标交互，PaddleOCR 负责文本检测与识别，两者之间用一层guiocr包组织起来。打开程序后，可以加载图片、一键 OCR、把识别框直接画在图上，再逐条修改文字内容和标签，整个过程不需要浏览器、不需要起服务，断网也能跑。比起 Web demo，这种形态更贴近真实标注工具，演示的时候老师可以亲手点鼠标改错字，体验比看接口返回强得多。适合三类人：拿它当毕设或课程设计底座、不想从零写前端交互的在校生；想快速给团队搭一个桌面文字识别工具、又不想被 Web 框架绕一圈的工程师；以及准备做数据集标注、但不想啃 labelme 源码的人。另外，如果只是想要 PyQt5 做界面，结构上也可以参考这个工程把 PaddleOCR 换成其他推理引擎，后面会讲怎么替换。
2. PaddleOCR 推理封装：引擎初始化、参数选择与 ocr_utils 返回结构
2.1 为什么识别逻辑要拆成独立模块
项目里所有模型相关代码都收在guiocr/utils/ocr_utils.py。这个拆分不只是为了目录好看：GUI 里的主窗口、画布、列表项都依赖识别结果，但没有任何一个控件应该直接知道 PaddleOCR 的调用方式。把引擎初始化、推理调用、返回值标准化放在一个模块里，界面层拿到的永远是list[dict]这样的统一结构，将来换引擎、换模型，或者从单张识别改成批量识别，只动这一个文件就行。
实际开发里我见过很多把PaddleOCR(...)直接写在按钮点击事件里的写法，当时方便，后面换一个lang参数要全局搜索替换，体验很差。所以看到项目里保留ocr_utils.py这一层，说明作者是认真考虑过结构而不是把代码堆在一个文件里。
2.2 初始化 PaddleOCR 时的推理参数
# guiocr/utils/ocr_utils.py 中常见的引擎初始化写法 from paddleocr import PaddleOCR _engine = None def get_engine(): global _engine if _engine is None: _engine = PaddleOCR( use_angle_cls=True, # 开启方向分类，倾斜图片识别率更高 lang="ch", # 识别语言，ch 为中文简体 show_log=False, # 关闭推理日志，避免刷屏 ) return _engine这段代码的逻辑是先判断_engine是否已经创建，避免每次识别都重新加载模型。use_angle_cls控制方向分类器，开启后会多跑一个分类分支，专门处理图片旋转 0 度和 180 度的情况，手机拍的票据、扫描件经常有这个问题。lang决定加载哪个语言的识别模型和字典，常见取值是ch、en、japan、korean。show_log建议设成False，否则 PaddleOCR 会把每一张图的推理耗时打到标准输出，在 PyQt5 里这些日志会混进你自己的调试信息，干扰判断。
需要注意 PaddleOCR 的推理模型分为三段：检测模型（det）负责找出文字框，方向分类模型（cls）负责纠正旋转，识别模型（rec）负责把框内图像转成字符串。平时说「PaddleOCR 模型」，默认把这三个都加载了。use_angle_cls=False时跳过 cls 这一个分支，速度更快，但图片有旋转时准确率会明显下降。
2.3 把返回结果整理成 GUI 能消费的结构
def recognize(img_path): engine = get_engine() result = engine.ocr(img_path, cls=True) items = [] for line in result: for box, (text, score) in line: items.append({ "box": box, # 四点坐标 [[x1,y1],[x2,y2],[x3,y3],[x4,y4]] "text": text, # 识别出的字符串 "score": score, # 置信度 0.0 ~ 1.0 }) return items这里的逻辑是把 PaddleOCR 的原始返回值拆成一个个dict。早期版本的ocr()返回嵌套结构：最外层是每一行文字，行内是坐标框加(文本, 置信度)元组，新版本改为predict()后返回结构略有差异，但只要recognize对外输出的结构不变，界面层的代码就完全不用改。
封装完之后，GUI 层不需要关心模型细节，拿到items直接画框、填列表就行。需要注意box里存的是原图像素坐标，不是控件坐标，后面 GUI 绘制时要做缩放换算，这一块在image.py里处理。常见的坑是有人把两次识别的结果格式搞混，直接在for line in result上取下标导致 IndexError。遇到这种情况，先把result打印出来看一层结构再继续写循环。
2.4 模块职责边界
| 模块 | 职责 | 对应文件 |
|---|---|---|
| 模型层 | 引擎初始化、推理调用、结果标准化 | utils/ocr_utils.py |
| 数据层 | 图片读写、缩放、坐标系换算 | utils/image.py |
| 界面层 | 画布绘制、列表渲染、交互 | widgets/canvas.py等 |
另外一个关键点：engine.ocr()是同步阻塞调用，图片较大时一次推理可能要一两秒，直接放在 GUI 线程里会卡界面。常见做法是放到QThread里执行，识别完成后通过pyqtSignal把items发回主线程。标注工具在加载 4000px 大图时，这个区别体感非常明显，演示前最好先确认一下项目里有没有做线程封装。
3. PyQt5 标注链路：canvas 坐标换算、列表联动与标签编辑
3.1 image.py：图片加载与坐标换算
GUI 里显示的图片永远是被缩放过的，画布上鼠标位置和原图像素位置不是一对一的关系。image.py要维护的就是这套换算关系：记录原始图片尺寸、当前缩放比例、画布偏移量，任一时间点都能把控件坐标换算回原图坐标。
# utils/image.py 的坐标换算思路 from PyQt5.QtGui import QImage class ImageView: def __init__(self, path): self.pix = QImage(path) self.scale = 1.0 def to_scene(self, x, y): # 控件坐标 -> 原图坐标 return int(x / self.scale), int(y / self.scale) def to_view(self, x, y): # 原图坐标 -> 控件坐标 return int(x * self.scale), int(y * self.scale)这段代码的逻辑很直白：所有标注框统一按原图坐标存储，渲染时才乘以缩放系数。只有这样，放大缩小、平移画布之后标注数据才不会漂移。最常见的 bug 是画框时忘了把鼠标坐标除以scale就存进去，结果放大两倍后框的位置全部错位。
3.2 canvas.py：画框与重绘策略
canvas.py是标注交互的核心。它继承QWidget，重写paintEvent绘制图片、绘制标注框、高亮当前选中的区域。绘制文字框的典型代码如下：
def paintEvent(self, event): painter = QPainter(self) painter.drawImage(0, 0, self.pix) for shape in self.shapes: pen = QPen(QColor(0, 255, 0), 2) painter.setPen(pen) box = shape["box"] # 原始四点坐标 # 坐标转换到控件后绘制 points = [QPoint(*self.view.to_view(x, y)) for x, y in box] painter.drawPolygon(QPolygon(points))逻辑说明：drawImage先把图片画到底层画布上，之后遍历标注框，用绿色画笔绘制多边形。这里画的是四边形，因为 PaddleOCR 返回的框不一定是正矩形，用drawPolygon比drawRect更通用。QPen的宽度一般设 2 像素，在缩放倍数较大时可以考虑按1 / scale动态调整线宽，避免放大后线条粗得看不清文字。
鼠标交互方面，常见做法是setMouseTracking(True)开启鼠标跟踪，在mousePressEvent记录起点，mouseMoveEvent更新橡皮筋矩形，mouseReleaseEvent确定最终坐标并生成 shape。项目里shape.py就是干这个的，把一次鼠标操作结果整理成一个带类型、坐标、标签的对象。
3.3 OCR 结果回填与 label_list 联动
OCR 识别完之后，结果要同时出现在右侧列表和画布上。label_list_widget.py和myQListWidgetItem.py配合实现「列表项与图像框」的双向联动，靠信号完成：
| 信号 | 触发时机 | 对应操作 |
|---|---|---|
itemClicked | 点击列表项 | 高亮画布上对应文字框 |
shape_selected | 点击画布上的框 | 滚动列表并选中对应项 |
ocr_finished | 识别线程结束 | 清空列表，批量重新填入 |
# 把 OCR 识别结果批量塞进列表的伪代码 def on_ocr_finished(self, items): self.list_widget.clear() for it in items: item = MyQListWidgetItem(it["text"]) item.setData(Qt.UserRole, it["box"]) # 坐标存进列表项 self.list_widget.addItem(item)这样做的好处是列表项和画布形状共享同一个box数据源，用户修改列表里的文字时，myQListWidgetItem里保存的数据同步更新，导出时不会出现「图上是新文本，列表里还是旧文本」这类不一致。
3.4 标签编辑、亮度调整与导出流程
实际标注流程中，识别结果不可能一次全对。label_dialog.py提供弹窗让用户修改文字内容和标签类别，brightness_contrast_dialog.py则负责调整图片亮度和对比度，改善低质量图片的识别效果。整体数据流是：加载原图 → 同步 OCR 识别 → 结果填入列表并绘制在画布 → 用户逐条修改 → 导出 JSON 或纯文本。导出时遍历列表里的所有 item，把Qt.UserRole中保存的坐标和编辑后的文本组合成结构化数据，这一步直接对接数据集格式。
4. requirements 与 default_config.yaml：依赖锁定和推理参数配置
4.1 requirements 里应该锁什么
requirements.txt是下载后第一个要看的文件。PyQt5、PaddleOCR 这类项目依赖复杂，paddleocr会连带安装 opencv、numpy、shapely 等一堆库，版本互相踩坑的概率很高。常见做法是先把关键包装上，再单独锁版本：
pip install -r requirements.txt一份常见的requirements.txt关键内容大致是这样的：
PyQt5>=5.15 paddleocr opencv-python PyYAML这里不建议把paddlepaddle手动写进去，因为 CPU 和 GPU 版本的安装方式不同，写死反而容易装错。安装时需要注意，pyqt5-qt5==5.15.19这类带精确版本号的间接依赖，如果 pip 解析失败，可以改用pip install pyqt5==5.15.9降级重试，通常是新版本 Qt 与当前系统的兼容性问题。
4.2 default_config.yaml 的参数拆解
项目里把推理参数抽到了config/default_config.yaml，好处是改配置不用动源码，答辩演示时现场切换语言模型比较方便。常见配置项如下：
| 配置键 | 作用 | 常用调整 |
|---|---|---|
ocr.lang | 识别语言 | ch/en/japan |
ocr.use_angle_cls | 是否启用方向分类 | 倾斜文本设true |
det.limit_side_len | 检测最长边 | 大图调 960 以上 |
rec.batch_num | 识别批次大小 | 文本行多时调大 |
det.limit_side_len这个参数容易被忽略。默认值对普通截图够用，但遇到超长图或者高清扫描件时，检测模型会把长边压缩到固定长度，小字会直接丢框。实际项目里我会把原图先做一次长边缩放再进 OCR，或者把limit_side_len调大，代价是推理时间变长、显存占用变高，需要按机器配置折中。
4.3 app.py 的启动顺序
# app.py 的启动逻辑 import sys from PyQt5.QtWidgets import QApplication from guiocr.widgets.main_window_ui import MainWindow def main(): app = QApplication(sys.argv) window = MainWindow() window.show() sys.exit(app.exec_()) if __name__ == "__main__": main()这段代码的逻辑是标准的 PyQt5 启动流程，但项目结构上把main.py和app.py分开是有讲究的：main.py负责读取 YAML 配置、初始化日志，app.py只负责创建界面。这样拆分之后，以后想写无界面的批处理脚本，可以跳过app.py直接复用配置加载和 OCR 封装，不需要把 GUI 代码也跑一遍。
4.4 .zbak 后缀文件怎么处理
项目里有大量.zbak后缀文件，比如misc.xml.zbak、profiles_settings.xml.zbak，这是 PyCharm 工程配置文件被改名后的备份。.idea目录属于 IDE 配置，跑代码用不到，可以直接忽略。真正需要关注的是guiocr/包、main.py、app.py、requirements.txt和config/目录。交作业之前建议清理掉这些备份文件：
rm -f *.zbak .gitignore.zbak rm -rf .idea清理之后代码结构更干净，论文里画系统结构图时也更容易向老师解释哪些是核心代码。
5. 部署排错：OpenGL 界面无显示、GPU 安装与中文路径
5.1 PyQt5 界面无显示与 OpenGL 软件渲染
把 PyQt5 程序放到服务器或虚拟机里运行时，最常见的问题是窗口起不来、白屏、或者直接段错误。大部分情况下是 Qt 检测 OpenGL 失败导致的，常见做法是在导入 PyQt5 之前设置环境变量：
export QT_OPENGL=software export QT_QPA_PLATFORM=xcb python main.pyQT_OPENGL=software强制 Qt 使用软件渲染，跳过显卡驱动检测；QT_QPA_PLATFORM=xcb指定 Linux 下的窗口系统协议，解决部分发行版默认平台插件找不到的问题。如果设了这两个变量后窗口能正常显示，说明是显卡驱动或 Qt 的 GL 检测有问题，而不是代码本身的问题。代码里也可以写死这个环境变量，避免每次都要手动 export：
import os os.environ.setdefault("QT_OPENGL", "software")5.2 PaddleOCR GPU 版本怎么装
经常有人把paddleocr和paddlepaddle搞混。paddleocr本身只提供 OCR 的 Python API，真正的底层算子在paddlepaddle里。想用 GPU 跑，需要安装paddlepaddle-gpu而不是paddlepaddle，并且版本要和本机 CUDA 对应。建议直接用虚拟环境安装，避免污染系统 Python：
python -m venv venv_ocr venv_ocr\Scripts\activate pip install paddlepaddle-gpu pip install paddleocr安装完成后可以用一行代码验证 GPU 是否生效：
import paddle print(paddle.is_compiled_with_cuda())输出True说明编译了 CUDA 支持，实际是否调用 GPU 还要看paddle.device.get_device()。如果输出False，说明装成了 CPU 版，需要重装对应 CUDA 版本的paddlepaddle-gpu。
5.3 中文路径导致解析错误
项目说明里特别强调「项目名和路径不要用中文」，这个提醒是真实的，不是套话。PaddleOCR 加载模型和 OpenCV 读取图片时，对中文路径兼容性很差，cv2.imread遇到中文路径直接返回None，后续代码执行findContours就会报空指针错误。z
解决方式有两个：一是把整个项目放到纯英文路径下，推荐这种；二是如果图片路径改不了，用np.fromfile加cv2.imdecode绕过imread的限制：
import cv2 import numpy as np def imread_unicode(path): data = np.fromfile(path, dtype=np.uint8) return cv2.imdecode(data, cv2.IMREAD_COLOR)Windows 下还会遇到另一个问题：控制台编码导致的中文乱码。运行前先执行chcp 65001切到 UTF-8，否则 logger 输出的中文信息在 cmd 里全是乱码，排查问题时完全找不到有效信息。
5.4 用 logger.py 判断是模型问题还是界面问题
项目自带的logger.py承担了日志输出职责。遇到程序异常时，不要直接扒代码，按顺序做三件事：先看日志里有没有 PaddleOCR 的推理耗时记录，确认模型是否正常加载；再单测ocr_utils.recognize接口，传一张测试图看返回结构是否符合预期；最后才打开 GUI 做界面交互测试。这样能快速区分问题出在模型层还是界面层，避免在 PyQt5 的信号槽里找半天，最后发现其实是模型路径加载失败。
6. 二次开发：把标注工具改造成批量识别与数据集导出工作台
6.1 写一个批量识别脚本
标注工具一次只能处理一张图，但实际场景往往是几十张合同一起扫描。基于现有的ocr_utils封装，写批量脚本只需要几十行：
# batch_ocr.py from guiocr.utils.ocr_utils import recognize import glob import json results = [] for img_path in glob.glob("imgs/*.jpg"): items = recognize(img_path) results.append({"image": img_path, "items": items}) with open("ocr_results.json", "w", encoding="utf-8") as f: json.dump(results, f, ensure_ascii=False, indent=2)这段代码把指定目录下所有 jpg 文件逐个识别，结果统一写入 JSON 文件。ensure_ascii=False保证中文直接以原文写入而不是转成\u转义序列，用文本编辑器打开也能读懂。
6.2 替换成自己的推理模型
如果想对特定场景优化，比如只识别发票号码，可以在初始化时指定自己的微调模型：
PaddleOCR( det_model_dir="models/det", rec_model_dir="models/rec", cls_model_dir="models/cls", lang="ch", )替换模型后先用单张测试图验证识别效果，再跑批量脚本，避免一次处理几百张才发现模型参数不对。模型目录里的配置文件也要一起保留，PaddleOCR 加载时会读取其中的 yaml 字段来初始化算子。
6.3 导出独立于 GUI 的数据集目录
对做标注数据集的人来说，可以把每张图的识别结果按图片同名存储，方便后续用 LabelMe 或其它工具打开校对：
for item in results: base = item["image"].replace(".jpg", ".json") with open(base, "w", encoding="utf-8") as f: json.dump(item["items"], f, ensure_ascii=False, indent=2)每个 JSON 文件里的box坐标都是原图像素坐标，和标注工具里看到的一致，配合shape.py里的结构可以直接画回原图验证。到这里，这个项目的价值就不止于一个毕设 demo，而是一个可以实际用来批量处理单据、生成训练数据的桌面工具。
本文还有配套的精品资源，点击获取
