DocLens开源OCR：扫描件转可编辑docx的版面还原与批量实践

我桌上常年堆着四类“看得见但拷不走”的东西白板拍下来的方案草图、扫描仪吐出来的PDF、对方发过来的合同截图、以及一批早年翻拍的纸质资料。想把里面某句话抠出来改两个数字多数人的做法是丢进某个在线转换页等半分钟下载一个Word然后发现段落全挤成一坨、表格变成一串散字、页眉页脚跑进正文中间。DocLens 这类开源扫描工具就是冲着这个场景来的图片扔进去本地跑完吐出一份能直接改字、改段落、改表格的 docx整个过程不联网。它做的事情并不神秘本质是把“图片里的文字”翻译成“带版面结构的文档对象”。但真要把它用得顺手得先搞清楚这条链路上哪一环最容易断、断了之后症状长什么样、以及怎么用最低的成本把它接回去。这篇东西写给三类人看手上有一批纸质材料要批量转成可编辑文档的、材料内容不方便外发的、以及想自己改代码调参数的。哪怕你完全不懂OCR看完也能判断一个转换结果到底“能用”还是“看着像能用”。1. 从一张照片到一份能改字的Word中间卡着五道关1.1 “看得见”和“拿得到”是两码事人眼看一张合同照片一眼就知道标题在中间、甲方乙方分两栏、落款在右下角、中间那个红章盖在签字上。机器看到的是一张矩阵每个格子是一个0到255之间的数它不知道什么叫标题也不知道哪块区域是表格。所谓识别其实是让模型在这片像素里先框出一堆矩形再逐个矩形猜里面是什么字。这两个动作是分开的而且失败的样子完全不同。框错了字认得再准也是白搭框对了但认错字至少位置还在还能靠上下文猜。很多人把OCR等同于“认字”实际上在文档场景里“框”的难度往往更高——尤其当图片拍歪了、有阴影、纸张有折痕、或者背景是带格子的稿纸时。1.2 五道工序各自负责什么失败时是什么症状把整个流程摊开从一张图到一份 docx中间固定有五道工序。理解这五步的分工是后面所有排查工作的基础因为每一个“结果不对”的抱怨最终都能定位到其中某一步。工序核心任务失败时的典型症状预处理纠偏、去噪、灰度化、缩放、裁掉无关边框整页文字歪斜、细笔画断裂、小字糊成一团文本检测在图上框出所有文字区域漏框某段话整个消失、误框把表格线当文字文本识别逐个区域输出字符序列和置信度形近字错、标点丢、竖排读成横排版面分析判断哪几块是一段、哪几块是表格、阅读顺序两栏被串成一行、表格被拉平成散句文档生成按结构写出 docx 的段落、表格、字号、间距全是空行、字体错乱、行距诡异、内容跑到页外五步里前四步决定“内容对不对”第五步决定“能不能直接用”。大部分一键工具在前四步做得还行栽在第五步——它们把识别结果按从上到下、从左到右拼成一个长字符串直接塞进文档。字是全的但你得自己重新分段、重新画表格改一份两页的合同可能要花二十分钟排版那这个工具的价值就没了。1.3 真正拉开差距的是第五步我试过好几个转换工具识别出来的文本内容差异其实没有想象中大同一张清晰扫描件A工具和B工具的错字数量差距通常在个位数。但输出文档的可用性差得非常远有的会把标题单独成段并加粗有的把所有内容塞进一个段落有的能还原三线表有的把表格拆成十几行散句还夹着一堆竖线符号。这也是 DocLens 这类工具值得单独拿出来讲的原因。它把“版面还原”当成一等公民识别完不是急着拼字符串而是先落一份带坐标的中间结构再根据坐标聚类出行、段、栏、表格最后按这个结构去写文档。多花这一层换来的是改字的时候不用重排。提示判断一个转换工具是不是真的做了版面分析有个很土但很准的办法——拿一张两栏排版的说明书去转。如果输出里左右两栏的文字交替出现、一句话被拆成两半那它基本没做版面如果输出顺序是先读完左栏再读右栏说明它至少做了栏检测。2. 识别率报95%却不能用文档转换的评价标准是版面2.1 字符准确率这个数字统计口径本身就有水分几乎所有工具都会标一个识别准确率动辄98%、99%。这个数字通常是在标准测试集上按字符级算出来的公式很朴素正确字符数除以总字符数。问题在于它把每个字符的权重看成一样的而实际使用中字符的价值完全不一样。一份采购合同里“人民币壹拾贰万元整”中的“壹”和“拾”如果认错整个金额就废了但页脚的一串页码认错你根本不会在意。一份技术文档里专有名词、型号、参数单位错一个字符可能就导致下游全部返工。字符准确率看不出这种差别。我自己的做法是不看厂家给的数字直接从自己的业务材料里抽一百张图覆盖打印件、扫描件、手机拍照、屏幕截图四种来源人工标一遍然后算两个指标整体字符错误率以及“关键字段错误率”——后者只统计数字、型号、金额、日期、人名这类不允许出错的片段。两个数字经常差出一大截后者才是你真正要关心的。2.2 字全对但版面错等于交了一份废稿有个特别典型的场景两栏排版的说明文档。检测和识别都没问题字一个不错。但如果没有栏检测程序按 y 坐标排序就会把左栏第一行和右栏第一行拼在一起读出来是“产品规格 注意事项 尺寸120×80mm 请勿倒置放置”。单看每个字都对连起来完全没法读。表格更明显。一张五列八行的参数表如果没做表格结构识别输出会变成四十个独立的段落你还得自己数着格子往回填。这时候“识别率99%”这个宣传语一点意义都没有因为你花在重建结构上的时间比重新手打一遍还长。注意验收转换结果时第一眼不要看字对不对先看段落数和表格数。段落数明显偏少说明合并过度表格数量为0而原图明明有表说明表格结构没识别出来。这两个指标比错字率更早暴露问题。2.3 一份我自己在用的验收清单转完之后我会按下面这几条快速过一遍基本两分钟能判断这份输出是“能用”还是“得重来”段落数对比原图目测有几个自然段输出是不是差不多。差太多就是行合并逻辑有问题。首行缩进与行距能看出段落边界说明写文档那一步有样式处理不是纯文本堆砌。表格还原度行列数对不对合并单元格有没有被拆散。阅读顺序随便挑一段中间的内容读一遍看有没有跨栏串行。特殊元素页眉页脚有没有被当成正文、页码有没有混进来、图片里的水印文字有没有被识别成正文。字体与字号标题是不是比正文大正文是不是统一字体。这一条不影响内容但直接影响你要不要重排。这六条里前四条不过关这份输出基本等于没用后两条不过关还能忍手动调一下样式就行。3. 引擎怎么挑把“准不准”拆成五个能测的维度3.1 五个维度每个都能自己测出来选识别引擎的时候最没用的信息就是别人嘴里的“这个准”。准不准取决于你的材料长什么样。我把选型拆成五个可测维度每个维度都能用你自己的样本在半天之内测出来印刷体中文准确率这是基本盘用你业务里最常见的文档类型测别用新闻截图。形近字与数字鲁棒性重点看 0/O、1/l/I、己/已/巳、未/末、拔/拨这几组以及带小数点的金额。单页耗时统一在单核、1080p 输入下测从解码到出结果别信“毫秒级”这种说法。模型体积与内存峰值这个直接决定你能在一台机器上并行跑几个任务。依赖复杂度要不要额外运行时、要不要显卡、装完占多大空间。这一条在容器化部署时特别要命。把这五项列成表每项给你的候选引擎打个分比看任何评测榜单都靠谱。因为你的材料分布和公开测试集大概率不一样公开榜单测的是通用场景你关心的是你那堆扫描件。3.2 轻量模型和高精度模型选哪个取决于你的瓶颈在哪社区里常见的识别引擎大致分两档一档是模型只有几十兆、CPU 上每秒能跑好几页的轻量方案另一档是模型几百兆、需要更多算力但复杂版面和低质量图片上明显更稳的高精度方案。它们不是替代关系是分工关系。场景特征建议方向理由批量处理清晰扫描件追求吞吐轻量方案清晰件上两者差距很小速度差好几倍手机随手拍、有阴影和倾斜高精度方案检测环节更稳漏框少表格、多栏、公式密集高精度方案 版面模块单靠识别引擎解决不了结构问题嵌入式或低配机器轻量方案内存和算力是硬约束混合材料一次性处理双引擎轻量先跑低置信度的页面转高精度重跑最后这条“双引擎”是我自己用得最多的策略先用快的跑一遍把平均置信度低于阈值的页面挑出来只用慢的重跑那一小部分。实测下来总耗时比全程用高精度方案少一半以上最终质量却接近全程高精度。3.3 语言包、竖排和生僻字是三个容易忽略的暗坑语言包这件事很多人以为装个中文包就完事了。实际上中文场景里至少有三类字符要单独确认全角标点、生僻字、以及中英混排时的空格处理。全角标点识别成半角会导致后续所有文本处理逻辑出错生僻字尤其是人名、地名里的如果不在字符集里会被强行替换成形近的常用字这种错误人工校对时极难发现。竖排文本是另一个坑。传统排版的书刊、部分票据都是竖排识别引擎如果只按横排切行会把一整列读成一行乱码。判断方法很简单拿一张竖排的图去试输出如果是横向的一长串那就是没做竖排支持。生僻字这块我的建议是如果你的材料里确实有大量人名地名宁可牺牲一点速度也要选字符集大的方案或者在后处理里加一步“可疑字标记”——把置信度低于某个值的字单独标红输出到一份校对清单里让人工只盯这几个字效率比通读全文高得多。4. 从像素到docx的实现骨架4.1 模块怎么切决定了你后期改起来有多痛苦这类工具最容易写成一个两千行的巨型脚本读图、识别、拼字符串、写文档全塞在一个函数里。跑通很快改起来要命。我建议一开始就按工序切模块哪怕每个模块只有几十行doclens/ io/ # 图片读取、格式转换、DPI 记录 preprocess/ # 纠偏、去噪、缩放 engine/ # 识别引擎的适配层统一接口 layout/ # 行聚类、段落合并、栏检测、表格重建 writer/ # docx 写入 pipeline.py # 串流程只负责调度重点是engine/这一层要做成适配器对外只暴露detect(image)和recognize(image, box)两个方法内部换任何引擎都不影响上下游。我最早没做这层抽象后来想换引擎做对比测试改了整整一个下午全是散落在各处的调用。4.2 先把中间结构落成 JSON再考虑写文档这是我认为整个设计里最关键的一条识别结果不要直接往 docx 里写先落一份带坐标的中间结构。好处有三个出问题时能直接看 JSON 定位是哪一步错了写文档那一步可以反复调样式而不用重跑识别批量处理时可以先把所有图的 JSON 跑完再统一生成文档。中间结构大概长这样{ page: {width: 2480, height: 3508, dpi: 300}, blocks: [ { type: paragraph, bbox: [220, 310, 2260, 420], lines: [ {text: 第一条 本合同自双方签字之日起生效。, score: 0.961} ] }, { type: table, bbox: [220, 460, 2260, 980], rows: 4, cols: 5, cells: [{r: 0, c: 0, text: 序号, score: 0.98}] } ] }有了这层你会发现很多问题根本不用改识别改 layout 就行。比如某段话被拆成两段去看看它两行的 y 间距是不是比阈值大了一点点调阈值就解决了完全不用碰引擎。4.3 串流程的骨架代码流程本身不复杂复杂的是每一步的容错。下面这段骨架把关键节点标出来了def image_to_docx(img_path, out_path, engine, cfg): page load_image(img_path) # 统一 RGB记录原始 DPI page preprocess(page, cfg) # 纠偏、去噪缩放要同步改坐标 boxes engine.detect(page) # [(x0, y0, x1, y1), ...] items [] for box in boxes: text, score engine.recognize(page, box) if score cfg[min_score]: continue # 低置信度先丢掉后面单独处理 items.append({box: box, text: text, score: score}) layout build_layout(items, page.size) # 行聚类 - 段合并 - 栏/表判定 dump_json(layout, out_path .json) # 一定要落盘 write_docx(layout, out_path, cfg) return layout写文档那一步核心是把结构映射成文档对象。不同 docx 写入库的 API 大同小异无非是加段落、设字体字号、加表格、填单元格def write_docx(layout, out_path, cfg): doc new_document() # 换成你惯用的 docx 写入库 for block in layout[blocks]: if block[type] paragraph: p doc.add_paragraph(block[lines][0][text]) set_font(p, cfg[font], cfg[size]) set_line_spacing(p, cfg[line_spacing]) elif block[type] table: t doc.add_table(rowsblock[rows], colsblock[cols]) for cell in block[cells]: t.cell(cell[r], cell[c]).text cell[text] doc.save(out_path)这里有个细节值得单独说preprocess里如果做了缩放坐标必须同步换算回去否则后面写文档时算出来的行距、段距全是错的。我第一次就栽在这图缩到一半大小做识别坐标没还原结果所有段落都被判成“页外元素”过滤掉了输出一份空文档。这个坑下面还会细说。提示min_score这个阈值不要设太高。设成 0.9 会把大量正常的低质量扫描件整段丢掉宁可先全部保留最后用统计指标筛出问题页面人工复核。5. 六种典型翻车形态与一次“输出全是空行”的排查链路5.1 多栏排版与页眉页脚是最常见的两个串行源多栏的问题前面提过根因是阅读顺序判定。判断逻辑通常是先按 x 坐标把文字块聚成几簇如果簇之间有明显的空白间隔比如超过页面宽度的5%就认为是多栏然后先读第一栏从上到下再读第二栏。这个逻辑在标准双栏论文上很好用遇到不规则排版比如左边一栏宽右边一栏窄或者中间插了一张跨栏大图就会失效。页眉页脚是另一个高频问题。它们的特征是位置固定、重复出现、字号偏小。如果程序把它们当正文处理你会发现每一页的开头都有一行无关的公司名或文件名。处理办法一般是按 y 坐标做区域排除页面上方5%和下方5%的内容单独归到页眉页脚区不进正文块。但这招遇到“首页没有页眉”或者“表格顶到页边”的文档会误伤需要加一条判断只有在页面中重复出现的文本才判定为页眉页脚。5.2 表格线丢失和合并单元格是两个不同层面的问题扫描件里的表格线经常是断的、淡的甚至根本没有竖线只有横线。检测环节如果只靠线条找表格遇到三线表基本全废。现在常见做法是双路判断一路找线条一路找文字块的空间对齐关系——如果一堆文字块的左右边界呈现明显的列对齐即使没有线也判定为表格。合并单元格是更麻烦的。识别出来的信息只有“哪个格子有字”没有“哪几个格子是同一个”。重建逻辑通常靠空白格推断如果某一行中间出现连续空单元格且上一行对应位置有跨列内容就尝试合并。这个推断错误率不低实际使用中我建议表格这块不要追求全自动输出时保留一份表格的 JSON 结构人工在 docx 里快速修一下合并关系比调算法划算。5.3 印章、水印、手写批注和竖排各有各的处理方式红章盖在文字上是文档转换里最讨厌的情况之一。印章的颜色和文字不同但识别引擎通常会把彩色图转灰度红章就变成了一块深色斑块压住的字直接消失或变成乱码。处理方式有两种一是在预处理阶段做颜色通道分离把红色通道单独提出来做掩膜把印章区域标出来但保留底层文字二是接受部分文字丢失把印章区域单独作为一个“图片块”嵌入文档。水印的情况类似但更简单因为水印通常是浅色的、大面积重复的用阈值过滤掉浅色像素基本能解决。手写批注则要看需求——如果手写内容重要得单独走手写识别模型通用印刷体引擎对手写的识别率基本不能看。5.4 一次“输出全是空行”的完整排查记录说个真实的排查过程这个坑我印象很深因为它完美演示了“问题现象和根因隔了三层”是什么感觉。现象一批扫面件转出来的 docx打开一看几乎全是空段落偶尔零星出现几个字还都挤在文档最末尾。第一层怀疑编码问题。很多人第一反应是中文编码出错导致文字丢失。我打开中间 JSON 看了一眼text字段里的中文完好无损所以不是编码问题排除。第二层怀疑写文档那一步。我把 JSON 直接喂给write_docx跳过识别结果还是一堆空行。说明问题出在 layout 或 writer跟引擎无关。第三层看坐标。打印出每个 block 的 bbox发现所有 y 坐标都远大于页面高度——比如页面高度记的是 1754某个 block 的 y 是 3400 多。原因找到了预处理阶段把图片缩放了 0.5 倍识别是在缩放后的图上做的坐标自然是缩放后的但page.size记录的是缩放前的尺寸。后面做行聚类时用“y 是否超出页面高度”来过滤页外元素于是全部被判定成页外只剩边缘几个坐标偏小的块活了下来。修复三处改动。一是预处理返回缩放比例坐标统一换算回原图坐标系二是行聚类不再用“是否超出页面”做过滤改成用“是否超出页面高度 1.2 倍”这种宽松阈值超出的记为异常但不丢弃三是加了一条断言——如果过滤掉的元素超过总数的 20%直接抛异常中断别让坏结果写进文档。回归验证把之前那批图重跑一遍段落数从 3 涨到正常的 60 多问题解决。同时这条断言在后来的批量任务里还救过我两次都是别的坐标问题导致的批量丢失。这个案例的经验是中间结构一定要落盘而且一定要带上坐标系信息。如果当时没有 JSON我得从头加日志重跑排查时间至少多三倍。6. 批量一千份并发、内存与自动质检6.1 并发不是开得越多越好先算清内存账单张转换跑通之后下一步一定是批量。最直观的做法是开进程池worker 数设成 CPU 核数。但识别引擎的模型是常驻内存的每个 worker 进程都要加载一份。假设模型加载后占 800MB机器 32GB 内存开 16 个进程就是 12.8GB看起来还行但加上图像解码、中间结构、docx 对象峰值很容易顶到 20GB 以上再跑一会儿就开始用交换分区速度断崖式下跌。正确顺序是先在单进程下测一张大图的峰值内存用系统监控看 RSS 峰值不要看平均值再乘以你计划的 worker 数留出 30% 余量反推最大并发数。我的经验是识别类任务的 worker 数设成核数的六到七成比设满更稳因为瓶颈往往在内存带宽而不是 CPU。另外模型初始化一定要放在 worker 启动时做一次不要每张图初始化一次。这个错误非常常见写起来很自然但性能损失是数量级的——初始化模型可能要两秒识别一张图只要半秒等于四分之三的时间在加载。6.2 内存持续增长通常来自三个地方批量跑几百张之后如果发现内存曲线一路上扬不回落基本可以从这三个方向找图像对象没释放预处理生成了中间图灰度图、二值图、纠偏后的图用完之后没置空。Python 里虽然靠引用计数回收但如果中间对象被塞进了某个全局列表或者日志里就一直不会被回收。引擎内部缓存累积有些识别引擎在处理时会缓存特征图或者批处理队列如果不显式清空长时间运行会持续吃内存。解决办法是每处理 N 张图重启一次 worker或者主动调用清理接口。日志和异常堆栈堆积批量任务里异常很多如果把每张图的完整堆栈都存进内存列表里最后统一写日志几千张图下来能吃掉好几个G。日志要边跑边写异常只记录关键字段。我自己的做法是给 worker 加一个计数器处理满 200 张就主动退出由进程池重新拉起。这种做法看起来土但比调内存泄漏稳得多代价只是每 200 张多花两秒加载模型。6.3 用几个统计指标自动筛出“看起来成功其实失败”的结果批量处理最怕的不是报错是静默失败——任务返回成功文件也生成了打开一看是空的或者乱码。等一千份跑完再发现返工成本极高。我的办法是在 pipeline 末尾加一层自动质检算几个简单指标超阈值就标记为可疑单独放进一个目录等人看指标计算方式异常阈值参考文字密度总字符数 / 页面面积低于 0.0005 视为偏空平均置信度所有块的 score 均值低于 0.75 重点复核空段落占比空块数 / 总块数高于 0.3 说明结构有问题乱码字符占比非常用字符数 / 总字符数高于 0.05 直接判废单页耗时处理时间超过均值三倍可能卡住了这套指标不精细但足够把 90% 的坏结果筛出来。剩下 10% 漏网的靠人工抽查——我的习惯是每批随机抽 20 份看抽到问题的批次全量复核。注意文字密度这个指标要按文档类型分别设阈值。一页满是字的合同和一页只有落款的签字页密度差几十倍用同一个阈值会误伤。最后分享一个我自己摸索出来的小技巧批量转换时把原始图片和输出的 docx 用同一个文件名命名同时把中间 JSON 也存一份到单独的目录。这样复核的时候发现哪份文档有问题直接搜文件名就能把原图、中间结构、输出三样东西同时调出来对照定位效率比翻目录找高得多。这套流程我用了大半年返工的时候基本不用凭记忆猜是哪一步出的错。