简介一套面向Linux平台的OCR工具包基于深度学习实现图像与扫描件的多语言文字识别适用于服务器、嵌入式设备或容器环境下的文档数字化、票据录入及批量文字提取场景。资源包共56个文件压缩后约308MB含Python入口脚本、Shell启动脚本、容器化配置文件、JSON/文本配置、Markdown说明文档、OCR模型压缩包以及sample样本图片等sample样本用于效果验证json与md文件则提供配置与调用说明整体结构清晰便于按模块调用。已有274人学习下载。读者可从中获得完整的Umi-OCR Linux版本覆盖嵌入式部署、运行时依赖、模型参数与启动示例并支持多线程加速、多语言识别和JSON结果输出借助容器化配置可快速搭建隔离环境也适合后续二次开发与模型调优。资源内附模型与运行时依赖解压配置后即可投入实际任务对需要定制识别能力的团队也可基于开源代码调整模型参数持续优化准确率。 大约一周前我在 Linux 桌面上遇到了一个不大不小但很烦人的需求把截图里的中文内容快速提取成可编辑文字。试了一圈手头的工具要么识别率惨不忍睹要么必须联网上传图片一想到隐私问题就直接劝退。后来想起来Windows 上有个口碑不错的开源项目 Umi-OCR基于 PaddleOCR 引擎离线运行中文识别表现相当能打。但在 Linux 上把它跑起来并不像 Windows 那样下载一个绿色包解压即用中间需要处理 Python 环境、Qt 依赖、OCR 引擎版本等一系列问题。这篇文章就把我这次在 Linux 上部署 Umi-OCR 的完整过程记录下来包括环境准备、源码启动、踩坑排查和实际使用体验希望能帮到想在 Linux 上获得一套靠谱离线 OCR 工具的朋友少走几步弯路。1. 为什么是 Umi-OCRLinux 桌面端的离线 OCR 缺口1.1 传统方案的最大痛点Tesseract 的中文识别短板之前很长一段时间我在 Linux 上处理文字提取都是靠 Tesseract命令行一条tesseract input.png output -l chi_sim就能跑听起来很方便。但真正用过中文图片的人应该都有体会Tesseract 对印刷体中文的识别率只能说勉强及格稍微遇到带点背景、混合标点、排版不整齐的截图输出结果就会变成一串需要二次修改的残句。更麻烦的是它没有“框选截图再识别”这种交互流程每次都要先手动保存图片、打开终端、输入命令、再打开输出文件识别一次要切好几次窗口效率很低。我也试过一些在线识别服务准确率确实不错但问题在于每张图片都要上传到远程服务器。工作里经常会截到带账号、内部代码、未公开资料的窗口这些内容不管是传到哪个第三方平台心里都很难踏实。所以对我来说一个离线、本地运行、中文识别精度高的 OCR 工具才是 Linux 桌面环境里真正缺的那块拼图。1.2 Umi-OCR 的核心价值与适用边界Umi-OCR 最大的特点是把 PaddleOCR 的识别能力和一套完整的图形界面结合到了一起。它内置了截图识别、批量识别、二维码解析、公式识别这些常用功能所有计算都在本地完成不需要联网也不会上传图片。识别结果可以直接复制到剪贴板或者导出成 txt、json 等格式日常使用比命令行 Tesseract 顺手太多。在文字识别精度方面PaddleOCR 在中英文混排、繁体、竖排、表格这些场景下都有不错的表现对比 Tesseract 的优势非常明显。当然它的短板也不是没有OCR 引擎的体积比较大首次运行需要加载模型文件在没有 GPU 的机器上识别速度会受 CPU 性能影响。另外在 Linux 下需要自己解决运行环境不能像 Windows 那样直接下载整合包。但只要你愿意花半小时折腾一下部署后续的使用体验是值得的。2. 环境准备Python 虚拟环境与 Qt 系统依赖2.1 Python 版本选择和虚拟环境隔离Linux 系统自带的 Python 版本通常比较保守比如 Ubuntu 22.04 默认是 Python 3.10Ubuntu 24.04 是 Python 3.12而 PaddleOCR 这类依赖较重的项目往往对 Python 版本有明确要求。为了不把系统的 Python 环境搞乱我强烈建议用虚拟环境来做隔离。我用的 Python 3.10 配合 venv 创建的独立环境sudo apt install python3-venv python3-pip mkdir -p ~/apps/umi-ocr cd ~/apps/umi-ocr python3 -m venv .venv source .venv/bin/activate后面所有依赖都装在这个虚拟环境里就算装坏了也不会影响系统 Python。这一步看起来简单却是整个部署过程中最值得养成习惯的操作尤其是 Linux 发行版升级频繁系统 Python 包和 pip 包一旦混在一起很容易出现互相踩版本的问题。2.2 Qt 运行所需的 Linux 图形依赖Umi-OCR 的图形界面基于 QtPyQt5 或 PySide6而 Qt 应用能在 Linux 桌面上正常显示需要依赖很多系统图形库。最典型的是 xcb 平台插件相关的动态库如果系统里缺少这些库启动时通常会直接报出类似Qt: Session management error或者Could not load the Qt platform plugin xcb这类错误。Debian/Ubuntu 系可以通过 apt 主动补齐这些依赖sudo apt install libxcb-cursor0 libxcb-xinerama0 libxkbcommon-x11-0 libxrandr2 libxi6 libgl1其中libxcb-cursor0是 Qt 6 版本比较依赖的库而老一些的 PyQt5 经常是缺libxcb-xinerama0。为了避免反复折腾我建议在启动应用之前把这几个直接装好。Fedora 系对应的是libxcb-cursor0、libxkbcommon-x11这些包包名略有差异但排查思路一致报错缺什么库就用包管理器搜索对应名字安装。2.3 PaddleOCR 引擎的版本约束Umi-OCR 项目在不同时期对 PaddleOCR 的依赖版本差异很大老版本一般依赖 PaddleOCR 2.x而 PaddleOCR 2.6 之后接口和模型格式都有过调整。这里必须提醒一句安装依赖时不要图省事直接pip install paddleocr装最新版因为最新版 3.x 的 API 与老代码的兼容性可能有问题导致应用启动时报 import 或调用错误。正确处理方法是先看项目 README 或者requirements.txt里锁定的版本范围。比如有些版本要求paddleocr2.7.0有些需要配合特定版本的paddlepaddle。在没有任何版本线索的情况下我建议优先选择 PaddleOCR 2.7.x 加上 CPU 版paddlepaddle这是兼容性较好的一组搭配我实测下来可以跑通典型功能。安装命令类似于pip install paddlepaddle2.6.1 pip install paddleocr2.7.0注意这里两个包是分开安装的paddlepaddle是推理底层paddleocr是对上层封装的 OCR 流程。如果你不小心先装好了最新版可以通过卸载重装的方式降级到锁定版本。3. 源码启动从 git clone 到主界面弹出的完整链路3.1 获取源码与项目结构一览Umi-OCR 的源码托管在 GitHub 上直接 clone 到本地git clone https://github.com/hiroi-sora/Umi-OCR.git cd Umi-OCR源码目录结构通常分成几个核心部分主程序入口、OCR 引擎封装、界面模块、配置文件、模型目录等。了解这些目录的作用对后面排查问题很有帮助。比如主程序负责启动 Qt 事件循环OCR 引擎模块负责与 PaddleOCR 交互配置目录里保存着语言设置、快捷键、识别参数等运行时配置。刚开始接触时不需要把每个文件都看一遍但至少要知道入口文件在哪、配置文件在哪个目录这样改参数、看日志的时候不迷路。3.2 安装依赖与版本锁定进入源码目录后先看有没有requirements.txt文件。通常项目作者会把运行必需的 Python 包都列在里面直接安装即可pip install -r requirements.txt但经验之谈是安装完以后最好再手动确认一遍关键包的版本尤其是paddleocr和pyqt5的版本是否符合预期。可以用pip list | grep -E paddle|pyqt来查看实际安装结果。如果requirements.txt里写的是不带版本号的依赖那么 pip 很可能装成最新版带来后续兼容性隐患。3.3 首次启动模型初始化与验证依赖装好之后就可以尝试启动主程序了。不同版本的入口文件名可能不一样常见的是main.py也有可能是UmiOCR.py看目录下的 Python 文件就能确认python main.py首次启动时PaddleOCR 会检查本地是否存在模型权重文件不存在时会尝试自动下载这一步需要网络状况稳定。下载完成后程序会加载模型并初始化 OCR 引擎之后才会弹出主窗口。如果在这一步看到下载进度条长时间卡住或者直接报网络超时可以参考下一章的排查思路。顺利的话你会看到 Umi-OCR 的主窗口界面上有截图识别、批量识别、设置等入口。到这一步部署已经成功了一大半可以先用一张带中文的图片测试一下识别效果。4. 部署排雷我在 Linux 上遇到的五个实际报错4.1 QXcbConnection 缺库报错这是我在 Linux 上跑 Qt 应用时遇到最多的一个问题。启动时终端里输出一堆日志最后停在Could not load the Qt platform plugin xcb窗口就是弹不出来。本质上是因为 Qt 的 xcb 平台插件需要加载一系列 xcb 相关的系统库任何一个缺失都会导致插件加载失败。排查命令可以用ldd查看插件动态库的依赖情况ldd .venv/lib/python3.10/site-packages/PyQt5/Qt5/plugins/platforms/libqxcb.so | grep not found哪一行显示not found就说明缺哪个库。我这边缺的是libxcb-cursor.so.0对应的包名是libxcb-cursor0直接 apt 安装再重新启动就解决了。如果你是第一次跑 Qt 程序建议直接先把上一节列的几个 xcb 相关依赖全部装好大概率能少踩这个坑。4.2 PaddleOCR API 版本冲突项目跑起来以后点一下“截图识别”程序卡了几秒然后日志里抛出一段看不懂的 Traceback提示 OCR 引擎调用出错。这类问题十有八九是 PaddleOCR 版本和代码预期不一致造成的。PaddleOCR 2.x 的典型用法是先创建PaddleOCR()实例再调用ocr.ocr(img_path)获取结果返回的是多层嵌套的列表结构。而 PaddleOCR 3.x 引入了新的预测接口predict()返回的数据结构也完全变了。如果 Umi-OCR 代码是基于 2.x 写的而环境里装的是 3.x那么内部解析结果的逻辑就会直接崩掉。解决方案就是锁定版本把paddleocr降回 2.7.x同时把paddlepaddle也装成匹配的版本。这一步做完之后API 兼容问题基本能消失。顺带提醒一句以后重装依赖的时候最好用pip freeze requirements.lock把当前可用版本记录下来下次部署环境直接照着装一劳永逸。4.3 模型权重下载卡住首次运行初始化模型时下载过程一直在转圈进度条不动最终超时。这是因为 OCR 模型文件本身有几十 MB 到几百 MB加上国内网络访问某些下载源不够稳定容易中断。遇到这种情况最直接的办法是找一台网络条件好的机器把模型文件提前下载好再手动放到模型缓存目录。PaddleOCR 2.x 的模型缓存目录一般在~/.paddleocr/里面会按照whl/det、whl/rec、whl/cls这样的结构存放检测模型、识别模型和方向分类模型。手动放置时保持同样的目录层级即可。放置完成后重新启动程序它检测到本地已有模型就不会再走下载流程。还有一种思路是通过环境变量或配置文件直接指定模型路径具体看项目的设计。如果代码里显式定义了det_model_dir、rec_model_dir等参数那就把参数指向你本地存放模型的目录绕过自动下载。这个方法在网络环境差的内网机器上尤其管用。4.4 界面字体与中文显示问题依赖装好了模型也正常加载窗口也弹出来了但界面上的中文全部显示成方块或乱码。这个问题通常不是字体文件缺失而是 Qt 在 Linux 下没有正确找到合适的中文字体。解决方法是确认系统里至少装了 Noto Sans CJK 或文泉驿这类的开源中文字体sudo apt install fonts-noto-cjk装完之后重启应用。如果还是乱码可以在系统设置里调整字体渲染相关的选项或者在 Qt 应用中手动指定一个中文字体名称。值得注意的是某些精简版 Linux 发行版可能自带的中文字体很少这一步很容易被忽略但不处理的话界面可读性会非常差。4.5 Wayland 会话下截图失效运行在 Wayland 会话下时Umi-OCR 的全局快捷键和区域截图可能出现异常比如快捷键没反应、截出来的图是全黑或者直接报权限错误。原因在于 Wayland 的安全模型限制了客户端程序随意抓取或模拟全局鼠标键盘事件而 Qt 应用如果没有以 XWayland 兼容方式运行很多桌面功能都会受限。最简单的处理办法是退出当前 Wayland 会话改用 X11 登录选项。如果你不想切换整个会话也可以尝试在启动命令前加上一些 Qt 环境变量配置export QT_QPA_PLATFORMxcb python main.py强制 Qt 走 XWayland 的 xcb 模式很多时候能缓解截图问题。我实际测试下来在同一台机器上切到 X11 会话后截图识别的稳定性和响应速度都明显更好。如果快捷键仍然无效还可以在 Umi-OCR 设置里改成与桌面环境不冲突的按键组合。5. 使用体验截图识别、批量识别与性能实测5.1 截图 OCR从按下快捷键到文字进剪贴板部署成功后的日常使用流程大概是这样按下截图快捷键框选屏幕上的目标区域松开鼠标识别结果很快出现在结果面板中同时自动复制到剪贴板。整个环节不需要打开终端也不用手动保存图片确实有 Windows 桌面工具那种“拿来即用”的感觉。识别质量方面我用一张包含中文标题、正文、数字和英文的混合截图测试PaddleOCR 的识别结果比较整齐标点符号和数字基本没有错漏。遇到识别不准的个别字符直接在结果面板里手动修正即可不用像 Tesseract 那样重新反复跑参数。对日常阅读资料、提取代码片段、记录会议截图里的信息来说这个速度和质量完全够用。5.2 批量识别与文档整理场景除了截图识别Umi-OCR 也支持批量识别可以一次性把整个文件夹里的图片全部放入任务队列逐张识别并导出结果。我试过一次处理 30 张左右的文档截图全程自动执行结束后统一导出成文本文件非常适合整理旧文档扫描件、批量提取漫画对白、或者给一些无文字层的 PDF 页面做 OCR。批量模式下有一个细节值得注意识别完成后最好检查一下输出文件的编码默认 UTF-8 一般没问题但如果你要在 Windows 上二次处理可能需要留意换行符的差异。另外图片数量特别多时建议把任务分批处理避免单次队列过长导致中途内存占用偏高。5.3 CPU 推理速度与资源占用实测在没有 GPU 的普通桌面机器上Umi-OCR 的识别速度仍然在可用范围内。我用一台几年前的双核 CPU 笔记本测试单张几 KB 的截图识别耗时大约在 1 到 2 秒之间批量处理时平均每张图也差不多是这个量级。相比之前用 Tesseract 跑中文学要反复调整参数这个体验已经提升不少。资源占用方面加载模型后内存大约增加 1 到 2 GBCPU 在识别时会短暂冲高空闲时回落。如果你机器内存吃紧可以考虑换用轻量一点的 OCR 模型配置或者在设置里关闭识别历史记录减少界面缓存。需要说明的是首次加载模型会明显慢一些等程序完全就绪后再操作会顺畅很多。5.4 三个提升使用舒适度的小调整用了一周之后我总结了三个实用的小调整。第一把截图识别的快捷键设置成与你常用的截图工具一致避免肌肉记忆冲突。第二在设置里开启“识别结果自动复制到剪贴板”这样识别完直接到目标应用里粘贴少一步手动操作。第三如果字体渲染感觉发虚可以在系统设置里打开字体抗锯齿和微调。这三件事都不复杂但对日常使用的顺畅度影响很明显。最后再分享一点个人经验这次部署 Umi-OCR最深的体会是Linux 上跑这类工具真正花时间的往往不是应用本身而是它依赖的系统库和 Python 包版本。遇到报错时别急着重新安装先看日志再用ldd或pip list这类工具排查具体原因能省下很多反复试错的精力。版本锁定这件事也是越早做越好把可用的版本记录成文件下次换机器、重装系统都能直接照着复现。如果你部署时遇到和我不同的报错欢迎在评论区一起交流我之后也打算再写一篇关于 Linux 下离线模型配置和批量识别流程优化的内容把这次的经验继续扩展下去。本文还有配套的精品资源点击获取