简介面向制造业物料标签核验与快递包裹条码识别场景这套代码示例聚焦中文、英文文字及条形码、二维码的快速检测与识别。包内共16个文件以4个py脚本承担推理入口与调用逻辑配合OCR模型文件pdmodel、pdiparams及info配置、xml与txt说明并附1张识别效果图压缩包约15MB便于直接运行和二次调试。已有174人学习适合具备一定Python基础、希望快速验证OCR与条码识别流程的开发者参考。读者可从中了解模型加载、分类与检测模块的组织方式借鉴视频/图像预测脚本的接口设计并据效果图核对识别结果为供应商物料标签自动识别和后台处理提供可复用的工程起点。1. 从一张货架照片说起一个入口同时搞定 OCR 中文识别、英文识别、条形码识别与二维码识别上周帮朋友处理一批仓库盘点照片一张图里同时躺着快递单上的中文地址、商品包装背面的英文说明、纸箱侧面的 EAN13 条形码还有贴在托盘上的二维码。如果按照常规做法得打开 OCR 工具识别文字、再切到扫码软件扫条码识别完还要手动把结果对应回同一张图。麻烦在于同一张图里这三类目标互相干扰——文字区域被当成噪声小条码被整体缩放后糊成一团。这个四合一识别工程解决的就是这个问题把 OCR 中文识别、英文识别、条形码识别、二维码识别四条链路收进一个统一入口一次调用返回四类结构化结果坐标都带回来后续想裁图、想标注、想存库都能直接对接。适合两类人一类是正在做仓储盘点、票证录入、资产标签管理这类小工具需要一个开箱能跑、又能修改的识别底座另一类是想搞清楚 OCR 与条码检测在同一个工程里如何共享预处理、如何合并结果、如何避免互相拖慢的开发者。代码规模不大技术栈也常见照着跑一遍大概半小时但拆开看每一层都有需要仔细检查的地方。2. 技术选型与工程骨架四条识别链路怎么共存于一个入口先把选型摆出来。四条识别链路没有哪个库能全部覆盖主流做法是「预处理统一 识别分开 结果归一」。预处理交给 OpenCV中文英文识别交给 PaddleOCR条形码和二维码先走 pyzbar模糊或尺寸过小的二维码再交给 WeChatQRCode 引擎补充识别界面层用 PyQt5 做一个最小可用的窗口不想用界面就走命令行批处理。2.1 为什么 OCR 选 PaddleOCR 而不是 TesseractOCR 这块最常见的选择有三个Tesseract、PaddleOCR、以及各家云 API。放到「中文识别 英文识别 本地离线」这个约束下差距很明显。Tesseract 是老牌选手英文识别干净利落但中文需要单独下载语言包而且对倾斜、低对比度、带表格线的票据很不友好。默认引擎在中文场景的断行和错字率经常需要额外做大量图像增强才能勉强可用。云 API 效果好但需要联网、按次计费做离线小工具不合适。PaddleOCR 的 PP-OCR 系列在中文场景基本是开箱可用内置方向分类器use_angle_clsTrue打开之后180 度倒置的图也能纠正过来。它对中英文混排的处理也比较自然不需要来回切换语言模型。代价是依赖链比较长首次运行会下载模型文件离线环境要提前把模型目录准备好。条码这块pyzbar 底层是 zbar速度快、支持的码制多EAN13、EAN8、Code128、Code39、QR、DataMatrix 都在列表里缺点是它对图像质量比较挑二维码稍微小一点或者有运动模糊就扫不出来。所以用 WeChatQRCode 做第二遍补充识别它自带超分辨率模块对小码和低分辨率图明显更稳。四类目标的选型结果汇总如下能力主用方案备用方案选它的理由主要短板中文 OCRPaddleOCRlangchTesseract chi_sim中文断行准自带方向分类依赖体积大首次加载慢英文 OCRPaddleOCRlangch 可混排Tesseracteng一套模型覆盖混排不用切纯英文长文本略逊于专用模型条形码pyzbar / ZBarSymbol—码制全、调用简单小码、模糊码召回低二维码pyzbarWeChatQRCode前者快后者抗模糊前者对低分辨率敏感提示如果目标机器是 ARM 架构或者内存只有 2GPaddleOCR 的模型加载会明显吃力这种情况优先考虑把 OCR 拆成独立进程按需启动不要和条码识别绑在一个常驻进程里。2.2 目录结构识别逻辑和界面逻辑必须分开工程骨架按「输入 → 预处理 → 识别 → 归一化 → 输出」分层目录大致长这样recognizer/ ├── app/ │ ├── main.py # 命令行入口支持单图和多图批处理 │ ├── ui_main.py # PyQt5 窗口只负责选图与展示 │ └── config.py # 阈值、语言、是否启用兜底引擎 ├── core/ │ ├── preprocess.py # 灰度、二值化、去噪、透视矫正 │ ├── ocr_engine.py # PaddleOCR 封装与结果归一化 │ ├── code_engine.py # pyzbar WeChatQRCode 双引擎 │ └── pipeline.py # 统一调度合并四类结果 ├── models/ │ ├── ocr/ # PaddleOCR 推理模型 │ └── wechat_qrcode/ # 检测/超分模型 ├── tests/ │ └── samples/ # 各类样本图含难例 └── requirements.txt这个结构的关键在于core/不 import 任何app/里的东西。识别层只接受 numpy 数组或者图片路径返回纯字典。这样一来想把界面换成 Web 服务、换成批处理脚本、换成消息队列消费者都只动app/层识别层一行不改。models/单独拎出来也很有必要。PaddleOCR 默认会把模型下到用户目录多人共用一台机器时会重复下载WeChatQRCode 的四个模型文件检测 prototxt、检测 caffemodel、超分 prototxt、超分 caffemodel也要显式指定路径。统一放在工程内部署时整个目录打包即可省掉现场联网拉模型的麻烦。2.3 统一入口一次调用返回四类结果所有链路最终收敛到一个函数返回结构固定。这种设计的好处是上层不用关心底下用了几个引擎加新能力时只往字典里加字段。# core/pipeline.py import time from core.preprocess import load_and_prepare from core.ocr_engine import OcrEngine from core.code_engine import CodeEngine class RecognizePipeline: def __init__(self, ocr_langch, enable_wechatTrue): # OCR 引擎常驻避免每次调用都重新加载模型 self.ocr OcrEngine(langocr_lang) self.code CodeEngine(enable_wechatenable_wechat) def run(self, image_path, need_ocrTrue, need_codeTrue): t0 time.time() # 预处理只做一次OCR 和条码共用同一份中间结果 img_raw, img_gray, img_bin load_and_prepare(image_path) result { path: image_path, texts: [], # [{text: str, score: float, box: [[x,y],...]}] barcodes: [], # [{type: EAN13, data: str, box: [...]}] qrcodes: [], # [{data: str, engine: zbar|wechat, box: [...]}] cost_ms: 0, } if need_code: # 条码优先用原图缩放会破坏细窄的条空比 result[barcodes], result[qrcodes] self.code.decode(img_raw, img_gray) if need_ocr: # OCR 用灰度图二值化结果留给低对比度场景兜底 result[texts] self.ocr.recognize(img_gray, fallback_binimg_bin) result[cost_ms] int((time.time() - t0) * 1000) return result这段代码有三个设计点值得说。第一OcrEngine和CodeEngine在__init__里初始化模型只加载一次如果把初始化写进run()单张图耗时会被模型加载拉到几秒批处理时更明显。第二预处理结果img_raw / img_gray / img_bin三份同时返回条码用原图保证条空比例不失真OCR 用灰度图二值图作为低对比度时的备选——不同任务对同一张图的最佳形态本来就不一样。第三返回字典里保留cost_ms后面做性能排查时不用再埋点。参数上need_ocr和need_code两个开关很重要。批量处理纯文字票据时关掉条码检测单张能省 20~40ms反过来扫码为主时关掉 OCR省得更多。默认全开是为了演示方便实际部署按场景收窄。3. 图像预处理链路灰度、二值化、透视矫正的落地写法预处理是这个工程里最容易被低估的一层。很多人拿原图直接喂给 OCR识别率不行就换模型换来换去发现还不如把图先摆正。实际经验是同一条 OCR 链路做好预处理之后中文识别准确率能提升一截条码的漏检也会明显减少。3.1 三步基础处理缩放、灰度、去噪第一步不是灰度化而是控制尺寸。手机拍的照片动辄 4000×3000直接送进检测网络会被内部缩放到固定边长缩放过程本身就会丢细节而太小的图放大后又会糊。常见做法是把长边限制在 1600 到 2000 之间。# core/preprocess.py import cv2 import numpy as np MAX_SIDE 1800 # 长边上限超过则等比缩小 MIN_SIDE 800 # 长边下限不足则等比放大 def resize_keep_ratio(img, max_sideMAX_SIDE, min_sideMIN_SIDE): h, w img.shape[:2] long_side max(h, w) if long_side max_side: scale max_side / long_side elif long_side min_side: scale min_side / long_side else: return img # INTER_AREA 缩小更干净INTER_CUBIC 放大更平滑 interp cv2.INTER_AREA if scale 1 else cv2.INTER_CUBIC return cv2.resize(img, (int(w * scale), int(h * scale)), interpolationinterp) def to_gray_and_denoise(img): gray cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) # 轻度去噪强度过大会把细小笔画一起抹掉 denoised cv2.fastNlMeansDenoising(gray, None, h7, templateWindowSize7, searchWindowSize21) return denoisedMAX_SIDE和MIN_SIDE这两个值是调过的设成 1800 是因为再大对 OCR 精度提升有限但耗时线性上涨设 800 下限是为了避免小图被检测网络放大后产生伪影。fastNlMeansDenoising的h参数控制去噪强度7 是个比较保守的值主要针对手机拍摄的传感器噪声。如果样本是扫描件、本身很干净这一步可以直接跳过能省十几毫秒。3.2 自适应二值化什么时候用、什么时候别用二值化不是万能药。光照均匀的文档图自适应二值化效果很好但如果是带纹理背景的商品包装、或者有渐变阴影的实拍图硬做二值化会把条码区域直接毁掉。def adaptive_binarize(gray): # blockSize 必须是奇数取值约为短边的 1/40太小会引入噪声 h, w gray.shape[:2] block max(15, (min(h, w) // 40) | 1) binary cv2.adaptiveThreshold( gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, blockSizeblock, C11 # 减去常数抑制背景噪点越大越白 ) return binaryblockSize按图像短边自适应是个很实用的技巧。固定 31 或 51 在大小图混跑时会翻车小图上单字被切碎大图上局部光照差异被平均掉。按短边除以 40 再取奇数大小图都能落在合理区间。C11偏大是为了让背景尽可能干净代价是浅色字可能丢失——所以二值化结果只作为 OCR 的fallback_bin不参与主链路。3.3 透视矫正票据和标签必备的一步拍歪的票据是识别率最大的敌人。一张倾斜 15 度的发票OCR 的行检测会错乱本来一行的金额被拆成两行。做法是先找最大四边形轮廓再套透视变换。def correct_perspective(img, min_area_ratio0.25): gray cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) edges cv2.Canny(gray, 50, 150) contours, _ cv2.findContours(edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE) h, w img.shape[:2] for c in sorted(contours, keycv2.contourArea, reverseTrue)[:5]: if cv2.contourArea(c) h * w * min_area_ratio: continue # 面积太小的轮廓大概率是噪声 peri cv2.arcLength(c, True) approx cv2.approxPolyDP(c, 0.02 * peri, True) if len(approx) ! 4: continue # 只接受四边形 pts approx.reshape(4, 2).astype(np.float32) # 按坐标和排序得到 左上、右上、右下、左下 s pts.sum(axis1) d np.diff(pts, axis1).ravel() rect np.array([pts[np.argmin(s)], pts[np.argmin(d)], pts[np.argmax(s)], pts[np.argmax(d)]], dtypenp.float32) dst np.array([[0, 0], [w - 1, 0], [w - 1, h - 1], [0, h - 1]], dtypenp.float32) m cv2.getPerspectiveTransform(rect, dst) return cv2.warpPerspective(img, m, (w, h)) return img # 找不到四边形就原样返回不做强制裁切min_area_ratio0.25的意思是只有轮廓面积超过整图四分之一才认为是「主体文档」否则宁可不动。这个阈值设低了会把包装上的小标签误当成主体拉正设高了稍小一点的票据又矫正不了。0.02 * peri的多边形逼近精度也需要留意值太大四边形拟合不出来太小会拟合出七八个顶点。最后一行return img比想象中重要。矫正失败时返回原图而不是抛异常或者返回空保证整条链路不会因为一张歪图直接中断。批处理场景下这一点尤其关键。4. OCR 中英文识别模块初始化、参数调优与结果归一化OCR 这一层看起来只是调一个 API实际上大部分工作量在参数和结果处理上。PaddleOCR 返回的原始结构是三层嵌套列表直接丢给业务层用起来很难受必须做一层归一化。4.1 引擎初始化语言、方向分类与线程数# core/ocr_engine.py from paddleocr import PaddleOCR import numpy as np class OcrEngine: def __init__(self, langch, use_gpuFalse, cpu_threads4): self.lang lang # use_angle_cls: 开启 180 度方向分类倒置票据能救回来 # det_limit_side_len: 检测网络输入长边1600 兼顾精度与速度 self.engine PaddleOCR( use_angle_clsTrue, langlang, use_gpuuse_gpu, cpu_threadscpu_threads, det_limit_side_len1600, det_db_thresh0.3, # 文本框概率阈值调低召回更多、误检也更多 det_db_box_thresh0.5, # 文本框得分阈值 drop_score0.5, # 识别置信度低于此值直接丢弃 show_logFalse, ) def recognize(self, gray_img, fallback_binNone): out self._infer(gray_img) # 主链路结果为空且提供了二值图时用二值图再试一次 if not out and fallback_bin is not None: out self._infer(fallback_bin) return out def _infer(self, img): raw self.engine.ocr(img, clsTrue) if not raw or raw[0] is None: return [] items [] for line in raw[0]: box, (text, score) line if not text.strip(): continue items.append({ text: text.strip(), score: round(float(score), 4), box: [[int(p[0]), int(p[1])] for p in box], }) return itemslangch这个参数经常被误解。它并不是「只能识别中文」而是加载中文为主的识别模型英文字母和数字同样能识别中英混排的效果也够用。真正需要纯英文高精度长文本时才换成langen。如果业务里两成以上是英文段落可以同时加载两个引擎按检测框宽高比或者字符集猜测走哪个但这会翻倍占内存一般工程没必要。det_limit_side_len1600是速度和精度的平衡点。调到 960速度能快将近一倍但小字比如 8 号字体的合同条款会整行漏检调到 2560精度有提升但单张耗时翻倍批量场景不划算。drop_score0.5是置信度过滤写进初始化参数里比在结果里再循环过滤更省事。但要注意这个值对中文手写体和艺术字影响很大手写场景建议降到 0.3 左右宁可留错字也别整行丢掉。4.2 结果归一化文本行合并与坐标回填原始结果是一行一个文本框实际业务里经常需要把同一段落的多行拼起来。直接.join()会把不同列的内容混在一起尤其在票据上会出大问题。def merge_lines(items, y_tol_ratio0.6, x_gap_ratio1.5): 把同一水平行、且间距不大的文本框合并成一行 if not items: return items # 按框的左上角 y 坐标排序再按 x 排序 items sorted(items, keylambda d: (d[box][0][1], d[box][0][0])) merged, current [], [items[0]] for it in items[1:]: prev current[-1] prev_h prev[box][2][1] - prev[box][0][1] cur_h it[box][2][1] - it[box][0][1] avg_h (prev_h cur_h) / 2 or 1 # 垂直方向偏差在半个字高内认为是同一行 same_line abs(it[box][0][1] - prev[box][0][1]) avg_h * y_tol_ratio # 水平间距不能超过 1.5 个字高否则是两列不合并 gap it[box][0][0] - prev[box][1][0] close_enough gap avg_h * x_gap_ratio if same_line and close_enough: current.append(it) else: merged.append(_flush(current)) current [it] merged.append(_flush(current)) return merged def _flush(group): return { text: .join(g[text] for g in group), score: round(sum(g[score] for g in group) / len(group), 4), box: [ min(g[box][0][0] for g in group), min(g[box][0][1] for g in group), max(g[box][2][0] for g in group), max(g[box][2][1] for g in group), ], }y_tol_ratio0.6表示垂直偏差在 0.6 个字高以内算同一行x_gap_ratio1.5表示水平间距超过 1.5 个字高就断开。这两个值是按常见票据和商品标签调出来的换成密集排版的表格x_gap_ratio要降到 0.8 左右否则相邻两列的单元格会被粘成一句。_flush里用空格拼接而不是直接相连是为了避免中英文边界粘连。中文之间其实不需要空格但混排时留一个空格更利于后续正则匹配。如果业务只做中文可以加个判断纯中文片段不加空格。4.3 字符级后处理正则与字典修正OCR 的错字有规律可循。数字0和字母O、1和l、5和S是最常见的混淆对在订单号、金额这类结构化字段上一条简单规则就能救回一批。import re # 只对看起来像订单号/金额的片段做字符替换避免污染普通文本 CODE_PATTERN re.compile(r^[0-9OolSsB]{8,}$) REPLACE_MAP str.maketrans({O: 0, o: 0, l: 1, I: 1, S: 5, s: 5, B: 8}) def fix_structured_text(text): if CODE_PATTERN.match(text): return text.translate(REPLACE_MAP) return text def extract_amounts(texts): 从识别结果里抽金额兼容 ¥、Y、 几种误识 pattern re.compile(r[¥Yy]\s*(\d{1,6}(?:\.\d{1,2})?)) out [] for t in texts: out.extend(pattern.findall(t[text])) return outCODE_PATTERN限定长度 8 以上且只含数字和易混字符是为了把「普通英文单词」排除在外。不加这个限制把所有O换成0英文说明会变成一堆乱码。extract_amounts里把Y也纳入前缀是因为实际样本中¥被识别成Y的概率不低这个细节是从几十张翻车样本里总结出来的。5. 条形码与二维码识别模块pyzbar 主链路与 WeChatQRCode 补充识别条码识别的代码比 OCR 短得多但调试起来更麻烦因为失败时它不告诉你为什么失败——返回空列表就完事了没有什么信息。所以这一层的重点是「多试几次、多换几种形态」。5.1 pyzbar 基础调用与码制白名单# core/code_engine.py import cv2 from pyzbar.pyzbar import decode, ZBarSymbol # 只启用需要的码制减少无效扫描也能避免误识别 WANTED [ ZBarSymbol.QRCODE, ZBarSymbol.EAN13, ZBarSymbol.EAN8, ZBarSymbol.CODE128, ZBarSymbol.CODE39, ZBarSymbol.DATABAR, ] class CodeEngine: def __init__(self, enable_wechatTrue): self.enable_wechat enable_wechat self.wechat self._init_wechat() if enable_wechat else None staticmethod def _decode_zbar(img): found [] for r in decode(img, symbolsWANTED): found.append({ type: r.type, # QRCODE / EAN13 / CODE128 ... data: r.data.decode(utf-8, errorsreplace), box: [[p.x, p.y] for p in r.polygon] if r.polygon else [], }) return foundsymbolsWANTED这个白名单值得单独说。不传参时 pyzbar 会尝试所有码制速度慢不说还容易把商品包装上的装饰性条纹误识别成 Code39。限定码制之后误检率明显下降。r.data.decode(utf-8, errorsreplace)里的容错也很必要某些码里塞的是 GBK 编码的中文硬解会抛异常加了容错至少能拿到部分内容。5.2 多尺度重试小码和远景码的救急方案同一张图里大二维码一次就能扫出来角落里的商品条码可能只有几十个像素宽。固定用原图扫小码基本没戏。做法是把图放大到不同倍数各扫一遍命中即停。SCALES [1.0, 1.6, 2.4, 0.7] # 先原图再放大最后缩小针对超大图 def decode_multi_scale(self, img, gray): hits, seen [], set() for s in SCALES: if s 1.0: canvas img else: interp cv2.INTER_CUBIC if s 1 else cv2.INTER_AREA canvas cv2.resize(img, None, fxs, fys, interpolationinterp) for item in self._decode_zbar(canvas): # 用类型 内容去重不同尺度扫到同一个码只留一条 key (item[type], item[data]) if key in seen: continue seen.add(key) # 缩放后的坐标要还原回原图坐标系 if s ! 1.0: item[box] [[int(x / s), int(y / s)] for x, y in item[box]] hits.append(item) return hitsSCALES里放 0.7 这个缩小档是为了应对手机直出的超高分辨率图——5000 像素宽的原图直接送 zbar扫描窗口相对条码太大反而不如缩到 70% 命中率高。坐标还原这一步经常被漏掉漏了之后画标注框会整体偏移排查半天以为是检测错了。放大 2.4 倍是有代价的一张 1800 长边的图放大后接近 4300单次解码耗时会翻几倍。所以顺序很重要原图先扫命中了就尽早结束实际工程里更稳妥的写法是先扫原图和缩小档没命中再进放大档。5.3 WeChatQRCode 补充识别与结果合并pyzbar 全军覆没的时候多半是二维码有轻微模糊、或者对比度太低。这时候交给 WeChatQRCode 再试一次。def _init_wechat(self): import os base os.path.join(models, wechat_qrcode) try: return cv2.wechat_qrcode_WeChatQRCode( os.path.join(base, detect.prototxt), os.path.join(base, detect.caffemodel), os.path.join(base, sr.prototxt), os.path.join(base, sr.caffemodel), ) except Exception: # 模型缺失时静默降级不能因为兜底引擎坏了影响主流程 return None def decode(self, img, gray): barcodes, qrcodes [], [] hits self.decode_multi_scale(img, gray) for h in hits: (qrcodes if h[type] QRCODE else barcodes).append(h) # 只有二维码没扫到时才启用兜底条形码它管不了 if not qrcodes and self.wechat is not None: try: texts, points self.wechat.detectAndDecode(img) for t, p in zip(texts, points): if t: qrcodes.append({ type: QRCODE, data: t, engine: wechat, box: [[int(x), int(y)] for x, y in p.reshape(-1, 2)], }) except Exception: pass return barcodes, qrcodes这个补齐策略的关键是「有条件的降级」。_init_wechat里用 try 包住模型文件不在就返回None后面调用处再判断一次整条链路不会因为一个可选依赖缺失而崩掉。detectAndDecode只处理二维码条形码没有覆盖所以触发条件写成not qrcodes而不是「什么都没扫到」。points的 shape 在不同 OpenCV 版本里可能是(N,1,2)也可能是(N,2)reshape(-1, 2)把两种情况统一掉这类兼容写法能省掉不少环境差异带来的麻烦。5.4 批量场景线程池与引擎复用一张一张串行处理一百张图要等几分钟。条码解码本身不占太多 CPU但图像缩放是计算密集的用线程池能明显提速。from concurrent.futures import ThreadPoolExecutor def batch_decode(pipeline, paths, workers4): results [] # 线程池大小不要超过物理核数超了反而因为 GIL 争抢变慢 with ThreadPoolExecutor(max_workersworkers) as pool: futures [pool.submit(pipeline.run, p, True, True) for p in paths] for f in futures: try: results.append(f.result()) except Exception as e: results.append({path: None, error: str(e)}) return resultsworkers4是经验值。PaddleOCR 的推理本身用到了多线程线程池开太大反而互相抢核。单张识别超过 300ms 的场景workers 设成 2 到 4 就够了如果确认 OCR 那一步是瓶颈更彻底的做法是把 OCR 拆成独立进程池绕开 GIL。6. 避坑与排查识别率上不去时先看这几处这一节全是踩过的坑。按现象、原因、解决三段写照着对号入座能省掉大半天。6.1 OCR 相关明明有字却识别不出来现象一张白底黑字的清晰截图OCR 返回空列表但同一张图用看图软件放大后肉眼完全正常。原因图片是 RGBA 四通道截图工具常见cv2.imread读进来是 4 通道直接送进 PaddleOCR 时内部转换出错检测阶段就返回 None。解决在load_and_prepare里统一转三通道两行代码的事。img cv2.imread(path, cv2.IMREAD_COLOR) # 强制三通道别用默认参数 if img is None: raise ValueError(f图片读取失败: {path})现象同一批图里中文识别正常数字识别频繁出错0识别成O、8识别成B。原因langch的识别模型以汉字为主数字字符的字典占比低遇到小字号数字时容易往形近字母上靠。解决不要换整个模型而是用 4.3 里的fix_structured_text做定向替换。如果数字占比很高比如全是流水号可以针对该批数据单独初始化一个langen的引擎按业务类型路由。现象竖排文字比如标签侧边的生产日期整段乱序识别出来的字是反的或者跳着来。原因检测框是竖长条识别阶段按横排切分字符顺序被打乱。use_angle_cls只处理 180 度翻转不处理 90 度旋转。解决检测到框的宽高比小于 0.5 时把该区域裁出来旋转 90 度再单独识别一次结果拼回原位置。这一步别图省事对所有图都做只对竖长框做否则耗时翻倍。6.2 条码相关能扫出来的只有一半现象手机拍的图二维码在屏幕上很清楚pyzbar 却返回空同一张图用手机自带相机一扫就出来了。原因图太大。原图长边 4000 时zbar 的扫描窗口相对单个码元过大密度不够解码失败。解决把 0.7 这一档缩放加进SCALES并且放在放大档之前执行。另外检查图是不是带 Alpha 通道条码检测同样需要三通道输入。现象一张图里有两个相同的二维码结果返回了两条重复记录业务侧统计数量出错。原因多尺度重试时同一个码在 1.0 和 1.6 倍都命中了没有去重。解决用(type, data)做 key 去重如 5.2 所示。注意不要用坐标做 key不同尺度的坐标本来就不一样。现象条形码识别出来的内容末尾多了一个字符或者少了一位校验位。原因EAN13 这类码制带校验位图像边缘被裁切或者条空比例失真时解码器会猜一个结果且不报错。解决对 EAN13/EAN8 的结果做一次校验位验算不通过就丢弃重试。这一步花不了几毫秒但能挡掉大部分脏数据。6.3 工程与部署本地跑得好好的换台机器就崩现象开发机上一切正常部署到客户机器上报ModuleNotFoundError: No module named pyzbar装完之后又报找不到libzbar。原因pyzbar 是 zbar 的 Python 封装系统层面还需要 zbar 的动态库。纯pip install只装了 Python 侧。解决打包时把系统依赖一并写进部署文档。Linux 下装libzbar0Windows 下需要把libzbar-64.dll放到可执行文件同级目录或者 PATH 里。这类问题属于纯环境坑跟识别本身无关但排查起来最耗时间。现象连续处理一百张图前二十张正常后面越来越慢最后内存爆掉。原因每张图都在run()里新建OcrEngine模型反复加载又不释放或者把每张图的中间结果都存进了列表没清理。解决引擎在__init__里只建一次run()里只做推理批处理时用生成器逐张产出结果不要一次性把所有图的 numpy 数组攒在内存里。注意PaddleOCR 首次调用会比后续慢很多测性能时至少跳过前 3 张否则得到的平均耗时没有参考价值。7. 二次开发把它改成一个带业务规则的识别服务拿到这套代码之后多数人的下一步不是继续调识别率而是把它接进自己的业务流。这里说三个改造方向按落地成本从低到高排。方向一包一层 HTTP 接口。用 FastAPI 把RecognizePipeline挂成服务/recognize收图片上传返回 JSON。注意引擎实例要在应用启动时初始化一次挂在app.state上别写在路由函数里。from fastapi import FastAPI, UploadFile import numpy as np, cv2 from core.pipeline import RecognizePipeline app FastAPI() pipe RecognizePipeline(ocr_langch, enable_wechatTrue) # 进程内单例 app.post(/recognize) async def recognize(file: UploadFile): data np.frombuffer(await file.read(), np.uint8) img cv2.imdecode(data, cv2.IMREAD_COLOR) # 内存解码免落盘 # 复用 pipeline 的预处理与引擎这里只走内存路径 texts pipe.ocr.recognize(cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)) barcodes, qrcodes pipe.code.decode(img, cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)) return {texts: texts, barcodes: barcodes, qrcodes: qrcodes}cv2.imdecode加np.frombuffer这套组合是为了避免每次请求都往磁盘写临时文件高并发下这块的 I/O 开销比想象中大。方向二加业务字段抽取。OCR 返回的是一堆散文本业务要的是订单号、金额、日期。做法是在pipeline.run()之后加一层规则引擎先用正则粗筛再用关键字定位。比如「合计」「总计」后面紧跟的数字最有可能是金额比全局搜¥准确得多。可以维护一张「关键字 → 字段」的映射表改起来不用动识别代码。方向三换模型或加自训练字典。如果某类专业术语反复识别错比如型号里的字母数字组合PaddleOCR 支持传入自定义字典把常见词加进去能明显改善。另一个更省事的办法是维护一张后处理替换表把「已确认的错误 → 正确写法」存下来命中就替换。规则积累到几百条之后效果比重新训练快得多。改造点主要改动文件风险提示包 HTTP 服务新增app/api.py引擎必须单例否则内存暴涨业务字段抽取新增core/extract.py正则别写太宽避免误抽自定义字典models/ocr/ 初始化参数字典改错会导致全量识别异常换条码引擎core/code_engine.py坐标体系要统一否则标注全偏验证这块给一个可执行的思路准备 50 张覆盖各类场景的样本图其中至少 15 张是「难例」倾斜、模糊、小码、低对比度每次改完参数跑一遍记录三组数字——文字行召回率、条码召回率、单张平均耗时。不要只看准确率很多时候准确率涨了两个点、耗时翻了一倍线上根本扛不住。改之前先跑一遍基线把数字记在 README 里后面每次改动都有对照。我自己的习惯是任何参数调整之前先把当前版本的输出完整存一份 JSON 快照改完之后 diff 一遍。有一次把det_db_thresh从 0.3 调到 0.2整体召回是涨了但金额字段多出一堆噪点如果没做 diff 根本发现不了——这种改动属于典型的「指标好看、业务翻车」。从那以后我每次动识别参数都强制走一遍「存快照 → 改参数 → diff → 只保留业务指标也涨的改动」后悔药不如提前留好。希望帮到你。本文还有配套的精品资源点击获取