Umi-OCR 开源离线OCR软件使用指南：界面操作、文本后处理与命令行/HTTP集成

2026-09-05 09:51:21作者：翟萌耘Ralph

本文以 Umi-OCR 项目的英文主文档（README_en.md）为主线，系统梳理这款免费、开源、可离线运行的批量 OCR 软件：从解压即用与 Scoop 安装，到截图 OCR、批量 OCR、文档识别、二维码等标签页的实际操作，再到文本后处理（段落合并、忽略区域）等进阶功能，以及命令行与 HTTP API 两种外部集成方式。读完后，你既能独立完成日常的文字识别任务，也能把 Umi-OCR 接入自己的自动化脚本与工作流。

一、项目定位与核心特性

英文 README 对 Umi-OCR 的定义是：Free, Open-source, Batch Offline OCR Software（免费、开源、可批量的离线 OCR 软件），并声明适用于 Windows 7 x64 及以上系统。其四项核心特性在 README_en.md 中给出：

免费（Free）：项目全部代码开源，完全免费；
方便（Convenient）：解压即用、离线运行，全程不需要联网；
高效（Efficient）：自带高效的离线 OCR 引擎，在计算机性能足够的前提下，识别速度可以快于在线 OCR 服务；
灵活（Flexible）：界面可自定义，并支持命令行、HTTP API 等多种外部调用方式。

从 CHANGE_LOG.md 可以补充一条平台演进的实现事实：软件在 v2.1.3（2024.7.23）起新增了对 Linux 平台的兼容，并支持 Docker 部署，也就是说当前版本并不局限于 Windows。仓库根目录随附的 Umi-OCR_Rapid_v2.1.5.7z 即基于 Rapid-OCR 引擎的 v2.1.5 发布包。

二、安装与启动

2.1 直接解压运行

发布包提供两种形态（见 README_en.md 的 Getting Started 章节）：

.7z 压缩包：需要 7z 等压缩软件解压；
.7z.exe 自解压包：在没有安装压缩软件的电脑上直接运行即可解压。

本软件无需安装，解压后点击 Umi-OCR.exe 即可启动。仓库中随附的 Umi-OCR_Rapid_v2.1.5.7z 就是一个标准的发布包样例。

2.2 通过 Scoop 安装

Scoop 是 Windows 下的命令行安装管理工具。安装 Scoop 后可用以下命令安装 Umi-OCR：

scoop bucket add extras

二选一安装（不要同时安装，快捷方式可能会互相覆盖）：

scoop install extras/umi-ocr        # 自带 Rapid-OCR 引擎，兼容性更好
scoop install extras/umi-ocr-paddle # 自带 Paddle-OCR 引擎，速度稍快

英文 README 特别提醒：两种引擎包不要同时安装；如需要切换 OCR 引擎，可以额外导入插件库（Umi-OCR_plugins）中的插件，随时切换不同的 OCR 引擎。

三、界面语言与多语言支持

Umi-OCR 的界面支持多国语言。第一次打开软件时，会按照电脑的系统设置自动切换语言；
如需手动切换，进入 全局设置 → 语言/Language 即可，支持的界面语言包括繁体中文、英语、日语等。

从仓库的本地化工程文件可以进一步确认语言覆盖面。dev-tools/i18n/lupdate_all.py 中维护了参与翻译的语言列表，包括：en_US（英语）、zh_TW（繁体中文）、ja_JP（日语）、fr_FR（法语）、pt（葡萄牙语）、ru_RU（俄语）、uz（乌兹别克语）、vi（越南语）、ta（泰米尔语）等，注释中还保留了 nb_NO、it_IT、es_ES、de_DE、ko_KR、pt_BR 等待启用的语言。该脚本调用 lupdate.exe 扫描 UmiOCR-data/qt_res/qml 目录下的 QML 源码（源语言为 zh_CN）生成各语言的 .ts 翻译工程文件，再由 dev-tools/i18n/lrelease_all.py 将 .ts 编译为二进制翻译包 .qm。

翻译协作流程在 dev-tools/i18n/README.md 中有明确说明：普通译者前往 Weblate 在线翻译平台校对、补充现有语言或新增语言；开发者则通过 lupdate_all.py 生成 .ts 文件、经 Weblate 平台协作后，再运行 lrelease_all.py 生成 .qm 文件并放入 UmiOCR-data/i18n 目录。此外，引擎组件等插件使用另一套轻量翻译机制（基于各插件目录下的 i18n.csv 文件），与主界面翻译体系相互独立。

四、标签页式界面总览

Umi-OCR v2 由一系列灵活易用的**标签页（tabbed interface）**组成，用户可按喜好自由打开所需标签页：

标签栏左上角可切换窗口常驻置顶；
标签栏右上角可锁定标签页，防止日常使用中误触关闭。

主要标签页包括：截图 OCR、批量 OCR、批量文档 OCR、二维码、全局设置。下面逐一说明。

五、截图 OCR（Screenshot OCR）

打开截图 OCR 标签页后，即可用键盘快捷键唤起截图，识别图中文字（见 README_en.md 的 Screenshot OCR 章节）：

左侧图片预览栏：可直接用鼠标划选并复制文字；
右侧识别记录栏：可以编辑文字，也允许划选多条记录批量复制；
支持在别处复制图片后，粘贴到 Umi-OCR 中进行识别。

5.1 文本后处理：段落合并

OCR 引擎的原始输出通常是一堆零散的文本块，**段落合并（Paragraph Merge）**属于 OCR 文本后处理功能，用于整理识别结果的排版与顺序，让文本更适合阅读和使用。英文 README 列出的预设方案有：

单行（Single line）：合并同一行的文字，适合大多数场景；
多行-自然段（Multiple lines - natural paragraphs）：智能识别并合并属于同一自然段的文字，适合大多数场景；
多行-代码块（Multiple lines - code block）：尽量还原文字的原始缩进与空格，适合识别代码片段或需要保留空格的场景；
竖排（Vertical layout）：适合竖排文字排版，需要配合同样支持竖排识别的模型库使用。

CHANGE_LOG.md 显示，这套后处理机制还在持续演进：v2.0.0（2024.2.29）引入了"更强大的排版解析器"，v1.3.6 起自动区分中/英文段落并采取对应的合并规则，v2.1.3 还对"单栏-单行"方案优化了相邻文本块之间间隔较大时的空格补全逻辑。

六、批量 OCR（Batch OCR）

批量 OCR 标签页用于批量导入本地图片进行识别，其能力要点如下：

识别结果可保存为 txt / jsonl / md / csv(Excel) 等多种格式；
与截图 OCR 一样支持文本后处理，可识别同属一个自然段的文字并合并，也支持代码块、竖排等多种处理方案；
单次导入的图片数量没有上限；
任务完成后，软件可以自动关机或休眠。

6.1 特殊功能：忽略区域（Ignore Regions）

忽略区域是批量 OCR 中专门用来排除图片中不想要的文字的功能：

入口在批量识别页右栏的设置中，可打开忽略区域编辑器；
典型场景：图片顶部、右下角存在多个水印/LOGO，批量识别这类图片时水印会污染识别结果；
操作方式：按住鼠标右键绘制多个矩形框，这些区域内的文字将在任务中被忽略；
建议把矩形框画得尽量大，完全包裹住水印可能出现的所有位置。

需要注意忽略的粒度：从中文 README 的说明可以确认，只有完全处于忽略区域框内部的整个文本块（而非单个字符）才会被忽略。例如一个水印框只覆盖住了 key_mouse 这一个文本块，则只忽略它，相邻的 pubsub_connector.py、pubsub_service.py 等文本块得以保留。该功能自 v2.0.0 dev（2023.10.25）引入，后续版本还在文档识别中支持了按页数范围指定忽略区域（v2.1.1），HTTP OCR 接口也暴露了忽略区域参数（v2.1.2）。

七、批量文档 OCR（Batch Documents OCR）

文档识别标签页用于从文档中批量提取文本。英文 README 对该页只给出了入口示意，结合 CHANGE_LOG.md 的记录，其能力为：

v2.1.0 起新增批量文档识别，支持 pdf、epub、mobi 等格式（中文 README 进一步列出 pdf, xps, epub, mobi, fb2, cbz）；
对扫描件可进行 OCR，也可直接提取文档原有文本，并可输出为双层可搜索 PDF；
支持设定忽略区域，常用于排除页眉、页脚文字，且可指定忽略区域生效的页数范围（v2.1.1）；
批量文档任务支持暂停/恢复（v2.1.2）：只要不退出软件，待机/休眠后可恢复任务；并可在任务完成后自动关机/休眠。

八、二维码（QR Code）

二维码标签页包含"扫码"与"生成码"两个方向的功能：

扫码（Scan Code）：

通过截图、粘贴或拖入本地图片，读取其中的二维码、条形码；
支持一图多码；
支持 19 种编码协议：Aztec、Codabar、Code128、Code39、Code93、DataBar、DataBarExpanded、DataMatrix、EAN13、EAN8、ITF、LinearCodes、MatrixCodes、MaxiCode、MicroQRCode、PDF417、QRCode、UPCA、UPCE。

生成码（Generate Code）：

输入文本生成二维码图片；
支持同样 19 种协议，并可提供**纠错等级（error correction level）**等参数。

实现层面，从 CHANGE_LOG.md 可见，二维码解析库在 v2.0.0 dev 阶段已从早期方案切换为性能更好、功能更丰富的 zxing-cpp（Windows 版 v2.1.5 更新为 zxing-cpp 2.3.0）。

九、全局设置（Global Settings）

全局设置页用于调整软件的全局参数，英文 README 列出的常用功能包括：

一键添加快捷方式或设置开机自启；
更改界面语言（支持繁体中文、英语、日语等）；
切换界面主题（提供多个亮色/暗色主题）；
调整界面文字的字号与字体；
切换 OCR 插件（即切换底层识别引擎）；
渲染器（Renderer）：界面默认使用 GPU 加速渲染；如果在你的机器上出现截屏闪烁、UI 错位的情况，可调整 Interface and Appearance → Renderer，尝试切换不同渲染方案，或关闭硬件加速。

另外从 v2.1.5 的更新日志可以补充：该版本新增了日志机制——指定级别以上（默认 ERROR）的日志会保存到 Umi-OCR/UmiOCR-data/logs 目录，保存级别可在全局设置标签页中更改，这对排查运行问题很有用。

十、API 集成：命令行与 HTTP

Umi-OCR 的"灵活"特性主要体现在两套外部调用接口上，详细手册分别见命令行手册与 HTTP接口手册，此处给出关键操作摘要。

10.1 命令行调用

命令行入口就是主程序 Umi-OCR.exe（注意：使用备用启动器如 UmiOCR-data/RUN_GUI.bat 时可能无法使用命令行），且必须在软件中允许 HTTP 服务（默认开启，主机选"仅本地"即可）。Umi-OCR 通过本地回回的 HTTP 接口进行跨进程通信，指令不会经过物理网卡，也不会泄露到外部。常用指令：

软件操控：

umi-ocr --help     # 获取说明
umi-ocr --show     # 弹出主窗口
umi-ocr --hide     # 隐藏主窗口
umi-ocr --quit     # 关闭软件
umi-ocr --reload   # 重新加载配置文件（v2.1.5 以上版本支持）

其中配置文件为 ./UmiOCR-data/.settings（ini 格式），允许手动修改后用 --reload 重载并刷新设置界面。

OCR 指令：

umi-ocr --screenshot                          # 鼠标框选截屏
umi-ocr --screenshot screen=1 rect=50,100,300,200  # 范围截屏：第2屏 (50,100) 起 300x200 区域
umi-ocr --clipboard                             # 识别剪贴板中的图片
umi-ocr --path "D:/xxx.png"                     # 识别指定图片
umi-ocr --path "D:/img1.png" "D:/img2.png" "D:/image/test"  # 多个路径，文件夹会递归搜索

范围截屏参数说明：screen 为显示器编号（从 0 开始，缺省 0），rect 为 x,y,w,h 矩形（缺省全屏）；两者至少填一个才会触发范围截图，否则执行鼠标截屏。

二维码指令：

umi-ocr --qrcode_read "D:/xxx.png"                    # 识别二维码/条形码（同样支持多路径）
umi-ocr --qrcode_create "文本内容" "D:/输出图片.jpeg"  # 生成二维码
umi-ocr --qrcode_create "文本内容" "D:/输出图片.jpeg" 128 256  # 手动指定宽128、高256

结果输出：

umi-ocr --screenshot --clip                 # 复制到剪贴板
umi-ocr --screenshot --output test.txt     # 输出到文件（覆盖）
umi-ocr --screenshot --output_append x.txt # 输出到文件（追加）
umi-ocr --screenshot "-->" test.txt        # "-->" 等价于 --output，"-->>" 等价于 --output_append

两个实用提示：其一，所有指令支持前缀简写，如 --screenshot 可简写为 --sc、--clipboard 可简写为 --clipbo；其二，受运行环境限制，Umi-OCR 暂时无法重定向输出流，系统的管道重定向符 > 和管道操作符 | 可能失效，需要用程序调用时建议改用 HTTP 的 argv 接口。

10.2 HTTP 接口

HTTP 接口的使用前提是全局设置中允许 HTTP 服务（默认开启）；若需局域网访问，将主机切换为"任何可用地址"即可。接口目录（见 docs/http/README.md）覆盖四类能力：

图片 OCR：参数查询（/api/ocr/get_options）与 Base64 图片识别；
文档识别（PDF）：完整的文档识别流程接口；
二维码：Base64 图片识别与从文本生成图片；
命令行接口：/argv 端点用于跨进程传输命令行参数——向 http://127.0.0.1:1224/argv 发送 POST 请求，body 为 JSON 列表，如 ["--path", "D:/xxx.png"]，等价于执行命令行 Umi-OCR.exe --path "D:/xxx.png"。该接口因较敏感（可访问本机图片、关闭软件等）仅允许本地环回 127.0.0.1 调用。

文档接口手册同时给出了三条注意事项：关闭软件时若仍有未断开的 HTTP 连接，可能导致进程未完全退出；后端组件对并发支持较差，尽量不要并发调用；长时间、大批量、连续调用时小概率出现 Error: connect ECONNREFUSED 之类的报错，重新发起请求即可。

十一、项目结构与引擎生态

从英文 README 的 About Project Structure 章节看，Umi-OCR 采用多仓库 + 插件的工程结构：

主仓库（本项目）：界面、业务逻辑与文档；
插件仓库（Umi-OCR_plugins）：可切换导入的 OCR 引擎插件；
Windows / Linux 运行库仓库（Umi-OCR_runtime_windows、Umi-OCR_runtime_linux）：负责各平台的开发/运行环境部署与构建，"构建项目"工作需在对应运行库仓库中完成。

主仓库目录中随附的 dev-tools/i18n/ 则是本地化开发工具集，含 lupdate_all.py、lrelease_all.py、convert_ts_txt.py 等脚本，供维护翻译文件的开发者使用。

支持的离线 OCR 引擎包括 PaddleOCR-json 与 RapidOCR-json 两套（以插件形式存在），运行环境框架基于 PyStand 定制版。引擎选择直接对应第二章提到的两个 Scoop 包：Rapid 版兼容性更好，Paddle 版速度稍快；v2.1.4 还针对 Paddle 插件优化了默认线程/内存限制（默认内存占用不超过系统总内存的一半）。

十二、版本与后续跟进

完整的版本演进记录见 CHANGE_LOG.md。与本文内容最相关的几个版本节点：

v2.1.5（2025.3.26，当前 main 分支）：新增日志机制、--reload 指令、Esc 隐藏主窗口、双栏布局手动切换，并新增俄语、泰米尔语 UI 语言；
v2.1.3：新兼容 Linux 平台，新增 HTTP 文档识别接口；
v2.1.2：批量任务支持暂停，--screenshot 支持指定屏幕范围；
v2.1.1：新增二维码命令行/HTTP 接口、--output/--output_append/--clip 输出指令；
v2.1.0：新增批量文档识别功能。