---
url: https://www.dreamlu.net/mica-ppocr.md
---

# mica-ppocr（Java 图片 OCR 识别）

[![Java CI](https://github.com/lets-mica/mica-ppocr/actions/workflows/test-and-build.yml/badge.svg)](https://github.com/lets-mica/mica-ppocr/actions/workflows/test-and-build.yml)
![JAVA 8](https://img.shields.io/badge/JDK-8+-brightgreen.svg)
[![Mica Maven release](https://img.shields.io/maven-central/v/net.dreamlu/mica-ppocr-core.svg?style=flat-square)](https://central.sonatype.com/artifact/net.dreamlu/mica-ppocr-core/versions)

PP-OCRv6 文字检测 + 识别的 **Java** 实现，纯 ONNX Runtime 推理，**零 PaddlePaddle 依赖**。完整复现预处理 / 后处理（DB 后处理、CTC 解码、pyclipper 等价的多边形 unclip），并与 Python 参考实现保持 **bit-exact**（默认 CPU 单线程）。

除纯 OCR 外，本项目还提供**开箱即用的证件 / 票据结构化解析**，省去从零写标签匹配的工作。

## 📦 模块导航

| 模块 | 说明 |
| ---- | ---- |
| [mica-ppocr-core](/mica-ppocr/) | 核心引擎 `PPOcrV6Engine`：检测 → 排序 → 裁剪 → 识别 |
| mica-ppocr-structured | 结构化解析层，各证件 / 票据的 `XxxParser` |
| mica-ppocr-spring-boot-starter | Spring Boot 自动装配，注入 `PPOcrTemplate` 即可用 |

## ✨ 能力一览

### 核心引擎

* 公开入口只暴露 `String` / `File` / `Path` / `byte[]` 四种入参，内部自动完成 OpenCV `Mat` 解码与 release，**调用方无需关心 native 内存**。
* `run(...)` 完整 OCR（检测 → 排序 → 裁剪 → 识别）；`detect(...)` 仅检测。
* 可选 `doc_ori` 文档方向分类模型，检测前对整图做方向校正（4 类：0°/90°/180°/270°），避免用户侧倒拍 / 横拍导致识别失败。
* DB 阈值、识别批大小、ORT 线程数、GPU 加速等全部走 `PPOcrV6Config` 的 `@Builder`。

### 已实现的结构化解析器

| 解析器 | 结果类型 | 生产验证 |
| ------ | -------- | -------- |
| 行驶证 | `VehicleLicenseResult` | ✅ |
| 身份证（正反面自动判定） | `IdCardResult` | ✅ |
| 银行卡 | `BankCardResult` | — |
| 机动车驾驶证 | `DriverLicenseResult` | — |
| 营业执照 | `BusinessLicenseResult` | — |
| 增值税发票 | `InvoiceResult` | — |
| 火车票 | `TrainTicketResult` | — |
| 出租车票 | `TaxiReceiptResult` | — |
| 户口本（常住人口登记卡） | `HouseholdRegisterResult` | — |
| 拼多多福袋（8 位邀请码） | `PddLuckyBagResult` | — |

> 每个解析器同时提供静态 `parse(List<PPOcrV6Result>)` 与 SPI `parseResults(...)` 两种调用形式，便于自定义扩展。

## 🚀 快速开始

### 1️⃣ 添加依赖

```xml
<!-- 核心引擎 -->
<dependency>
    <groupId>net.dreamlu</groupId>
    <artifactId>mica-ppocr-core</artifactId>
    <version>${mica.ppocr.version}</version>
</dependency>

<!-- 或 Spring Boot Starter（自动传递 core + structured） -->
<dependency>
    <groupId>net.dreamlu</groupId>
    <artifactId>mica-ppocr-spring-boot-starter</artifactId>
    <version>${mica.ppocr.version}</version>
</dependency>
```

### 2️⃣ 准备模型

下载 PP-OCRv6 官方 ONNX 模型（det + rec）到 `models/ppocr-v6/{tier}/`：

| 档次 | 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 | 精度优先，字符集更全 |

> `medium` 的 det/rec 为 `.onnx.zip`，需解压后使用。

### 3️⃣ 跑通

**Spring Boot 入口**（详见 mica-ppocr-core 的 Spring Boot 章节）：

```java
@Autowired
private PPOcrTemplate ppocr;

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

**纯 Java 引擎**：

```java
try (PPOcrV6Engine engine = new PPOcrV6Engine(config)) {
    List<PPOcrV6Result> results = engine.run("_assets/test_images/vehicle/vehicle1.png");
    for (PPOcrV6Result r : results) {
        System.out.printf("%s  (%.3f)%n", r.text(), r.score());
    }
}
```

## 🛠️ 环境要求

| 组件 | 版本 | 说明 |
| ---- | ---- | ---- |
| JDK | 8+ | |
| ONNX Runtime | 1.18.0 | 内置原生库兼容更多操作系统版本 |
| OpenCV | 4.10.0-0 | 含 Windows/Linux/macOS 原生库 |
| JTS | 1.20.0 | 多边形偏移（pyclipper 等价物） |
| PDFBox | 3.0.8 | PDF 双通道（文本层抽取 + 渲染兜底） |

## ⚙️ 调优要点

* `intra-op-num-threads` 建议设为 CPU **物理核数**（非逻辑核）。
* CPU arena / memory pattern 自 v1.2.0 起**默认关闭**：动态分辨率下两者不归还内存给 OS，会导致内存持续增长直至 OOM（[issue #14](https://github.com/lets-mica/mica-ppocr/issues/14)），关闭约损失 10% 吞吐。输入分辨率固定且追求极致吞吐时可成对开启。
* GPU：替换为 `onnxruntime_gpu` 并设 `prefer-accelerator: true`，此时 `intra-op-num-threads` 设为 `1`（甚至 `0`），把并行让给 GPU。

## 🤖 AI 辅助开发

项目内置两个 skill，可通过 [skills.sh](https://skills.sh/) 一键安装：

```bash
npx skills add lets-mica/mica-ppocr
```

* `mica-ppocr-custom-parser` — 新增证件 / 票据解析器的完整开发链路
* `ocr-parser-optimizer` — 已有解析器的批量调优（跑批 → 失败模式诊断 → 最小改动 → 对比报告）

## 🔗 相关链接

* 源码：<https://github.com/lets-mica/mica-ppocr>
* 移植自 [AIwork4me/ppocrv6\_onnx](https://github.com/AIwork4me/ppocrv6_onnx) 的 `ppocrv6_onnx.py` 单文件参考实现

## 📄 License

Apache License 2.0