xberg Dart 绑定批量字节提取实战：使用 extractBatch 与 per-input 配置提取多格式文档

后端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 绑定将 Rust 核心的多格式文档智能提取能力封装为跨语言 FFI 接口其中XbergBridge.extractBatch是面向批量处理场景的统一入口一次调用即可同时提交多个输入内存字节、本地路径、file://URI 或 HTTP(S) URL并为每个输入独立指定提取配置。本文以extract_batch的契约测试为骨架讲解如何在 Dart 中构造ExtractInput、通过 per-inputconfig覆盖全局配置如输出格式output_format: markdown并解读结果结构mimeType/content/metadata.outputFormat与底层实现原理。读完本文你将能直接写出可运行、可验证的 Dart 批量提取代码并理解其在 Rust 核心 中的对应数据模型。一、背景xberg 的批量提取 API 家族xberg 以 Rust 为核心引擎支持从 106 种格式、140 种文件扩展名中提取文本、元数据、图像、表格与结构化数据。对 Dart以及其余十余种语言绑定来说批量提取统一由extract_batch调用承载它有两条主要形态extract_batch字节输入输入直接携带内存字节数组kind: bytes适用于已加载到内存、无法直接访问文件系统的场景如网络下载、上传文件、数据库 BLOB。extract_batchURI 输入输入携带kind: uri指向本地路径、file://URI 或 HTTP(S) URL由引擎负责读取、下载或爬取。本文聚焦的关联文档展示的是“字节输入 每个输入独立携带配置”的组合对应的仓库契约 JSON 位于 fixtures/contract/api_extract_batch_bytes_with_config.json而 Dart 端的真实测试在 e2e/dart/test/contract_test.dart 的Tests batch bytes extraction with per-input config (extract_batch)用例中内容与该文档完全一致。二、输入模型ExtractInput 的字段与语义批量提取的每个元素都是统一的输入对象。在 Rust 核心中其定义位于 crates/xberg/src/core/config/extraction/types.rs第 200-223 行的ExtractInput结构体核心字段如下字段类型说明kindExtractInputKind输入来源类型bytes内存字节或uri路径/URI/URLbytesOptionVecu8kind bytes时必填的原始字节uriOptionStringkind uri时填写的本地路径、file://URI 或 HTTP(S) URLmime_typeOptionStringMIME 类型提示可辅助识别filenameOptionString文件名提示用于 MIME 探测与元数据configOptionFileExtractionConfigper-input 提取配置覆盖仅作用于当前输入其中ExtractInputKind被#[serde(rename_all snake_case)]序列化为bytes/uri而ExtractInput使用#[serde(default)]因此构造时未提供的字段会自动取默认值默认kind Uri其余字段为None。从源码结构看该结构体同时被 REST APIcrates/xberg/src/api/handlers.rs中extract_batch入口与各语言绑定复用是 xberg 所有公开提取入口的统一数据模型。三、核心代码Dart 端批量字节提取带 per-input 配置关联文档给出的 Dart 示例是理解整条调用链的最佳起点。其完整流程为await RustLib.init()初始化 Rust FFI 运行时用jsonDecode解析内联的 JSON 输入数组通过createExtractInputFromJson将每个 JSON 元素转换为类型化的ExtractInput调用XbergBridge.extractBatch(inputs)执行批量提取从result.results[0]读取首个结果的mimeType、content与metadata.outputFormat结束后RustLib.dispose()释放资源。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[{bytes:pdf/fake_memo.pdf,config:{output_format:markdown},filename:fake_memo.pdf,kind:bytes}], ) as Listdynamic) .map((element) createExtractInputFromJson(json: jsonEncode(element))), ); final result await XbergBridge.extractBatch(inputs); stdout.writeln(result.results[0].mimeType); stdout.writeln(result.results[0].content); stdout.writeln(result.results[0].metadata.outputFormat); } finally { RustLib.dispose(); } }该示例对应的契约测试e2e/dart/test/contract_test.dart对运行结果施加了三条断言断言字段期望值含义results[0].mimeTypeapplication/pdf引擎正确识别了 PDF 字节的 MIME 类型results[0].content.length 10确实提取出了非空正文内容results[0].metadata.outputFormatmarkdownper-input 的output_format配置真实生效三条断言分别验证了输入识别、内容提取、配置下发三个环节因此该用例不仅是代码示例更是 xberg 对“批量 per-input 配置”这一能力的回归测试基准。仓库中 fixtures/contract/api_extract_batch_bytes_with_config.json 与 fixtures/contract/api_extract_batch_bytes.json 分别对应“带配置”与“不带配置”两种字节批量场景fixtures/batch/ 目录还收录了bytes_mixed_format.json、bytes_size_cap.json等混合输入与容量边界用例可作为理解批量语义的参考。四、per-input 配置output_format 与 FileExtractionConfig 支持面示例中config只出现了一个键output_format但这不是全部。Rust 核心对 per-input 配置的类型是FileExtractionConfig定义在 crates/xberg/src/core/config/extraction/file_config.rs第 48 行起其语义为“针对本文件覆盖批量级配置”。从源码中可以确认以下常用覆盖项配置键类型说明output_formatOptionOutputFormat覆盖输出内容格式本示例使用的键mime_detection_policyOptionMimeDetectionPolicy覆盖该文件的 MIME 推断策略enable_quality_processingOptionbool覆盖质量后处理开关ocr/force_ocr/disable_ocrOption...覆盖 OCR 配置、强制 OCR、禁用 OCRocr_strategy/force_ocr_pagesOption...覆盖 OCR 页选择策略与强制页码1 起始chunkingOptionChunkingConfig覆盖分块配置content_filterOptionContentFilterConfig覆盖内容过滤imagesOptionImageExtractionConfig覆盖图像提取配置pdf_optionsOptionPdfConfig覆盖 PDF 专属选项token_reductionOptionTokenReductionOptions覆盖 token 缩减language_detectionOptionLanguageDetectionConfig覆盖语言检测pagesOptionPageConfig覆盖页提取范围keywordsOptionKeywordConfig覆盖关键词提取postprocessorOptionPostProcessorConfig覆盖后处理器include_document_structureOptionbool覆盖文档结构输出timeout_secsOptionu64覆盖单文件提取超时超时的文件产生错误结果不影响批内其他文件structured_extractionOptionStructuredExtractionConfig启用针对该文件的 LLM 结构化提取JSON schema注意output_format的取值类型是OutputFormat枚举crates/xberg/src/core/config/formats.rs支持plain默认、markdown、djot、html、json、doc_tags以及自定义渲染器名称。因此把config改为{output_format:html}或{output_format:json}即可在保持输入不变的情况下切换结果形态。在批量调用中per-inputconfig与批量级配置的关系是“覆盖”该文件指定了某配置项就以文件级为准未指定的项继续沿用批量默认。从Option字段与文档注释None in the Option use batch defaultfile_config.rs 第 58 行附近可以确认这一设计——这也正是“混合格式批量”场景的基础一批文档可以各自输出不同的格式、执行不同的 OCR 策略。五、结果结构从 results[0] 读取 mimeType、content 与 metadata调用返回的result对应 Rust 侧的ExtractionResult定义于 crates/xberg/src/core/config/extraction/types.rs 第 294 行起其结构为results提取出的文档列表VecExtractedDocument按发现顺序排列errors非致命的逐输入错误列表ExtractionErrorItem含index、code、error_type、source、messagesummary聚合统计ExtractionSummary含inputs、results、errors、remote_urls、pages_crawled、documents_downloaded等计数。单个ExtractedDocument的关键字段即示例中访问的三个mimeType识别出的 MIME 类型对 PDF 输入为application/pdfcontent按output_format渲染后的正文本示例为 Markdownmetadata.outputFormat本次实际生效的输出格式回显markdown用于校验配置是否生效。因为批量语义是“逐输入独立成败”单个文件失败不会拖垮整批失败会进入errors数组其余输入继续产出结果summary给出聚合计数。这从ExtractionResult::refresh_countstypes.rs 第 330 行根据results与errors长度刷新计数、以及timeout_secs的“超时文件产生错误而不影响批内其他文件”注释均可得到印证。六、边界场景与测试佐证在 e2e/dart/test/batch_test.dart 中extract_batch的边界行为被系统化覆盖可作为生产代码设计的参照混合输入happy path同一批内混用bytes与uri输入验证统一入参模型无效/不支持的 MIME 类型bytes携带非法 MIME 或引擎不支持的 MIME验证逐输入错误处理而非整批失败空批次输入数组为空时的行为缺失 URI 输入kind: uri但未提供uri字段部分失败一个 URI 有效、另一个下载后无法解析验证错误隔离。结合 fixtures/batch/ 下的契约输入bytes_mixed_format.json、bytes_size_cap.json、extract_batch_uri_partial_failure.json等可以确认xberg 的批量提取被设计为“尽力而为、逐项隔离、聚合汇报”——这正是 per-input 配置存在的意义在同一批中让每个文档拥有独立的解析、OCR、分块与输出策略。七、总结在 Dart 中使用 xberg 做批量字节提取核心路径只有四步RustLib.init()→ 将输入数组经createExtractInputFromJson转为ExtractInput→XbergBridge.extractBatch(inputs)→ 读取results/errors/summary。per-inputconfig让同一批次内的每个文档可以拥有完全独立的输出格式与提取策略output_format: markdown只是其中最直观的一例完整的FileExtractionConfig覆盖面OCR、分块、过滤、PDF 选项、超时、结构化提取等都可通过该字段下发。若需进一步确认行为可直接运行 e2e/dart/test/contract_test.dart 中的同名契约测试或在 fixtures/contract/ 中查阅对应契约输入以作对照。赞分享后端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 C 绑定批量文档抽取实战xberg_extract_batch 与 per-input config 逐条配置xberg C 绑定批量文档抽取实战xberg_extract_batch 与 per input config 逐条配置 本篇技术指南聚焦 xberg 的后端AI 应用NLPLunaTranslator 文字处理全解析16 种文本清洗/去重方法的原理、配置与实战指南LunaTranslator 文字处理全解析16 种文本清洗/去重方法的原理、配置与实战指南 导读 在 Visual Novel TranslatorLu后端AI 应用NLPG-Helper技术解析华硕笔记本开源控制工具深度指南G Helper技术解析华硕笔记本开源控制工具深度指南 G Helper是一款专为华硕笔记本设计的开源控制工具以轻量级架构和高效性能管理为核心优势为ROG后端AI 应用NLP上一篇FreeGLUT终极实战指南掌握跨平台OpenGL开发的完整构建流程下一篇最完整OpenHands 0.25.0升级指南GitLab集成与多会话管理新范式创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考