首页 > 开源 > mica-ppocr v1.2.3 发布：Java 8 兼容的 PP-OCRv6 纯 ONNX 推理引擎，内置 10 类证件/票据结构化解析

mica-ppocr v1.2.3 发布：Java 8 兼容的 PP-OCRv6 纯 ONNX 推理引擎，内置 10 类证件/票据结构化解析

OSChina资讯 2026-09-20 10:11 12 阅读 查看原文
OCR Java 开源

项目简介

mica-ppocr 是 PP-OCRv6 文字检测与识别流水线的 Java 移植版，使用纯 ONNX Runtime 推理、零 PaddlePaddle 依赖，并完整复现预处理 / 后处理（DB 后处理、CTC 解码、pyclipper 等价的多边形 unclip）。移植自 AIwork4me/ppocrv6_onnx 的单文件 Python 参考实现，与 Python 版本保持 bit-exact（默认 CPU 单线程，跨平台输出确定）。

定位上，mica-ppocr 不只是一个 OCR 引擎，更是一套面向证件 / 票据 / 卡证场景的端到端识别方案：

  • OCR 核心 mica-ppocr-core：检测 + 识别 + 文档方向分类 + PDF 双通道

  • 结构化解析 mica-ppocr-structured：内置 10 类常用证件 / 票据解析器

  • Spring Boot Starter mica-ppocr-spring-boot-starter：自动装配引擎与解析器，开箱即用

  • Solon 插件 mica-ppocr-solon-plugin：Solon 用户同等体验
    全模块 Java 8 兼容，已发布到 Maven Central，坐标 net.dreamlu:mica-ppocr-*。

核心特性

  • 零 Paddle 依赖：仅需 ONNX Runtime + OpenCV + JTS（PDF 模块再 + PDFBox），没有 C++ 编译、没有原生 Paddle 库，jar 包直跑。

  • 与 Python 参考 bit-exact：默认 intraOp=interOp=1，跨机器输出完全一致，便于回归测试与模型调优。

  • Java 8 全兼容：源码、依赖字节码均校验为 Java 8，可直接用于 Spring Boot 2.x / Solon 等 Java 8 老项目。

  • 10 类内置结构化解析器：行驶证、身份证（正反面自动判定）、银行卡、机动车驾驶证、营业执照、增值税发票（含新版数电票）、火车票、出租车票、户口本（常住人口登记卡）、拼多多福袋（8 位邀请码）。

  • PDF 双通道：run(byte[]) / run(Path) 自动嗅探 %PDF- 魔数，文字型 PDF 直接走 PDFBox 文本层抽取（无 OCR 开销），扫描件自动降级渲染位图 + OCR（DPI 可配）。

  • 文档方向分类（可选）：在检测前对整图做 4 类方向（0°/90°/180°/270°）校正，避免侧拍 / 横拍导致的识别失败。

  • 按调用覆盖检测阈值：run(...) / runMat(...) 新增 DbDetParams 重载，临时调整 thresh / boxThresh / unclipRatio 等，无需改动引擎配置，线程安全。

  • 可视化友好：结构化结果同时返回 rawResults（全部文字框）与 fieldBoxes（字段→坐标），可在前端高亮"这个字段来自画面哪几块"。

  • AI 协作原生支持：项目内置 mica-ppocr-custom-parser 与 ocr-parser-optimizer 两个 Skill，覆盖新增解析器全链路与已有解析器批量调优，可通过 npx skills add lets-mica/mica-ppocr 一键安装到 Claude Code / Cursor 等 AI 编码工具。

快速上手（Spring Boot 一行接入）

  • 引入 starter：

    net.dreamlu
    mica-ppocr-spring-boot-starter
    1.2.3

application.yml 指定模型路径：

mica:
  ai:
    ppocr:
      det-model-path: models/ppocr-v6/tiny/det.onnx
      rec-model-path: models/ppocr-v6/tiny/rec.onnx
      rec-char-dict-path: models/ppocr-v6/tiny/dict.txt

  • Controller 直接调：

@Autowired
private PPOcrTemplate ppocr;
@PostMapping("/ocr/vehicle")
public VehicleLicenseResult vehicle(@RequestParam MultipartFile file) throws IOException {
    return ppocr.vehicleLicense().parse(file.getBytes());  // 一行：检测 → 识别 → 结构化
}

已实现的结构化解析器

解析器

解析类

结果类型

行驶证

VehicleLicenseParser

VehicleLicenseResult

身份证（正反面自动判定）

IdCardParser

IdCardResult

银行卡

BankCardParser

BankCardResult

机动车驾驶证

DriverLicenseParser

DriverLicenseResult

营业执照

BusinessLicenseParser

BusinessLicenseResult

增值税发票（含数电票）

InvoiceParser

InvoiceResult

火车票

TrainTicketParser

TrainTicketResult

出租车票

TaxiReceiptParser

TaxiReceiptResult

户口本（常住人口登记卡）

HouseholdRegisterParser

HouseholdRegisterResult

拼多多福袋（8 位邀请码）

PddLuckyBagParser

PddLuckyBagResult

公共能力下沉在 LabelMatcher（标签定位 + 位置匹配 + 正则兜底 + 版面布局兜底）；新增自定义解析器只需实现 BaseStructuredParser 接口即可挂载到 PPOcrTemplate。

    

模型三档速览

档次

det 模型

rec 模型

字符表

定位

tiny

1.7 MB

4.3 MB

~2855 字符

轻量优先，速度快，精度一般

small

9.4 MB

20.2 MB

~2855 字符

速度与精度均衡，推荐默认

medium

59.2 MB

73.0 MB

~7180 字符

精度优先，覆盖更全字符集

可选文档方向分类模型 PP-LCNet_x1_0_doc_ori（6.47 MB），从 ModelScope 下载 model.onnx 即可，零 Paddle 依赖。

        

版本更新汇总（v1.0.0 → v1.2.3）

v1.2.3 - 2026-09-12（本次主推）

  • feat：run 系列方法全面支持按调用覆盖 DB 参数。run / runMat 新增 DbDetParams 重载（thresh / boxThresh / unclipRatio / maxCandidates / minSize），按调用临时调整检测阈值、无需改动引擎构造期配置，线程安全（临时构造 DbPostProcessor，不修改共享状态）；同步下沉到 PDF 双通道，BaseStructuredParser 新增 5 个 parse(..., DbDetParams) 重载，Spring Boot / Solon PPOcrTemplate 同步支持。

  • fix：修复词典空白 token 处理导致识别结果丢空格、英文单词粘连问题。CtcLabelDecoder 对齐 Python 参考实现（仅剥 \n\r），原样保留词典中间全角空格（U+3000）与末尾 ASCII 空格两个空白 token，并新增回归测试锁定。（GitHub #23）

  • fix：修复发票大写金额转换 parseJiaoFen 的整型隐患（curDigit 由 long 改为 int），消除 CodeQL 告警。

v1.2.2 - 2026-09-07

  • feat：新增 PDF 双通道模块，文字型 PDF 走文本层抽取（无 OCR 开销），扫描件自动降级 PDFBox 渲染位图（DPI 可配，默认 200）。

  • feat：新增 DbDetParams + detectMat(Mat, DbDetParams) 按调用覆盖 DB 阈值。（GitHub #24）

  • fix：修复发票商品名称跨行被误拆为两条明细。明细行的"锚"是数值列（金额 / 税额），InvoiceTableParser 新增续行合并。

  • fix：修复 GPU 加速 provider 未注册问题。

v1.2.1 - 2026-09-01

  • feat：优化行驶证结构化解析。

  • feat：发票解析统一入口 + 支持新版电子发票（数电票）。

  • fix：修复发票解析器地址电话 / 开户行账号多框拼接与发票号码解析。

v1.2.0 - 2026-08-27

  • fix：根治动态分辨率下内存持续增长（GitHub #14）。新增 enableCpuMemArena（默认 false）、enableMemoryPattern（默认 false）配置，关闭 ONNX Runtime CPU arena / 内存模式优化，临时内存用完即释放，Docker 等内存受限环境不再 OOM；新增 execMode 配置（sequential / parallel）暴露 ORT 执行模式。

  • refactor：全面支持 Java 8。record / List.of / Path.of 等 Java 9+ API 替换为 CollUtil 工具与 Lombok @Value 风格；Spring Boot Starter 改用 @Configuration 兼容 2.5~4.x。

v1.1.7 - 2026-08-26

  • feat：新增拼多多福袋 OCR 结构化解析器，从"百亿补贴 抽福袋"分享图提取 8 位福袋码（邀请码）。

  • feat：身份证性别解析支持合并框切割，兼容"性别男民族汉"双标签连写合并框及"性""别"字缺失场景。

  • fix：优化身份证地址跨行解析逻辑与消除多标签合并框告警。

  • fix：提升身份证识别精度。

  • fix：新增真实 OCR 样本单元测试验证合并框"所有人 xxx"正确剥离前缀。

  • fix：修正户籍信息日期识别和关系字段匹配逻辑。

  • fix：修复 PPOcrV6Engine.decodeMat 泄漏 MatOfByte native buffer。

v1.1.6 - 2026-08-21

  • fix：还原 detLimitSideLen、detLimitType 默认组合为 64 + min，更适合证件类解析。

v1.1.4 - 2026-08-21

  • feat：新增火车票、出租车票、户口本（常住人口登记卡）OCR 结构化解析器。

  • feat：兼容 15 位身份证号解析，并增加按身份证号推算出生日期的兜底。

  • feat：模型路径支持 classpath: 前缀，可把模型打进 Spring Boot Fat Jar。

  • refactor：文档方向分类阈值由 0.3 调至 0.4；detLimitSideLen、detLimitType 默认组合由 64 + min 改为 960 + max（PaddleX v4 / v5 / v6 官方推荐组合）。

  • refactor：简化 PPOcrTemplate 结构化解析器管理实现，Solon 与 Spring Boot Starter 同步新增户口本解析器注册及参数校验。

  • docs：新增 mica-ppocr-custom-parser skill，覆盖自定义结构化解析器全链路。

v1.1.3 - 2026-08-15

  • feat：身份证多标签合并框解析逻辑优化，新增正面字段标签数组，支持"性别男民族汉"双标签连写的合并框切分。

  • refactor：重构结构化解析器基类及测试基类。BaseStructuredParser 由接口改为抽象类，统一持有 PPOcrV6Engine 引擎并提供一站式 parse() 实现，子类构造时绑定引擎、仅需重写 parseResults。

  • refactor：简化 PPOcrTemplate 模板，各个结构化解析器改为链式调用。

v1.1.2 - 2026-08-13

  • feat：新增 Solon 插件适配模块 mica-ppocr-solon-plugin，提供 PPOcrTemplate 一站式封装与结构化解析器自动装配，能力与 Spring Boot Starter 对齐。

  • feat：新增营业执照结构化解析器（BusinessLicenseParser），抽取社会信用代码、单位名称、住址、法定代表人、有效日期至、成立日期、类型、注册资本、经营范围共 9 个字段。

  • feat：新增增值税发票结构化解析支持（InvoiceParser），配套上海 / 湖北 / 江苏等多张发票 OCR JSON 样本。

  • refactor：优化 BusinessLicenseParser 编码规范，12 个 LABEL 常量、5 个调参常量集中化、4 个子函数便于单测。

  • refactor：结构化解析模块日志级别全面由 info 调整为 debug，显著降低控制台噪音。

v1.1.1 - 2026-08-13

  • feat：支持 PP-OCRv6 文档方向分类（use_doc_orientation_classify）。使用 PP-LCNet_x1_0_doc_ori 模型（4 类：0°/90°/180°/270°），在 OCR 检测前对整图做方向校正。新增 useDocOrientationClassify / docOrientationModelPath / docOrientationThresh 配置项，行为完全向后兼容（默认关闭）。

  • perf：性能优化 + 修 native Mat 泄漏。DocOrientationPreprocessor 修 resizeShort 返回新 Mat 未 release 的泄漏；CtcLabelDecoder 解码循环 3 合并为 1 次。

  • chore：onnxruntime 依赖版本降级为 1.18.0，兼容更多系统版本。

v1.1.0 - 2026-08-12

  • feat：新增 mica-ppocr-structured 结构化解析模块，支持行驶证、身份证、银行卡、驾驶证 4 类证件；提供 SPI 接口 BaseStructuredParser 与公共骨架 LabelMatcher（标签定位 + 位置匹配 + 正则兜底）。

  • feat：新增 PPOcrTemplate 一站式封装（mica-ppocr-spring-boot-starter），自动装配 PPOcrTemplate 与 4 个结构化解析器 Bean。

  • feat：结构化结果支持可视化坐标，新增 BaseStructuredResult 抽象类，统一持有 rawResults（完整 OCR 原始框）与 fieldBoxes（字段→坐标列表映射）。

  • refactor：公开 API 去掉 Mat 入参；PPOcrV6Engine 的 run / detect 统一委托到 Path 版本，新增 String / File / Path / byte[] / InputStream 5 种入参重载；内部统一 try-finally 释放 Mat，调用方无需任何 native 内存管理。

v1.0.1 - 2026-08-10

  • fix：释放原生推理资源，避免本地句柄泄漏；新增泄漏回归测试并加固构造器清理路径。

  • refactor：OpenCV 加载方法由 loadShared 改为 loadLocally。

v1.0.0 - 2026-08-07

  • feat：实现 PP-OCRv6 文字检测与识别核心功能（DB 后处理 + CTC 解码）。

路线与计划

  • 持续打磨已实现的 10 类结构化解析器精度与鲁棒性。

  • 跟进 PaddleOCR / PP-OCR 系列新模型（如更高精度模型、行业版模型）。

  • 持续完善 PDF 双通道与文档方向分类的边界场景。

  • 欢迎社区贡献：自定义解析器、更多 OCR 噪声场景 case、Spring Boot / Solon 生态适配。

相关推荐