Umi-OCR高效实战指南：从基础配置到批量PDF识别全攻略

Umi-OCR是一款免费开源的离线OCR工具，专为Windows系统设计，支持截图识别、批量处理和二维码解析等核心功能。本指南将帮助你从零开始掌握这款工具的使用技巧，通过命令行和HTTP接口实现PDF文档的自动化识别，提升工作效率。

零基础环境部署与验证

在开始使用Umi-OCR前，需确保本地服务已正确配置。默认情况下，软件会启用1224端口作为HTTP服务接口，支持跨进程通信。你可以通过以下步骤验证环境是否就绪：

Umi-OCR.exe --help

成功执行后将显示完整的命令帮助信息。基础命令结构遵循"指令-参数-输出"的三段式设计：

Umi-OCR.exe [指令] [参数] [输出选项]

核心功能解析：双层PDF技术

Umi-OCR的双层PDF技术是处理扫描文档的理想解决方案。该技术通过保留原始图像层并添加可搜索文本层，实现了"视觉保持原貌，内容可检索"的双重需求。目前支持三种主要输出格式：

• pdfLayered：双层PDF（推荐）- 保留原始图像并叠加文本层
• pdfOneLayer：单层纯文本PDF - 仅保留识别文本
• txt/csv：纯文本格式 - 适用于数据处理场景

批量PDF处理全流程

模块加载与状态检查

在处理文档前，建议先确认批量处理模块状态：

# 查看所有可用页面模板
Umi-OCR.exe --all_pages

# 创建批量文档标签页
Umi-OCR.exe --add_page 3

# 检查模块运行状态
Umi-OCR.exe --all_modules

文档添加与任务执行

添加PDF文件并启动识别任务的基本命令如下：

# 添加单个PDF文件（Windows系统路径使用正斜杠）
Umi-OCR.exe --call_qml BatchDOC --func addDocs '[ "C:/docs/example.pdf" ]'

# 启动OCR处理任务
Umi-OCR.exe --call_qml BatchDOC --func docStart

对于多文件处理，可使用JSON数组格式传递路径列表。处理过程中可通过界面实时监控进度，如文档数量、处理耗时和识别置信度等关键指标。

结果导出与参数配置

任务完成后，可通过以下命令指定输出位置和格式：

# 基础输出命令
Umi-OCR.exe --path "C:/input.pdf" --output "C:/output.txt"

# 追加模式输出（适用于批量汇总）
Umi-OCR.exe --path "C:/input.pdf" --output_append "C:/output.log"

HTTP接口高级应用

对于自动化集成需求，Umi-OCR提供了功能完备的HTTP接口。以下是常用接口示例：

参数查询接口

curl http://127.0.0.1:1224/api/doc/get_options

文件上传Python示例

import requests

url = "http://127.0.0.1:1224/api/doc/upload"
file_path = "document.pdf"

with open(file_path, "rb") as f:
    response = requests.post(url, files={"file": f})
    task_id = response.json()["data"]

性能优化参数配置

合理调整以下参数可显著提升处理效率：

参数	功能描述	推荐配置
ocr.limit_side_len	控制图像处理尺寸	4320（平衡速度与精度）
ocr.cls	文本方向自动校正	false（非必要时关闭以提升速度）
pageRangeStart/End	指定处理页码范围	按需设置（避免全文档处理）

自动化脚本示例

Windows批处理脚本

@echo off
set "INPUT_DIR=C:\pdf_docs"
set "OUTPUT_FILE=ocr_results.txt"

echo. > %OUTPUT_FILE%

for %%f in (%INPUT_DIR%\*.pdf) do (
    echo 正在处理: %%f
    Umi-OCR.exe --path "%%f" --output_append %OUTPUT_FILE%
)

echo 所有任务完成！结果已保存至 %OUTPUT_FILE%

常见问题解决方案

服务连接失败

• 检查Umi-OCR主程序是否已启动
• 使用netstat -ano | findstr :1224确认端口占用情况

大文件处理策略

对于超过100页的PDF，建议分段处理：

# 设置处理范围为1-50页
Umi-OCR.exe --call_qml BatchDOC --func setOption '{"pageRangeStart": 1, "pageRangeEnd": 50}'

多语言识别切换

通过命令行快速切换识别语言模型：

# 切换至英文识别模型
Umi-OCR.exe --call_qml BatchDOC --func setOption '{"ocr.language": "models/config_en.txt"}'

项目获取与安装

要开始使用Umi-OCR，请通过以下命令克隆项目仓库：

git clone https://gitcode.com/GitHub_Trending/um/Umi-OCR

建议定期查看项目更新，以获取最新功能和性能优化。对于企业级应用，可参考docs/http/api_doc.md进行定制化集成。

通过本指南的学习，你已掌握Umi-OCR的核心使用技巧。无论是日常办公还是企业级文档处理，这款工具都能为你提供高效、可靠的OCR解决方案。合理利用命令行和HTTP接口，可进一步实现工作流自动化，大幅提升文档处理效率。