在 Kotlin Android 应用中配置 PaddleOCR 后端：语言、模型层级与模型版本实战指南

• 后端
• AI 应用
• NLP

导读

本文基于 xberg 开源仓库中的 Kotlin (Android) PaddleOCR 配置片段，系统讲解如何在 Android 应用内通过ExtractionConfig选择 PaddleOCR 后端，并精确控制 OCR 语言、模型层级（model_tier）与模型版本（model_version）。读完本文，你将掌握从构造ExtractInput、拼装paddle_ocr_settings到调用Xberg.extract的完整链路，并理解每个配置项的默认值、取值范围及其背后的模型下载与推理机制。

PaddleOCR 后端：何时选择，需要什么前提

PaddleOCR 是 xberg 内置的 OCR 后端之一，底层基于 ONNX Runtime（可选纯 Rust 的tract引擎）运行 PP-OCR 检测 / 方向分类 / 识别三段式模型，在 CJK（中、日、韩）等脚本上表现优异，且不依赖 Python 运行时。从 crates/xberg/src/paddle_ocr/mod.rs 的模块说明可以看到，PaddleOCR 需要三类 ONNX 模型文件：

• 检测模型（*_det_*.onnx）
• 方向分类模型（*_cls_*.onnx）
• 识别模型（*_rec_*.onnx）

这些模型在首次使用时通过标准 Hugging Face 缓存（HF_HUB_CACHE、HUGGINGFACE_HUB_CACHE或$HF_HOME/hub）自动下载。需要特别说明的运行前提：

• 必须使用启用了 PaddleOCR 的原生（native）构建（对应 Cargo feature 如paddle-ocr-ort/paddle-ocr-tract）；
• 首次调用会触发模型权重下载，因此需要网络可达且具备模型缓存目录；
• 契约测试 fixtures/contract/ocr_paddle_backend.json 中明确标注：标准 E2E 任务不预置 PaddleOCR 构建与权重，浏览器 WASM 构建也不包含 PaddleOCR，因此该测试在多数语言下被跳过。

完整配置示例：Kotlin (Android) 中的 PaddleOCR 调用

原文档给出了一个可直接复刻的 Kotlin 示例，其核心思路是：用 Jackson（jacksonObjectMapper+SNAKE_CASE命名策略）将 JSON 字符串反序列化为类型化的ExtractInput与ExtractionConfig，再交给Xberg.extract执行。

import io.xberg.* import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper fun main() = kotlinx.coroutines.runBlocking { val mapper = jacksonObjectMapper().setPropertyNamingStrategy(com.fasterxml.jackson.databind.PropertyNamingStrategies.SNAKE_CASE) val input = mapper.readValue("{\"kind\":\"uri\",\"mime_type\":\"image/png\",\"uri\":\"https://example.com/images/test_hello_world.png\"}", ExtractInput::class.java) val config = mapper.readValue("{\"ocr\":{\"backend\":\"paddleocr\",\"enabled\":true,\"language\":[\"en\"],\"paddle_ocr_settings\":{\"language\":\"en\",\"model_tier\":\"mobile\",\"model_version\":\"pp-ocrv6\"}},\"url\":{\"crawl\":{\"ssrf\":{}}}}", ExtractionConfig::class.java) val result = Xberg.extract(input, config) println(result.results.first().content) }

代码要点拆解：

• 输入声明：kind: "uri"表示按 URI 拉取文档，mime_type: "image/png"显式声明图片类型，避免依赖内容嗅探；
• OCR 配置：backend: "paddleocr"显式选择 PaddleOCR 后端，enabled: true开启 OCR，language: ["en"]声明顶层语言候选；
• PaddleOCR 专属设置：paddle_ocr_settings内层进一步指定language: "en"、model_tier: "mobile"（移动端轻量模型）与model_version: "pp-ocrv6"（第六代模型）；
• SSRF 防护："url":{"crawl":{"ssrf":{}}}是为远程 URI 请求声明 SSRF 防护配置，所有涉及远程拉取的 E2E 用例（参见 e2e/kotlin_android/src/test/kotlin/io/xberg/e2e/ContractTest.kt）都携带该字段。

从配置解析的实现看，paddle_ocr_settings会被反序列化为类型化的PaddleOcrConfig结构体（见 crates/xberg/src/core/config/ocr.rs 中的test_paddle_ocr_settings_deserializes_to_typed_struct测试），未显式给出的字段自动落到默认值。

paddle_ocr_settings 字段全解：默认值与取值范围

PaddleOcrConfig定义于 crates/xberg/src/paddle_ocr/config.rs，除本文主题的language/model_tier/model_version外，还提供一组检测与识别的调参项。下表汇总了字段、默认值及取值范围（全部来自PaddleOcrConfig::new默认实现与 builder 方法的 clamp 逻辑）：

其中det_db_thresh、det_db_box_thresh、drop_score、padding等字段在 crates/xberg/src/paddle_ocr/config.rs 的 builder 方法中均做了clamp约束（如det_limit_side_len限制在 64–4096），因此在 JSON 中传入越界值也不会产生非法配置。

此外，该结构体保留了与早期 Node 绑定一致的 camelCase 兼容别名（如cacheDir、useAngleCls、modelTier），由LEGACY_CAMEL_CASE_FIELD_ALIASES映射到 snake_case 规范字段；同时存在#[serde(deny_unknown_fields)]严格反序列化，未知键会直接报错，避免静默吞掉拼写错误。

model_tier 与 model_version：如何选择模型规模

model_tier与model_version是本文档的主题参数，二者的组合语义在PaddleOcrConfig的字段注释中有完整说明：

当model_version = "pp-ocrv5"（第五代，按脚本分族）：

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

当model_version = "pp-ocrv6"（默认的第六代，统一中英日韩模型）：

• small：检测约 9.9MB，带完整 18,708 字 CJK+Latin+JA/KO 识别词典。默认的mobile在此代会解析为small，也就是说一个未配置 tier 的提取请求实际使用的就是该档；
• medium：检测约 62MB，同一词典，精度更高但在 CPU 上明显更慢；遗留的server档或任何未识别值都会解析到这一档；
• tiny：检测仅约 1.8MB，但只有缩减的 6,904 字（约中/英）词典，无法识别另外两档覆盖的其它文字系统。

脚本回退机制：PP-OCRv6 统一识别模型未覆盖的脚本（阿拉伯文、西里尔文、天城文、希腊文、泰米尔文、泰卢固文、泰文）会透明回退到 PP-OCRv5 的按脚本识别模型。需要固定旧版模型时，显式选择model_version: "pp-ocrv5"即可。

对吞吐量的实际影响：从 crates/xberg/src/paddle_ocr/backend.rs 的实现看，PaddleOCR 的 ONNX 会话被互斥锁保护，同一池键下页面 OCR 不并发执行，线程预算投入 intra-op 并行，整体耗时近似「页数 × 每页推理时间」。因此对多页文档，model_tier的选择直接主导吞吐量——批量扫描场景建议从small/mobile档起步，精度敏感场景再评估medium/server。

支持的语言列表

PaddleLanguage枚举（crates/xberg/src/paddle_ocr/config.rs）定义了后端可识别的语言代码，包括：en（英语）、ch（简体中文）、jpn（日语）、kor（韩语）、deu（德语）、fra（法语）、latin（拉丁语系）、cyrillic（西里尔文）、chinese_cht（繁体中文）、thai（泰文）、greek（希腊文）、eslav（东斯拉夫语系）、arabic（阿拉伯文）、devanagari（天城文）、tamil（泰米尔文）、telugu（泰卢固文）。

对应的测试test_paddle_language_code/test_paddle_language_from_code验证了这些代码与枚举的互转关系。在paddle_ocr_settings.language中填写的字符串即上述代码之一。

模型下载、缓存与校验机制

从 crates/xberg/src/paddle_ocr/model_manager.rs 可以看到模型的来源与可靠性设计：

• 模型仓库固定为 Hugging Face 上的xberg-io/paddleocr-onnx-models，并锁定到不可变 revisionbc5ec866cf0e798e667808dfa51b0ba8ad0dafc8；
• 下载流程为：先解析本地 Hub 缓存中的不可变 revision → 缓存未命中时下载（除非启用 Hugging Face 离线模式）→每次冷热解析都校验 SHA-256 并修复损坏条目→ 直接返回快照产物路径；
• PP-OCRv5 的 9 个按脚本分族识别模型（latin、korean、eslav、thai、greek、arabic、devanagari、tamil、telugu）各自带独立的 model 与 dict 双重 SHA-256 校验值；
• 检测模型按 tier 分文件管理（V2DetModelDefinition），统一多语识别模型按池键（如unified_server、unified_mobile、en_mobile）组织（V2RecModelDefinition）。

这一设计意味着：首次在 Android 应用中触发 PaddleOCR 时会有一次模型下载过程，之后走本地缓存；任何一次损坏都会被 SHA-256 校验发现并自动修复，避免静默加载坏模型。

推理引擎：ORT 与 Tract 两条路径

PaddleInferenceBackend枚举（crates/xberg/src/paddle_ocr/config.rs）区分两种推理引擎：

• ort：原生 ONNX Runtime 全功能路径，支持加速 / 执行提供方挂钩（CUDA、TensorRT、CoreML、Auto、CPU）以及 ONNX 内嵌词典元数据；
• tract：纯 Rust、仅 CPU 的 ONNX 路径，用于无法链接ort的目标平台（如 Android x86_64 模拟器，以及未来接入的 WASM）。

缺省时按编译特性解析：启用了paddle-ocr-ortfeature 则用ort，否则用tract。若在配置中显式请求了未编译进来的引擎，会在构造 OCR 引擎时直接报配置错误，而非静默回退（参见effective_backend的实现）。从backend.rs的engine_pool_key可以看出，引擎池键会同时折叠version/tier/model_key/accel/backend五个维度，保证同一配置复用同一会话，而不同加速配置（如cuda:0与cpu）不会互相污染。

契约测试与验证闭环

原文档对应的契约测试是 fixtures/contract/ocr_paddle_backend.json，它给出了同一配置在服务端契约测试中的形态：

• 输入为 URI 指向的image/png（mock 响应映射到test_documents/images/test_hello_world.png）；
• 配置与文档示例一致：backend: "paddleocr"、language: ["en"]、paddle_ocr_settings: {language: "en", model_tier: "mobile", model_version: "pp-ocrv6"}；
• 断言包括results[0].mime_type == "image/png"以及results[0].content同时包含Hello与World两个词，即图片 OCR 必须正确识别出这两词；
• 该测试同样被列为「需要 PaddleOCR-enabled 原生构建 + 已下载模型权重」，因此在标准 CI 中按语言跳过。

而在 Android/Kotlin 的 E2E 测试中（e2e/kotlin_android/src/test/kotlin/io/xberg/e2e/ContractTest.kt），可以看到完全相同的调用模式：MAPPER.readValue(json, ExtractionConfig::class.java)+Xberg.extract(input, config)。其中testConfigOcrPipelineNestedTypes用例进一步演示了在 OCR pipeline 的 stage 内嵌入paddle_ocr_settings（含enable_table_detection: true、model_tier: "server"、use_angle_cls: true），说明paddle_ocr_settings既可用于顶层ocr段，也可用于 pipeline 各阶段的类型化配置。

实战注意事项

1. 表格检测默认关闭：enable_table_detection默认false，与 Tesseract 后端默认开启不同。原因在于 PaddleOCR 没有 Tesseract TSV 那样的逐词表格候选置信度信号，每个识别词都会成为聚类候选，未过滤的聚类会在普通散文上过度生成表格。因此从 Tesseract 切换到 PaddleOCR 时，默认不会产出 OCR 表格；需要表格时务必显式开启该选项（参见 crates/xberg/src/paddle_ocr/config.rs 中的字段注释与固定测试）。
2. 方向分类谨慎开启：use_angle_cls在短文本区域可能误判方向、错误旋转裁剪块，仅在语料确有旋转文本时启用。
3. 批量识别调优：对长文档可适当提高rec_batch_num（上限 64）以提升识别吞吐；drop_score用于过滤低置信噪声行。
4. Android 平台注意：x86_64 模拟器等无法链接ort的目标建议使用tract引擎；在真机上可配置ort并搭配执行提供方（如 CoreML/GPU）加速。
5. 模型缓存规划：首次运行会下载模型（PP-OCRv6small档检测约 9.9MB），需在网络环境与存储规划上留出空间，可通过cache_dir指定应用私有目录，便于 APK 内预置或预下载。

以上内容完整覆盖了原文档的 Kotlin (Android) PaddleOCR 配置骨架，并依据 crates/xberg/src/paddle_ocr/config.rs、crates/xberg/src/paddle_ocr/model_manager.rs、crates/xberg/src/paddle_ocr/backend.rs 以及 fixtures/contract/ocr_paddle_backend.json 等仓库内证据展开，帮助你从「能跑」到「会调」。

• 后端
• AI 应用
• NLP