后端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点击查看免费下载导读当一批待提取的文档 URI 全部指向不存在的文件如路径拼写错误、文件已被迁移或删除时Xberg 的批量提取 APIextract_batch不会抛出异常终止整个任务而是把每个失败折叠为一条结构化错误在返回的summary中给出精确的results与errors计数。本文以 Xberg 仓库中 Dart 绑定的一则官方夹具fixture为核心逐行拆解这段 Dart 代码并深入 Rust 引擎源码说明全部失败场景下的内部行为、结果类型设计以及在实际批量处理中如何利用summary与错误明细做容错与审计。场景一个全数落空的批量输入本篇文章讲解的夹具位于 docs-site/src/snippets-generated/dart/batch/extract_batch_uri_all_missing.md对应的 JSON 契约定义在 fixtures/batch/extract_batch_uri_all_missing.json。该夹具的输入是两个指向不存在路径的 URI[ {kind: uri, uri: /nonexistent/a.pdf}, {kind: uri, uri: /nonexistent/b.txt} ]它同时给出了本次调用必须满足的三条断言assertions断言期望值含义not_error无错误整个extract_batch调用本身成功返回不会因单个输入失败而抛出异常summary.results0没有任何一条输入产出提取结果summary.errors2两条输入各产生一条错误记录这正是批量 API 与单文件 API 的核心差异调用级成功与条目级失败是分离的。两个输入全部失败但外层调用依然返回一个结构化的ExtractionResult其中summary.errors inputs.length。Dart 侧完整代码逐行解读以下代码就是该夹具在 Dart 语言绑定下的可运行形态它演示了从 JSON 构造输入、调用批量接口、读取汇总计数的完整链路import dart:convert; import dart:io; import package:xberg/xberg.dart; import package:xberg/src/xberg_bridge_generated/frb_generated.dart show RustLib; Futurevoid main() async { await RustLib.init(); try { final inputs await Future.wait((jsonDecode(r[{kind:uri,uri:/nonexistent/a.pdf},{kind:uri,uri:/nonexistent/b.txt}]) as Listdynamic).map((element) createExtractInputFromJson(json: jsonEncode(element)))); final result await XbergBridge.extractBatch(inputs); stdout.writeln(result.summary.results); stdout.writeln(result.summary.errors); } finally { RustLib.dispose(); } }逐行拆解导入依赖package:xberg/xberg.dart提供XbergBridge、ExtractInput等公开 APIfrb_generated.dart中的RustLib是 flutter_rust_bridge 生成的运行时入口负责初始化与释放与 Rust 核心的通信通道。await RustLib.init()在使用任何 Xberg 能力之前必须先初始化桥接运行时对应的RustLib.dispose()放在finally中保证无论成功失败都会释放资源。构造输入这里没有直接用 Dart 的ExtractInput构造器而是把一段 JSON 数组通过jsonDecode解析后逐个用createExtractInputFromJson(json: jsonEncode(element))转成ExtractInput。这种从 JSON 构造输入的方式与 Rust 侧ExtractInput的 serde 反序列化一一对应可以让前端代码与后端契约fixture JSON保持同构。每个输入元素的kind: uri表示这是一个路径/URL 输入uri字段则给出具体位置。调用批量接口XbergBridge.extractBatch(inputs)对应 Dart 封装在 packages/dart/lib/src/xberg.dart 中定义的方法extractBatch(ListExtractInput inputs, {ExtractionConfig? config})——未传config时默认使用{}对应的 Rust 侧默认配置。读取汇总result.summary.results与result.summary.errors分别是成功结果数与错误条目数。本场景下输出两行第一行0第二行2。引擎内部失败条目如何被收集而不是抛错Dart 绑定背后是 Rust 核心的统一公共 API。在 crates/xberg/src/core/extract/mod.rs 中extract_batch把输入委托给进程级默认引擎pub async fn extract_batch(inputs: VecExtractInput, config: ExtractionConfig) - ResultExtractionResult { DEFAULT_ENGINE.extract_batch(inputs, config).await }真正的实现位于 crates/xberg/src/engine/extract_impl.rs 的extract_batchL217 起。它的关键设计包括先校验、再缓存调用前先执行config.validate()随后计算批量内容的缓存键若命中缓存且反序列化成功则直接返回缓存结果。仅零错误才写缓存代码中只有当output.errors.is_empty()时才会把结果写入缓存见 extract_impl.rs。本场景errors 2因此不会污染缓存——有失败项的批量结果不会被误当成干净数据复用。两种执行路径在启用tokio-runtime且非 wasm32 的目标上走extract_batch_concurrentextract_impl.rs通过tokio::task::JoinSet并发处理各输入在 wasm32 或未启用tokio-runtime时退化为extract_batch_sequentialextract_impl.rs逐个await。两条路径的失败处理策略完全一致单项失败被捕获并追加进output.errors不会中断整批循环。以顺序路径为例循环体内Err(error) output.errors.push(error_item(index, source, error))处理完所有输入后调用output.refresh_counts()重新统计计数。文件不存在这类错误在底层表现为XbergError::Io其io::ErrorKind为NotFound——这一点在 crates/xberg/src/core/extractor/file.rs 的测试should_report_missing_file_before_invalid_ocr_configuration中有明确印证即使同时配置了 OCR缺失文件也会优先以 NotFound 报告。结果类型summary 与 error 条目的字段契约批量调用的返回类型定义在 crates/xberg/src/core/config/extraction/types.rsExtractionSummarytypes.rs是result.summary的类型包含六个计数字段类型含义本场景取值inputsusize调用方提交的输入总数2resultsusize成功产出的提取结果数0errorsusize逐条错误数2remote_urlsusize解析为远程 HTTP(S) URL 的 URI 数0pages_crawledusize被抓取/爬取的 HTML 页数0documents_downloadedusize从 URL 下载的非 HTML 文档数0ExtractionResulttypes.rs除results、errors、summary外还携带爬取过程信息crawl_final_urls、crawl_redirect_count、crawl_unique_normalized_urls便于审计 URL 跳转链路。每条错误都是结构化的ExtractionErrorItemtypes.rs字段类型含义indexusize出错输入在原始请求中的下标codeu32稳定的数字错误码error_typeString稳定的 snake_case 错误类别sourceString尽力而为的源标识如 URI 原文messageString人类可读的错误信息这意味着你不仅知道失败了 2 条还能通过errors[i].index精确还原是哪两条、通过source看到原始 URI、通过code/error_type做程序化分类。输入模型kind 与 uri 的约束Dart 侧createExtractInputFromJson转换出的结构对应 Rust 侧ExtractInputtypes.rs。其中ExtractInputKindtypes.rs只有两种取值bytes内存中直接给出的原始字节配套字段bytesuri文件系统路径、file://URI 或 HTTP(S) URL配套字段uri。类型定义上bytes要求bytes、uri要求uriuri缺省时还会触发校验错误见 crates/xberg/tests/core_integration.rs 的missing uri field should fail validation。本场景两个输入都正确提供了kind: uri与uri问题只在于路径指向的文件不存在因此错误发生在提取阶段而非校验阶段。与其他批量夹具的对照判断全部失败的边界同一目录下的系列夹具可以帮助你判断当前场景在整个批量错误矩阵中的位置见 docs-site/src/snippets-generated/dart/batchextract_batch_uri_basic全部 URI 存在期望results inputs、errors 0extract_batch_uri_partial_failure部分 URI 存在、部分缺失期望results errors inputsextract_batch_empty_inputs输入列表为空summary.inputs 0extract_batch_uri_all_missing本文场景全部URI 缺失期望results 0、errors inputs且调用本身不报错。这些行为在 Rust 集成测试中同样被覆盖例如 crates/xberg/tests/batch_processing.rs 的test_batch_extract_all_fail三个不存在的文件txt/pdf/docx批量提取后断言批量调用整体成功但每个结果的 metadata.error 均非空。实战要点如何把全失败变成可运维的信号结合上述类型契约在真实项目中处理全部缺失场景时建议不要用 try/catch 判断单个文件失败。extract_batch的调用级错误只代表配置非法、取消或灾难性故障文件缺失这种条目级错误永远出现在result.errors里。判断维度始终是summary.results、summary.errors与summary.inputs三者是否满足results errors inputs。用errors[i].index与source回填原始输入。批量输入在客户端往往有业务序号文件名、数据库 ID而错误项只携带下标因此保持输入列表顺序不变即可精确映射哪条输入失败了、失败原因是什么。对code/error_type做程序化分类。不要靠解析message字符串判断错误类别优先使用稳定的错误码与错误类型字段例如把NotFound类错误与超时格式不支持区分处理。注意缓存语义。只有零错误的批量结果才会被写入提取缓存包含失败项的批次每次都会重新执行。若你的批处理经常出现部分失败可通过错误计数提前感知缓存未命中的开销。配合单文件容错链路理解。批量内部的错误处理与extract_uri_document等单条路径共用同一套ExtractionErrorItem契约因此你可以先在小样本上逐个验证单文件行为再放大到批量场景。小结extract_batch面对全部 URI 缺失时的行为可以概括为一句话调用级成功、条目级全失败、失败信息结构化。通过 extract_batch_uri_all_missing.md 这段 Dart 示例配合 fixtures/batch/extract_batch_uri_all_missing.json 的断言、engine/extract_impl.rs 的实现以及 types.rs 的类型定义你可以在自己的 Dart/Flutter 应用中可靠地实现批量提取 逐条容错 精确审计让异常输入不再中断整条流水线。赞分享后端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 Dart 批量提取容错实战用 extract_batch 优雅处理部分失败Xberg Dart 批量提取容错实战用 extract_batch 优雅处理部分失败 导读 在真实的生产环境中批量文档提取永远不会全对或全错一批后端AI 应用NLPXberg C 绑定批量提取容错指南用 extract_batch 处理全部 URI 缺失的场景Xberg C 绑定批量提取容错指南用 extract_batch 处理全部 URI 缺失的场景 批量文档提取 extract_batch 是 Xberg后端AI 应用NLPXberg Elixir 批量提取URI 输入全部缺失时 extract_batch 的 summary 错误语义与失败隔离实践Xberg Elixir 批量提取URI 输入全部缺失时 extract_batch 的 summary 错误语义与失败隔离实践 本篇指南聚焦 Xberg E后端AI 应用NLP创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/28 20:16:43 · 阅读 1.2k Xberg Dart 批量提取容错实战：extract_batch 处理全部缺失 URI 输入
后端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点击查看免费下载导读当一批待提取的文档 URI 全部指向不存在的文件如路径拼写错误、文件已被迁移或删除时Xberg 的批量提取 APIextract_batch不会抛出异常终止整个任务而是把每个失败折叠为一条结构化错误在返回的summary中给出精确的results与errors计数。本文以 Xberg 仓库中 Dart 绑定的一则官方夹具fixture为核心逐行拆解这段 Dart 代码并深入 Rust 引擎源码说明全部失败场景下的内部行为、结果类型设计以及在实际批量处理中如何利用summary与错误明细做容错与审计。场景一个全数落空的批量输入本篇文章讲解的夹具位于 docs-site/src/snippets-generated/dart/batch/extract_batch_uri_all_missing.md对应的 JSON 契约定义在 fixtures/batch/extract_batch_uri_all_missing.json。该夹具的输入是两个指向不存在路径的 URI[ {kind: uri, uri: /nonexistent/a.pdf}, {kind: uri, uri: /nonexistent/b.txt} ]它同时给出了本次调用必须满足的三条断言assertions断言期望值含义not_error无错误整个extract_batch调用本身成功返回不会因单个输入失败而抛出异常summary.results0没有任何一条输入产出提取结果summary.errors2两条输入各产生一条错误记录这正是批量 API 与单文件 API 的核心差异调用级成功与条目级失败是分离的。两个输入全部失败但外层调用依然返回一个结构化的ExtractionResult其中summary.errors inputs.length。Dart 侧完整代码逐行解读以下代码就是该夹具在 Dart 语言绑定下的可运行形态它演示了从 JSON 构造输入、调用批量接口、读取汇总计数的完整链路import dart:convert; import dart:io; import package:xberg/xberg.dart; import package:xberg/src/xberg_bridge_generated/frb_generated.dart show RustLib; Futurevoid main() async { await RustLib.init(); try { final inputs await Future.wait((jsonDecode(r[{kind:uri,uri:/nonexistent/a.pdf},{kind:uri,uri:/nonexistent/b.txt}]) as Listdynamic).map((element) createExtractInputFromJson(json: jsonEncode(element)))); final result await XbergBridge.extractBatch(inputs); stdout.writeln(result.summary.results); stdout.writeln(result.summary.errors); } finally { RustLib.dispose(); } }逐行拆解导入依赖package:xberg/xberg.dart提供XbergBridge、ExtractInput等公开 APIfrb_generated.dart中的RustLib是 flutter_rust_bridge 生成的运行时入口负责初始化与释放与 Rust 核心的通信通道。await RustLib.init()在使用任何 Xberg 能力之前必须先初始化桥接运行时对应的RustLib.dispose()放在finally中保证无论成功失败都会释放资源。构造输入这里没有直接用 Dart 的ExtractInput构造器而是把一段 JSON 数组通过jsonDecode解析后逐个用createExtractInputFromJson(json: jsonEncode(element))转成ExtractInput。这种从 JSON 构造输入的方式与 Rust 侧ExtractInput的 serde 反序列化一一对应可以让前端代码与后端契约fixture JSON保持同构。每个输入元素的kind: uri表示这是一个路径/URL 输入uri字段则给出具体位置。调用批量接口XbergBridge.extractBatch(inputs)对应 Dart 封装在 packages/dart/lib/src/xberg.dart 中定义的方法extractBatch(ListExtractInput inputs, {ExtractionConfig? config})——未传config时默认使用{}对应的 Rust 侧默认配置。读取汇总result.summary.results与result.summary.errors分别是成功结果数与错误条目数。本场景下输出两行第一行0第二行2。引擎内部失败条目如何被收集而不是抛错Dart 绑定背后是 Rust 核心的统一公共 API。在 crates/xberg/src/core/extract/mod.rs 中extract_batch把输入委托给进程级默认引擎pub async fn extract_batch(inputs: VecExtractInput, config: ExtractionConfig) - ResultExtractionResult { DEFAULT_ENGINE.extract_batch(inputs, config).await }真正的实现位于 crates/xberg/src/engine/extract_impl.rs 的extract_batchL217 起。它的关键设计包括先校验、再缓存调用前先执行config.validate()随后计算批量内容的缓存键若命中缓存且反序列化成功则直接返回缓存结果。仅零错误才写缓存代码中只有当output.errors.is_empty()时才会把结果写入缓存见 extract_impl.rs。本场景errors 2因此不会污染缓存——有失败项的批量结果不会被误当成干净数据复用。两种执行路径在启用tokio-runtime且非 wasm32 的目标上走extract_batch_concurrentextract_impl.rs通过tokio::task::JoinSet并发处理各输入在 wasm32 或未启用tokio-runtime时退化为extract_batch_sequentialextract_impl.rs逐个await。两条路径的失败处理策略完全一致单项失败被捕获并追加进output.errors不会中断整批循环。以顺序路径为例循环体内Err(error) output.errors.push(error_item(index, source, error))处理完所有输入后调用output.refresh_counts()重新统计计数。文件不存在这类错误在底层表现为XbergError::Io其io::ErrorKind为NotFound——这一点在 crates/xberg/src/core/extractor/file.rs 的测试should_report_missing_file_before_invalid_ocr_configuration中有明确印证即使同时配置了 OCR缺失文件也会优先以 NotFound 报告。结果类型summary 与 error 条目的字段契约批量调用的返回类型定义在 crates/xberg/src/core/config/extraction/types.rsExtractionSummarytypes.rs是result.summary的类型包含六个计数字段类型含义本场景取值inputsusize调用方提交的输入总数2resultsusize成功产出的提取结果数0errorsusize逐条错误数2remote_urlsusize解析为远程 HTTP(S) URL 的 URI 数0pages_crawledusize被抓取/爬取的 HTML 页数0documents_downloadedusize从 URL 下载的非 HTML 文档数0ExtractionResulttypes.rs除results、errors、summary外还携带爬取过程信息crawl_final_urls、crawl_redirect_count、crawl_unique_normalized_urls便于审计 URL 跳转链路。每条错误都是结构化的ExtractionErrorItemtypes.rs字段类型含义indexusize出错输入在原始请求中的下标codeu32稳定的数字错误码error_typeString稳定的 snake_case 错误类别sourceString尽力而为的源标识如 URI 原文messageString人类可读的错误信息这意味着你不仅知道失败了 2 条还能通过errors[i].index精确还原是哪两条、通过source看到原始 URI、通过code/error_type做程序化分类。输入模型kind 与 uri 的约束Dart 侧createExtractInputFromJson转换出的结构对应 Rust 侧ExtractInputtypes.rs。其中ExtractInputKindtypes.rs只有两种取值bytes内存中直接给出的原始字节配套字段bytesuri文件系统路径、file://URI 或 HTTP(S) URL配套字段uri。类型定义上bytes要求bytes、uri要求uriuri缺省时还会触发校验错误见 crates/xberg/tests/core_integration.rs 的missing uri field should fail validation。本场景两个输入都正确提供了kind: uri与uri问题只在于路径指向的文件不存在因此错误发生在提取阶段而非校验阶段。与其他批量夹具的对照判断全部失败的边界同一目录下的系列夹具可以帮助你判断当前场景在整个批量错误矩阵中的位置见 docs-site/src/snippets-generated/dart/batchextract_batch_uri_basic全部 URI 存在期望results inputs、errors 0extract_batch_uri_partial_failure部分 URI 存在、部分缺失期望results errors inputsextract_batch_empty_inputs输入列表为空summary.inputs 0extract_batch_uri_all_missing本文场景全部URI 缺失期望results 0、errors inputs且调用本身不报错。这些行为在 Rust 集成测试中同样被覆盖例如 crates/xberg/tests/batch_processing.rs 的test_batch_extract_all_fail三个不存在的文件txt/pdf/docx批量提取后断言批量调用整体成功但每个结果的 metadata.error 均非空。实战要点如何把全失败变成可运维的信号结合上述类型契约在真实项目中处理全部缺失场景时建议不要用 try/catch 判断单个文件失败。extract_batch的调用级错误只代表配置非法、取消或灾难性故障文件缺失这种条目级错误永远出现在result.errors里。判断维度始终是summary.results、summary.errors与summary.inputs三者是否满足results errors inputs。用errors[i].index与source回填原始输入。批量输入在客户端往往有业务序号文件名、数据库 ID而错误项只携带下标因此保持输入列表顺序不变即可精确映射哪条输入失败了、失败原因是什么。对code/error_type做程序化分类。不要靠解析message字符串判断错误类别优先使用稳定的错误码与错误类型字段例如把NotFound类错误与超时格式不支持区分处理。注意缓存语义。只有零错误的批量结果才会被写入提取缓存包含失败项的批次每次都会重新执行。若你的批处理经常出现部分失败可通过错误计数提前感知缓存未命中的开销。配合单文件容错链路理解。批量内部的错误处理与extract_uri_document等单条路径共用同一套ExtractionErrorItem契约因此你可以先在小样本上逐个验证单文件行为再放大到批量场景。小结extract_batch面对全部 URI 缺失时的行为可以概括为一句话调用级成功、条目级全失败、失败信息结构化。通过 extract_batch_uri_all_missing.md 这段 Dart 示例配合 fixtures/batch/extract_batch_uri_all_missing.json 的断言、engine/extract_impl.rs 的实现以及 types.rs 的类型定义你可以在自己的 Dart/Flutter 应用中可靠地实现批量提取 逐条容错 精确审计让异常输入不再中断整条流水线。赞分享后端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 Dart 批量提取容错实战用 extract_batch 优雅处理部分失败Xberg Dart 批量提取容错实战用 extract_batch 优雅处理部分失败 导读 在真实的生产环境中批量文档提取永远不会全对或全错一批后端AI 应用NLPXberg C 绑定批量提取容错指南用 extract_batch 处理全部 URI 缺失的场景Xberg C 绑定批量提取容错指南用 extract_batch 处理全部 URI 缺失的场景 批量文档提取 extract_batch 是 Xberg后端AI 应用NLPXberg Elixir 批量提取URI 输入全部缺失时 extract_batch 的 summary 错误语义与失败隔离实践Xberg Elixir 批量提取URI 输入全部缺失时 extract_batch 的 summary 错误语义与失败隔离实践 本篇指南聚焦 Xberg E后端AI 应用NLP创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考