简介这份面向OCR入门与文档数字化实践的下载包围绕图片文字转机器编码文字这一核心需求提供可参考的代码样例与示例素材适合刚开始接触光学字符识别、希望快速跑通识别流程的开发者与学生。压缩包共3个文件以2个Python脚本和1个JPG示例图片为主整体约2.03MB脚本便于了解识别调用、结果输出与基础处理思路示例图片可用于验证票据类文档的识别效果包体轻量便于在本地环境中复现和按需修改。已有192人学习或下载说明其在OCR基础实践场景中具备一定参考价值。读者可从中获得一份结构简洁的OCR练习素材用于理解图像输入、文字提取和结果呈现之间的对应关系也可作为课程作业、原型验证或二次开发的起点进一步结合Tesseract等开源工具或在线服务扩展识别能力。1. 从一摞扫描件说起这套文档 OCR 工具到底解决哪类活某公司档案整理小组去年接了个活把三百多份扫描件里的事项编号、金额、落款日期录进系统。他们先直接调开源 OCR 命令行两百页十几分钟就跑完了可导出的文本是一大坨——编号跑到金额后面跨栏段落首尾相接最后两个人对着原图核了两周。OCR 在现代文档处理里应用面确实广但“识别出来”和“能用”之间隔着一层没人写进文档的东西版面顺序、置信度过滤、失败重试、结构化导出。这个项目就是把这一层补齐的批处理工具本地开源引擎为主、在线服务做兜底插件式适配层换引擎不动业务代码。手上有一堆扫描件 PDF、截图、拍照件需要批量转文本或抽字段的开发拿过去改最省事。2. 架构与目录检测、识别、版面还原各自负责什么把一个 OCR 引擎当成ocr(image) - str来用是这类工具最常见的翻车起点。引擎返回的从来不是一段话而是一堆带坐标的文本框从文本框到可读段落中间那一步没有任何现成库替你做完。项目的结构就是围绕这条边界切的预处理负责让引擎看得清引擎负责像素到字符串版面还原负责字符串到阅读顺序导出负责顺序到文件格式。四段职责不交叉哪一段出问题看日志里对应阶段的输出就能定位。2.1 一张图从进来到出去三段式链路的边界单张图的完整链路是read - preprocess - detect - crop - recognize - layout - export。检测detect输出的是文本行外接四边形识别recognize吃的是 quadrilateral 裁出来的小图两者在多数开源引擎里是两套模型可以分开替换。真正需要自己写的是 layout 这一步引擎给的框是按检测顺序吐出来的跟人眼阅读顺序没有关系横排、竖排、双栏、表格混在同一页时直接拼字符串必然错乱。# ocrkit/pipeline.py 里单页处理的主干去掉异常分支后的样子 def process_page(image_path, engine, cfg): img read_image(image_path) # PIL/cv2 统一读成 RGB ndarray img preprocess(img, cfg[preprocess]) # 缩放、去噪、纠偏 boxes engine.run(img) # 引擎只返回坐标文本置信度 lines group_lines(boxes, cfg[layout][line_gap_ratio]) paras group_paragraphs(lines, cfg[layout][para_gap_ratio]) return PageResult(sourceimage_path, paragraphsparas)这段的价值在于把边界钉死了engine.run不允许返回排序结果group_lines不允许调用引擎。后面换引擎、换排序策略、加表格识别改动都落在单个函数里。参数line_gap_ratio控制同行的判定容差para_gap_ratio控制段落切分阈值两个值都跟字号强相关所以代码里用中位行高做基准而不是写死像素。2.2 目录结构与每个模块的真实职责目录按“引擎无关”和“引擎相关”分成两块engine/下面全是跟具体 OCR 实现绑定的代码其余目录不 import 任何模型库这是能换引擎的前提。mkdir -p ocr-doc-tool/{configs,ocrkit/engine,tests,data/in,data/out} cd ocr-doc-tool touch ocrkit/__init__.py ocrkit/pipeline.py ocrkit/preprocess.py \ ocrkit/layout.py ocrkit/exporter.py ocrkit/cli.py \ ocrkit/engine/{__init__,base,local_engine,remote_engine}.py建完之后的核心文件职责如下改动前先对着表定位比全仓库搜关键字快。文件职责改动频率ocrkit/preprocess.py缩放、灰度、去噪、纠偏高跟输入质量强相关ocrkit/engine/base.pyTextBox数据结构与引擎抽象低定了就别动ocrkit/engine/local_engine.py本地开源引擎的加载与调用中换模型时改ocrkit/engine/remote_engine.py在线服务封装、超时与重试中换服务商时改ocrkit/layout.py行聚类、段落切分、阅读顺序高业务差异都在这里ocrkit/exporter.pytxt / json / md 三种输出中加字段时改ocrkit/cli.py命令行入口与参数透传低配置统一放configs/default.yaml命令行只暴露最常调的三个参数其余走配置文件避免参数膨胀成几十个 flag。# configs/default.yaml preprocess: target_short_side: 1600 # 短边缩放到这个像素低于则放大高于 2400 再缩回 denoise: true deskew: true deskew_max_angle: 8.0 # 超过 8 度视为人为旋转不自动纠偏 engine: backend: local # local | remote适配层按这个字段实例化 min_score: 0.55 # 置信度低于此值直接丢弃宁可少字不要错字 batch_size: 8 layout: line_gap_ratio: 0.55 # 行聚类容差 中位行高 * 该比例 para_gap_ratio: 1.8 # 段落切分阈值同样以行高为基准 export: formats: [txt, json, md]target_short_side是最容易被忽略又最影响结果的一项。开源的检测模型通常在 960 到 1600 的短边尺度上训练直接把 300dpi 的 A4 扫描件短边两千多像素喂进去小字号会被缩没反过来把手机拍的低分辨率图直接送进去模型根本找不到字。统一缩放到目标短边是让同一套参数在不同来源的素材上表现稳定的最低成本做法。2.3 为什么本地开源引擎优先在线服务留在适配层选型上没有绝对答案取决于三个约束数据能不能出内网、每天的量有多大、准确率要求到什么档。做档案、合同、票据这类场景原文带编号和金额出内网这件事通常一票否决在线方案所以默认 backend 是 local在线服务只作为兜底。维度本地开源引擎在线 OCR 服务数据流向全程不出机器图片需上传单页耗时首次加载模型慢之后百毫秒级受网络与服务并发影响成本一次性硬件投入按调用量计费准确率印刷体够用手写与复杂版式弱复杂版式通常更好可定制可换模型、可微调只能调参数适配层的关键不是抽象得多漂亮而是把两边返回结构强行拉平。在线接口返回的字段名、坐标格式、置信度语义都跟本地不一样有的给左上角加宽高有的给四点坐标有的干脆只给文本不给位置。所以在base.py里定死一个TextBox两个实现负责翻译layout.py只认TextBox。这样后面想加第三种引擎只需要再写一个几十行的翻译类。3. 核心模块拆解预处理、引擎封装、结果拼装的关键代码这一段是真正要动手改的部分。四个模块的代码量都不大加起来四百行出头但每一处参数都影响最终文本的可读性。我按调用顺序拆每段给完整可抄的代码参数含义和失败时的表现都写在后面。3.1 预处理把玄学调参变成几步固定动作预处理最容易写成玄学加个滤波、换个阈值这页好了那页坏了。稳定的做法是固定四步、每步都有开关和上限缩放、灰度、去噪、纠偏。纠偏一定要设角度上限否则遇到带表格线的页面霍夫变换会把表格线当成文字基线整页转成 30 度识别率直接归零。# ocrkit/preprocess.py import cv2 import numpy as np def preprocess(img: np.ndarray, cfg: dict) - np.ndarray: img resize_by_short_side(img, cfg[target_short_side]) gray cv2.cvtColor(img, cv2.COLOR_RGB2GRAY) if img.ndim 3 else img if cfg.get(denoise): # 中值滤波对扫描件的椒盐噪声有效核必须是奇数 gray cv2.medianBlur(gray, 3) if cfg.get(deskew): gray deskew(gray, cfg[deskew_max_angle]) # 引擎大多吃三通道统一转回去避免下游判断维度 return cv2.cvtColor(gray, cv2.COLOR_GRAY2RGB) def resize_by_short_side(img, target): h, w img.shape[:2] short min(h, w) if short 0: raise ValueError(empty image) scale target / short if 0.9 scale 1.1: # 缩放幅度太小就跳过省一次重采样 return img interp cv2.INTER_CUBIC if scale 1 else cv2.INTER_AREA return cv2.resize(img, (int(w * scale), int(h * scale)), interpolationinterp) def deskew(gray, max_angle8.0): # 反色后找前景点用最小外接矩形估主方向 binary cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY_INV cv2.THRESH_OTSU)[1] coords cv2.findNonZero(binary) if coords is None: return gray angle cv2.minAreaRect(coords)[-1] angle -(90 angle) if angle -45 else -angle if abs(angle) max_angle: # 超限认为是扫描时人为放置的旋转不做纠正 return gray h, w gray.shape[:2] m cv2.getRotationMatrix2D((w / 2, h / 2), angle, 1.0) return cv2.warpAffine(gray, m, (w, h), flagscv2.INTER_CUBIC, borderModecv2.BORDER_REPLICATE)resize_by_short_side里的 0.91.1 是防抖区间避免原图刚好接近目标尺寸时反复重采样损失细节插值方式按放大缩小分开选放大用三次插值保边缘缩小用区域插值抗混叠。deskew用 Otsu 反色后取前景点比直接对原图做霍夫稳因为扫描件的底色通常是白的前景点集中才代表文字方向。deskew_max_angle设 8 度是个经验值正常扫描偏差很少超过 5 度超过的基本是人为放歪或者页面本身有斜线装饰这时候不纠比纠错强。注意二值化只在估角度时用不要拿二值图去喂识别模型。彩色信息对某些引擎的识别有帮助压成黑白反而掉点。3.2 引擎适配层一个接口包住本地和在线两种实现适配层要解决两个具体问题本地模型加载慢且吃内存不能 import 时就初始化在线调用有超时和限流必须能重试且不拖垮整批。所以BaseEngine只定义run本地实现做懒加载在线实现做退避重试两者都对上层返回统一的TextBox列表。# ocrkit/engine/base.py from dataclasses import dataclass, field from typing import List, Tuple dataclass class TextBox: text: str score: float points: List[Tuple[float, float]] field(default_factorylist) # 左上、右上、右下、左下 property def x_center(self) - float: return sum(p[0] for p in self.points) / len(self.points) property def y_center(self) - float: return sum(p[1] for p in self.points) / len(self.points) property def height(self) - float: ys [p[1] for p in self.points] return max(ys) - min(ys) class BaseEngine: def run(self, image) - List[TextBox]: raise NotImplementedError# ocrkit/engine/local_engine.py from .base import BaseEngine, TextBox class LocalEngine(BaseEngine): def __init__(self, model_dir, min_score0.55, batch_size8, devicecpu): self._model_dir model_dir self._min_score min_score self._batch_size batch_size self._device device self._model None # 懒加载进程起来时不占内存 def _ensure_loaded(self): if self._model is None: # build_pipeline 换成你环境里的检测识别组合返回可调用对象 self._model build_pipeline(self._model_dir, deviceself._device) return self._model def run(self, image): model self._ensure_loaded() raw model(image, batch_sizeself._batch_size) boxes [] for item in raw: text (item.get(text) or ).strip() if not text or item[score] self._min_score: continue # 空串和低分框一起丢后面排序才不会出现孤立碎片 boxes.append(TextBox(texttext, scorefloat(item[score]), pointsitem[points])) return boxesmin_score设 0.55 是个偏保守的值。调高到 0.8 会大量丢字尤其表格里的小字号调到 0.3 以下就会开始出现“的”变“的,”这类噪声。真正要调的时候先看导出 json 里被丢掉的框长什么样再决定是调阈值还是回预处理阶段治源。batch_size对 CPU 推理影响明显8 是个折中显存小的时候设 24否则第一次跑就会 OOM。在线实现只在网络允许且数据合规的场景下启用核心是超时、重试、限流三件事接口返回的坐标格式在翻译成TextBox时一次性对齐别把差异漏到 layout 层。3.3 版面还原把几百个文本框排回人能读的顺序这一步决定了导出文本能不能直接给人看。做法是先把框按纵坐标聚成行再按横坐标排行内顺序最后按行间距切段。核心参数只有一个容差取中位行高的比例而不是固定像素因为同一批文件里字号差异很大固定像素在小字号页面上会把三行并成一行。# ocrkit/layout.py import statistics def group_lines(boxes, gap_ratio0.55): if not boxes: return [] tol statistics.median(b.height for b in boxes) * gap_ratio boxes sorted(boxes, keylambda b: b.y_center) lines, current [], [boxes[0]] for box in boxes[1:]: if abs(box.y_center - statistics.mean(b.y_center for b in current)) tol: current.append(box) # 同一行继续收 else: lines.append(sorted(current, keylambda b: b.x_center)) current [box] lines.append(sorted(current, keylambda b: b.x_center)) return lines def join_line(boxes): out for i, b in enumerate(boxes): if i and _need_space(boxes[i - 1], b): out out b.text return out def _need_space(prev, cur): # 中文之间不加空格中英/数字之间加避免“共 12 项”变成“共12项” gap cur.points[0][0] - prev.points[1][0] threshold max(prev.height, cur.height) * 0.25 return gap threshold and not (_is_cjk(prev.text[-1]) and _is_cjk(cur.text[0])) def _is_cjk(ch): return \u4e00 ch \u9fffgap_ratio取 0.55 意味着两个框的纵向中心差在半个行高内就算同行这个值对横排印刷体很稳遇到竖排文本古籍、部分票据需要单独走一套按 x 聚列的路径别硬套。_need_space是那种看起来无关紧要、实际决定输出像不像人写的细节中文之间插空格会让整篇文本在下游做正则匹配时全部失配这坑我踩过。段落切分在group_lines之后做相邻两行的垂直间距超过para_gap_ratio * 行高就断开另外首行缩进超过一个字宽也视为新段起点。表格区域建议直接跳过段落切分按检测框的行列关系单独还原混在一起处理只会两头不讨好。3.4 批量跑线程池、断点记录与失败重试单页代码写完真正的痛点在批处理。几百上千页跑两小时中间挂一次全部重来这个体验没法交付。所以批量入口必须做三件事并发、断点、失败隔离。# ocrkit/pipeline.py import json, os, hashlib from concurrent.futures import ThreadPoolExecutor, as_completed def run_batch(paths, engine, cfg, workers4, done_file.done.json): done _load_done(done_file) todo [p for p in paths if _file_key(p) not in done] with ThreadPoolExecutor(max_workersworkers) as pool: futures {pool.submit(_safe_process, p, engine, cfg): p for p in todo} for fut in as_completed(futures): path, ok, err fut.result() if ok: done[_file_key(path)] 1 _flush_done(done_file, done) # 每完成一页就落盘别攒到最后 else: print(f[FAIL] {path}: {err}) return done def _safe_process(path, engine, cfg): try: return path, True, None except Exception as exc: # 单页异常不影响整批 return path, False, repr(exc) def _file_key(path): stat os.stat(path) return hashlib.md5(f{path}:{stat.st_size}:{stat.st_mtime}.encode()).hexdigest()线程数不是越多越好。识别阶段大部分时间在模型推理里底层 C 扩展会释放 GIL所以线程池有效但超过物理核心数两倍之后收益趋零还容易把内存吃满。_file_key用路径加大小加修改时间做指纹比单纯路径可靠文件被替换过会重新跑避免拿着旧结果交差。断点文件每完成一页就写一次写成原子替换更稳别用追加模式进程被杀时容易留下半行 JSON。4. 排查笔记识别乱码、框错位、跑不动时按什么顺序定位OCR 的报错大多不是异常而是“能跑但结果不对”这种问题最难查。我的习惯是固定一条排查顺序先看预处理产物再看引擎原始输出导出 json 里保留 score 和坐标最后才怀疑排序。跳过前两步直接改参数通常是在给一个错误的前提打补丁。下面五条是这个工具在真实素材上反复遇到的。4.1 现象整页识别为空或只出来零星几个字现象是导出文件几乎空的日志显示引擎正常返回但boxes数量个位数。原因多数在预处理原图短边太大被缩没或者 Otsu 二值化在整页都是浅灰底的扫描件上把文字一起判成背景。还有一种情况是图片通道顺序错了RGB 当 BGR 送进去某些模型对颜色通道敏感字符笔画直接糊掉。解决分三步先把预处理后的图存出来看一眼确认字还清晰再检查缩放后的短边是否落在 9001800 之间最后把min_score临时降到 0.1 跑一次看看是不是框都在、只是被阈值筛掉了。这三步做完基本能定位在哪一段。我一般会在调试模式下把预处理图和带框可视化图都落盘比打印日志直观得多。4.2 现象中文变乱码、英文数字混排丢字现象是导出文本里出现大量形近字错误数字 0 和字母 O 混淆或者英文字符成片消失。原因通常是识别模型的语言库不匹配只加载了中文识别模型去跑英文票据或者模型自带的字典文件缺失、路径指到了默认的空字典。另一种原因是图像被过度二值化细笔画断成两截识别器对断笔的容忍度很低。解决上先确认加载的模型和字典版本一致多语言场景要么换多语言模型要么按页做语种判断后分流。图像侧把二值化从预处理链路里去掉只保留灰度加轻度去噪通常能救回一部分细笔画。若某几类字符稳定出错最省事的办法是收集两百张左右样本做后处理纠错表比摸索模型参数见效快。4.3 现象文字顺序错乱表格被拼成一坨现象是文本内容都对但顺序完全没法读双栏文档左右两栏交错表格里同一行的内容跑到不同段落。原因在 layout双栏页面按全页宽度做行聚类左右两栏同一水平线上的框会被判成同一行。表格则是因为单元格高度差异大中位行高被拉偏容差算出来不适用。解决办法是先做栏检测再聚类简单做法是按所有框的 x 中心做一维聚类得到两簇就分栏处理各栏内部独立聚行。表格区域靠长直线检测圈出来圈到的区域单独按行列还原不参与段落切分。gap_ratio在多字号混排的页面上建议按区域动态算中位行高别用全页统一值。4.4 现象批量跑一半内存爆掉或越跑越慢现象是跑到两三百页时进程被系统杀掉或者速度从每页 200 毫秒退化到好几秒。原因一般有两个图片对象在循环里没释放cv2的 ndarray 引用一直挂着以及线程池里每个任务都触发了一次模型加载懒加载没加锁多个线程同时进_ensure_loaded模型被初始化了多份。解决是给_ensure_loaded加线程锁保证只初始化一次任务函数里把大对象的作用域收窄处理完及时delPython 的引用计数会立刻回收。线程数按物理核心数配经验值是核数的 12 倍超过之后收益递减内存却线性上涨。另外导出时不要把所有页结果攒在内存里最后统一写逐页落盘。4.5 现象同一批图跑两次结果不一样现象是同一张图两次运行导出的文本有细微差别个别字的置信度跳变。原因通常出在批量推理上batch_size变化会让某些模型的 padding 方式不同边缘框的识别结果随之浮动还有在线服务实现里带了随机重试第二次走了不同节点。解决办法是固定batch_size、固定设备、固定随机种子把这三项写进配置文件而不是靠命令行默认值。对稳定性要求高的场景把min_score调高一点换取一致性宁可少几个字也别在两次结果之间反复横跳。这一点做验收时尤其重要客户拿两次结果一对比发现不一致解释成本极高。5. 二次开发从通用文本到你业务字段的三处改造拿到通用识别结果只是起点业务要的是“合同编号”“金额”“签署日期”这些字段。改造集中在三处按投入产出排序先做字段抽取再做坐标回填最后才是换引擎。字段抽取不用上模型锚点加正则就够覆盖八成场景。思路是先定位包含关键词的行再在该行及其下一行里取值避免全文档正则误命中。import re FIELD_RULES { contract_no: (r(?:合同编号|编号)[:\s]*([A-Z0-9\-]{6,24}), 1), amount: (r(?:金额|合计)[:\s]*(?:人民币)?\s*([\d,]\.?\d{0,2}), 1), sign_date: (r(\d{4})\s*[年\-/]\s*(\d{1,2})\s*[月\-/]\s*(\d{1,2}), 3), } def extract_fields(text): out {} for name, (pattern, groups) in FIELD_RULES.items(): m re.search(pattern, text) if not m: out[name] None continue out[name] -.join(m.groups()) if groups 1 else m.group(1).strip() return outFIELD_RULES里第二个元素表示分组数多分组时按-拼成日期这种标准格式。这张规则表建议直接做成外部 yaml法务或运营改字段不用动代码。实测下来锚点词加分组约束的组合比一上来微调模型现实得多。坐标回填是第二个改造点。识别结果自带points把它映射回 PDF 的页面坐标系就能在原文上做高亮、做审阅界面、做“点字段跳原文”。注意 PDF 的坐标系原点在左下、单位是 point而图像坐标原点在左上、单位是像素中间要过一次 DPI 换算这一步算错会让高亮整体偏移一截。最后才是换引擎。有了适配层换引擎的成本就是写一个翻译类把新接口的返回塞进TextBox。我的判断标准很简单在固定的一百页验收集上字段抽取准确率提升超过 5 个点才值得换否则光调适配就够喝一壶。验收集一定要提前留好每次改动都跑一遍指标落在同一个口径上。血泪经验是别在没有验收集的情况下调参数。OCR 这块调参的反馈太容易骗人这一页好了另一页悄悄坏掉不看整体指标根本发现不了。从那以后我每次动预处理或阈值之前都强制先把那一百页跑一遍留下基线改完再跑一遍做对比对不上的改动一律回滚。希望帮到你。本文还有配套的精品资源点击获取
简介这份面向OCR入门与文档数字化实践的下载包围绕图片文字转机器编码文字这一核心需求提供可参考的代码样例与示例素材适合刚开始接触光学字符识别、希望快速跑通识别流程的开发者与学生。压缩包共3个文件以2个Python脚本和1个JPG示例图片为主整体约2.03MB脚本便于了解识别调用、结果输出与基础处理思路示例图片可用于验证票据类文档的识别效果包体轻量便于在本地环境中复现和按需修改。已有192人学习或下载说明其在OCR基础实践场景中具备一定参考价值。读者可从中获得一份结构简洁的OCR练习素材用于理解图像输入、文字提取和结果呈现之间的对应关系也可作为课程作业、原型验证或二次开发的起点进一步结合Tesseract等开源工具或在线服务扩展识别能力。1. 从一摞扫描件说起这套文档 OCR 工具到底解决哪类活某公司档案整理小组去年接了个活把三百多份扫描件里的事项编号、金额、落款日期录进系统。他们先直接调开源 OCR 命令行两百页十几分钟就跑完了可导出的文本是一大坨——编号跑到金额后面跨栏段落首尾相接最后两个人对着原图核了两周。OCR 在现代文档处理里应用面确实广但“识别出来”和“能用”之间隔着一层没人写进文档的东西版面顺序、置信度过滤、失败重试、结构化导出。这个项目就是把这一层补齐的批处理工具本地开源引擎为主、在线服务做兜底插件式适配层换引擎不动业务代码。手上有一堆扫描件 PDF、截图、拍照件需要批量转文本或抽字段的开发拿过去改最省事。2. 架构与目录检测、识别、版面还原各自负责什么把一个 OCR 引擎当成ocr(image) - str来用是这类工具最常见的翻车起点。引擎返回的从来不是一段话而是一堆带坐标的文本框从文本框到可读段落中间那一步没有任何现成库替你做完。项目的结构就是围绕这条边界切的预处理负责让引擎看得清引擎负责像素到字符串版面还原负责字符串到阅读顺序导出负责顺序到文件格式。四段职责不交叉哪一段出问题看日志里对应阶段的输出就能定位。2.1 一张图从进来到出去三段式链路的边界单张图的完整链路是read - preprocess - detect - crop - recognize - layout - export。检测detect输出的是文本行外接四边形识别recognize吃的是 quadrilateral 裁出来的小图两者在多数开源引擎里是两套模型可以分开替换。真正需要自己写的是 layout 这一步引擎给的框是按检测顺序吐出来的跟人眼阅读顺序没有关系横排、竖排、双栏、表格混在同一页时直接拼字符串必然错乱。# ocrkit/pipeline.py 里单页处理的主干去掉异常分支后的样子 def process_page(image_path, engine, cfg): img read_image(image_path) # PIL/cv2 统一读成 RGB ndarray img preprocess(img, cfg[preprocess]) # 缩放、去噪、纠偏 boxes engine.run(img) # 引擎只返回坐标文本置信度 lines group_lines(boxes, cfg[layout][line_gap_ratio]) paras group_paragraphs(lines, cfg[layout][para_gap_ratio]) return PageResult(sourceimage_path, paragraphsparas)这段的价值在于把边界钉死了engine.run不允许返回排序结果group_lines不允许调用引擎。后面换引擎、换排序策略、加表格识别改动都落在单个函数里。参数line_gap_ratio控制同行的判定容差para_gap_ratio控制段落切分阈值两个值都跟字号强相关所以代码里用中位行高做基准而不是写死像素。2.2 目录结构与每个模块的真实职责目录按“引擎无关”和“引擎相关”分成两块engine/下面全是跟具体 OCR 实现绑定的代码其余目录不 import 任何模型库这是能换引擎的前提。mkdir -p ocr-doc-tool/{configs,ocrkit/engine,tests,data/in,data/out} cd ocr-doc-tool touch ocrkit/__init__.py ocrkit/pipeline.py ocrkit/preprocess.py \ ocrkit/layout.py ocrkit/exporter.py ocrkit/cli.py \ ocrkit/engine/{__init__,base,local_engine,remote_engine}.py建完之后的核心文件职责如下改动前先对着表定位比全仓库搜关键字快。文件职责改动频率ocrkit/preprocess.py缩放、灰度、去噪、纠偏高跟输入质量强相关ocrkit/engine/base.pyTextBox数据结构与引擎抽象低定了就别动ocrkit/engine/local_engine.py本地开源引擎的加载与调用中换模型时改ocrkit/engine/remote_engine.py在线服务封装、超时与重试中换服务商时改ocrkit/layout.py行聚类、段落切分、阅读顺序高业务差异都在这里ocrkit/exporter.pytxt / json / md 三种输出中加字段时改ocrkit/cli.py命令行入口与参数透传低配置统一放configs/default.yaml命令行只暴露最常调的三个参数其余走配置文件避免参数膨胀成几十个 flag。# configs/default.yaml preprocess: target_short_side: 1600 # 短边缩放到这个像素低于则放大高于 2400 再缩回 denoise: true deskew: true deskew_max_angle: 8.0 # 超过 8 度视为人为旋转不自动纠偏 engine: backend: local # local | remote适配层按这个字段实例化 min_score: 0.55 # 置信度低于此值直接丢弃宁可少字不要错字 batch_size: 8 layout: line_gap_ratio: 0.55 # 行聚类容差 中位行高 * 该比例 para_gap_ratio: 1.8 # 段落切分阈值同样以行高为基准 export: formats: [txt, json, md]target_short_side是最容易被忽略又最影响结果的一项。开源的检测模型通常在 960 到 1600 的短边尺度上训练直接把 300dpi 的 A4 扫描件短边两千多像素喂进去小字号会被缩没反过来把手机拍的低分辨率图直接送进去模型根本找不到字。统一缩放到目标短边是让同一套参数在不同来源的素材上表现稳定的最低成本做法。2.3 为什么本地开源引擎优先在线服务留在适配层选型上没有绝对答案取决于三个约束数据能不能出内网、每天的量有多大、准确率要求到什么档。做档案、合同、票据这类场景原文带编号和金额出内网这件事通常一票否决在线方案所以默认 backend 是 local在线服务只作为兜底。维度本地开源引擎在线 OCR 服务数据流向全程不出机器图片需上传单页耗时首次加载模型慢之后百毫秒级受网络与服务并发影响成本一次性硬件投入按调用量计费准确率印刷体够用手写与复杂版式弱复杂版式通常更好可定制可换模型、可微调只能调参数适配层的关键不是抽象得多漂亮而是把两边返回结构强行拉平。在线接口返回的字段名、坐标格式、置信度语义都跟本地不一样有的给左上角加宽高有的给四点坐标有的干脆只给文本不给位置。所以在base.py里定死一个TextBox两个实现负责翻译layout.py只认TextBox。这样后面想加第三种引擎只需要再写一个几十行的翻译类。3. 核心模块拆解预处理、引擎封装、结果拼装的关键代码这一段是真正要动手改的部分。四个模块的代码量都不大加起来四百行出头但每一处参数都影响最终文本的可读性。我按调用顺序拆每段给完整可抄的代码参数含义和失败时的表现都写在后面。3.1 预处理把玄学调参变成几步固定动作预处理最容易写成玄学加个滤波、换个阈值这页好了那页坏了。稳定的做法是固定四步、每步都有开关和上限缩放、灰度、去噪、纠偏。纠偏一定要设角度上限否则遇到带表格线的页面霍夫变换会把表格线当成文字基线整页转成 30 度识别率直接归零。# ocrkit/preprocess.py import cv2 import numpy as np def preprocess(img: np.ndarray, cfg: dict) - np.ndarray: img resize_by_short_side(img, cfg[target_short_side]) gray cv2.cvtColor(img, cv2.COLOR_RGB2GRAY) if img.ndim 3 else img if cfg.get(denoise): # 中值滤波对扫描件的椒盐噪声有效核必须是奇数 gray cv2.medianBlur(gray, 3) if cfg.get(deskew): gray deskew(gray, cfg[deskew_max_angle]) # 引擎大多吃三通道统一转回去避免下游判断维度 return cv2.cvtColor(gray, cv2.COLOR_GRAY2RGB) def resize_by_short_side(img, target): h, w img.shape[:2] short min(h, w) if short 0: raise ValueError(empty image) scale target / short if 0.9 scale 1.1: # 缩放幅度太小就跳过省一次重采样 return img interp cv2.INTER_CUBIC if scale 1 else cv2.INTER_AREA return cv2.resize(img, (int(w * scale), int(h * scale)), interpolationinterp) def deskew(gray, max_angle8.0): # 反色后找前景点用最小外接矩形估主方向 binary cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY_INV cv2.THRESH_OTSU)[1] coords cv2.findNonZero(binary) if coords is None: return gray angle cv2.minAreaRect(coords)[-1] angle -(90 angle) if angle -45 else -angle if abs(angle) max_angle: # 超限认为是扫描时人为放置的旋转不做纠正 return gray h, w gray.shape[:2] m cv2.getRotationMatrix2D((w / 2, h / 2), angle, 1.0) return cv2.warpAffine(gray, m, (w, h), flagscv2.INTER_CUBIC, borderModecv2.BORDER_REPLICATE)resize_by_short_side里的 0.91.1 是防抖区间避免原图刚好接近目标尺寸时反复重采样损失细节插值方式按放大缩小分开选放大用三次插值保边缘缩小用区域插值抗混叠。deskew用 Otsu 反色后取前景点比直接对原图做霍夫稳因为扫描件的底色通常是白的前景点集中才代表文字方向。deskew_max_angle设 8 度是个经验值正常扫描偏差很少超过 5 度超过的基本是人为放歪或者页面本身有斜线装饰这时候不纠比纠错强。注意二值化只在估角度时用不要拿二值图去喂识别模型。彩色信息对某些引擎的识别有帮助压成黑白反而掉点。3.2 引擎适配层一个接口包住本地和在线两种实现适配层要解决两个具体问题本地模型加载慢且吃内存不能 import 时就初始化在线调用有超时和限流必须能重试且不拖垮整批。所以BaseEngine只定义run本地实现做懒加载在线实现做退避重试两者都对上层返回统一的TextBox列表。# ocrkit/engine/base.py from dataclasses import dataclass, field from typing import List, Tuple dataclass class TextBox: text: str score: float points: List[Tuple[float, float]] field(default_factorylist) # 左上、右上、右下、左下 property def x_center(self) - float: return sum(p[0] for p in self.points) / len(self.points) property def y_center(self) - float: return sum(p[1] for p in self.points) / len(self.points) property def height(self) - float: ys [p[1] for p in self.points] return max(ys) - min(ys) class BaseEngine: def run(self, image) - List[TextBox]: raise NotImplementedError# ocrkit/engine/local_engine.py from .base import BaseEngine, TextBox class LocalEngine(BaseEngine): def __init__(self, model_dir, min_score0.55, batch_size8, devicecpu): self._model_dir model_dir self._min_score min_score self._batch_size batch_size self._device device self._model None # 懒加载进程起来时不占内存 def _ensure_loaded(self): if self._model is None: # build_pipeline 换成你环境里的检测识别组合返回可调用对象 self._model build_pipeline(self._model_dir, deviceself._device) return self._model def run(self, image): model self._ensure_loaded() raw model(image, batch_sizeself._batch_size) boxes [] for item in raw: text (item.get(text) or ).strip() if not text or item[score] self._min_score: continue # 空串和低分框一起丢后面排序才不会出现孤立碎片 boxes.append(TextBox(texttext, scorefloat(item[score]), pointsitem[points])) return boxesmin_score设 0.55 是个偏保守的值。调高到 0.8 会大量丢字尤其表格里的小字号调到 0.3 以下就会开始出现“的”变“的,”这类噪声。真正要调的时候先看导出 json 里被丢掉的框长什么样再决定是调阈值还是回预处理阶段治源。batch_size对 CPU 推理影响明显8 是个折中显存小的时候设 24否则第一次跑就会 OOM。在线实现只在网络允许且数据合规的场景下启用核心是超时、重试、限流三件事接口返回的坐标格式在翻译成TextBox时一次性对齐别把差异漏到 layout 层。3.3 版面还原把几百个文本框排回人能读的顺序这一步决定了导出文本能不能直接给人看。做法是先把框按纵坐标聚成行再按横坐标排行内顺序最后按行间距切段。核心参数只有一个容差取中位行高的比例而不是固定像素因为同一批文件里字号差异很大固定像素在小字号页面上会把三行并成一行。# ocrkit/layout.py import statistics def group_lines(boxes, gap_ratio0.55): if not boxes: return [] tol statistics.median(b.height for b in boxes) * gap_ratio boxes sorted(boxes, keylambda b: b.y_center) lines, current [], [boxes[0]] for box in boxes[1:]: if abs(box.y_center - statistics.mean(b.y_center for b in current)) tol: current.append(box) # 同一行继续收 else: lines.append(sorted(current, keylambda b: b.x_center)) current [box] lines.append(sorted(current, keylambda b: b.x_center)) return lines def join_line(boxes): out for i, b in enumerate(boxes): if i and _need_space(boxes[i - 1], b): out out b.text return out def _need_space(prev, cur): # 中文之间不加空格中英/数字之间加避免“共 12 项”变成“共12项” gap cur.points[0][0] - prev.points[1][0] threshold max(prev.height, cur.height) * 0.25 return gap threshold and not (_is_cjk(prev.text[-1]) and _is_cjk(cur.text[0])) def _is_cjk(ch): return \u4e00 ch \u9fffgap_ratio取 0.55 意味着两个框的纵向中心差在半个行高内就算同行这个值对横排印刷体很稳遇到竖排文本古籍、部分票据需要单独走一套按 x 聚列的路径别硬套。_need_space是那种看起来无关紧要、实际决定输出像不像人写的细节中文之间插空格会让整篇文本在下游做正则匹配时全部失配这坑我踩过。段落切分在group_lines之后做相邻两行的垂直间距超过para_gap_ratio * 行高就断开另外首行缩进超过一个字宽也视为新段起点。表格区域建议直接跳过段落切分按检测框的行列关系单独还原混在一起处理只会两头不讨好。3.4 批量跑线程池、断点记录与失败重试单页代码写完真正的痛点在批处理。几百上千页跑两小时中间挂一次全部重来这个体验没法交付。所以批量入口必须做三件事并发、断点、失败隔离。# ocrkit/pipeline.py import json, os, hashlib from concurrent.futures import ThreadPoolExecutor, as_completed def run_batch(paths, engine, cfg, workers4, done_file.done.json): done _load_done(done_file) todo [p for p in paths if _file_key(p) not in done] with ThreadPoolExecutor(max_workersworkers) as pool: futures {pool.submit(_safe_process, p, engine, cfg): p for p in todo} for fut in as_completed(futures): path, ok, err fut.result() if ok: done[_file_key(path)] 1 _flush_done(done_file, done) # 每完成一页就落盘别攒到最后 else: print(f[FAIL] {path}: {err}) return done def _safe_process(path, engine, cfg): try: return path, True, None except Exception as exc: # 单页异常不影响整批 return path, False, repr(exc) def _file_key(path): stat os.stat(path) return hashlib.md5(f{path}:{stat.st_size}:{stat.st_mtime}.encode()).hexdigest()线程数不是越多越好。识别阶段大部分时间在模型推理里底层 C 扩展会释放 GIL所以线程池有效但超过物理核心数两倍之后收益趋零还容易把内存吃满。_file_key用路径加大小加修改时间做指纹比单纯路径可靠文件被替换过会重新跑避免拿着旧结果交差。断点文件每完成一页就写一次写成原子替换更稳别用追加模式进程被杀时容易留下半行 JSON。4. 排查笔记识别乱码、框错位、跑不动时按什么顺序定位OCR 的报错大多不是异常而是“能跑但结果不对”这种问题最难查。我的习惯是固定一条排查顺序先看预处理产物再看引擎原始输出导出 json 里保留 score 和坐标最后才怀疑排序。跳过前两步直接改参数通常是在给一个错误的前提打补丁。下面五条是这个工具在真实素材上反复遇到的。4.1 现象整页识别为空或只出来零星几个字现象是导出文件几乎空的日志显示引擎正常返回但boxes数量个位数。原因多数在预处理原图短边太大被缩没或者 Otsu 二值化在整页都是浅灰底的扫描件上把文字一起判成背景。还有一种情况是图片通道顺序错了RGB 当 BGR 送进去某些模型对颜色通道敏感字符笔画直接糊掉。解决分三步先把预处理后的图存出来看一眼确认字还清晰再检查缩放后的短边是否落在 9001800 之间最后把min_score临时降到 0.1 跑一次看看是不是框都在、只是被阈值筛掉了。这三步做完基本能定位在哪一段。我一般会在调试模式下把预处理图和带框可视化图都落盘比打印日志直观得多。4.2 现象中文变乱码、英文数字混排丢字现象是导出文本里出现大量形近字错误数字 0 和字母 O 混淆或者英文字符成片消失。原因通常是识别模型的语言库不匹配只加载了中文识别模型去跑英文票据或者模型自带的字典文件缺失、路径指到了默认的空字典。另一种原因是图像被过度二值化细笔画断成两截识别器对断笔的容忍度很低。解决上先确认加载的模型和字典版本一致多语言场景要么换多语言模型要么按页做语种判断后分流。图像侧把二值化从预处理链路里去掉只保留灰度加轻度去噪通常能救回一部分细笔画。若某几类字符稳定出错最省事的办法是收集两百张左右样本做后处理纠错表比摸索模型参数见效快。4.3 现象文字顺序错乱表格被拼成一坨现象是文本内容都对但顺序完全没法读双栏文档左右两栏交错表格里同一行的内容跑到不同段落。原因在 layout双栏页面按全页宽度做行聚类左右两栏同一水平线上的框会被判成同一行。表格则是因为单元格高度差异大中位行高被拉偏容差算出来不适用。解决办法是先做栏检测再聚类简单做法是按所有框的 x 中心做一维聚类得到两簇就分栏处理各栏内部独立聚行。表格区域靠长直线检测圈出来圈到的区域单独按行列还原不参与段落切分。gap_ratio在多字号混排的页面上建议按区域动态算中位行高别用全页统一值。4.4 现象批量跑一半内存爆掉或越跑越慢现象是跑到两三百页时进程被系统杀掉或者速度从每页 200 毫秒退化到好几秒。原因一般有两个图片对象在循环里没释放cv2的 ndarray 引用一直挂着以及线程池里每个任务都触发了一次模型加载懒加载没加锁多个线程同时进_ensure_loaded模型被初始化了多份。解决是给_ensure_loaded加线程锁保证只初始化一次任务函数里把大对象的作用域收窄处理完及时delPython 的引用计数会立刻回收。线程数按物理核心数配经验值是核数的 12 倍超过之后收益递减内存却线性上涨。另外导出时不要把所有页结果攒在内存里最后统一写逐页落盘。4.5 现象同一批图跑两次结果不一样现象是同一张图两次运行导出的文本有细微差别个别字的置信度跳变。原因通常出在批量推理上batch_size变化会让某些模型的 padding 方式不同边缘框的识别结果随之浮动还有在线服务实现里带了随机重试第二次走了不同节点。解决办法是固定batch_size、固定设备、固定随机种子把这三项写进配置文件而不是靠命令行默认值。对稳定性要求高的场景把min_score调高一点换取一致性宁可少几个字也别在两次结果之间反复横跳。这一点做验收时尤其重要客户拿两次结果一对比发现不一致解释成本极高。5. 二次开发从通用文本到你业务字段的三处改造拿到通用识别结果只是起点业务要的是“合同编号”“金额”“签署日期”这些字段。改造集中在三处按投入产出排序先做字段抽取再做坐标回填最后才是换引擎。字段抽取不用上模型锚点加正则就够覆盖八成场景。思路是先定位包含关键词的行再在该行及其下一行里取值避免全文档正则误命中。import re FIELD_RULES { contract_no: (r(?:合同编号|编号)[:\s]*([A-Z0-9\-]{6,24}), 1), amount: (r(?:金额|合计)[:\s]*(?:人民币)?\s*([\d,]\.?\d{0,2}), 1), sign_date: (r(\d{4})\s*[年\-/]\s*(\d{1,2})\s*[月\-/]\s*(\d{1,2}), 3), } def extract_fields(text): out {} for name, (pattern, groups) in FIELD_RULES.items(): m re.search(pattern, text) if not m: out[name] None continue out[name] -.join(m.groups()) if groups 1 else m.group(1).strip() return outFIELD_RULES里第二个元素表示分组数多分组时按-拼成日期这种标准格式。这张规则表建议直接做成外部 yaml法务或运营改字段不用动代码。实测下来锚点词加分组约束的组合比一上来微调模型现实得多。坐标回填是第二个改造点。识别结果自带points把它映射回 PDF 的页面坐标系就能在原文上做高亮、做审阅界面、做“点字段跳原文”。注意 PDF 的坐标系原点在左下、单位是 point而图像坐标原点在左上、单位是像素中间要过一次 DPI 换算这一步算错会让高亮整体偏移一截。最后才是换引擎。有了适配层换引擎的成本就是写一个翻译类把新接口的返回塞进TextBox。我的判断标准很简单在固定的一百页验收集上字段抽取准确率提升超过 5 个点才值得换否则光调适配就够喝一壶。验收集一定要提前留好每次改动都跑一遍指标落在同一个口径上。血泪经验是别在没有验收集的情况下调参数。OCR 这块调参的反馈太容易骗人这一页好了另一页悄悄坏掉不看整体指标根本发现不了。从那以后我每次动预处理或阈值之前都强制先把那一百页跑一遍留下基线改完再跑一遍做对比对不上的改动一律回滚。希望帮到你。本文还有配套的精品资源点击获取
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
