后端AI 应用NLP【免费下载链接】xbergPolyglot document intelligence with a Rust core: extract text, metadata, images, tables, and structured data from 106 formats across 140 file extensions, plus code intelligence for 371 languages. Fifteen bindings, with CLI, REST API, and MCP server.项目地址https://gitcode.com/gh_mirrors/kr/xberg点击查看免费下载本篇技术指南聚焦 xberg 文档抽取库 Java 绑定中的force_ocr配置项讲解如何对本身已携带原生文本层的 PDF 强制执行 OCR覆盖配置结构、Java 代码写法、底层路由原理与契约测试验证帮助开发者在需要统一 OCR 输出、修复劣质文本层或处理扫描版 PDF 时快速落地。一、为什么需要 force_ocr强制 OCR 的典型场景xberg 的默认行为是能用原生文本就用原生文本PDF 一旦带有文本层抽取器会优先读取该层只有文本层质量不达标时才回退到 OCR。这一默认策略在绝大多数场景下既快又准但也存在几个无法覆盖的盲区可搜索 PDF 的文本层质量不可信某些 PDF 虽然带文本层内容却是错位的、乱码的或缺失字形的肉眼看到的页面与提取出的文本完全对不上扫描件携带 OCR sidecar扫描仪的不可见 OCR 侧边文本层sidecar能通过质量检查此时原生抽取返回的是 sidecar 文本而非真实图像内容需要统一 OCR 输出批量处理混合文档时希望所有页面都走同一套 OCR 引擎与语言配置保证结果一致性而不是原生层与 OCR 层混用。force_ocr正是为这些场景设计的开关。从 xberg 源码定义看它是ExtractionConfig顶层的一个布尔字段注释直白地写着 Force OCR even for searchable PDFscrates/xberg/src/core/config/extraction/core.rs含义就是即使 PDF 有文本层也把每一页都送去 OCR。二、配置结构force_ocr 在 ExtractionConfig 中的位置force_ocr不是 OCR 引擎自身的参数而是文档级抽取配置ExtractionConfig的顶层字段与ocr配置块平级。在 crates/xberg/src/core/config/extraction/core.rs 中可以看到与之相关的完整字段族字段类型作用force_ocrbool强制对整份 PDF 的所有页面执行 OCR忽略文本层是否存在及其质量force_ocr_pagesOptionVecu32仅强制 OCR 指定页码1 起始未列出的页面走原生文本抽取force_ocr为true时该字段被忽略ocrOptionOcrConfigOCR 引擎与语言配置不设置时使用默认值ocr_strategyOcrStrategy不满足force_ocr/force_ocr_pages时决定哪些页面走 OCR 的选择策略默认Auto仅对质量不合格的页面 OCRdisable_ocrbool彻底禁用 OCR不能与force_ocr同时为true需要注意两点约束force_ocr与disable_ocr互斥源码明确标注二者不能同时为真配置校验阶段会直接报错仓库的 Java 端到端测试 e2e/java/src/test/java/io/xberg/e2e/ErrorTest.java 专门覆盖了{disable_ocr:true,force_ocr:true}的冲突输入force_ocr_pages的页码是 1 起始的OCR 路由在处理时遇到 0 会打印警告并忽略见 crates/xberg/src/extractors/pdf/ocr/pipeline.rs。三、OcrConfig 详解backend、enabled 与 language开启force_ocr之后OCR 具体由谁执行、识别什么语言由内嵌的ocr配置块决定。该块对应 Rust 侧OcrConfigcrates/xberg/src/core/config/ocr.rs核心字段如下enabled是否启用 OCR默认true设为false等价于在父级设置disable_ocrbackendOCR 后端默认tesseract可选paddleocr/paddle-ocr/sceptre/vlm。后端名称拼写错误会在配置校验阶段被捕获而不是运行期才暴露crates/xberg/src/core/config/ocr.rslanguage识别语言代码列表默认[eng]。支持两种写法字符串eng、engdeu加号连接多语言或数组[eng, deu]。源码中的反序列化器会同时接受这两种形式并归一化为列表crates/xberg/src/core/config/ocr.rs。除这三个基础项外OcrConfig还提供tesseract_config、output_format、paddle_ocr_settings、vlm_config、quality_thresholds、pipeline多后端流水线、auto_rotate自动纠偏等扩展配置满足更精细的识别需求。即便完全不写ocr块force_ocr: true也会使用引擎默认值Tesseract eng执行。四、Java 代码示例完整可运行的调用方式原文档给出的 Java 片段展示了最简调用范式先用JsonUtil.fromJson把 JSON 字符串反序列化为强类型的ExtractInput与ExtractionConfig再调用Xberg.extract得到ExtractionResult。下面是对应完整代码import io.xberg.*; public final class Example { public static void main(String[] args) throws Exception { // 1. 构造输入一个指向 PDF 的 URImime_type 显式声明为 application/pdf var inputJson {\kind\:\uri\,\mime_type\:\application/pdf\,\uri\:\https://example.com/pdf/fake_memo.pdf\}; var input JsonUtil.fromJson(inputJson, ExtractInput.class); // 2. 构造配置开启 force_ocr使用 tesseract 后端识别英文 var configJson {\force_ocr\:true,\ocr\:{\backend\:\tesseract\,\enabled\:true,\language\:[\eng\]}}; var config JsonUtil.fromJson(configJson, ExtractionConfig.class); // 3. 执行抽取 var result Xberg.extract(input, config); // 4. 读取第一个文档的结果文本 System.out.println(result.results().get(0).content()); } }对这段代码的补充说明JsonUtil.fromJson(json, Class)是 xberg Java 绑定提供的 JSON 反序列化入口定义于 packages/java/io/xberg/JsonUtil.java把 JSON 字符串映射为类型安全的 Java 对象Xberg.extract(input, config)是单文档抽取的静态方法声明为public static ExtractionResult extract(final ExtractInput input, final ExtractionConfig config)内部委托给XbergRs.extract见 packages/java/io/xberg/Xberg.java结果对象为ExtractionResult通过results()取得文档列表get(0).content()取第一个文档的正文文本如需多文档批量处理可改用extractBatch(ListExtractInput, ExtractionConfig)。五、底层原理force_ocr 如何改变 PDF 抽取路径从源码可以还原force_ocr在 PDF 抽取管线中的实际影响关闭层级段落保留在 crates/xberg/src/extractors/pdf/extraction.rs 中retain_hierarchy_segments needs_structured !config.force_ocr——强制 OCR 时不再保留原生结构层级段落因为输出将完全由 OCR 重建跳过预渲染结构化文档同文件 crates/xberg/src/extractors/pdf/extraction.rs 中pre_rendered_doc仅在needs_structured !config.force_ocr时才构建强制 OCR 直接走整文档 OCR 路由全页面渲染并并行 OCRforce_ocr整文档路由与force_ocr_pages指定页路由是两条独立的渲染路径前者会渲染全部页面见 crates/xberg/src/extractors/pdf/ocr/rendering.rs渲染后的每个页面再交给后端识别失败策略差异混合 OCR 路由中force_ocr_pages模式下所有指定页 OCR 失败会直接返回错误AllPagesFailedPolicy::ReturnError而默认回退场景则保留原生文本AllPagesFailedPolicy::PreserveNative见 crates/xberg/src/extractors/pdf/ocr/pipeline.rs。此外当force_ocr开启且页面渲染后的 OCR 失败时管线还有一套重新打开 PDF 恢复 XObject 嵌入图像字节再 OCR的兜底逻辑crates/xberg/src/extractors/pdf/ocr/rendering.rs进一步提升强制 OCR 场景的鲁棒性。六、如何验证契约 fixture 与 Java 端到端测试仓库为force_ocr提供了双重验证证据可作为自己集成测试的模板契约 fixturefixtures/contract/ocr_force_all_pages.json 定义了完整的抽取契约描述为 Forces OCR on every PDF page even when a text layer exists。它使用fake_memo.pdf作为样例经由 mock 服务器以application/pdf返回配置为{force_ocr:true,ocr:{enabled:true,backend:tesseract,language:[eng]}}断言results[0].mime_type为application/pdf且results[0].content必须包含bottles、blankets、laptops三个词Java 端到端测试e2e/java/src/test/java/io/xberg/e2e/ContractTest.java 中的testOcrForceAllPages与上述 fixture 一一对应用同样的 JSON 配置构造输入并断言content().contains(bottles/blankets/laptops)。这个测试直接验证了即使 PDF 已含文本层force_ocr 输出的也是 OCR 识别出的真实页面内容。七、使用建议与注意事项性能成本force_ocr会对每一页执行渲染 识别开销远高于原生文本抽取。仅对确实存在文本层质量问题的文档开启若只是部分页面需要 OCR优先使用force_ocr_pages: [1, 2, 5]按页控制与ocr_strategy的关系若需求是仅对看起来像扫描件的页面 OCR使用OcrStrategy::ScannedPages { min_confidence }比force_ocr更精准——前者按扫描置信度选页默认阈值为 0.70见 crates/xberg/src/core/config/ocr.rs后者是无差别全量强制后端与语言务必显式指定全量 OCR 会放大配置失误的影响建议总是显式给出backend与language避免默认 Tesseract eng 与目标语言不符冲突校验不要在同一个配置里同时设置force_ocr: true与disable_ocr: truexberg 会在配置校验阶段直接拒绝该组合分块处理强制 OCR 的大文件会进入分块chunking逻辑ChunkingReason::OcrRequired会携带force_ocr标记用于决策见 crates/xberg/src/heuristics/decision.rs超大文档可据此预先规划处理策略。掌握force_ocr的语义边界与配套配置即可在原生文本不可信与OCR 成本可控之间找到正确的平衡点将 xberg 的 Java 抽取能力稳定地用于扫描件治理、文档归一化与高质量 RAG 数据管线。赞分享后端AI 应用NLP【免费下载链接】xbergPolyglot document intelligence with a Rust core: extract text, metadata, images, tables, and structured data from 106 formats across 140 file extensions, plus code intelligence for 371 languages. Fifteen bindings, with CLI, REST API, and MCP server.项目地址https://gitcode.com/gh_mirrors/kr/xberg点击查看免费下载相关推荐Handsontable 行虚拟化Row Virtualization完全指南百万行数据渲染不卡顿的原理与实践Handsontable 行虚拟化Row Virtualization完全指南百万行数据渲染不卡顿的原理与实践 导读 行虚拟化Row Virtualiz后端AI 应用NLPElixir 中使用 Xberg force_ocr 强制 OCR对含原生文本层 PDF 的深度处理指南Elixir 中使用 Xberg force_ocr 强制 OCR对含原生文本层 PDF 的深度处理指南 本文讲解如何在 Elixir 语言绑定中通过 for后端AI 应用NLPxberg C FFI 实战用 force_ocr 强制对每一页 PDF 执行 OCRxberg C FFI 实战用 force_ocr 强制对每一页 PDF 执行 OCR 本篇技术指南基于仓库中的 C 语言示例 ocr_force_all_p后端AI 应用NLP上一篇5分钟搞定游戏汉化XUnity.AutoTranslator让你告别外语障碍下一篇XUnity.AutoTranslator5分钟解决Unity游戏语言障碍的终极方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考