mica-ppocr 1.2.4 发布:OCR 预处理内存砍半,检测提速 2.6 倍
> 发布日期: 2026-10-25 · 上一版本:v1.2.3(2026-09-12) 这一版把预处理内存砍掉一半、检测提速 2.6 倍,顺手清掉了两类「写了却不生效」「关了却关不掉」的问题:PDF 双通道的配置终于传到了引擎,mica.ai.ppocr.enabled=false 之后应用也能正常启动;海报类版面也有了声明检测参数的口子。 变更总览 模块 变更 类型 mica-ppocr-core 预处理内存融合(堆 -50%、检测提速 2.6×);mica.ai.ppocr.pdf.* 接通引擎;输入校验修复 perf / feat / fix mica-ppocr-structured 热路径分配优化;新增 detParams() 钩子;拼多多福袋类型识别 perf / feat mica-ppocr-spring-boot-starter 总开关闸门补齐;PDF 配置默认值对齐 fix mica-ppocr-solon-plugin 总开关闸门对齐;补注册 PdfAutoConfiguration fix 一、预处理内存砍半,检测提速 2.6 倍 三处预处理(det / rec / doc_ori)改成「归一化结果直接写入 CHW / NCHW 输出数组」,不再 materialize 中间 HWC 数组,也不再生成 CV_32F 中间 Mat。 场景 堆分配 耗时 det 预处理(3000×4000 图) 275 MB → 137 MB(-50%) 110 ms → 42 ms(2.6×) rec 预处理(50 框 × 1200px 宽) 79.1 MB → 39.8 MB(-50%) 21.1 ms → 15.9 ms(-25%) 另省约 40 MB native 内存。 对使用者的实际影响: 预处理一度是大图 OCR 的内存大头 —— 一张 3000×4000 的图,光归一化就吃掉 275 MB 堆。砍掉一半之后,Docker 里给容器的内存配额、或者本地跑批处理时的峰值占用都跟着松一截。 数值一个字节都没变 uint8 → CV_32F 与 uint8 → 提升为 float 在 0~255 上逐位相同,所以「先转 float 再算」与「直接提升再算」结果一致 —— 这正是省掉 CV_32F 中间 Mat 的依据。 三个预处理测试各保留了一个 reference* 方法(旧实现的副本)做 assertArrayEquals 逐位比对。后续再做优化时,按同样模式把参照实现留在测试里 —— 那是数值真相源,不是死代码。 顺手修掉的 native 内存滞留 文档方向预处理的中心裁剪子 Mat 视图与 resize 本体原先释放顺序颠倒(先放本体、后放视图),现改为「先视图、后本体」,引用计数 2 → 1 → 0 依次归零。 写反了不会立刻报错,只是 native 缓冲滞留到 GC —— 长时间跑批处理时,这是一笔看不见的账。 二、PDF 通道配置接通了 背景 v1.2.2 引入 PDF 双通道(文本层坐标抽取 + 渲染位图 OCR)时,mica.ai.ppocr.pdf.* 只停留在配置对象上,没有传到引擎。引擎的 PDF 入口始终用 PdfOcrConfig.defaults()。 实际表现是: render-dpi 调成 300 没反应,min-text-chars 调成 10 没反应 —— 参数写得对,行为纹丝不动。 现在 PPOcrV6Config 新增 pdfOcrConfig 字段,PPOcrV6Engine 构造期取它,PDF 入口(run(byte[]) / run(Path) 嗅探到 %PDF- 时)实际消费。图片通道不受影响。 参数 默认值 作用 render-dpi 200 渲染通道输出 DPI。扫描件内嵌位图有原始分辨率,超过原图信息量的重采样只会放大噪声,发票 / 证件类 200~300 为宜 min-text-chars 20 文本层可用所需的最小非空白字符数,低于则判定无文本层 min-readable-ratio 0.90 文本层可读字符占比下限。缺 ToUnicode 映射的 CID 字体会抽出一批私有区字符,拉低占比 force-ocr false 跳过文本层探测,所有页面强制走渲染 + OCR,用于竖排、页面旋转等文本层坐标不可信的版式 YAML 写法不变: mica: ai: ppocr: pdf: enabled: true render-dpi: 200 min-text-chars: 20 min-readable-ratio: 0.90 force-ocr: false 也可以直接用代码覆盖 —— 自定义一个 PdfOcrConfig Bean 即可(Spring @Bean / Solon @Configuration),引擎会直接采用它,无需再改 yml。 两处需要留意的行为变更 1. PdfOcrConfig Bean 现在就是引擎使用的配置,不再是只读副本。此前业务方自定义同名 Bean 会被静默忽略(容器里是自定义值、引擎仍用 yml 或默认值),现在会直接改变引擎行为。 2. pdf.enabled=false 时 Bean 仍然存在,取 PdfOcrConfig.defaults()(此前是不注册这个 Bean)。两端都容忍该 Bean 缺失(回落到 yml 派生值),不会因为排除自动配置类而启动失败。 两端默认值对齐了 v1.2.3 时 Starter 暴露的默认值是 minTextChars=10 / minReadableRatio=0.6,而引擎实际在用的是 20 / 0.90 —— 文档写 10、引擎跑 20。两端现已统一为 20 / 0.90,不配置即保持原有行为。 Solon 端此前还漏了 PdfAutoConfiguration 的注册,压根拿不到 PdfOcrConfig Bean,本次补上。 三、关掉总开关不再启动失败 背景 Spring 端的 StructuredParserAutoConfiguration 漏挂了 mica.ai.ppocr.enabled 这个闸门。 10 个解析器 Bean 都以 PPOcrV6Engine 为构造参数注入。主配置被关掉 ⇒ 引擎 Bean 不存在 ⇒ 抛 NoSuchBeanDefinitionException ⇒ 容器 refresh 直接失败。 也就是说,想用这个开关在某些环境关掉 OCR,结果应用启动失败。 现在 三个配置类统一挂到同一个闸门: Spring:@ConditionalOnProperty(prefix = "mica.ai.ppocr", name = "enabled", havingValue = "true", matchIfMissing = true) Solon:@Condition(onExpression = "${mica.ai.ppocr.enabled:true} == true") 关闭时容器里不注册任何 PP-OCR 功能 Bean(引擎 / 10 个解析器 / PPOcrTemplate / 配置对象),应用照常启动,可用于「同一套代码在部分环境不启用 OCR」的场景。 ⚠️ 行为变更: 关闭时两端都不再留下 PdfOcrConfig Bean —— Spring 端此前会残留一个(它的 PdfAutoConfiguration 只挂在 mica.ai.ppocr.pdf.enabled 上),Solon 端此前压根没注册过 PdfAutoConfiguration。 例外: OpenCVNativeLoader 不受该开关约束,OpenCV 原生库仍会加载。业务方若自行使用 org.opencv.*,需知晓这一点。 四、按版面类型声明 DB 检测参数 一个容易被误判的现象 海报类版面(大字号稀疏数字 + 满屏背景水印),rec 单独跑同一张图完全正确,det 却一个框都没给。 根因不在模型,而在 DB 后处理: boxScore 是框(minAreaRect)内概率图的平均值,本质是「框内文字像素占比」。这种版面上 DB 把 8 位大数字和背景水印连成一个整体轮廓,框内真正的笔画只占约 42%,低于默认 detBoxThresh=0.6 被直接丢弃。 模型看见了,是后处理过滤掉的。 排查时先把 det 的概率图 dump 成 PNG(目标区域纯白高响应即模型看见了),再复刻 DbPostProcessor.extractBoxes 逐条打印 origRect / minSideLen / score / PASS|DROP(原因),就能定位到是哪一条判据把它过滤掉了。 解法:解析器自己声明检测参数 BaseStructuredParser 新增 detParams() 钩子(默认 null = 引擎默认),一站式 parse(...) 自动带上,显式传入的 DbDetParams 优先。解析器可以按自己的版面类型声明专属参数,不影响同引擎上的其它解析器。 public class MyPosterParser extends BaseStructuredParser { @Override protected DbDetParams detParams() { // 放宽 boxThresh 让稀疏大字符框过关,同时收紧 unclipRatio 避免外扩把上下水印卷进来 return DbDetParams.of(0.3f, 0.4f, 1.0f); } // ... } 参数顺序是 DbDetParams.of(thresh, boxThresh, unclipRatio)。已落地在 PddLuckyBagParser.DET_PARAMS(0.3f / 0.4f / 1.0f)。 但别照抄这个参数 证件 / 票据类版面沿用引擎默认(min/64 + 0.6/1.5)。 不要改成 detLimitType=max + 大 detLimitSideLen —— 那会缩小整图,小字成片漏检(实测出租车票框数 55 → 26)。 不要靠调大 DbDetParams.minSize 过滤碎片 —— 会连小字标签一起丢(如行驶证「所有人」变 null)。 五、拼多多福袋类型识别 PddLuckyBagResult 新增 getType(),返回 PddLuckyBagType。两类分享图版式几乎一致(搜索邀请码 → 组队双方必得 → 大字号邀请码),仅靠文案区分: 枚举 含义 标题 口号 LUCKY_BAG 福袋券 百亿补贴 抽福袋 组队双方 必得现金或券 FRUIT 水果券 百亿补贴 水果分享券 组队双方 必得水果券 UNKNOWN 无法判定 特征文案缺失(如只识别出邀请码数字框) — fieldBoxes 同步回填 type 关键框。 六、其他修复与优化 识别 / 文档方向预处理显式校验输入为 8bit 3 通道:归一化按「每像素 3 字节」逐行读,而 Mat.get(row, 0, byte[]) 是从 (row, 0) 起连续读满数组长度 —— 通道数 3 会通道步长错位。OpenCV 虽有「缓冲长度须为通道数整数倍」的前置校验,但 1 通道(灰度图)恒能绕过。旧实现越界即抛 ArrayIndexOutOfBoundsException,故障模式由「立刻报错」退化为「静默产出错误张量」,现改为显式抛 IllegalArgumentException。 MemoryLeakReproTest 误报:判据参考点由 round 5 改为 max(round 5, round 10),并移除 stabilizeJvmMemory() 的早退守卫。round 5 紧跟强制 GC,是堆刚被 uncommit 的人为凹点,后续正常回升被算成「增长」;实测误报样本 round 20 仍比 baseline 低 26.8 MB,却因以 round 5 为参考被判成 +87 MB 泄漏。 结构化解析热路径分配优化:火车票解析器 3 处 Pattern.compile 提为类常量;户口本解析器标签片段数组提为类常量(消除逐框每次约 110 个 String 引用分配);银行卡持卡人反查 O(n²) → O(n)(语义不变)。 死代码清理:Offset.toFloat,以及 PDF 通道三个无 detParams 的私有重载。 升级指引 net.dreamlu mica-ppocr-spring-boot-starter 1.2.4 Solon 用户换 mica-ppocr-solon-plugin,纯 Java 用户换 mica-ppocr-core + mica-ppocr-structured。 升级前必读:行为变更汇总 变更 影响 应对 mica.ai.ppocr.pdf.* 真的生效了 之前靠改 yml 调 PDF 参数的用户会发现行为变了 —— 之前根本没生效 不配置即保持原行为;默认值两端已对齐 PdfOcrConfig Bean 会被引擎直接采用 自定义同名 Bean 会改变引擎行为,此前是静默忽略 检查自定义 Bean 是否符合预期 pdf.enabled=false 时 Bean 仍存在 取默认值 如依赖 Bean 缺失做判断,需调整 mica.ai.ppocr.enabled=false 时不再留下 PdfOcrConfig Bean 此前 Spring 会残留一个 按需改成读配置属性而非读 Bean 识别 / 文档方向预处理对非 8bit 3 通道 Mat 抛 IllegalArgumentException 此前要么越界异常,要么静默产出错误张量 传入前先转成 CV_8UC3 兼容性 Java 8 兼容不变,运行依赖字节码均为 major 52。 依赖版本:onnxruntime 1.18.0 / opencv 4.9.0-0 / jts-core 1.20.0 / pdfbox 3.0.8 / slf4j 2.0.20 / spring-boot 2.7.18 / mica-auto 2.3.5 / solon 4.1.1。 本版实际升级的依赖只有两项:slf4j 2.0.19 → 2.0.20、solon 4.1.0 → 4.1.1(均为小版本,向后兼容)。其余依赖版本未动。 Spring Boot Starter 与 Solon 插件能力对齐,类名一一对应。