企业官网建设流程全解析

• 后端
• AI 应用
• NLP

本篇技术指南以 Xberg 仓库的 Java 自动化测试片段 ocr_paddle_backend.md 为核心骨架，讲解如何在 Java 中通过ExtractionConfig配置 PaddleOCR 后端：包括 OCR 语言选择、model_tier（模型等级）与model_version（模型代际）的完整含义与取值，并结合 PaddleOcrConfig 源码 剖析每个参数的默认值、作用范围与底层实现，帮助读者在实际项目中准确复现该配置并理解其运行原理。

一、示例场景：一段图片 URL 的 PaddleOCR 抽取

仓库中的 Java 片段演示了最典型的用法：传入一张 PNG 图片的 URL，通过 JSON 构造输入与配置，调用Xberg.extract完成 OCR 识别。其核心配置 JSON 如下：

{ "ocr": { "backend": "paddleocr", "enabled": true, "language": ["en"], "paddle_ocr_settings": { "language": "en", "model_tier": "mobile", "model_version": "pp-ocrv6" } } }

对应的 Java 代码完整逻辑：

import io.xberg.*; public final class Example { public static void main(String[] args) throws Exception { var inputJson = "{\"kind\":\"uri\",\"mime_type\":\"image/png\",\"uri\":\"https://example.com/images/test_hello_world.png\"}"; var input = JsonUtil.fromJson(inputJson, ExtractInput.class); var configJson = "{\"ocr\":{\"backend\":\"paddleocr\",\"enabled\":true,\"language\":[\"en\"],\"paddle_ocr_settings\":{\"language\":\"en\",\"model_tier\":\"mobile\",\"model_version\":\"pp-ocrv6\"}}}"; var config = JsonUtil.fromJson(configJson, ExtractionConfig.class); var result = Xberg.extract(input, config); System.out.println(result.results().get(0).content()); } }

这段代码包含三个要点：ExtractInput描述待抽取的文档来源（这里是uri类型的 PNG 图片，并显式声明mime_type）；ExtractionConfig承载 OCR 配置；Xberg.extract返回的结果对象中，results().get(0).content()即第一份文档的抽取文本。

二、backend 与 enabled：如何选中 PaddleOCR 引擎

在 OcrConfig 源码 中，backend字段声明支持的取值包括tesseract、paddleocr、paddle-ocr、sceptre、vlm。其中paddleocr与paddle-ocr均指向 PaddleOCR 引擎，默认值是tesseract，因此要切换到 PaddleOCR 必须显式设置"backend": "paddleocr"。

enabled: true控制 OCR 是否开启，默认即为true；当设置为false时，等价于父级ExtractionConfig上的disable_ocr: true——图片只返回元数据，PDF 走原生文本抽取而不触发 OCR 兜底，此时其余 OCR 配置一律被忽略。

三、language：识别语言的两种配置层级

配置 JSON 中有两处 language：

1. ocr.language（数组["en"]）：OcrConfig层的语言列表，默认["eng"]。在 ocr.rs 的反序列化逻辑中，它同时接受数组（如["en", "deu"]）、单个字符串（如"eng"）以及+连接形式（如"eng+deu"），数组是绑定对象 API 的规范形式。
2. paddle_ocr_settings.language（字符串"en"）：PaddleOcrConfig层的语言代码，直接决定 PaddleOCR 引擎加载哪个语言的识别模型。

源码中PaddleLanguage枚举（见 config.rs）定义了引擎支持的完整语言代码集合：

四、model_tier 与 model_version：模型选择的核心参数

示例中model_tier: "mobile"、model_version: "pp-ocrv6"是本次配置最值得展开的两个字段，它们共同决定加载的检测/识别模型的体积、精度与推理速度。

model_version：模型代际（默认pp-ocrv6）

• pp-ocrv6（默认）：引入统一的 CJK+拉丁+日韩识别模型，带medium/small/tiny三级模型等级；对于 v6 统一模型未覆盖的文字体系（阿拉伯文、西里尔文、天城文、希腊文、泰米尔文、泰卢固文、泰文），会自动透明回退到 PP-OCRv5 的按语种识别模型。
• pp-ocrv5：固定使用旧的按语种/统一模型族，此时model_tier取mobile或server。

model_tier：模型等级（默认mobile）

等级的具体含义随代际不同：

PP-OCRv5 下：

• mobile（默认）：轻量模型（检测约 4.5MB、识别约 16.5MB），下载与推理都快；
• server：大而准的模型（检测约 88MB、识别约 84MB），适合 GPU 或复杂文档。

PP-OCRv6 下：

• small：检测约 9.9MB，带完整的 18,708 字 CJK+拉丁+日韩识别字典；默认值mobile会解析到这一档，因此未做任何配置的抽取实际上使用的是 small 档；
• medium：检测约 62MB，字典相同，精度更高但 CPU 上显著更慢；旧的server档或任何无法识别的值都会解析到这里；
• tiny：检测仅约 1.8MB，但字典缩减到 6,904 字（约中/英），无法覆盖另外两档支持的书写体系。

源码注释特别强调了一个吞吐量要点：PaddleOCR 页面不并发——ONNX session 被互斥锁保护，线程预算全部用于算子内并行，因此多页文档的总耗时约等于页数乘以单页推理时间，模型等级的选择在多页文档上直接决定吞吐量。

缓存键与模型下载

在 backend.rs 中，模型缓存以"{model_version}/{model_tier}"作为键，即"pp-ocrv6/small"这类组合会各自独立缓存，同一代际内切换等级会触发对应模型的下载与缓存。模型文件按 Hugging Face Hub 约定缓存（可通过paddle_ocr_settings.cache_dir显式指定根目录），所以首次使用某个组合需要联网下载，之后直接复用本地缓存。

五、paddle_ocr_settings 的其余可调参数

PaddleOcrConfig还提供一批检测/识别相关的可配置项（默认值均来自 config.rs 的PaddleOcrConfig::new）：

值得留意的是enable_table_detection的坑：若把原来 Tesseract 的配置直接切到 PaddleOCR 且保持默认值，会静默地不产出任何 OCR 表格，需要表格输出时必须显式开启。

六、配置的三种落地方式：JSON、TOML 与环境变量

除 Java 片段中演示的 JSON 方式外，同一组配置还有两种等价写法：

TOML（配置文件中paddle_ocr_settings的典型用法，见 ocr.rs 文档注释）：

[ocr] backend = "paddleocr" enabled = true language = ["en"] [ocr.paddle_ocr_settings] language = "en" model_version = "pp-ocrv5" model_tier = "server"

环境变量（面向服务端部署）：在 env.rs 中，XBERG_OCR_MODEL_VERSION与XBERG_OCR_MODEL_TIER可分别设置与model_version、model_tier相同的两个键，用于环境变量驱动的服务配置：

export XBERG_OCR_MODEL_VERSION=pp-ocrv5 export XBERG_OCR_MODEL_TIER=server

环境变量方式适合在服务器上快速切换模型代际/等级而无需改动配置文件。

七、结果读取与工程建议

示例通过result.results().get(0).content()取回识别文本；results()返回的是按输入文档顺序排列的抽取结果列表，每个结果还携带元数据与页面级信息。工程实践上建议：

1. 对固定语种的业务，优先在paddle_ocr_settings.language中锁定语言代码，避免依赖默认en；
2. CPU 部署多页文档时默认mobile/small档即可；高精度需求再切server（v5）或medium（v6），并接受明显更长的单页耗时；
3. 需要表格输出时显式设置enable_table_detection: true；
4. 首次使用新模型组合前预留模型下载时间，或提前预热缓存。

八、验证依据

• 关联文档：ocr_paddle_backend.md，Java 端完整配置示例；
• 参数定义与默认值：PaddleOcrConfig，含model_tier/model_version的逐档说明、PaddleLanguage枚举及大量配置反序列化测试；
• 配置挂载点：OcrConfig 中的paddle_ocr_settings字段、TOML 示例与backend取值集合；
• 模型缓存键：backend.rs 中"{model_version}/{model_tier}"的缓存组织方式；
• 环境变量：env.rs 中的XBERG_OCR_MODEL_VERSION/XBERG_OCR_MODEL_TIER解析逻辑。

• 后端
• AI 应用
• NLP