简介Umi-OCR是一套面向Linux平台的开源OCR工具基于深度学习实现多语言印刷文字识别适用于文档数字化、票据信息提取、商品录入等场景。资源共56个文件压缩包约308.04MB涵盖样例、配置、文档与脚本等类型sample目录提供测试样例json与config定义识别参数sh和py脚本用于启动与扩展Dockerfile便于容器化部署md文档说明安装与使用方式。已有303人学习浏览。包内核心组件包括Umi-OCR_v2.1.3_Linux_embeddable.tar.xz嵌入式版本、PaddleOCR-json_v141模型配置以及runtime运行时依赖配合main_linux.py、umi-ocr.sh等入口脚本可快速在Linux服务器或应用程序后台集成OCR能力同时携带.git版本信息和LICENSE开源许可方便二次开发与定制优化。1. 把 Umi-OCR for linux 变成你的离线识别服务不联网也能用的中文 OCRUmi-OCR for linux 的价值是它把一条完整的中文 OCR 流水线直接放到了你的本机里。没有云服务、没有上传图片到第三方 API 的环节也不需要在浏览器里开一个谁也管不住的网页服务。对于 Linux 用户来说最顺手的用法不是打开一个图形界面慢慢点而是把这套识别能力接进自己的脚本、截图工具和批量处理流程里让它变成系统自带的一项能力。它能解决的是三类具体问题把扫描件和图片里的中文变成可检索文本、把桌面上随手截的图转成可复制的文字、以及在没有外网的服务器或内网环境里对图片做离线识别。适合的人群也很明确Linux 桌面用户、运维、写 Python 的开发者以及所有要做文档数字化的人。2. Linux 上跑通 Umi-OCRAppImage 与 Python 源码两种落地姿势2.1 两条路线怎么选先想清楚你要的是“工具”还是“引擎”Umi-OCR 在 Linux 上最常见的两种落地方式一个是官方打包的 AppImage一个是直接从源码运行的 Python 工程。两条路都有人走得通但选错会很痛苦。AppImage 的定位是“开箱即用的桌面工具”。它的好处是可见即所得界面、截图、剪贴板、拖拽识别都是现成的适合你只是想把日常截图和扫描件转成文字不想碰环境依赖的情况。它的坏处是你想改模型、想自定义输出格式、想在无显示器的服务器上跑会很受限制因为 AppImage 内部的目录结构不是给你随意翻的。源码方式则适合另一类人你要在这套 OCR 上做二次开发比如把识别结果接进自己的知识库比如你需要换一个更小或更准的中文识别模型比如你要在只有 Python 环境的服务器上跑批量任务。源码方式暴露的接口更完整PaddleOCR 底层的检测、识别、方向分类三个模型都能单独拆出来调。我一般这样建议先花十分钟把 AppImage 跑通让 Umi-OCR 给你一个准确率的“体感基线”。如果你发现只是截图识别那 AppImage 就够了。一旦你开始想“能不能让服务器定时识别一批图片”立刻切换到源码方式。不要一上来就折腾源码环境。2.2 AppImage 最小安装与启动依赖缺失怎么补Umi-OCR 的 AppImage 在 Releases 页面可以下载到文件名通常类似Umi-OCR_linux_x64.AppImage。Linux 下跑 AppImage 有一个前置条件你的系统要有libfuse2而现在很多新发行版默认不再安装它。我踩过的典型场景是 Ubuntu 22.04AppImage 双击没有任何反应命令行执行报fuse: device not found多半就是 libfuse2 没装。# 下载到本地后先做两件事赋权、查看能否运行 chmod x Umi-OCR_linux_x64.AppImage # 直接运行如果失败先看报错 ./Umi-OCR_linux_x64.AppImage # Ubuntu / Debian 系列缺 libfuse2 时这样做 sudo apt install libfuse2 # Arch 系 sudo pacman -S fuse2赋权这一步是新手最容易漏的。AppImage 本质上是一个带文件系统的可执行镜像没有执行权限时双击毫无反应。运行失败时别急着卸载或换版本先看终端输出里有没有libGL.so、libxcb、libQt5这类字样。有就挨个补。libfuse2只是最出名的一个如果启动画面出来后闪退常见系统中还缺libnss3和libatk-bridge2.0-0一并装上再试。这套环境补齐之后每次启动走./Umi-OCR_linux_x64.AppImage就行。如果不想每次输路径把 AppImage 的启动命令做一条软链接到/usr/local/bin/umi-ocr体验会好很多。AppImage 方式启动后进入的是图形界面主窗口左侧是截图识别右侧是批量识别功能入口很直观第一轮熟悉界面花不了五分钟。2.3 源码方式Python 环境与依赖安装的三个关键版本源码方式的坑不在代码本身而在 Python 环境、PaddlePaddle 版本和模型文件三者的配合。Umi-OCR 依赖 PaddleOCR而 PaddlePaddle 的预编译包对不同 Python 版本的支持是有差异的。我在 Python 3.10 上跑过比较顺在 3.12 上遇到过编译型依赖找不到预编译 wheel 的情况所以建议先用系统自带的 Python 3.9 或 3.10 起步别为了新而新。# 创建一个干净的虚拟环境避免污染系统 Python python3.10 -m venv umi_venv source umi_venv/bin/activate # 拉取源码然后装依赖 git clone https://github.com/hiroi-sora/Umi-OCR.git cd Umi-OCR pip install -r requirements.txt # 启动 CLI 或图形界面 python cli.py --help # 命令行模式 python main.py # 图形界面模式这里最常被忽略的是requirements.txt里的paddlepaddle版本。CPU 机器安装默认的 paddlepaddle 就能跑但如果你机器有 NVIDIA 显卡且想用 GPU需要显式装paddlepaddle-gpu并且注意它和你的 CUDA 版本要匹配。另一个关键是首次启动时会检查模型目录Umi-OCR 的模型放在models/下如果这个目录是空的程序不会报“模型缺失”而是识别结果全空白、日志里只有一行警告。源码方式的目录结构比 AppImage 清晰models/、config/、screenshots/都是可见的方便排查这个差异是源码方式最大的优势。装完依赖之后建议先跑一行python cli.py --help确认 CLI 入口是通的路。Umi-OCR 的版本历史上 CLI 入口名有过多次变化有的是cli.py有的是直接通过main.py --cli。你的下载版本是什么就用什么不用刻舟求剑。3. 把识别接到工作流命令行调用、截图识别与批处理3.1 从图形界面走向命令行Umi-OCR 的 CLI 入口与输出格式一旦跑通真正让 Umi-OCR 产生生产力的是命令行调用。无论是服务器端批量识别还是桌面端接进自己的快捷方式图形界面只是壳核心是 CLI 的参数和输出。常见调用是这样的# 单张图片识别输出到标准输出 python cli.py -i ./data/scan_001.png # 指定输出目录结果保存为 txt python cli.py -i ./data/scan_001.png -o ./out/scan_001.txt # 批量识别一个目录下所有图片保持文件名输出 python cli.py -i ./data/ -o ./out/ --output-format txt-i参数接受文件或目录目录模式下会遍历子目录-o指定输出位置不提供时终端直接打印--output-format决定保存格式。大多数版本支持txt、json、md三种。做知识库导入时建议用 json因为 json 里除了文本还带了置信度和每个文字块的位置坐标后面做版面还原、做检索都方便。而纯做速记时用 txt 就好干净。CLI 的退出码也是有含义的。识别正常返回 0找不到输入路径返回 1模型加载失败返回 2。写自动化脚本时不要只判断返回码是 0要额外判断输出文件是否存在且有非空内容因为模型相关错误有时会以空结果文件的形式出现而不是非零退出码。这是我在服务端集成时被坑过的细节。3.2 截图识别接入工作流X11 与 Wayland 面对的问题不一样桌面端最爽的用法是“截图即识别”。Umi-OCR 的图形界面自带这个功能但命令行用户往往想把它接到自己的窗口管理器快捷键上。这里必须区分你的 Linux 桌面用的是 X11 还是 Wayland因为两者的截图方式和工作原理完全不同。在 X11 环境下常见做法是用flameshot或import来自 imagemagick截取选定区域把临时图片存到/tmp/shot.png然后调用 Umi-OCR 的 CLI 识别最后把结果塞进剪贴板。截图工具负责取图像Umi-OCR 负责识别剪贴板工具负责输出三个进程协作#!/bin/bash # 先截屏flameshot 的 gui 模式返回用户选区路径 flameshot gui -p /tmp/umi_shot.png # 识别 python cli.py -i /tmp/umi_shot.png -o /tmp/umi_shot.txt # 把识别结果装进剪贴板 xclip -selection clipboard /tmp/umi_shot.txt这段脚本贴在 Openbox、i3、Xfce 的快捷键配置里就能用。有几个要点flameshot gui -p是保存模式不会打开编辑窗口识别时不要使用-o输出文件后直接cat文件再进 xclip因为 cli 的启动有模型加载时间直接管道会读到一个空文件。xclip在没有安装时会报 command not found先装好。Wayland 下截图工具的选择就少很多import和flameshot的兼容性都不稳定。更麻烦的是剪贴板权限Wayland 对全局剪贴板的访问是受限的xclip大概率拿不到数据需要改用wl-clipboard的wl-copy。在 GNOME Wayland 环境里更现实的做法是直接用 GNOME 自带的截图交互CtrlShiftPrintScreen 选择区域到剪贴板然后让 Umi-OCR 直接读取剪贴板图片这部分在图形界面里已经内置命令行方案更适合快速验证而不是长期稳定。3.3 批量识别一批 PDF 或图片循环、命名与失败重试批量识别是最考验脚本素养的场景。不要直接在命令行里对一张张图片执行 Umi-OCR而是写一个小脚本做好三件事先转 PDF再识别最后检查漏网之鱼。PDF 文件 Umi-OCR 不直接处理要先转成图片# 安装 poppler-utils 后用 pdftoppm 转 300 DPI 的图片 mkdir -p /tmp/pdf_pages pdftoppm -png -r 300 input.pdf /tmp/pdf_pages/page # 识别所有 page 前缀的文件 python cli.py -i /tmp/pdf_pages/ -o ./ocr_result/ --output-format txt # 检查是否有空结果重新跑失败项 find ./ocr_result/ -name *.txt -empty -exec rm {} \;pdftoppm的 300 DPI 是我做扫描件识别的基准。低于 200 DPI小字号中文会糊高于 600 DPI识别时间成倍上涨而准确率收益极小性价比不高。-r 300这个参数是最稳的选点扫描件和电子版 PDF 都能覆盖。识别完成后用find -empty找出空结果文件并删掉再基于ocr_result目录下缺失的文件名反向生成重试列表。这个“识别一次再补漏”的写法比一次性强行跑完要实用得多。批量识别的另一个值得做的事是让输出文件保持和输入一致的文件名。Umi-OCR 在目录模式下默认按输入文件名加同名后缀输出这个默认行为在多数场景是够用的。如果你希望把识别结果和原图归档在同一个目录树里建议输出结构和输入结构保持镜像后面做检索时按路径反查原图最方便。4. 影响识别结果与速度的 5 个必调参数4.1 检测、方向分类与识别三个模型开关的取舍Umi-OCR 底层复用 PaddleOCR 的流程它把一张图变成文本经历三步检测文本行位置det、判断该行是否需要纠偏cls方向分类、对文本行做字符识别rec。这三步对应的参数直接决定识别结果。参数作用关闭的影响适用场景--det是否启用文本检测关闭后只能识别整图必须裁好单行你已经裁好文本行的场景--use-angle-cls是否启用方向分类关闭后旋转超过 90 度的图识别率剧降手机拍照、竖版文字不常用时--rec是否启用文本识别关闭后只输出文本框位置只需要版面分析、不要文本时--text-score识别置信度阈值调高时低质量图会被丢弃对准确率有硬要求的生产环境--limit-side-len检测输入图最长边数值高时小字更清晰耗时上升高分辨率扫描件det和rec同时默认开启是通用配置不要轻易关。真正值得调的是text-score和limit-side-len。默认置信度阈值一般在 0.5 左右这个值偏低导致大量模糊字的识别结果被保留下来。如果你做的录入工作对错误零容忍把阈值拉到 0.75 到 0.8识别结果里拿不准的字符就会直接变成空或低置信度内容宁可少识别也不能错识别。limit-side-len控制的是检测阶段输入图像的最长边缩放。默认值经常是 960 或 3200。做扫描件批处理时我习惯把它调到 2000 左右因为 2000 以上计算量膨胀太明显而 960 以下对 300 DPI 扫描件来说又太小字迹密集时容易出现漏行。4.2 把 CPU 性能吃满线程数、预处理宽度与并行CPU 模式下最让人着急的症状是“CPU 占用 100% 但识别速度只有每秒两张”。这往往不是 Umi-OCR 本身慢而是 PaddleOCR 内部使用了 OpenMP而你的 Python 或环境变量限制了线程池。这里有一个反直觉的坑你设置的环境变量越多可能越慢。# 公开的离线识别方案中一个常见的错误是给每个线程都设置大数 export OMP_NUM_THREADS16 export MKL_NUM_THREADS16 python cli.py -i ./data -o ./out这样做的结果是线程切换开销吃掉性能。更合理的做法是只设一个主线程数并且让它和你的物理核心数一致而不是逻辑线程数。我通常先在机器上查核数再决定设多少nproc --all # 例如物理核心数为 8则 export OMP_NUM_THREADS8 export MKL_NUM_THREADS1 python cli.py -i ./data -o ./outMKL_NUM_THREADS1的目的是让矩阵运算库别抢 OpenMP 的线程避免两个线程池自相残杀。这个组合在我的多台 Intel 机器上都能把识别速度提升 30% 到 50%。如果你用的是 AMD 机器把MKL_NUM_THREADS换掉改设OMP_NUM_THREADS一个变量就够了。做纯 CPU 识别时别指望 GPU 的加速效果能把线程池理顺、把 300 DPI 扫描件跑出每分钟 20 页左右就是不错的成绩。除了线程--rec-batch-num也值得注意。识别阶段可以把多行文本拼成一个 batch 送给模型默认值一般是 6 或 8调大到 16 时对 CPU 机器会增大单次计算的内存峰值但对含大量文本行的扫描件有明显加速效果。如果你的机器内存 16G 以上可以试试调大内存小的机器翻车概率很高不要冒险。4.3 用配置文件固化你的参数偏好每次在命令行把五个参数敲一遍既容易错又不可维护。Umi-OCR 的 CLI 一般支持读取配置文件常见做法是写一个自己的 yaml然后在每次运行时指定。配置文件的作用不只是省事更是让团队里其他人能稳定复现同一套识别设置。# umi_config.yaml input_dir: ./data/scan output_dir: ./out/ocr device: cpu model_dir: ./models limit_side_len: 2000 text_score: 0.75 use_angle_cls: true rec_batch_num: 8 output_format: json调用时指过去python cli.py --config umi_config.yaml配置文件的命名参数可能因版本不同略有差异但无论如何要点是“把识别当服务配置管理”而不是“当场敲命令试”。用配置文件把input_dir、output_dir、device拆到固定字段之后后续你用系统服务接管批量识别、用 cron 定时跑都会省很多事。5. Linux 上跑 Umi-OCR 的避坑清单从启动失败到截图失效5.1 启动即崩溃Qt 动态库缺失现象是执行 AppImage 或源码的python main.py后窗口还没弹出来就整个退出终端里没有明显报错或只有一句Segmentation fault。原因是 Linux 发行版对 Qt 的依赖比较分散AppImage 虽然自带 Qt但显卡驱动和系统库缺一不可。最常见的是libnss3和libxkbcommon缺失。解决先看两步第一步用ldd检查主程序的动态库依赖第二步对照结果安装。ldd的输出会列出所有“找不到”的库这是最快的排错手段。补完库之后若还是闪退检查 NVIDIA 显卡驱动是否正常nvidia-smi能输出就说明驱动没大问题剩下多半是 Wayland 兼容改回 Xorg 会话再试。5.2 识别结果全空白模型目录有个“不存在的空目录”现象是识别流程没有报错输出文件生成了但打开是空文件日志里只有一条类似ocr engine init failed的警告。原因特别容易误判模型目录存在但里面没有实际模型文件。Umi-OCR 的初始化逻辑对模型目录做了检查不会因为它空就抛异常而是悄悄跳过初始化。解决也简单把 Release 页面上的模型包下载完解压到models/目录后确认目录结构形如models/rec/xxx.pdmodel。只看目录名存在没用要看有没有以.pdmodel结尾的文件。5.3 Wayland 下截图识别失效剪贴板权限与截图协议现象是点击“截图识别”后区域选择是正常的但识别结果永远为空。原因是 Wayland 会话下应用访问全局剪贴板需要用户授权图形界面第一次请求时如果没有弹窗或你已经点过拒绝后续就再也不弹了。解决方式是到系统设置里重置剪贴板权限或者把会话临时切到 Xorg。还有一个相关场景是部分 Linux 桌面用wl-copy复制截图但 Umi-OCR 读取剪贴板时走的是 Qt 自己的接口两者对接不上。稳妥的做法是避免“剪贴板接力”把截图直接保存成临时文件再走 CLI 识别路径。5.4 CPU 跑满但识别速度慢OpenMP 线程池相互干扰现象是识别过程中top显示 CPU 满载但实际每秒只处理一两张图识别一张大图要好几秒。原因经常是环境变量里同时设置了OMP_NUM_THREADS和MKL_NUM_THREADS或者设置的数字超过了物理核心。解决的路径是先把环境变量清理干净只保留一个线程数并让它等于物理核心数。我见过最夸张的一次是把线程设到 32速度反而比默认值还慢。线程数这块没有“越多越好”稳定压倒一切。5.5 中文文件名乱码压缩包编码与 locale 问题现象是模型包解压后目录名全乱码Umi-OCR 找不到模型报model not found。原因是模型包是在特定系统里打包的文件名编码可能和你的 locale 不一致。解决方式是在解压时显式指定编码或者在解压后再用脚本重命名。Linux 下最省心的处理是装unzip解压命令加上-O gbk或-O utf8参数。如果你的发行版 unzip 不支持-O就用python3 -c import zipfile; zipfile.ZipFile(models.zip).extractall()直接解压Python 的解压逻辑一般能自动处理常见编码问题。6. 上生产前这样验证给场景造一组“失真样本”在把 Umi-OCR 真正交给业务用之前先做一次“验证准确率”的操作。不要拿一张清晰的截图测一下就自信上线而要做一组贴近真实业务的样本把它变成可重复的验证集。建立验证集时我一般会造三组第一组是清晰截图用来测识别引擎能否正常拿到 98% 以上的准确率第二组是模拟失真样本把图片做轻度模糊、压缩、曝光不足用来测你的参数阈值是否太激进第三组是真实样本比如你业务里的手机拍照、传真件、低分辨率扫描件。每组保持 10 张左右、统一放置之后每次调参都用同一组图跑一次避免用感觉调参。# 用 imagemagick 快速造失多样本 convert scan_001.png -blur 0x1.5 -quality 80 blur_001.jpg convert scan_001.png -brightness-contrast -20x15 dark_001.png计算准确率的脚本不需要太复杂拿原识别结果做字符级别比较。中文 OCR 的准确率建议用编辑距离衡量而不是简单相等判断因为漏两个字和错整行是完全不同量级的失误。简单比较后如果你发现失真样本的准确率从 95% 掉到 60%那说明生产场景里大量图片会被系统性误识别。此时先不要急着调算法先看是不是输入质量的原因很多扫描件没有做歪斜矫正方向分类也没开先开use_angle_cls再说。验证脚本跑完把当前这组参数和准确率结果写进一个固定文件比如benchmark_result.md。每次调参后更新这个文件你就能直观看到每次改动是正向还是负向的。这个动作看起来简单却是决定 Umi-OCR 能否承担生产任务的关键。我养成的习惯是每次更换模型或修改阈值后先用失真样本把上一版结果并列摆出来对比没有提升就不上线。这套“拿自己的图说话”的校验流程算是我在 Umi-OCR 上最值得的一笔投入希望帮到你。本文还有配套的精品资源点击获取 Linux离线中文OCR实战：Umi-OCR本地识别服务搭建指南
简介Umi-OCR是一套面向Linux平台的开源OCR工具基于深度学习实现多语言印刷文字识别适用于文档数字化、票据信息提取、商品录入等场景。资源共56个文件压缩包约308.04MB涵盖样例、配置、文档与脚本等类型sample目录提供测试样例json与config定义识别参数sh和py脚本用于启动与扩展Dockerfile便于容器化部署md文档说明安装与使用方式。已有303人学习浏览。包内核心组件包括Umi-OCR_v2.1.3_Linux_embeddable.tar.xz嵌入式版本、PaddleOCR-json_v141模型配置以及runtime运行时依赖配合main_linux.py、umi-ocr.sh等入口脚本可快速在Linux服务器或应用程序后台集成OCR能力同时携带.git版本信息和LICENSE开源许可方便二次开发与定制优化。1. 把 Umi-OCR for linux 变成你的离线识别服务不联网也能用的中文 OCRUmi-OCR for linux 的价值是它把一条完整的中文 OCR 流水线直接放到了你的本机里。没有云服务、没有上传图片到第三方 API 的环节也不需要在浏览器里开一个谁也管不住的网页服务。对于 Linux 用户来说最顺手的用法不是打开一个图形界面慢慢点而是把这套识别能力接进自己的脚本、截图工具和批量处理流程里让它变成系统自带的一项能力。它能解决的是三类具体问题把扫描件和图片里的中文变成可检索文本、把桌面上随手截的图转成可复制的文字、以及在没有外网的服务器或内网环境里对图片做离线识别。适合的人群也很明确Linux 桌面用户、运维、写 Python 的开发者以及所有要做文档数字化的人。2. Linux 上跑通 Umi-OCRAppImage 与 Python 源码两种落地姿势2.1 两条路线怎么选先想清楚你要的是“工具”还是“引擎”Umi-OCR 在 Linux 上最常见的两种落地方式一个是官方打包的 AppImage一个是直接从源码运行的 Python 工程。两条路都有人走得通但选错会很痛苦。AppImage 的定位是“开箱即用的桌面工具”。它的好处是可见即所得界面、截图、剪贴板、拖拽识别都是现成的适合你只是想把日常截图和扫描件转成文字不想碰环境依赖的情况。它的坏处是你想改模型、想自定义输出格式、想在无显示器的服务器上跑会很受限制因为 AppImage 内部的目录结构不是给你随意翻的。源码方式则适合另一类人你要在这套 OCR 上做二次开发比如把识别结果接进自己的知识库比如你需要换一个更小或更准的中文识别模型比如你要在只有 Python 环境的服务器上跑批量任务。源码方式暴露的接口更完整PaddleOCR 底层的检测、识别、方向分类三个模型都能单独拆出来调。我一般这样建议先花十分钟把 AppImage 跑通让 Umi-OCR 给你一个准确率的“体感基线”。如果你发现只是截图识别那 AppImage 就够了。一旦你开始想“能不能让服务器定时识别一批图片”立刻切换到源码方式。不要一上来就折腾源码环境。2.2 AppImage 最小安装与启动依赖缺失怎么补Umi-OCR 的 AppImage 在 Releases 页面可以下载到文件名通常类似Umi-OCR_linux_x64.AppImage。Linux 下跑 AppImage 有一个前置条件你的系统要有libfuse2而现在很多新发行版默认不再安装它。我踩过的典型场景是 Ubuntu 22.04AppImage 双击没有任何反应命令行执行报fuse: device not found多半就是 libfuse2 没装。# 下载到本地后先做两件事赋权、查看能否运行 chmod x Umi-OCR_linux_x64.AppImage # 直接运行如果失败先看报错 ./Umi-OCR_linux_x64.AppImage # Ubuntu / Debian 系列缺 libfuse2 时这样做 sudo apt install libfuse2 # Arch 系 sudo pacman -S fuse2赋权这一步是新手最容易漏的。AppImage 本质上是一个带文件系统的可执行镜像没有执行权限时双击毫无反应。运行失败时别急着卸载或换版本先看终端输出里有没有libGL.so、libxcb、libQt5这类字样。有就挨个补。libfuse2只是最出名的一个如果启动画面出来后闪退常见系统中还缺libnss3和libatk-bridge2.0-0一并装上再试。这套环境补齐之后每次启动走./Umi-OCR_linux_x64.AppImage就行。如果不想每次输路径把 AppImage 的启动命令做一条软链接到/usr/local/bin/umi-ocr体验会好很多。AppImage 方式启动后进入的是图形界面主窗口左侧是截图识别右侧是批量识别功能入口很直观第一轮熟悉界面花不了五分钟。2.3 源码方式Python 环境与依赖安装的三个关键版本源码方式的坑不在代码本身而在 Python 环境、PaddlePaddle 版本和模型文件三者的配合。Umi-OCR 依赖 PaddleOCR而 PaddlePaddle 的预编译包对不同 Python 版本的支持是有差异的。我在 Python 3.10 上跑过比较顺在 3.12 上遇到过编译型依赖找不到预编译 wheel 的情况所以建议先用系统自带的 Python 3.9 或 3.10 起步别为了新而新。# 创建一个干净的虚拟环境避免污染系统 Python python3.10 -m venv umi_venv source umi_venv/bin/activate # 拉取源码然后装依赖 git clone https://github.com/hiroi-sora/Umi-OCR.git cd Umi-OCR pip install -r requirements.txt # 启动 CLI 或图形界面 python cli.py --help # 命令行模式 python main.py # 图形界面模式这里最常被忽略的是requirements.txt里的paddlepaddle版本。CPU 机器安装默认的 paddlepaddle 就能跑但如果你机器有 NVIDIA 显卡且想用 GPU需要显式装paddlepaddle-gpu并且注意它和你的 CUDA 版本要匹配。另一个关键是首次启动时会检查模型目录Umi-OCR 的模型放在models/下如果这个目录是空的程序不会报“模型缺失”而是识别结果全空白、日志里只有一行警告。源码方式的目录结构比 AppImage 清晰models/、config/、screenshots/都是可见的方便排查这个差异是源码方式最大的优势。装完依赖之后建议先跑一行python cli.py --help确认 CLI 入口是通的路。Umi-OCR 的版本历史上 CLI 入口名有过多次变化有的是cli.py有的是直接通过main.py --cli。你的下载版本是什么就用什么不用刻舟求剑。3. 把识别接到工作流命令行调用、截图识别与批处理3.1 从图形界面走向命令行Umi-OCR 的 CLI 入口与输出格式一旦跑通真正让 Umi-OCR 产生生产力的是命令行调用。无论是服务器端批量识别还是桌面端接进自己的快捷方式图形界面只是壳核心是 CLI 的参数和输出。常见调用是这样的# 单张图片识别输出到标准输出 python cli.py -i ./data/scan_001.png # 指定输出目录结果保存为 txt python cli.py -i ./data/scan_001.png -o ./out/scan_001.txt # 批量识别一个目录下所有图片保持文件名输出 python cli.py -i ./data/ -o ./out/ --output-format txt-i参数接受文件或目录目录模式下会遍历子目录-o指定输出位置不提供时终端直接打印--output-format决定保存格式。大多数版本支持txt、json、md三种。做知识库导入时建议用 json因为 json 里除了文本还带了置信度和每个文字块的位置坐标后面做版面还原、做检索都方便。而纯做速记时用 txt 就好干净。CLI 的退出码也是有含义的。识别正常返回 0找不到输入路径返回 1模型加载失败返回 2。写自动化脚本时不要只判断返回码是 0要额外判断输出文件是否存在且有非空内容因为模型相关错误有时会以空结果文件的形式出现而不是非零退出码。这是我在服务端集成时被坑过的细节。3.2 截图识别接入工作流X11 与 Wayland 面对的问题不一样桌面端最爽的用法是“截图即识别”。Umi-OCR 的图形界面自带这个功能但命令行用户往往想把它接到自己的窗口管理器快捷键上。这里必须区分你的 Linux 桌面用的是 X11 还是 Wayland因为两者的截图方式和工作原理完全不同。在 X11 环境下常见做法是用flameshot或import来自 imagemagick截取选定区域把临时图片存到/tmp/shot.png然后调用 Umi-OCR 的 CLI 识别最后把结果塞进剪贴板。截图工具负责取图像Umi-OCR 负责识别剪贴板工具负责输出三个进程协作#!/bin/bash # 先截屏flameshot 的 gui 模式返回用户选区路径 flameshot gui -p /tmp/umi_shot.png # 识别 python cli.py -i /tmp/umi_shot.png -o /tmp/umi_shot.txt # 把识别结果装进剪贴板 xclip -selection clipboard /tmp/umi_shot.txt这段脚本贴在 Openbox、i3、Xfce 的快捷键配置里就能用。有几个要点flameshot gui -p是保存模式不会打开编辑窗口识别时不要使用-o输出文件后直接cat文件再进 xclip因为 cli 的启动有模型加载时间直接管道会读到一个空文件。xclip在没有安装时会报 command not found先装好。Wayland 下截图工具的选择就少很多import和flameshot的兼容性都不稳定。更麻烦的是剪贴板权限Wayland 对全局剪贴板的访问是受限的xclip大概率拿不到数据需要改用wl-clipboard的wl-copy。在 GNOME Wayland 环境里更现实的做法是直接用 GNOME 自带的截图交互CtrlShiftPrintScreen 选择区域到剪贴板然后让 Umi-OCR 直接读取剪贴板图片这部分在图形界面里已经内置命令行方案更适合快速验证而不是长期稳定。3.3 批量识别一批 PDF 或图片循环、命名与失败重试批量识别是最考验脚本素养的场景。不要直接在命令行里对一张张图片执行 Umi-OCR而是写一个小脚本做好三件事先转 PDF再识别最后检查漏网之鱼。PDF 文件 Umi-OCR 不直接处理要先转成图片# 安装 poppler-utils 后用 pdftoppm 转 300 DPI 的图片 mkdir -p /tmp/pdf_pages pdftoppm -png -r 300 input.pdf /tmp/pdf_pages/page # 识别所有 page 前缀的文件 python cli.py -i /tmp/pdf_pages/ -o ./ocr_result/ --output-format txt # 检查是否有空结果重新跑失败项 find ./ocr_result/ -name *.txt -empty -exec rm {} \;pdftoppm的 300 DPI 是我做扫描件识别的基准。低于 200 DPI小字号中文会糊高于 600 DPI识别时间成倍上涨而准确率收益极小性价比不高。-r 300这个参数是最稳的选点扫描件和电子版 PDF 都能覆盖。识别完成后用find -empty找出空结果文件并删掉再基于ocr_result目录下缺失的文件名反向生成重试列表。这个“识别一次再补漏”的写法比一次性强行跑完要实用得多。批量识别的另一个值得做的事是让输出文件保持和输入一致的文件名。Umi-OCR 在目录模式下默认按输入文件名加同名后缀输出这个默认行为在多数场景是够用的。如果你希望把识别结果和原图归档在同一个目录树里建议输出结构和输入结构保持镜像后面做检索时按路径反查原图最方便。4. 影响识别结果与速度的 5 个必调参数4.1 检测、方向分类与识别三个模型开关的取舍Umi-OCR 底层复用 PaddleOCR 的流程它把一张图变成文本经历三步检测文本行位置det、判断该行是否需要纠偏cls方向分类、对文本行做字符识别rec。这三步对应的参数直接决定识别结果。参数作用关闭的影响适用场景--det是否启用文本检测关闭后只能识别整图必须裁好单行你已经裁好文本行的场景--use-angle-cls是否启用方向分类关闭后旋转超过 90 度的图识别率剧降手机拍照、竖版文字不常用时--rec是否启用文本识别关闭后只输出文本框位置只需要版面分析、不要文本时--text-score识别置信度阈值调高时低质量图会被丢弃对准确率有硬要求的生产环境--limit-side-len检测输入图最长边数值高时小字更清晰耗时上升高分辨率扫描件det和rec同时默认开启是通用配置不要轻易关。真正值得调的是text-score和limit-side-len。默认置信度阈值一般在 0.5 左右这个值偏低导致大量模糊字的识别结果被保留下来。如果你做的录入工作对错误零容忍把阈值拉到 0.75 到 0.8识别结果里拿不准的字符就会直接变成空或低置信度内容宁可少识别也不能错识别。limit-side-len控制的是检测阶段输入图像的最长边缩放。默认值经常是 960 或 3200。做扫描件批处理时我习惯把它调到 2000 左右因为 2000 以上计算量膨胀太明显而 960 以下对 300 DPI 扫描件来说又太小字迹密集时容易出现漏行。4.2 把 CPU 性能吃满线程数、预处理宽度与并行CPU 模式下最让人着急的症状是“CPU 占用 100% 但识别速度只有每秒两张”。这往往不是 Umi-OCR 本身慢而是 PaddleOCR 内部使用了 OpenMP而你的 Python 或环境变量限制了线程池。这里有一个反直觉的坑你设置的环境变量越多可能越慢。# 公开的离线识别方案中一个常见的错误是给每个线程都设置大数 export OMP_NUM_THREADS16 export MKL_NUM_THREADS16 python cli.py -i ./data -o ./out这样做的结果是线程切换开销吃掉性能。更合理的做法是只设一个主线程数并且让它和你的物理核心数一致而不是逻辑线程数。我通常先在机器上查核数再决定设多少nproc --all # 例如物理核心数为 8则 export OMP_NUM_THREADS8 export MKL_NUM_THREADS1 python cli.py -i ./data -o ./outMKL_NUM_THREADS1的目的是让矩阵运算库别抢 OpenMP 的线程避免两个线程池自相残杀。这个组合在我的多台 Intel 机器上都能把识别速度提升 30% 到 50%。如果你用的是 AMD 机器把MKL_NUM_THREADS换掉改设OMP_NUM_THREADS一个变量就够了。做纯 CPU 识别时别指望 GPU 的加速效果能把线程池理顺、把 300 DPI 扫描件跑出每分钟 20 页左右就是不错的成绩。除了线程--rec-batch-num也值得注意。识别阶段可以把多行文本拼成一个 batch 送给模型默认值一般是 6 或 8调大到 16 时对 CPU 机器会增大单次计算的内存峰值但对含大量文本行的扫描件有明显加速效果。如果你的机器内存 16G 以上可以试试调大内存小的机器翻车概率很高不要冒险。4.3 用配置文件固化你的参数偏好每次在命令行把五个参数敲一遍既容易错又不可维护。Umi-OCR 的 CLI 一般支持读取配置文件常见做法是写一个自己的 yaml然后在每次运行时指定。配置文件的作用不只是省事更是让团队里其他人能稳定复现同一套识别设置。# umi_config.yaml input_dir: ./data/scan output_dir: ./out/ocr device: cpu model_dir: ./models limit_side_len: 2000 text_score: 0.75 use_angle_cls: true rec_batch_num: 8 output_format: json调用时指过去python cli.py --config umi_config.yaml配置文件的命名参数可能因版本不同略有差异但无论如何要点是“把识别当服务配置管理”而不是“当场敲命令试”。用配置文件把input_dir、output_dir、device拆到固定字段之后后续你用系统服务接管批量识别、用 cron 定时跑都会省很多事。5. Linux 上跑 Umi-OCR 的避坑清单从启动失败到截图失效5.1 启动即崩溃Qt 动态库缺失现象是执行 AppImage 或源码的python main.py后窗口还没弹出来就整个退出终端里没有明显报错或只有一句Segmentation fault。原因是 Linux 发行版对 Qt 的依赖比较分散AppImage 虽然自带 Qt但显卡驱动和系统库缺一不可。最常见的是libnss3和libxkbcommon缺失。解决先看两步第一步用ldd检查主程序的动态库依赖第二步对照结果安装。ldd的输出会列出所有“找不到”的库这是最快的排错手段。补完库之后若还是闪退检查 NVIDIA 显卡驱动是否正常nvidia-smi能输出就说明驱动没大问题剩下多半是 Wayland 兼容改回 Xorg 会话再试。5.2 识别结果全空白模型目录有个“不存在的空目录”现象是识别流程没有报错输出文件生成了但打开是空文件日志里只有一条类似ocr engine init failed的警告。原因特别容易误判模型目录存在但里面没有实际模型文件。Umi-OCR 的初始化逻辑对模型目录做了检查不会因为它空就抛异常而是悄悄跳过初始化。解决也简单把 Release 页面上的模型包下载完解压到models/目录后确认目录结构形如models/rec/xxx.pdmodel。只看目录名存在没用要看有没有以.pdmodel结尾的文件。5.3 Wayland 下截图识别失效剪贴板权限与截图协议现象是点击“截图识别”后区域选择是正常的但识别结果永远为空。原因是 Wayland 会话下应用访问全局剪贴板需要用户授权图形界面第一次请求时如果没有弹窗或你已经点过拒绝后续就再也不弹了。解决方式是到系统设置里重置剪贴板权限或者把会话临时切到 Xorg。还有一个相关场景是部分 Linux 桌面用wl-copy复制截图但 Umi-OCR 读取剪贴板时走的是 Qt 自己的接口两者对接不上。稳妥的做法是避免“剪贴板接力”把截图直接保存成临时文件再走 CLI 识别路径。5.4 CPU 跑满但识别速度慢OpenMP 线程池相互干扰现象是识别过程中top显示 CPU 满载但实际每秒只处理一两张图识别一张大图要好几秒。原因经常是环境变量里同时设置了OMP_NUM_THREADS和MKL_NUM_THREADS或者设置的数字超过了物理核心。解决的路径是先把环境变量清理干净只保留一个线程数并让它等于物理核心数。我见过最夸张的一次是把线程设到 32速度反而比默认值还慢。线程数这块没有“越多越好”稳定压倒一切。5.5 中文文件名乱码压缩包编码与 locale 问题现象是模型包解压后目录名全乱码Umi-OCR 找不到模型报model not found。原因是模型包是在特定系统里打包的文件名编码可能和你的 locale 不一致。解决方式是在解压时显式指定编码或者在解压后再用脚本重命名。Linux 下最省心的处理是装unzip解压命令加上-O gbk或-O utf8参数。如果你的发行版 unzip 不支持-O就用python3 -c import zipfile; zipfile.ZipFile(models.zip).extractall()直接解压Python 的解压逻辑一般能自动处理常见编码问题。6. 上生产前这样验证给场景造一组“失真样本”在把 Umi-OCR 真正交给业务用之前先做一次“验证准确率”的操作。不要拿一张清晰的截图测一下就自信上线而要做一组贴近真实业务的样本把它变成可重复的验证集。建立验证集时我一般会造三组第一组是清晰截图用来测识别引擎能否正常拿到 98% 以上的准确率第二组是模拟失真样本把图片做轻度模糊、压缩、曝光不足用来测你的参数阈值是否太激进第三组是真实样本比如你业务里的手机拍照、传真件、低分辨率扫描件。每组保持 10 张左右、统一放置之后每次调参都用同一组图跑一次避免用感觉调参。# 用 imagemagick 快速造失多样本 convert scan_001.png -blur 0x1.5 -quality 80 blur_001.jpg convert scan_001.png -brightness-contrast -20x15 dark_001.png计算准确率的脚本不需要太复杂拿原识别结果做字符级别比较。中文 OCR 的准确率建议用编辑距离衡量而不是简单相等判断因为漏两个字和错整行是完全不同量级的失误。简单比较后如果你发现失真样本的准确率从 95% 掉到 60%那说明生产场景里大量图片会被系统性误识别。此时先不要急着调算法先看是不是输入质量的原因很多扫描件没有做歪斜矫正方向分类也没开先开use_angle_cls再说。验证脚本跑完把当前这组参数和准确率结果写进一个固定文件比如benchmark_result.md。每次调参后更新这个文件你就能直观看到每次改动是正向还是负向的。这个动作看起来简单却是决定 Umi-OCR 能否承担生产任务的关键。我养成的习惯是每次更换模型或修改阈值后先用失真样本把上一版结果并列摆出来对比没有提升就不上线。这套“拿自己的图说话”的校验流程算是我在 Umi-OCR 上最值得的一笔投入希望帮到你。本文还有配套的精品资源点击获取