我桌上常年堆着四类“看得见但拷不走”的东西：白板拍下来的方案草图、扫描仪吐出来的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(rows=block["rows"], cols=block["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 也存一份到单独的目录。这样复核的时候，发现哪份文档有问题，直接搜文件名就能把原图、中间结构、输出三样东西同时调出来对照，定位效率比翻目录找高得多。这套流程我用了大半年，返工的时候基本不用凭记忆猜是哪一步出的错。
