Xberg Java 多语言 OCR 实战：以 Tesseract 语言列表识别英德法多语种文档

• 后端
• AI 应用
• NLP

本指南围绕 Xberg 文档仓库中的 Java 多语言 OCR 示例展开，讲解如何通过ExtractionConfig的OcrConfig.language列表，让 Tesseract 后端同时识别英文、德文、法文等多种语言的图片与扫描文档，并延伸到 CLI、配置文件等多入口的语言选择方式、各 OCR 后端的语言编码差异与安装前提。读完本文，你将掌握在 Java 绑定中配置多语言 OCR、校验语言包可用性、以及在不同后端间切换语言配置的完整实战方案。

一、从一个 Java 多语言 OCR 示例说起

仓库文档示例 ocr_multi_language.md 给出了最简洁的 Java 调用方式：把多个 Tesseract 语言代码作为 JSON 列表传入配置，一次提取即可识别多种语言：

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\":\"tesseract\",\"enabled\":true,\"language\":[\"eng\",\"deu\",\"fra\"]}}"; var config = JsonUtil.fromJson(configJson, ExtractionConfig.class); var result = Xberg.extract(input, config); System.out.println(result.results().get(0).content()); } }

这段代码有三个关键点：

1. 输入对象：ExtractInput通过JsonUtil.fromJson从 JSON 反序列化而来，kind: "uri"表示以 URI 方式提供文档，mime_type: "image/png"明确声明这是 PNG 图片——图片类输入总是需要 OCR 的；
2. 配置对象：ExtractionConfig内嵌ocr块，backend: "tesseract"选择 OCR 引擎，language: ["eng", "deu", "fra"]以**数组（列表）**形式声明三种语言；
3. 执行与输出：Xberg.extract(input, config)同步返回ExtractionResult，results().get(0).content()取出第一个文档的识别文本。

如果你更喜欢类型安全的构造器风格，仓库中对应的手工维护示例 ocr_multi_language.md 展示了完全等价的 Builder 写法：

import io.xberg.Xberg; import io.xberg.ExtractInputKind; import io.xberg.ExtractionResult; import io.xberg.ExtractedDocument; import io.xberg.ExtractionConfig; import io.xberg.ExtractInput; import io.xberg.OcrConfig; import java.util.List; ExtractionConfig config = ExtractionConfig.builder() .withOcr(OcrConfig.builder() .withBackend("tesseract") .withLanguage(List.of("eng", "deu", "fra")) .build()) .build(); ExtractionResult output = Xberg.extract( ExtractInput.builder().withKind(ExtractInputKind.URI).withUri("multilingual.pdf").build(), config ); ExtractedDocument result = output.results().get(0); System.out.println(result.content());

两种写法的语义完全一致：withLanguage(List.of("eng", "deu", "fra"))就是language: ["eng", "deu", "fra"]的面向对象表达。OcrConfig的 Builder 方法（withBackend、withLanguage等）在 api-java.md 中有完整说明。

二、理解ocr.language字段：列表是规范形式，"+" 是兼容语法

language字段是 Xberg 多语言 OCR 的核心配置项。在核心配置源码 ocr.rs 中可以看到其完整定义：

/// Language code(s) for OCR recognition. Defaults to `["eng"]`. For Tesseract, /// languages are joined with "+". /// /// A list is the canonical form and the only form accepted by the binding /// object APIs (Python, Node, PHP, WASM, etc.): `["eng", "deu"]`. When /// deserializing from a config file, JSON body, or the REST/MCP API, a /// single string is also accepted, either as one code ("eng") or /// "+"-joined ("eng+deu"). /// /// The four candle-based backends also use this list to decide which scripts are /// plausible in their output, dropping a line written in an unconfigured script. #[serde(default = "default_eng", deserialize_with = "deserialize_languages")] pub language: Vec<String>,

从这段源码注释可以提炼出几个重要结论：

• 默认值是["eng"]：不显式配置时，OCR 只识别英文；
• 列表（数组）是规范形式：所有绑定对象的 API（包括 Java 的withLanguage(List.of(...))）都只接受列表；
• 单字符串与 "+" 连接是反序列化兼容语法：在 TOML 配置文件、JSON 请求体或 REST/MCP API 中，既允许写"eng"，也允许写"eng+deu"——底层deserialize_languages会把它们拆分成等价的列表；
• 该列表不只服务 Tesseract：四个基于 Candle 的视觉语言模型后端（GLM-OCR、TrOCR、DeepSeek-OCR、PaddleOCR-VL）也会依据这份列表判断输出中哪些语言脚本是合理的，并丢弃那些"未配置脚本"的噪声行。

在多语言场景下，Tesseract 后端在真正执行时会把语言列表用"+"拼接成 Tesseract 要求的格式。这一逻辑位于 tesseract_backend.rs：

// `TesseractConfig::from` above takes its language from `tess_config.language`, which // silently discards `OcrConfig.language` (#1572). Reconcile the two through the shared // rule so an `OcrConfig(language=..., tesseract_config=...)` caller is not OCR'd in // English only. internal.language = config.effective_tesseract_language().join("+"); if internal.language.trim().is_empty() { internal.language = crate::core::config::ocr::DEFAULT_OCR_LANGUAGE.to_string(); }

也就是说：你在 Java 里写List.of("eng", "deu", "fra")，Xberg 底层会执行["eng", "deu", "fra"].join("+")，最终交给 Tesseract 的是eng+deu+fra。文档指南 ocr.mdx 中"Multiple Languages"一节也明确说明：Tesseract 用+连接多语言代码，PaddleOCR 与 VLM 后端则直接使用列表。

三、各 OCR 后端的语言编码体系

配置多语言前，先要清楚不同后端使用的语言编码各不相同。文档参考 ocr-languages.mdx 给出了权威对照：

以 Tesseract 为例，其语言覆盖面超过 100 种，既包含通用 ISO 639-3 代码，也包含文字变体与特殊用途代码。部分常用条目摘录如下（完整表格见 ocr-languages.mdx）：

注意equ（公式）和osd（方向/脚本检测）是特殊用途代码，分别用于数学公式识别和版面方向检测，并非普通自然语言。

四、语言包安装：Tesseract 多语言的必要前提

Tesseract 是系统包依赖，使用多语言前必须确保对应语言的 traineddata 语言包已安装。文档指南 ocr.mdx 给出了各平台安装方式：

# macOS —— 安装全部语言 brew install tesseract-lang # Ubuntu/Debian —— 按语言逐个安装 sudo apt-get install tesseract-ocr-deu # 德语 sudo apt-get install tesseract-ocr-fra # 法语 # 验证已安装语言 tesseract --list-langs

安装完成后，建议先在 Java 中跑一次单文档 OCR 提取（force_ocr可强制对已有文本层的 PDF 也执行 OCR）来确认绑定能找到 Tesseract。参考 ocr_extraction.md 中的 Java 完整示例：

import io.xberg.ExtractInput; import io.xberg.ExtractInputKind; import io.xberg.ExtractedDocument; import io.xberg.ExtractionConfig; import io.xberg.ExtractionResult; import io.xberg.OcrConfig; import io.xberg.Xberg; import io.xberg.XbergRsException; import java.util.List; public class Main { public static void main(String[] args) { try { ExtractionConfig config = ExtractionConfig.builder() .withForceOcr(true) .withOcr(OcrConfig.builder() .withBackend("tesseract") .withLanguage(List.of("eng")) .build()) .build(); ExtractInput input = ExtractInput.builder() .withKind(ExtractInputKind.URI) .withUri("scanned.pdf") .build(); ExtractionResult output = Xberg.extract(input, config); ExtractedDocument document = output.results().get(0); System.out.println(document.content()); } catch (XbergRsException e) { System.err.println("Extraction failed: " + e.getMessage()); } } }

缺失语言包时的行为：根据 ocr-languages.mdx 的"Fallback Strategy"一节，Tesseract 在请求的语言包未安装时会直接报错（而不是静默降级）；PaddleOCR 会回退到模型训练基础或返回错误；Candle 系列 VLM 则接受所有语言代码、尝试识别（优雅降级）。因此使用 Tesseract 多语言前，务必用tesseract --list-langs确认deu、fra等语言包已就位。

从测试基建也能看到这一约束的体现：契约用例 ocr_multi_language.json 专门验证"配置英德法三种语言"的场景，其skip原因明确写道——"Requires the eng, deu, and fra Tesseract traineddata packs; CI guarantees only English, and WASM bundles only English"（需要 eng/deu/fra 三份语言包，而 CI 只保证英文、WASM 也只内置英文）。该用例通过 mock 服务器提供test_hello_world.png，最终断言识别结果必须同时包含 "Hello" 与 "World"。

五、语言选择的优先级：CLI、JSON、配置文件、默认值

除了 Java 绑定内的配置对象，多语言还能通过 CLI 标志、内联 JSON、配置文件等多种入口设置。根据 ocr-languages.mdx 的"Configuration Precedence"，配置级联优先级从高到低为：

1. CLI 标志：--ocr-language eng或--ocr-language eng+deu；
2. 内联 JSON 配置：--config-json '{"ocr": {"language": ["eng", "deu"]}}'；
3. 配置文件：xberg.toml或xberg.yaml中的[ocr]段；
4. 默认值：后端默认语言行为（通常是英文或自动检测）。

# CLI：用 "+" 连接多个语言 xberg extract --ocr-language eng+deu+fra file.pdf

# xberg.toml：列表形式 [ocr] backend = "tesseract" language = ["eng", "deu", "fra"]

// 内联 JSON：列表形式 { "ocr": { "language": ["eng", "deu", "fra"] } }

无论哪种入口，最终都会归一化到OcrConfig.language: Vec<String>这一列表字段——这正是 ocr.rs 中deserialize_with = "deserialize_languages"所处理的兼容逻辑。顺带一提，环境变量XBERG_OCR_*也可在服务端配置中影响 OCR 行为，OCR_LANGUAGE还作为遥测约定字段出现在 conventions.rs。

六、语言检测与 OCR 的联动

如果你不确定文档使用什么语言，Xberg 提供了language-detection特性：先自动检测文档语言，再把检测结果交给 OCR。参考 ocr-languages.mdx 的"Language Detection"一节：

from xberg import ( ExtractInput, ExtractionConfig, LanguageDetectionConfig, OcrConfig, extract, ) config = ExtractionConfig( language_detection=LanguageDetectionConfig(enabled=True), ocr=OcrConfig(backend="tesseract", language=["eng"]), ) output = await extract(ExtractInput(kind="uri", uri="document.pdf"), config) document = output.results[0] print(document.detected_languages)

检测出的语言会出现在结果的detected_languages字段中，可据此动态构造后续的ocr.language列表——适合处理语言来源混杂的批量文档。语言检测的详细配置见 language-detection.mdx。

七、写在最后：多语言 OCR 的完整工作流

把本指南的知识串起来，一套健壮的 Xberg Java 多语言 OCR 工作流包含四步：

1. 确认后端与语言编码：默认 Tesseract 使用 ISO 639-3 三位码；PaddleOCR 用两位码（如en、zh_hans）；Candle VLM 兼容多种写法；
2. 安装语言包：brew install tesseract-lang或apt-get install tesseract-ocr-deu等，并用tesseract --list-langs验证；
3. 配置OcrConfig.language：Java 中用withLanguage(List.of("eng", "deu", "fra"))，或在配置文件/CLI 中用列表或+连接语法；
4. 校验输出：查看results().get(0).content()，必要时结合force_ocr、DPI 配置（ocr.mdx 中有 150/300/600 DPI 的精度权衡表）与语言检测结果调优。

进一步阅读：

• OCR 完整指南 —— 八个后端的对比、安装与配置
• OCR 语言支持参考 —— 各后端语言全覆盖表格与回退策略
• 配置参考 ——OcrConfig全部字段
• Java API 参考 —— Java 绑定完整方法签名
• 核心配置实现 ——language字段的底层定义与反序列化逻辑

• 后端
• AI 应用
• NLP