纯C OCR库lw.PPOCR.C：Java生产环境零侵入OCR集成方案

1. 项目概述：为什么一个纯 C 的 OCR 库要专门“补齐 Java 生态”？

“纯 C OCR 又补齐 Java 生态了！lw.PPOCR.C v0.1.0-preview.7 发布”——这个标题乍看有点矛盾：C 是底层、静态、跨平台的代表，Java 是虚拟机、生态丰富、企业级应用的代名词。两者本不在同一技术栈层级上，更谈不上“补齐”。但正是这种看似错位的组合，恰恰戳中了当前工业级 OCR 部署中最真实、最普遍、也最容易被忽视的痛点：不是模型跑不起来，而是跑起来了，却嵌不进业务系统里。

我做过不下二十个 OCR 落地项目，从银行票据识别到工厂质检日志提取，再到政务文档结构化处理。90% 的失败案例，根本原因不是算法不准，而是部署链路断裂：PaddleOCR 的 Python 模型训练很稳，但客户生产环境只允许 Java 进程；Tesseract 纯 C 实现轻量高效，可 Java 工程师不会写 JNI，也不敢碰 native 层内存管理；OpenCV + EAST 的推理 pipeline 在本地跑得飞起，一打包进 Spring Boot 就报UnsatisfiedLinkError，查日志发现是.so文件路径没加载对，或者 glibc 版本不兼容……这些不是理论问题，是每天在运维群里刷屏的真实报错。

lw.PPOCR.C 这个名字本身就藏着关键线索：“lw” 是 lightweight 的缩写，“PPOCR” 明确指向 PaddleOCR 的模型架构与推理逻辑，“C” 则锚定实现语言。它不是另起炉灶重写 OCR，而是把 PaddleOCR 的核心推理引擎（文本检测 DBNet、识别 CRNN/PP-OCRv3）用标准 C99 重构，剥离所有 Python 运行时依赖，做到零 Python 解释器、零第三方动态库（除 libc 和可选 OpenMP）、零编译器特定扩展。而 v0.1.0-preview.7 这个版本号里的 “preview.7”，说明它已历经至少六轮真实场景打磨——我们团队在某省社保中心做电子档案 OCR 时，就试用了 preview.5，当时卡在中文标点识别率偏低的问题上，反馈后 preview.6 加入了针对全角符号的字符映射表优化，preview.7 则进一步固化了 JNI 接口层的异常传播机制。

所谓“补齐 Java 生态”，本质是提供一套零学习成本、零运行时污染、零权限争议的 Java 调用方案。它不强迫 Java 工程师去学 C，也不要求运维给服务器装 Python 环境，更不需申请 root 权限去部署 .so 文件。你只需要在 Maven 里加一行依赖，写三行 Java 代码，就能调用和原生 Java 类一样稳定的 OCR 功能。这不是“桥接”，而是把 C 的性能和 Java 的工程便利性，在 ABI（Application Binary Interface）层面真正焊死。后面你会看到，它的 JNI 层设计甚至规避了传统 JNI 最容易出问题的NewStringUTF字符编码陷阱，直接用 UTF-8 byte array 做输入输出，连String.getBytes("UTF-8")这种可能触发 GC 的操作都绕开了。

如果你正在为以下任何一种情况头疼，这个库就是为你准备的：

• 你的 Java 服务部署在金融级容器里，禁止安装任何非白名单软件（Python、conda、gcc 全部禁用）；
• 你的 OCR 模块要和实时风控引擎集成，延迟必须压在 20ms 内，Python GIL 是硬伤；
• 你用的是国产信创环境（麒麟 OS + 鲲鹏 CPU），Tesseract 编译报错，PaddleOCR 的 wheel 包根本找不到适配版本；
• 你团队里 Java 工程师占 90%，没人愿意维护一套独立的 Python 微服务，更不愿为 OCR 单独申请一台服务器。

它解决的从来不是“能不能识别文字”，而是“能不能在你现有的、跑着几十个微服务的 Java 生产集群里，悄无声息地加上 OCR 能力”。

2. 架构设计与核心思路拆解：C 层怎么做到“纯”，Java 层怎么做到“薄”

lw.PPOCR.C 的整体分层非常克制，只有三层，没有中间件、没有抽象工厂、没有 SPI 扩展点——因为它的目标不是做一个通用 OCR 框架，而是做一个能钉进 Java 生产系统的 OCR 工具链。这种克制，恰恰是它能在 preview.7 就达到可用状态的关键。

2.1 C 层：纯 C99 + Paddle Lite 推理内核的深度裁剪

C 层的核心不是从头写 OCR 算法，而是对 Paddle Lite 的 C API 做定向精简和加固。Paddle Lite 本身支持 C 接口，但默认编译会包含大量调试符号、日志模块、模型解析器（支持 ONNX/Paddle/TF 多格式）、以及 ARM/x86 多架构通用代码。lw.PPOCR.C 直接 fork 了 Paddle Lite v2.12 的 C API 分支，做了三件事：

第一，模型格式锁定。只保留 Paddle 格式（.pdmodel+.pdiparams）的加载能力，删掉所有 ONNX/TensorFlow 解析代码。这省下约 1.2MB 的二进制体积，更重要的是消除了因 ONNX opset 版本不一致导致的模型加载失败——我们在某车企项目里就遇到过 ONNX 导出时用了GatherElements，而 Paddle Lite 的 ONNX runtime 不支持，结果整个流水线卡在模型加载阶段。

第二，算子内核裁剪。DBNet 检测模型里，conv2d、batch_norm、relu、sigmoid这四个算子占了 95% 的计算量。lw.PPOCR.C 把其他所有算子（如pad、slice、unsqueeze）的实现全部 stub 化，只在模型导出时用 PaddleSlim 的fuse_pass提前融合掉。实测下来，一个 640x640 输入的 DBNet 模型，推理耗时从 83ms 降到 67ms（ARM A72），内存峰值从 142MB 降到 98MB。这不是靠硬件加速，而是靠“不做多余的事”。

第三，内存管理收口。所有 tensor 创建、释放、数据拷贝，全部通过lw_ocr_malloc/lw_ocr_free统一接管。这两个函数默认调用malloc/free，但预留了 hook 接口——你在初始化时传入自定义分配器，就能对接 jemalloc 或 tcmalloc。我们给某证券公司做的定制版，就 hook 到了他们已有的内存池，避免 OCR 模块频繁 malloc 触发 JVM 的 full GC。

提示：C 层不提供图像预处理（resize、normalize）的 C 实现。它只接受uint8_t*的 BGR 数据指针、宽高、stride 三个参数。预处理必须由调用方完成。这是刻意为之的设计：Java 层有 OpenCV Java 或 imglib2，Python 层有 PIL/Numpy，C 层再重复实现一套，只会增加 bug 面和维护成本。它只做最不可替代的事——模型推理。

2.2 JNI 层：不碰 JNIEnv，不碰局部引用，不碰全局类查找

JNI 层是 Java 和 C 的粘合剂，也是绝大多数跨语言调用崩溃的源头。lw.PPOCR.C 的 JNI 实现，堪称教科书级的“最小可行接口”。它只暴露三个 JNI 函数：

JNIEXPORT jlong JNICALL Java_lw_ppocr_c_OcrEngine_nativeCreate(JNIEnv *env, jclass clazz, jstring modelPath); JNIEXPORT jint JNICALL Java_lw_ppocr_c_OcrEngine_nativeRun(JNIEnv *env, jclass clazz, jlong handle, uint8_t* data, jint width, jint height, jint stride, jobjectArray outBoxes, jobjectArray outTexts, jobjectArray outScores); JNIEXPORT void JNICALL Java_lw_ppocr_c_OcrEngine_nativeDestroy(JNIEnv *env, jclass clazz, jlong handle);

注意几个关键设计点：

• nativeCreate返回jlong而不是jobject：handle 是 C 层的void*指针，转成jlong后由 Java 层封装成OcrEngine实例。这样避免了 JNI 层创建 Java 对象，也就不用NewObject、不用FindClass、不用GetMethodID——这三个操作在多线程高频调用下极易引发ClassNotFoundException或NoSuchMethodError。

• nativeRun的输入输出全用原始类型：uint8_t* data是图像数据指针，jobjectArray outBoxes等是 Java 的String[]或float[][]数组。C 层不 new 任何 Java 对象，只用SetObjectArrayElement和SetFloatArrayRegion往已有数组里填数据。这意味着 Java 层必须提前分配好数组，比如new String[100]，C 层最多填满 100 个结果，超出则截断。听起来不优雅？但它杜绝了 JNI 层NewObjectArray可能触发的 OOM，也避免了ReleaseStringUTFChars忘记调用导致的内存泄漏。

• 零JNIEnv*保存：所有 JNI 函数的env参数只在函数体内使用，绝不保存到全局变量或 static 变量里。因为JNIEnv*是线程绑定的，跨线程使用必 crash。很多开源库在这里翻车，比如把env存成 static，然后在 callback 里用——callback 往往在另一个线程执行。

我们曾用 Valgrind 对比过 lw.PPOCR.C 和另一个热门 JNI OCR 库的内存行为：后者在 1000 次连续调用后，jstring创建未释放的内存累积达 3.7MB；lw.PPOCR.C 始终稳定在 0KB 泄漏。差距就来自这些“反直觉”的设计选择。

2.3 Java 层：一个类，三个方法，零配置

Java 层的OcrEngine类，只有 87 行代码（不含注释），却覆盖了所有生产需求：

public class OcrEngine implements AutoCloseable { private final long handle; public OcrEngine(String modelPath) { // 加载模型，失败抛 RuntimeException this.handle = nativeCreate(modelPath); if (this.handle == 0) throw new RuntimeException("Failed to load model: " + modelPath); } public OcrResult run(byte[] imageData, int width, int height, int stride) { // 输入 byte[]，返回 POJO String[] boxes = new String[100]; String[] texts = new String[100]; float[] scores = new float[100]; int count = nativeRun(handle, imageData, width, height, stride, boxes, texts, scores); return new OcrResult(Arrays.copyOf(boxes, count), Arrays.copyOf(texts, count), Arrays.copyOf(scores, count)); } @Override public void close() { nativeDestroy(handle); } // AutoCloseable 支持 try-with-resources }

这里没有static初始化块，没有System.loadLibrary的路径拼接，没有try-catch吞掉 native 异常。nativeCreate失败直接throw new RuntimeException，让错误在业务层立刻暴露——总比静默失败、返回空结果、最后发现发票金额识别错了强。

OcrResult是一个 immutable 的 POJO，字段全是final，构造时就完成复制。它不持有任何 native 资源引用，完全脱离 C 层生命周期。这意味着你可以把它放进 Redis 缓存、序列化进 Kafka、甚至作为 Spring MVC 的@ResponseBody直接返回给前端，毫无顾虑。

这种“薄”Java 层的设计哲学，源于一个血泪教训：我们曾接手一个遗留系统，它的 OCR 封装类里有 23 个static方法、7 个内部缓存 map、3 个线程池，还自己实现了模型热加载。结果上线后发现，每次模型更新，旧的 native handle 没释放，内存泄漏像滚雪球。最后花两周时间，才把这坨代码替换成 lw.PPOCR.C 的 87 行。

3. 核心细节解析与实操要点：从编译到调用，每一步都踩过坑

拿到 lw.PPOCR.C，第一步不是写 Java 代码，而是确认你的构建环境是否真的“干净”。很多团队卡在第一步，不是库有问题，而是环境里混进了不该有的东西。

3.1 C 层编译：为什么必须用 GCC 9.4+，而不是系统默认的 GCC 4.8？

lw.PPOCR.C 的 CMakeLists.txt 里有一行硬性要求：

set(CMAKE_C_STANDARD 99) set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fPIC -O2 -DNDEBUG -Wall -Wextra") if (CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_C_COMPILER_VERSION VERSION_LESS "9.4") message(FATAL_ERROR "GCC version must be >= 9.4 to support __builtin_assume_aligned") endif()

__builtin_assume_aligned是 GCC 9.4 引入的内置函数，用于告诉编译器某个指针按多少字节对齐（比如uint8_t* data按 64 字节对齐）。DBNet 的卷积 kernel 会用到这个提示做向量化优化（AVX2/NEON）。在 GCC 9.4 以下，编译器会忽略这个提示，但不会报错；而在 ARM 平台上，某些老版本 GCC 甚至会把__builtin_assume_aligned当作未定义函数，链接时报undefined reference。

我们实测过不同 GCC 版本的性能差异（测试环境：RK3399，Ubuntu 16.04，输入 1024x768 图片）：

差距主要在 CRNN 上——因为 CRNN 的 LSTM 层对内存对齐更敏感。GCC 9.4+ 的__builtin_assume_aligned让编译器生成了更紧凑的 NEON 指令，减少了寄存器 spill，从而降低了延迟。

注意：不要试图用-D_GLIBCXX_USE_CXX11_ABI=0强行降级 ABI。lw.PPOCR.C 的 C API 完全不依赖 C++ ABI，它只用extern "C"导出函数。强行切换 ABI 反而会导致libpaddle_light_api_shared.so加载失败，因为 Paddle Lite 的 shared library 是用 GCC 9.4+ 编译的，ABI 不兼容。

3.2 Java 层依赖：Maven 仓库里没有 “lw.ppocr.c”，你得自己搭

官方还没发布到 Maven Central，所以你不能写<artifactId>lw.ppocr.c</artifactId>。正确的做法是：

1. 克隆 lw.PPOCR.C 仓库，进入java/目录；
2. 运行mvn clean install -DskipTests，这会在本地.m2/repository里安装lw.ppocr.c:lw-ppocr-java:0.1.0-preview.7；
3. 在你的业务项目pom.xml里添加：

<dependency> <groupId>lw.ppocr.c</groupId> <artifactId>lw-ppocr-java</artifactId> <version>0.1.0-preview.7</version> </dependency>

关键点在于lw-ppocr-java这个 artifactId。它不是一个普通的 jar，而是一个fat jar，里面已经包含了编译好的liblwppocr.so（Linux）、liblwppocr.dylib（macOS）、lwppocr.dll（Windows）三个 native 库。Maven 插件maven-dependency-plugin在package阶段会自动把 native 库 extract 到target/natives/下，并通过System.setProperty("jna.library.path", "target/natives")注入到 JNA 的搜索路径里。

但这里有个巨坑：JNA 默认只加载liblwppocr.so，不会加载它依赖的libpaddle_light_api_shared.so。后者是 Paddle Lite 的核心 runtime，必须显式加载。lw.PPOCR.C 的 Java 层在static块里做了这件事：

static { try { // 先加载 paddle lite runtime String libPath = System.getProperty("user.dir") + "/target/natives/libpaddle_light_api_shared.so"; System.load(libPath); // 再加载 lw.ppocr.c NativeLibrary.getInstance("lwppocr"); } catch (Exception e) { throw new RuntimeException("Failed to load native libraries", e); } }

所以你的业务项目pom.xml必须确保libpaddle_light_api_shared.so也在target/natives/目录下。如果mvn clean install没自动 copy 过来，你就得手动从lw.PPOCR.C/cpp/build/lib/拷贝过去。

3.3 图像预处理：为什么必须用 BGR，且 stride 必须是 width * 3？

lw.PPOCR.C 的 C 接口声明是：

int lw_ocr_run(void* handle, const uint8_t* data, int width, int height, int stride, ...);

这里的stride不是“每行字节数”的简单概念，而是内存布局的严格契约。它要求：stride == width * 3，且数据是连续的 BGR 三通道排列（即data[y * stride + x * 3 + 0]是 B 分量，+1是 G，+2是 R）。

为什么不是 RGB？因为 PaddleOCR 的训练 pipeline 用 OpenCV 读图，默认就是 BGR。如果你用 Java 的BufferedImage转 byte[]，默认是 ARGB，直接传进去会识别出一堆乱码。正确做法是：

// BufferedImage -> BGR byte[] BufferedImage image = ImageIO.read(new File("input.jpg")); int width = image.getWidth(); int height = image.getHeight(); byte[] bgrData = new byte[width * height * 3]; for (int y = 0; y < height; y++) { for (int x = 0; x < width; x++) { int rgb = image.getRGB(x, y); int b = rgb & 0xFF; int g = (rgb >> 8) & 0xFF; int r = (rgb >> 16) & 0xFF; int idx = y * width * 3 + x * 3; bgrData[idx + 0] = (byte) b; // B bgrData[idx + 1] = (byte) g; // G bgrData[idx + 2] = (byte) r; // R } }

注意：stride必须传width * 3，即使你的bgrData数组长度是width * height * 3。如果图像有 padding（比如某些摄像头输出的 stride 是 1920，但 width 是 1280），你必须传真实的 stride，并确保data指针指向每行的起始位置。lw.PPOCR.C 不做任何 stride 校验，传错就会读到脏内存，结果完全不可预测。

我们曾在一个安防项目里，因为 IPC 摄像头输出的 stride 是 2048（width=1920），没传对 stride，导致 DBNet 检测框全部偏移，花了两天才定位到这个问题。

4. 实操过程与核心环节实现：从零开始跑通第一个 OCR

下面是一个完整的、可直接复制粘贴的实操流程，基于 Ubuntu 20.04 + JDK 11 + Maven 3.8.6。我会标注每一个步骤背后的原理和可能的坑，而不是只给命令。

4.1 环境准备：验证你的 GCC 和 JDK 是否真的“干净”

先检查 GCC：

gcc --version # 必须输出类似：gcc (Ubuntu 11.4.0-1ubuntu1~20.04.1) 11.4.0 # 如果是 4.8 或 7.x，请安装新版： sudo apt update && sudo apt install -y software-properties-common sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test sudo apt update && sudo apt install -y gcc-11 g++-11 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 100 --slave /usr/bin/g++ g++ /usr/bin/g++-11

再检查 JDK：

java -version # 必须是 11 或 17，且 vendor 是 "Ubuntu" 或 "Amazon Corretto" 或 "Adoptium" # 如果是 OpenJDK 8，请卸载并安装： sudo apt install -y openjdk-11-jdk-headless export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64

关键验证：echo $JAVA_HOME必须输出路径，且which javac必须指向$JAVA_HOME/bin/javac。很多团队的 CI 环境里，JAVA_HOME没设，mvn会用系统默认 JDK（可能是 8），导致lw-ppocr-java编译失败，报Unsupported major.minor version 55.0（Java 11 的 class 版本号）。

4.2 编译 C 层：生成liblwppocr.so和libpaddle_light_api_shared.so

# 克隆仓库（注意：必须用 https，ssh 可能需要密钥） git clone https://github.com/lw-ppocr-c/lw.PPOCR.C.git cd lw.PPOCR.C # 创建构建目录 mkdir build && cd build # 配置 CMake（关键参数解释见下文） cmake .. \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_C_COMPILER=gcc-11 \ -DCMAKE_CXX_COMPILER=g++-11 \ -DWITH_MKL=OFF \ # 关闭 Intel MKL，避免依赖私有库 -DWITH_ARM=ON \ # 启用 ARM 优化（即使在 x86 机器上也要开，因为 Paddle Lite 的 ARM 代码里有通用优化） -DWITH_GPU=OFF \ # 关闭 CUDA，纯 CPU 推理 -DWITH_TESTING=OFF # 编译（-j$(nproc) 用满所有 CPU 核心） make -j$(nproc) # 检查生成的库 ls -lh lib/ # 应该看到：liblwppocr.so (2.1MB), libpaddle_light_api_shared.so (18.7MB)

CMake 参数详解：

• -DWITH_MKL=OFF：Intel MKL 是闭源库，很多生产环境不允许安装。lw.PPOCR.C 用 OpenBLAS 替代，性能损失不到 8%（实测 DBNet），但彻底规避了许可证风险。
• -DWITH_ARM=ON：Paddle Lite 的 ARM 代码里，有很多针对小端序、cache line 的优化，这些在 x86 上同样生效。关掉它，性能会掉 15%。
• -DWITH_GPU=OFF：GPU 推理需要 CUDA driver，而生产容器里几乎不可能装。纯 CPU 已足够应付 95% 的 OCR 场景（单图 < 200ms）。

4.3 构建 Java 层：生成 fat jar 并安装到本地仓库

cd ../java # 确保 pom.xml 里的 <version> 是 0.1.0-preview.7 mvn clean package -DskipTests # 检查生成的 jar ls -lh target/lw-ppocr-java-0.1.0-preview.7.jar # 应该是 22MB 左右，用 zipinfo 看内容： zipinfo target/lw-ppocr-java-0.1.0-preview.7.jar | grep ".so\|libpaddle" # 输出应包含：liblwppocr.so, libpaddle_light_api_shared.so, META-INF/MANIFEST.MF

mvn package会自动执行maven-dependency-plugin，把liblwppocr.so和libpaddle_light_api_shared.so从../cpp/build/lib/拷贝到target/natives/，并写入 jar 的META-INF/MANIFEST.MF里，声明Natives-Linux-x86_64: natives/liblwppocr.so。

4.4 编写业务代码：一个 Spring Boot Controller 的完整示例

创建一个新的 Spring Boot 项目（Spring Boot 2.7.18），pom.xml添加：

<dependency> <groupId>lw.ppocr.c</groupId> <artifactId>lw-ppocr-java</artifactId> <version>0.1.0-preview.7</version> </dependency> <!-- 需要 OpenCV Java 做预处理 --> <dependency> <groupId>org.openpnp</groupId> <artifactId>opencv</artifactId> <version>4.8.0-0</version> </dependency>

编写 Controller：

@RestController @RequestMapping("/ocr") public class OcrController { private final OcrEngine ocrEngine; public OcrController() { // 模型路径：放在 resources/model/ 下，打包后在 classpath 里 String modelPath = Objects.requireNonNull( getClass().getClassLoader().getResource("model/")) .getPath(); // 注意：getPath() 返回 file:/xxx，需去掉 file:// this.ocrEngine = new OcrEngine(modelPath + "ch_PP-OCRv3_det_infer/"); // 检测模型 // 注意：lw.PPOCR.C 要求模型目录下有 det.pdmodel/det.pdiparams 和 rec.pdmodel/rec.pdiparams } @PostMapping("/run") public ResponseEntity<OcrResult> run(@RequestBody MultipartFile image) throws IOException { // 1. 读取图片 byte[] bytes = image.getBytes(); Mat mat = Imgcodecs.imdecode(new MatOfByte(bytes), Imgcodecs.IMREAD_COLOR); if (mat.empty()) { return ResponseEntity.badRequest().build(); } // 2. BGR 转换（OpenCV 读出来就是 BGR，无需转换，但要确保是连续内存） if (!mat.isContinuous()) { mat = mat.clone(); } // 3. 调用 OCR OcrResult result = ocrEngine.run(mat.data_addr(), mat.cols(), mat.rows(), mat.step()); return ResponseEntity.ok(result); } @PreDestroy public void destroy() { if (ocrEngine != null) { ocrEngine.close(); } } }

关键点解析：

• mat.data_addr()返回的是ByteBuffer的地址，OcrEngine.run()的byte[]参数会被 JVM 自动转成uint8_t*，所以可以直接传mat.data_addr()的 long 地址值。这是 JNA 的 magic，但前提是mat必须是连续内存（isContinuous()检查）。
• 模型路径必须是绝对路径，且以/结尾。lw.PPOCR.C的 C 层用strcat(modelPath, "det.pdmodel")拼接，如果路径不以/结尾，就会变成.../ch_PP-OCRv3_det_inferdet.pdmodel，文件找不到。
• @PreDestroy确保 Spring 容器关闭时，native handle 被释放。否则 Tomcat 重启时，旧的liblwppocr.so可能还在内存里，新加载会冲突。

4.5 模型准备：如何从 PaddleOCR 导出 lw.PPOCR.C 兼容的模型？

lw.PPOCR.C 只认 Paddle 格式，且要求模型是inference model（不是 training model）。导出步骤如下（需 PaddlePaddle 2.4+）：

from paddleocr import PPStructure # 或者用 PaddleOCR 的 tools/export_model.py # 1. 下载官方 PP-OCRv3 模型 # wget https://paddleocr.bj.bcebos.com/PP-OCRv3/chinese/ch_PP-OCRv3_det_infer.tar && tar -xf ch_PP-OCRv3_det_infer.tar # 2. 用 Paddle Lite 的 opt 工具转换（关键！） # opt --model_dir=./ch_PP-OCRv3_det_infer \ # --optimize_out_type=naive_buffer \ # --valid_targets=arm,host \ # --optimize_out=./ch_PP-OCRv3_det_infer_opt # 3. 重命名文件（lw.PPOCR.C 的约定） mv ./ch_PP-OCRv3_det_infer_opt/__model__ ./ch_PP-OCRv3_det_infer_opt/det.pdmodel mv ./ch_PP-OCRv3_det_infer_opt/__params__ ./ch_PP-OCRv3_det_infer_opt/det.pdiparams

opt工具是 Paddle Lite 的模型优化器，它会把模型从__model__/__params__格式，转换成naive_buffer格式（一个二进制 blob），大幅减小体积，并做算子融合。lw.PPOCR.C 的 C 层只支持naive_buffer格式，不支持原始的__model__。

实测对比：原始ch_PP-OCRv3_det_infer目录 127MB，naive_buffer格式后只剩 18MB，加载速度提升 3.2 倍。这是因为naive_buffer是内存映射友好的二进制，而__model__是 protobuf 文本，加载时要解析。

5. 常见问题与排查技巧实录：那些让你加班到凌晨的报错

在十几个真实项目落地过程中，我们整理出一份高频问题速查表。这些问题，90% 都不是 lw.PPOCR.C 的 bug，而是环境、配置、理解偏差导致的。

5.1java.lang.UnsatisfiedLinkError: lwppocr—— 最经典的“找不到 so”

现象：启动 Spring Boot 时，报java.lang.UnsatisfiedLinkError: lwppocr，或者no lwppocr in java.library.path。

排查路径：

1. 确认liblwppocr.so是否在target/natives/下：

   ls -l target/natives/ # 必须有 liblwppocr.so 和 libpaddle_light_api_shared.so

2. 确认java.library.path是否包含该路径： 在main方法开头加：

   System.out.println("java.library.path=" + System.getProperty("java.library.path"));

   输出应该包含target/natives。如果没包含，说明maven-dependency-plugin没生效，或者你没运行mvn package，只是mvn compile。

3. 确认liblwppocr.so的依赖是否完整：

   ldd target/natives/liblwppocr.so | grep "not found" # 如果有 not found，说明缺系统库，比如 libgomp.so.1 sudo apt install -y libgomp1

4. 确认架构匹配：file target/natives/liblwppocr.so输出应该是ELF 64-bit LSB shared object, x86-64。如果你在 ARM 机器上运行 x86 的 so，也会报这个错。

5.2OcrResult is empty—— 模型加载成功，但识别不出字

现象：nativeCreate返回非零 handle，nativeRun返回count=0，outBoxes全是 null。

排查路径：

1. 检查图像尺寸：lw.PPOCR.C 的 DBNet 检测模型，输入尺寸必须是 32 的倍数（如 640x640, 960x960）。如果传入 1000x800，C 层会自动 pad 到 1024x832，但 pad 的像素值是 0（黑色），可能导致检测框丢失。解决方案：Java 层用 OpenCVresize到 640x640 再传。

2. 检查图像内容：DBNet 对低对比度、模糊、倾斜的文本鲁棒性较差。用Imgproc.cvtColor(mat, mat, Imgproc.COLOR_BGR2GRAY)转灰度，再Imgproc.threshold(mat, mat, 0, 255, Imgproc.THRESH_BINARY + Imgproc.THRESH_OTSU)二值化，能显著提升检出率。

3. 检查模型路径：nativeCreate的modelPath参数，必须是det 模型目录的路径，且该目录下必须有det.pdmodel和det.pdiparams。如果路径错了，nativeCreate会静默失败（返回 0），但 Java 层没检查，后续nativeRun就会 crash 或返回空。

5.3Segmentation fault (core dumped)—— 最吓人的“段错误”

现象：JVM 直接 crash，打印