企业官网建设流程全解析

• 后端
• AI 应用
• NLP

本指南以 Xberg 官方 Java 示例 extract_batch_uri_all_missing 为骨架，讲解 Java 绑定中Xberg.extractBatch面对批量 URI 输入全部缺失（文件不存在）时的真实行为：调用本身不会抛异常，而是在返回结果中通过summary.errors精确统计失败项，实现“单次调用、逐项容错”。读完本文，你将掌握ExtractInput（kind: uri）的 JSON 构造方式、批量提取结果ExtractionResult的三层结构（results/errors/summary），以及如何把这一模式用于生产级批处理管线的失败率监控。

场景定位：为什么需要“全部缺失”这一用例

在文档智能提取系统中，批量任务往往来自异步队列：一批文件路径由调度器下发，处理时某些文件可能已被删除、迁移或权限不可读。Xberg 的extractBatch设计目标之一就是让这类“文件级失败”不中断整个批次：

• 单个输入失败不会让整批调用抛出异常（not_error语义）；
• 失败项会被捕获到ExtractionResult.errors中，附带输入下标与稳定错误码；
• 调用方通过summary.results与summary.errors的计数即可判断整批任务的健康度。

对应的契约 fixture extract_batch_uri_all_missing.json 明确断言了这一行为：summary.results == 0、summary.errors == 2，且整批调用类型为not_error（即成功返回而非抛异常）。

官方示例：两个不存在的 URI 输入

关联文档 docs-site/src/snippets-generated/java/batch/extract_batch_uri_all_missing.md 给出的完整 Java 代码如下：

import io.xberg.*; public final class Example { public static void main(String[] args) throws Exception { var result = Xberg.extractBatch(java.util.Arrays.asList(JsonUtil.fromJson("{\"kind\":\"uri\",\"uri\":\"/nonexistent/a.pdf\"}", ExtractInput.class), JsonUtil.fromJson("{\"kind\":\"uri\",\"uri\":\"/nonexistent/b.txt\"}", ExtractInput.class)), ExtractionConfig.builder().build()); System.out.println(result.summary().results()); System.out.println(result.summary().errors()); } }

该示例的关键要素可以拆解为四部分：

1. JsonUtil.fromJson(json, ExtractInput.class)：将 JSON 字符串反序列化为ExtractInput对象。这是生成式 Java 绑定提供的手写 JSON 便捷工具，对应包io.xberg；
2. "kind":"uri"：声明输入类型为 URI 而非字节流（"bytes"），详见下文ExtractInput的两种 kind；
3. "uri":"/nonexistent/a.pdf"：指向不存在的本地文件路径，用于触发文件缺失错误；
4. ExtractionConfig.builder().build()：使用全默认配置，ExtractionConfig采用 builder 模式构造。

若希望以面向对象方式而非 JSON 字符串构造输入，同样语义的等价代码可见 java 语言包示例，它使用ExtractInput.builder().withKind(ExtractInputKind.URI).withUri("report.pdf").build()，两种方式在运行时完全等价。

运行结果与预期断言

运行上述示例，打印结果应为：

0 2

即summary.results()为 0（没有任何成功提取结果），summary.errors()为 2（两条输入全部失败）。这一预期由 fixtures/batch/extract_batch_uri_all_missing.json 中的断言（summary.results == 0、summary.errors == 2）与 Java 端到端测试 BatchTest.java 双重锁定：

@Test void testExtractBatchUriAllMissing() throws Exception { // extract_batch with missing URI inputs var result = Xberg.extractBatch(java.util.Arrays.asList(JsonUtil.fromJson("{\"kind\":\"uri\",\"uri\":\"/nonexistent/a.pdf\"}", ExtractInput.class), JsonUtil.fromJson("{\"kind\":\"uri\",\"uri\":\"/nonexistent/b.txt\"}", ExtractInput.class)), ExtractionConfig.builder().build()); assertEquals(0, result.summary().results()); assertEquals(2, result.summary().errors()); }

需要特别说明：断言中检查的是result.summary()，而示例代码打印的result.summary().results()与之等价。Java 绑定中ExtractionResult的summary()访问器即指向 Rust 侧ExtractionSummary结构。

深入底层：ExtractionResult 的三层结构

Java 绑定入口 Xberg.java 将extractBatch(List<ExtractInput>, ExtractionConfig)委托给 Rust 引擎；返回的ExtractionResult在 Rust 侧定义于 extraction/types.rs，由三部分构成：

其中ExtractionSummary（types.rs）包含六个计数：

• inputs：调用方提交的输入总数（本示例为 2）；
• results：成功产生的提取结果数（本示例为 0）；
• errors：逐条错误数（本示例为 2）；
• remote_urls：解析为远程 HTTP(S) 的 URI 输入数；
• pages_crawled：爬取/抓取的 HTML 页数；
• documents_downloaded：从 URL 下载并提取的非 HTML 文档数。

引擎在批处理收尾时通过refresh_counts()依据results.len()与errors.len()重算 summary（见 extract_impl.rs），因此results + errors未必等于inputs（例如 URL 爬取场景下一条输入可能产生多个结果，或部分输入被去重），这一点在统计失败率时需要注意。

错误项的结构

每个失败项ExtractionErrorItem（types.rs）包含：

• index：输入在原始请求中的下标（从 0 开始）；
• code：稳定的数值错误码（u32）；
• error_type：稳定的 snake_case 错误类型字符串；
• source：尽力而为的来源标识（本示例为/nonexistent/a.pdf这类 URI）；
• message：可读的错误消息。

Java 中通过result.errors()获取错误列表，配合summary()的计数即可实现“按失败项聚合告警”：例如遍历errors()按error_type()分组，统计各错误类型占比。

引擎实现：批处理如何逐项捕获错误

extract_batch的引擎级实现位于 extract_impl.rs，根据编译特性存在两条路径：

• 顺序执行extract_batch_sequential（L357-L387）：适用于未启用tokio-runtime特性或 WASM 目标，逐个await输入；
• 并发执行extract_batch_concurrent（L389-L459）：适用于启用了tokio-runtime的宿主环境，通过有界任务队列（bounded batch tasks）并行处理，并按批次预算初始化线程池（init_thread_pools）。

两条路径共享相同的容错逻辑：对每个输入调用extract_one，成功则把产出合并进输出，失败则调用error_item(index, source, &error)生成错误项压入output.errors（L378-L381）。error_item（L1866-L1874）将 Rust 的XbergError映射为稳定的code（extraction_error_code）与error_type（extraction_error_type）。对于文件不存在的 URI，对应错误即从输入解析/读取阶段抛出并被捕获，这正是示例中errors == 2的来源。

此外，批处理还包含“未匹配错误”的兜底机制：当批量结果被排空后，若某个槽位仍为None，说明该输入既未产生结果也未产生错误，此时会用unmatched_errors补齐，确保任何输入都不会同时从results与errors中消失（见 extract_impl.rs 的注释说明）。

同族用例对照：从全部失败到部分失败

仓库中与本次“全部缺失”配套的同类 fixture 可以帮助你快速理解批处理语义的边界：

这些用例在 BatchTest.java 中均有同名测试方法（testExtractBatchUriNotFound、testExtractBatchUriBasic、testExtractBatchUriPartialFailure等），可作为回归基准。对照可见：单个输入失败不会影响其他输入的提取，这正是extractBatch相比逐条循环调用extract的核心优势——一次网络/FFI 往返即可拿到整批结果与逐项错误。

实战建议：把批量提取接到生产管线

1. 失败率监控：对每批调用计算summary.errors() / summary.inputs，超过阈值（例如 5%）触发告警；由于results + errors在爬取场景下可能不等于inputs，建议同时上报summary.inputs、remote_urls、pages_crawled以辅助归因。
2. 错误分类：遍历errors()，按error_type()聚合（例如文件缺失、权限、解析失败等），驱动重试策略——仅对可重试类型（如临时网络错误）重试，文件缺失类错误直接进入补偿队列。
3. 结果-错误联合消费：利用index字段把每个错误项映射回原始输入列表，精确定位失败文件；成功结果与错误项分开消费，避免混用。
4. 配置默认值：示例使用ExtractionConfig.builder().build()全默认配置即可覆盖文件缺失场景；若输入可能指向远程 URL，可在ExtractionConfig中按需配置 URL 提取与爬取相关参数（参考 extract_batch_uri_basic.json 的 mock server 用法）。
5. 测试保障：在 CI 中复用 BatchTest.java 的模式，把“全部缺失”“部分失败”“全部成功”“空批次”四类用例固化为回归测试，确保引擎行为变更时能第一时间感知。

小结

extract_batch面对全部缺失的 URI 输入时，既不抛异常也不静默吞错，而是返回results == 0、errors == 2的完整结果信封，把“文件级失败”显式暴露给调用方。理解ExtractionResult的results/errors/summary三层结构，以及引擎层逐项捕获、refresh_counts重算、未匹配错误兜底这三重机制，就能在 Java 中构建健壮、可观测、可重试的批量文档提取管线。

• 后端
• AI 应用
• NLP