Umi-OCR 实践手册：从零搭建离线 OCR 环境的完整指南

本篇以 Umi-OCR 的《实践手册》为蓝本，结合仓库中的 README.md、命令行手册、更新日志 与 错误排查手册，完整讲解这款免费、开源、离线 OCR 软件的安装部署、核心功能使用（截图识别、批量处理、二维码）、常见启动故障的排查方法，以及基于插件目录的引擎扩展方式。读完后，你可以独立在 Windows 7+ 或 Linux x64 上部署并跑通 Umi-OCR，并能处理绝大多数启动与识别质量问题。

一、认识 Umi-OCR：离线 OCR 软件与核心文件

Umi-OCR 是一款免费、开源、可批量的离线 OCR（光学字符识别）软件，将图片中的文字转换为可编辑文本，全程无需联网。项目当前版本为 v2.1.5（见 about.json 中的版本号 2.1.5），运行环境框架采用 PyStand 定制版，默认提供 PaddleOCR-json 与 RapidOCR-json 两套离线引擎，并内置多国语言识别库。

按官方文档，软件发布包为 .7z 压缩包或 .7z.exe 自解压包，解压即用，无需安装，解压后点击 Umi-OCR.exe 即可启动。发行包内部的核心文件如下表（与 README.md 中“工程结构”一节相互印证）：

文件/目录	功能说明
Umi-OCR.exe	Windows 平台主程序，同时也是命令行调用入口
umi-ocr.sh	Linux 平台启动脚本
UmiOCR-data/plugins	功能扩展插件目录（OCR 引擎、二维码等组件）
UmiOCR-data/i18n	多语言界面翻译文件（.qm 编译产物）
UmiOCR-data/main.py	程序 Python 入口，含 MIT 许可证声明（见 main.py）
UmiOCR-data/.settings	软件设置保存文件（ini 格式），界面参数均写回此处
UmiOCR-data/logs	v2.1.5 新增的日志保存目录

从源码结构看，UmiOCR-data 是整个程序的数据与代码根目录：main.py 负责启动，plugins 存放引擎插件，i18n 存放翻译包；界面上做的所有设置会持久化到 .settings，因此备份或迁移软件时，把整个解压目录原样拷贝即可保留全部配置。

二、环境准备：搭建运行基础

Windows 系统配置

官方明确软件适用于 Windows 7 x64 及以上版本。部署步骤：

1. 确认系统版本为 Windows 7+（64 位）；
2. 将下载的 .7z 压缩包解压到合适目录（自解压包则直接运行即可）；
3. 避免使用中文路径，以免个别组件加载失败。

另外两点与运行环境强相关：

• 若系统未安装 Visual C++ 运行库，启动时可能报 Cannot find Py_Main() 或丢失 api-ms-win-crt-runtime-l1-1-0.dll（见下文故障排除）；
• Windows 7 早期版本需通过 Windows Update 补齐系统补丁（如 KB2533623、KB4534310），否则可能出现 0xc0000142 或保存双层 PDF 时崩溃。

Linux 系统要求

Linux 版本适用于 x64 架构，基于 Python + PySide 运行。官方 更新日志 在 v2.1.4 中将 glibc 依赖降级至 2.31，以兼容 Debian 11、Ubuntu 20 等较老发行版——这是选择 Linux 版本前最应核实的系统条件：

# 检查 glibc 版本，2.31 及以上即可运行
ldd --version | grep glibc

下载发行包后，给启动脚本添加执行权限并运行：

chmod +x umi-ocr.sh
./umi-ocr.sh

提示：从 v2.1.5 起，命令行方式启动可以看到实时日志，这对排查 Linux 环境下的启动问题非常有帮助。

界面语言

Umi-OCR 支持界面多国语言。第一次打开软件时，会按电脑系统设置自动切换语言；手动切换路径为 全局设置 → 语言/Language。UmiOCR-data/i18n 目录存放的就是这些语言包，翻译协作流程详见 dev-tools/i18n/README.md（译者通过 Weblate 平台提交 .ts 翻译，开发者用 lrelease_all.py 编译为 .qm 放入 i18n 目录）。

三、功能实践：掌握核心技能

批量处理技巧

批量 OCR 标签页用于批量导入本地图片进行识别：

• 支持格式：jpg, jpe, jpeg, jfif, png, webp, bmp, tif, tiff，没有数量上限，可一次导入几百张图片排队处理；
• 识别结果可保存为 txt, jsonl, md, csv(Excel) 四种格式，输出目录可自定义；
• 支持将文件夹直接拖入界面，程序会搜索文件夹中所有图片（包括嵌套子文件夹）；
• 支持任务完成后自动关机/待机，适合夜间批量作业。

两个值得知道的细节：

• 长图/大图处理：如果要识别像素超大的长图或大图，请在 页面的设置 → 文字识别 → 限制图像边长 中调高数值，否则超大图片可能被压缩降采样；
• 忽略区域：在批量页右栏设置中可打开忽略区域编辑器，按住鼠标右键绘制多个矩形框，框内文本块在识别时会被整体忽略。适合排除图片中的水印、LOGO。注意只有处于框内部的整个文本块（而不是单个字符）会被忽略，因此矩形框要画得足够大，完全包裹住水印可能出现的所有位置。

命令行方式同样支持批量：--path 指令可传入图片路径、文件夹路径或多个路径（用双引号包裹单个路径、空格分隔），例如：

umi-ocr --path "D:/img1.png" "D:/img2.png" "D:/image/test"

截图识别进阶

截图 OCR 标签页是日常使用频率最高的功能：打开该页后，用快捷键唤起截图、划选区域，即可识别图中文字。

• 左侧图片预览栏可直接用鼠标划选复制；右侧识别记录栏支持编辑文字、划选多条记录一起复制；
• 也支持在别处复制图片后直接粘贴到 Umi-OCR 进行识别；
• 快捷键效率技巧：结合第三方热键工具（如 HotkeysCMD）可以免鼠标完成截图识别，例如按下 F10 时对第 1 个显示器的指定区域自动截图识别：

F10 umi-ocr --screenshot screen=0 rect=50,100,300,200

• 文本后处理（排版解析）：OCR 原始输出常是错乱的文本块，Umi-OCR 提供排版解析方案整理顺序，使其更适合阅读——

  • 多栏-按自然段换行：适合大部分情景，自动识别多栏布局，按自然段换行；
  • 多栏-总是换行：每段语句都换行；多栏-无换行：强制合并到同一行；
  • 单栏-* 系列：与上述类似，但不区分多栏布局；
  • 单栏-保留缩进：适合解析代码截图，保留行首缩进和行中空格；
  • 不做处理：输出引擎原始结果。

  上述方案均能自动处理横排和竖排（从右到左）排版（竖排文字还需 OCR 引擎本身支持）。

• 结果即时使用：命令行下可用 --clip 复制识别结果到剪贴板，或用 --output/--output_append 覆盖/追加写入文件：

umi-ocr --screenshot --clip
umi-ocr --screenshot --output test.txt

文档识别与二维码

除草稿提到的图片批量处理外，v2 还提供两个常用标签页：

• 文档识别：支持 pdf, xps, epub, mobi, fb2, cbz 格式，可对扫描件 OCR 或提取原有文本，并可输出为双层可搜索 PDF；同样支持设置忽略区域（排除页眉页脚）与任务完成后自动关机；
• 二维码：截图/粘贴/拖入本地图片即可识别二维码、条形码，支持一图多码，覆盖 QRCode、EAN13、PDF417 等 19 种协议；反向操作则支持输入文本生成二维码图片，可配置 19 种协议与纠错等级。命令行对应指令为 umi-ocr --qrcode_read "D:/xxx.png" 与 umi-ocr --qrcode_create "文本" "D:/out.jpeg" [宽] [高]。

四、问题解决：常见故障排除

Umi-OCR 发行包内附带了 错误排查手册，与草稿中“启动异常处理”一节对应。下表汇总了最常见的启动异常及处理方式：

症状	原因与处理
弹窗报错 Cannot find Py_Main() / 丢失 api-ms-win-crt-runtime-l1-1-0.dll	缺少 VC 运行库。安装 Visual C++ Redistributable（x64）后重启系统
用备用启动脚本仍失败	可用 UmiOCR-data/RUN_GUI.bat 代替 Umi-OCR.exe 启动（草稿中“尝试备用启动脚本”）。注意：通过 bat 启动时部分功能受限——无法使用命令行指令、无法创建快捷方式，且不要移动 bat 位置
Failed to create OpenGL context	显卡驱动/渲染问题。可按手册放置软渲染 dll 到 UmiOCR-data/site-packages/PySide2/；也可在全局设置 界面和外观 → 渲染器 中切换渲染方案或关闭硬件加速
Umi-OCR.exe 已停止工作（从 Win10 拷到 Win7 后）	配置冲突。删除 UmiOCR-data/.pre_settings 配置文件
0xc0000142 或 OCR init fail 含 enable_mkldnn 报错	CPU 不支持 AVX 指令集。换用 Umi-OCR_Rapid 版本，或额外导入 RapidOCR 插件（见下一节）
黑框控制台报 OSError 找不到指定的程序	Win7 早期版本缺少系统补丁，通过 Windows Update 安装全部更新（尤其 KB2533623）
保存双层 PDF 时崩溃（BEX64 / ucrtbase.DLL）	Win7 缺少 KB4534310 等前置补丁，必须通过 Windows Update 完整安装月度安全更新（KB4534310 有前置依赖，不能单独下载安装）
快捷方式无法由软件创建	手动创建快捷方式，放入开始菜单目录 C:\ProgramData\Microsoft\Windows\Start Menu 或开机自启目录 ...\Start Menu\Programs\Startup

草稿中提到的“调整兼容性模式”“检查目录权限”同样适用：解压目录需要有读写权限（.settings、logs 都要写入），路径中避免中文与特殊符号。

识别质量优化

• 切换 OCR 引擎：PaddleOCR 与 RapidOCR 对字体、分辨率的表现各有差异。CPU 不支持 AVX 时必须使用 RapidOCR 类插件；在全局设置页可切换当前启用的 OCR 插件，也可通过插件库随时导入新引擎；
• 清理配置/缓存：设置错乱时可删除 UmiOCR-data/.settings（界面参数将恢复默认）或 .pre_settings（跨版本预配置），然后重启软件。v2.1.5 支持 umi-ocr --reload 指令重新加载配置文件并刷新设置界面，无需重启程序；
• 调整识别参数：识别语言、图像边长限制、文本后处理方案均在对应标签页的“页面的设置”中调整；
• 查看日志定位问题：v2.1.5 起新增日志机制，命令行启动时可见实时日志，达到设定级别（默认 ERROR）的日志保存到 Umi-OCR/UmiOCR-data/logs 目录，日志级别可在全局设置标签页更改。这是排查“识别结果异常/任务失败”类问题最直接的依据。

五、扩展应用：插件生态探索

Umi-OCR 的扩展能力建立在插件目录之上。UmiOCR-data/plugins 中的每个插件都是一个独立的功能组件，OCR 引擎本身就是以插件形式提供的（PaddleOCR-json、RapidOCR-json），此外二维码功能也通过插件接入。借助插件系统你可以：

• 安装额外的 OCR 引擎（如在不支持 AVX 的老机器上换用 RapidOCR）；
• 扩展识别语言库与文件格式支持；
• 添加实用功能模块。

安装方法（与草稿一致）：将插件文件夹复制到 UmiOCR-data/plugins/ 目录，重启程序即可启用，随后在全局设置中切换要使用的 OCR 插件。

注意：README 提醒，通过 Scoop 等方式安装时，umi-ocr（Rapid 引擎）与 umi-ocr-paddle（Paddle 引擎）两个版本不要同时安装，快捷方式可能被覆盖；但可以随时额外导入插件来切换引擎。

六、总结：从部署到排障的完整闭环

回顾这条实践路径：核实系统环境（Windows 7 x64+ / Linux x64 + glibc ≥ 2.31）→ 解压即用、避免中文路径 → 在截图 OCR / 批量 OCR / 文档识别 / 二维码标签页间按需作业 → 用忽略区域、排版解析、引擎切换优化识别质量 → 启动异常时对照 错误排查手册 逐项排查，必要时借助 v2.1.5 的日志机制与 --reload 指令定位问题 → 需要更多引擎或功能时向 plugins 目录导入插件。

Umi-OCR 还支持命令行调用（见 命令行手册，umi-ocr --help 查看全部指令）与 HTTP 接口（见 HTTP 接口手册），可以将 OCR 能力嵌入自动化脚本；命令行依赖 HTTP 接口在本地环回上进行跨进程通信，仅本机可见，不经过物理网卡。对于学习、办公、文档数字化等场景，这套“部署—使用—排障—扩展”的闭环足以覆盖绝大多数需求；项目本身的更新动态可继续参考 CHANGE_LOG.md。