标题里这个工具说白了就是把我常用的开源OCR程序Umi-OCR用API方式跑在一台内网机器上前面套一个网页让整个办公室的人都能共享文档转换能力。这东西的起因其实特别朴素我们组里隔三差五就有“把这几页合同转成文字”“把扫描版的PDF导成可编辑文档”的活儿挨个拿本地软件去识别、复制、排版效率太低了。虽然Umi-OCR本身在个人电脑上用得挺顺手但不能要求每个同事都装一遍、都会用命令行。与其反复传文件不如直接在局域网里搭一个“多用户都能上传、自动识别、统一导出”的小工具谁要用谁打开网页就行。如果你也在纠结类似的问题——本地OCR工具挺好用但不知道怎么变成团队服务或者你在研究Umi-OCR的API到底怎么接、参数怎么传、并发能扛多少——那这篇就是写给你看的。下面是我从选型到落地、再到给同事试用的完整思路和踩坑记录代码不会很长但坑都是真踩过的。1. 为什么不做“每人装一个客户端”非要单独搭服务先说结论如果你的需求只是偶尔识别一两张图那直接在个人电脑上装Umi-OCR的图形版就够了折腾服务纯属浪费。但一旦到了“多人、批量、需要统一管理结果”这个层面单机版的短板就很明显了。1.1 单机版遇到的问题Umi-OCR本身是一个开源的OCR工具基于深度学习模型做文字检测和识别中文、英文、公式都能处理桌面版的实测准确率在常见印刷体场景下表现相当好。但它默认是“打开一个窗口选图片点识别”的交互模式这带来两个问题。第一识别能力被绑定在某一台电脑上。一个几十人的团队里只给一个人装Umi-OCR那他就是全组的“人肉中转站”文件传来传去识别完再传回去路径一乱就全乱套。第二结果不沉淀。今天识别了一份合同明天想搜一下“违约金”在哪个文件里单机版给你的是一段段txt既不集中也没法检索。时间一长文件散落在各个聊天记录和临时目录里等于白干。1.2 恰好Umi-OCR提供了API模式Umi-OCR的项目里其实带了一个独立的API服务可以把OCR能力封装成HTTP接口别的程序通过请求就能调用不需要打开图形界面。这个设计本来是为了方便二次开发但拿来部署成内网服务刚刚好。我在这一步做个简单的技术判断如果自己用PaddleOCR或者Tesseract重新封装不是不行但训练和调参成本太高。Umi-OCR的API模式等于把“识别模型、图像预处理、文字检测、结果格式化”这些脏活全都包好了我只需要关心HTTP请求怎么写、任务怎么调度。**能用现成的优质轮子就不要自己造。**尤其是OCR这种高度依赖模型效果和工程经验的领域自己从零搞一套效果大概率不如开源项目调好的方案。1.3 部署成服务带来的三个好处真正搭完跑起来之后我对比了一下和单机版的使用体验差别非常明显多用户并行每个人打开网页就能传文件任务在后端排队互不干扰。结果统一管理识别完的文本自动存到服务器的指定目录还能顺便生成可下载的txt、Markdown文件管理成本很低。维护集中模型升级、参数调整只动服务器上一份配置就行不用挨个帮同事更新客户端。所以最终方案定为在局域网的一台Windows/Linux机器上常驻运行Umi-OCR的API服务再写一个简单的Web后端做文件接收、任务分发、结果回传前端就是一张极简的上传页面。2. 整体架构核心链路到底是怎么走的这个工具本质上是一个“中转站”它本身不识别图片只负责把用户上传的文件转成Umi-OCR能识别的格式再把识别结果转回给用户。实际上分为四条链路。2.1 从浏览器到服务端的链路用户打开浏览器访问的是一个FastAPI或者Flask看你顺手服务。服务端负责接收上传文件、保存到临时目录、创建任务ID、把任务加入队列然后立即返回“任务已接收”。这一步用异步库处理避免大文件上传把请求卡死。前端不是实打实地一直等待识别结果而是通过轮询接口查询任务状态。识别一小张图可能就两三秒但识别一份几十页的PDF可能要几分钟用户不可能一直保持一个HTTP连接不关闭。所以整体请求流向是这样的浏览器上传PDF/图片 - Web服务FastAPI - 临时目录/任务队列 - 文档解析模块PDF渲染成PNG - Umi-OCR API服务端口默认1224 - 识别文本 - 结果写入结果目录 - 浏览器轮询任务状态完成后触发下载这一条链路上每一步都要有明确的职责和超时控制不然任何一个环节卡住都会导致整个任务僵在那里。2.2 文档转换的细节PDF要先变成图片这里有个重要的前提OCR识别的对象是“图片像素”不是“PDF文件”本身。Umi-OCR的API接口接收的是图片或者图片的base64编码而PDF是一种矢量/混合格式不能直接丢给OCR引擎。所以我的流程是如果用户上传的是PDF先调用PyMuPDFfitz把每一页渲染成PNG格式的图片再逐页调用OCR接口。渲染参数有一个关键值叫DPI。默认我用200-300 DPI太低的话小字会糊OCR准确率会明显下降太高的话图片尺寸过大传输和识别内存都会飙升识别速度也不成比例地变慢。实测下来300 DPI对绝大多数办公文档来说已经是性价比极优的选择。如果有朋友上传的是高清长截图那就不需要渲染直接走“接收图片→调OCR接口”的路径。这里我还做了一个分支判断先尝试用PyMuPDF直接提取PDF里的文本层如果能提取到说明这份PDF是文字版直接返回即可根本不需要OCR只有“提取不到任何文字”的PDF才进入OCR流程。这个前置判断能省掉大量不必要的计算。2.3 技术栈到底怎么选我当时后端用的是FastAPI因为这个框架处理文件上传、异步任务、JSON返回都很顺手而且自带接口文档局域网里别人调用时也方便。前端没有用框架就是一个单HTML页面里面写了上传组件、任务列表、轮询逻辑。这是刻意为之——工具面向的是部门内部不需要复杂的构建工程越简单越不容易坏。另外为了配合Umi-OCR API的调用后端还要配一个HTTP客户端库我用的是httpx因为它同时支持同步和异步对超时控制也更细致。数据库方面初期没有上MySQL直接用了SQLite存任务ID、用户标识、文件路径、状态、结果路径这几张表对内网几十人的使用量完全够。3. 核心实现Umi-OCR API调用时的工程化细节这一章是技术含量最高的一部分也是网上资料最少的部分。官方文档里给的示例大多是“打开API发一张图返回一句话”但真正拿到生产环境里用还差着好几层包装。3.1 如何启动Umi-OCR的API服务Umi-OCR安装包里通常会自带一个专门的服务端启动程序找类似umi-ocr_server的入口双击启动后它会默认监听127.0.0.1的某个端口常见是1224# 以Windows服务方式举例 umi-ocr_server.exe如果是在Linux服务器上跑也可以用命令行方式启动然后让它常驻后台。启动成功后它其实就是一个小型HTTP服务我们可以用浏览器访问它的根路径确认状态。注意Umi-OCR的版本迭代比较活跃不同版本的服务端接口路径和字段名可能有变化。你在本地部署时先用浏览器打开API地址查看它提供的接口说明页面确认当前版本的请求字段再写代码千万别直接照抄旧文档。3.2 单张图片识别的最简调用假设API接收的是base64编码的图片数据那么最直接的请求是这样的import base64 import httpx def ocr_image_bytes(image_bytes: bytes, api_url: str http://127.0.0.1:1224/api/ocr) - str: b64 base64.b64encode(image_bytes).decode(utf-8) payload { base64: b64, options: {} } # 这里的超时是个关键长图识别可能超过10秒 resp httpx.post(api_url, jsonpayload, timeout60) resp.raise_for_status() data resp.json() # 返回结构里通常包含data字段存的是识别出的文本 return data.get(data, )这个代码里有两处是经验值尤其值得新人注意第一个是timeout60。很多第一次写的人会默认用requests的默认超时也就是不设超时结果是服务端一旦识别慢前端请求就挂着占线程任务一多整个Web服务都被拖死。我后来统一把超时调成60秒并且做了一个简单的重试机制超时或者返回空文本时最多重试一次因为OCR偶尔会因为内存或模型推理的偶发问题返回空结果。第二个是串行限制。Umi-OCR的API服务虽然可以接收并发请求但它的识别引擎处理图片是消耗CPU和内存的并发太猛会直接把内存打满。在初期测试时我试着同时提交10张图片结果服务直接假死了。所以后端里我加了一个全局的信号量Semaphore限制同一时间最多只有1个或者按服务器CPU核数放宽到2个OCR请求在跑其他任务老老实实在队列里排队。核心观点Umi-OCR API本身不难调难点在于“并发控制”。多用户场景下你必须把“并发请求”降级成“队列请求”识别正确率才会稳定。3.3 多页PDF逐页识别与结果拼装PDF渲染之后会产生多张PNG图片我的处理逻辑是逐页调用上面的ocr_image_bytes函数然后把每一页的文本拼在一起中间用分页符隔开方便用户在导出文本时看清楚“第几页内容结束第几页内容开始”。这个做法看起来没什么技术含量但省掉了传统导出时“一页一个txt文件”的麻烦。用户拿到的是一个完整度很高的纯文本文件或者Markdown文件后续直接交给别的大模型做摘要、关键词抽取都行。同时我还把每一页的“平均识别置信度”打印到日志里。Umi-OCR的返回对象里如果带了置信度字段就顺手取出来如果整页置信度偏低就给前端任务加一个“低置信度”标识让用户自己决定要不要人工校对。这一点是我后面被同事抱怨“识别出来有错字”之后加上的——OCR工具不可能100%准确与其让用户默默接受错字不如主动提示可信度至少让用户心里有数。3.4 图片预处理和后处理在实际调用中我发现有些图片识别效果不好并不是引擎不行而是图像本身没做好预处理。以下两个场景是最高频的手机拍照的文档倾斜严重Umi-OCR虽然内置了方向检测和校正但有时还是会误判。我这边做了一个简单策略用OpenCV先做一次边缘检测计算文档主体轮廓的角度超过阈值就做透视校正再送识别。效果提升非常明显。文字颜色浅或者背景有底纹直接转灰度化再用自适应阈值处理能极大减少背景干扰。预处理这块我控制得比较克制只做了校正和灰度化没有用太重的滤波因为过度处理反而会让笔画断裂降低准确率。工程上什么都要克制不要一上来就叠滤镜。4. 多用户任务队列与并发控制核心难点是怎么不“打架”既然是给局域网内多用户用的工具就不能只关心“识别的准不准”还要关心“同时10个人用会不会崩”。这一章的标题已经说明了并发控制才是这个工具最需要花心思的地方。4.1 任务状态与数据库设计我为每一个上传的任务创建了一条记录字段大概是字段类型说明task_id字符串唯一任务ID用uuid生成user_id字符串用户名或IP标识用于隔离目录file_name字符串原始文件名status字符串pending / processing / done / failedresult_path字符串识别结果文件路径created_at时间戳任务创建时间progress整数识别进度用于前端展示SQLite存这些完全够用。之所以没用内存结构全存是因为担心进程重启导致任务状态丢失用户看不到历史记录会觉得莫名其妙。前端每2秒轮询一次/api/task/status/{task_id}接口拿到progress和status后更新页面上的任务卡片。任务结束之后按钮从“识别中”变成“下载结果”。4.2 临时目录按用户隔离这里有个安全细节容易被忽略如果所有用户的上传文件都放在同一个目录下文件名一旦相同就会互相覆盖。我用的方案是uploads/{user_id}/{task_id}/原始文件.pdf results/{user_id}/{task_id}/识别结果.txtuser_id直接用登录时的用户名或内网IP前两段生成目录结构天然隔离不仅避免了覆盖问题还方便定期清理老任务——超过一周的目录直接按创建时间删除。清理脚本我写成了一个后台定时任务每天晚上把7天前的临时文件全部删掉。这个清理必须做否则服务器的磁盘很快会被几十页的高清PNG塞满。4.3 全局并发限制OCR识别是CPU密集型的活儿那台内网机器再强也经不住无限制的并发。我给OCR调用加了锁import asyncio ocr_semaphore asyncio.Semaphore(2) async def ocr_with_limit(render_image): async with ocr_semaphore: return await asyncio.to_thread(ocr_image_bytes, render_image)设置Semaphore2是因为那台服务器有4核CPU留出两个核给Web服务和系统调度。如果你跑在Windows办公电脑上建议设成1因为Windows的进程调度和内存控制都不如Linux那么从容。这个数值可以在配置项里改不写死。4.4 前端轮询策略前端我用一个极简的setInterval去轮询。需要注意的一个坑是任务处理完如果用户还开着页面一定要让轮询停下来否则会一直对服务器发起无效请求function checkTaskStatus(taskId) { const timer setInterval(async () { const res await fetch(/api/task/status/${taskId}); const data await res.json(); if (data.status done || data.status failed) { clearInterval(timer); renderResult(data); } else { updateProgress(data.progress); } }, 2000); }2秒一个请求几十个人同时用对服务器的压力非常小完全够用。5. 实测中踩过的那些坑从中文乱码到PDF页面丢失这一章全是实打实的教训。有些问题排查了一天最后发现只是一个编码没处理对。我不把它们列全挑几个最典型的说。5.1 中文文件名的编码问题当一个用户上传“第1季度报-扫描版.pdf”时FastAPI的UploadFile.filename在Windows浏览器下通常是UTF-8编码的但在某些国产浏览器或者老旧的HTTP代理环境下后端拿到的文件名会出现乱码最常见的就是“锟斤拷”。解决方法是明确后端和前端的字符编码一致前端在FormData提交时不需要特殊处理后端在保存文件时强制转成UTF-8并且不直接用原始文件名落盘而是用task_id 扩展名的方式来命名文件。原始文件名只存进数据库字段用于展示。# 不要这样做 file_path os.path.join(task_dir, upload_file.filename) # 应该这样做 ext os.path.splitext(upload_file.filename)[-1] file_path os.path.join(task_dir, f{task_id}{ext})这个坑主要坑在“直接从浏览器调试时正常一用内网部署的反向代理就乱”排序下来优先级很高。5.2 图片过大导致API返回空结果Umi-OCR识别很清晰但如果你把一张5000x10000像素的长截图直接塞过去它可能会默默返回空文本而不是报错。这个问题非常坑因为它表现为“识别完成但结果为空”没有异常日志。我当时的解决思路是在调用OCR接口之前先检查图片的像素尺寸。如果单边超过2000像素就先等比缩小到2000以内然后再送识别。或者更稳妥的把长图从上到下切成若干块逐块识别最后拼接。切分方案对合同、聊天记录这类长截图效果极好。这个方法顺带提升了整体准确率因为Umi-OCR对“单张图片里文字密度太高”的情况偶尔会漏检切成块之后反而更稳。5.3 把“文字版PDF”也送去OCR白白浪费时间扫描版PDF识别很慢但有些用户上传的其实是“由Word保存而成的PDF”这种PDF里本身就带文本层根本不需要OCR。刚开始没做判断一份50页的文字版PDF送去逐页渲染识别足足跑了十几分钟用户还以为工具坏了。后来在渲染之前增加了一个文本提取尝试import fitz doc fitz.open(pdf_path) full_text for page in doc: full_text page.get_text() if full_text.strip(): break只要某一页能提取到非空文本就判定为文字版PDF直接跳过OCR流程速度从十几分钟降到几秒钟。这个优化带来的体验提升是巨大的也让我意识到一个好工具不仅是“能干活”还得“聪明地干活”。5.4 OCR服务与Web服务的端口暴露问题Umi-OCR的API服务默认监听的是127.0.0.1也就是只有本机能访问这是安全的。但如果你在启动时不小心让它绑定了0.0.0.0那局域网内任何一个人都能绕过你的Web页面直接调用它虽然不致命但也不好。我在部署时把Umi-OCR的API服务保持只监听127.0.0.1Web服务监听0.0.0.0:8080所有流量都先到Web服务再由Web服务转发给本机的OCR API。这样既保证了安全又让外部访问统一不暴露多余端口。6. 部署到局域网真正让同事用起来的最后一步代码写完、本地测试通过之后离“能用”还差一步这一步叫部署。我把这个工具跑在实验室一台常开的办公电脑上做了三件关键的事。6.1 用systemd/开机自启服务管理进程Linux服务器上我用systemd维护两个服务一个是Umi-OCR的API服务另一个是FastAPI的Web服务。写两个独立的service文件就可以启动顺序上让Web服务依赖OCR服务# 大致思想 systemctl enable umi-ocr-api systemctl enable doc-converter-web如果是Windows机器可以用计划任务或者nssm把程序注册成Windows服务实现开机自启免登录自启。这一步不做好同事周末加班要用时发现电脑被重启过、服务没起来就很头疼。6.2 反向代理与前端访问我在Web服务前面挂了一层Nginx做反向代理端口统一收敛到8080。同事访问时只要在浏览器里输入http://内网IP:8080就行不用记一串带端口号的诡异地址。Nginx的配置里额外加大了一点上传体积限制client_max_body_size 200m;不加大这个值的话一个100MB的高清扫描件会被Nginx直接拒收。6.3 用户边界与访问控制因为是内网工具我没有做复杂的登录体系但也不能完全裸奔。我直接用内网IP的前两段生成user_id做隔离。如果后续要接入公司统一的账号体系只需要替换成从请求头里读取用户名即可改动成本很低。这里有必要提醒一句这个工具只适用于可信内网不要图省事把端口映射到公网。OCR服务一旦暴露在公网任何人都能上传任意文件那你的内网机器就成了别人的免费扫描器还可能被恶意灌入超大文件把磁盘塞满。安全边界一定要守住。7. 可扩展方向别让工具停留在“能用”就结束这个工具上线跑了半个多月组里反馈很好但我自己知道它还能做得更多。有些是顺手能做的有些是下一步可以想的。7.1 批量压缩包处理目前每次只允许上传单个文件但实际场景里经常有人一次发来一个压缩包里面有二十份扫描文件。下一步可以支持zip上传解压后自动批量走队列生成结果时也打包成zip返回。这个功能在代码上不复杂只是把“单文件任务”改成“目录任务”就行。7.2 对接全文搜索让识别结果变成“可检索资产”识别出来的文字如果只停留在txt里价值就打折了。我现在正在做的是把结果文本同步到一份SQLite全文搜索引擎里这样以后组里想查“哪份合同里出现过指定条款”直接在搜索框里输入一句话就能定位到具体文件识别结果才真正变成了数字资产。如果你有更高阶的需求接Elasticsearch也行但内网这个量级没必要。7.3 和AI总结能力联动现在识别出的文本大多是长段落阅读成本还是偏高。下一步的计划是把识别整段文本送到本地或云端的大模型API做一个结构化摘要直接生成“关键条款”“金额”“日期”这些结构化字段。这样用户上传一份合同扫描件拿到的就不只是文字版而是可直接录入系统的条目工具也从“转换器”升级成了“信息抽取器”。我个人建议你如果时间有限优先做“压缩包批量全文搜索”这两个因为它们对日常效率的提升是肉眼可见的。识别完生成结构化摘要这个方向挺诱人但要做好准确率评估不要一上来就全量铺开。最后分享一个我在实际运行中特别受用的心得别把OCR当成一个一次性的功能它更适合作为整个文档处理链路的一个前置步骤。只要把识别这步做到稳定、可控再往后面接搜索、接摘要、接自动化分发都会顺畅得多。这个工具我后续还会迭代核心思路就是扩大“它能自动完成的事情占比”让同事打开网页、上传、下载三个动作甚至三个动作缩成一个。
