用 Dart 调用 xberg bytes 提取 API 输出 Markdown：从契约测试到源码实现

后端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 仓库中的契约测试用例output_format_bytes_markdown为核心讲解如何通过 Dart 绑定调用XbergBridge.extract把内存中的 PDF 字节流直接转换成 Markdown 文档并完整覆盖输入构造、配置传递、结果断言与底层OutputFormat的实现原理。读完本文你将能够在 Dart 应用中复现并扩展这一提取流程理解output_format配置项在 xberg Rust 内核中的解析与渲染路径。场景定位bytes 输入 markdown 输出在 xberg 的跨语言 E2E 测试体系中fixture_dart_output_format_bytes_markdown属于 contract 类目契约测试用例文档它验证的是不依赖文件系统与网络仅凭一段二进制 PDF 字节数组即可完成文档提取并以 Markdown 格式返回。这在需要处理上传文件、加密文档或内存缓存数据的服务端场景中非常实用。该场景的核心输入来自 fixtures/contract/output_format_bytes_markdown.json其要点如下字段值说明callextract调用单文档提取 API非批量extract_batchinput.kindbytes输入类型为内存字节流input.mime_typeapplication/pdf显式声明 MIME 类型避免嗅探input.filenamefake_memo.pdf用于错误提示与元数据回填config.output_formatmarkdown核心配置要求结果渲染为 Markdown断言 1results[0].mime_type application/pdf输入类型被正确识别并透传断言 2results[0].content长度 ≥ 10成功提取出非空内容断言 3results[0].metadata.output_format markdown输出格式标记被正确记录对应地e2e/dart/test/contract_test.dart 中自动生成并实际运行了同名测试对mimeType、content长度和metadata.outputFormat三者逐一断言保证了 fixture 定义与真实 Dart 绑定行为一致。Dart 侧完整调用代码原文档给出了可直接运行的 Dart 示例其完整调用链如下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 input await createExtractInputFromJson(json: {bytes:pdf/fake_memo.pdf,config:{output_format:markdown},filename:fake_memo.pdf,kind:bytes,mime_type:application/pdf}); final config await createExtractionConfigFromJson(json: {output_format:markdown}); final result await XbergBridge.extract(input, config: config); stdout.writeln(result.results[0].mimeType); stdout.writeln(result.results[0].content); stdout.writeln(result.results[0].metadata.outputFormat); } finally { RustLib.dispose(); } }逐段拆解这段代码的关键点RustLib.init()与RustLib.dispose()xberg 的 Dart 包基于 Flutter 与 Rust 的 FFI 桥接frb_generated.dart即 flutter_rust_bridge 生成的胶水代码调用任何提取 API 前必须初始化原生运行时结束后必须显式释放否则进程不会干净退出。finally块保证了异常路径下也能释放资源。createExtractInputFromJson契约测试通过 JSON 字符串构造强类型输入对象kind为bytes时携带二进制数组需要说明的是真实使用中bytes应替换为 PDF 文件的字节列表Listint测试用例中内联了整份fake_memo.pdf的字节序列。createExtractionConfigFromJson同样以 JSON 字符串构造配置对象这里只设置了output_format。XbergBridge.extract(input, config: config)真正发起提取的入口返回包含results列表的提取结果results[0]即该文档的提取结果对象。结果字段mimeType为原始 MIME 类型content为提取出的正文在 Markdown 格式下即 Markdown 文本metadata.outputFormat记录了本次实际使用的输出格式。输出格式配置的源码级原理output_format不是 Dart 绑定层发明的概念而是直接映射到 Rust 内核的OutputFormat枚举。该枚举定义于 crates/xberg/src/core/config/formats.rs#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all lowercase)] pub enum OutputFormat { #[default] Plain, // 纯文本默认 Markdown, // Markdown 格式 Djot, // Djot 标记语言 Html, // HTML 格式 Json, // 以标题驱动的 JSON 树 DocTags, // Docling DocTags 格式表格渲染为 OTSL #[serde(untagged)] Custom(String), // 通过 RendererRegistry 注册的自定义渲染器 }几个值得注意的实现细节大小写不敏感与别名FromStr实现同文件 L68-L82对markdown与md都解析为Markdownplain与text解析为Plain解析过程先to_lowercase()因此MARKDOWN同样有效。serde 反序列化同样采用rename_all lowercase所以 JSON 中的键必须是全小写markdown。默认值是Plain在 crates/xberg/src/core/config/extraction/core.rs 的ExtractionConfig::default()中output_format默认为OutputFormat::Plain即不配置时返回纯文本显式指定markdown才会触发 Markdown 渲染管线。拼写错误的兜底行为任何未识别的字符串如markdwon会落入Custom(String)分支而不是报错源码测试should_treat_typo_of_a_keyword_as_custom_not_a_real_variant专门固化了这一行为——这意味着配置拼写错误不会抛异常但也不会按预期渲染需要靠结果元数据校验。元数据回填fixture 断言metadata.output_format markdown对应 Rust 侧提取结果会把实际生效的OutputFormat写入元数据这也是端到端验证配置确实被消费的关键信号。从配置到渲染Markdown 的产出路径当output_format Markdown时内核会走一条与纯文本不同的渲染路径。从源码结构看OutputFormat::Markdown对应名为markdown的渲染器见 formats.rs 中的renderer_name该渲染器在 crates/xberg/src/core/pipeline/format.rs 的格式管线中被调用负责把各提取器产出的结构化内容标题、段落、表格、列表等序列化为 Markdown 语法。在实际 PDF 提取场景中Rust 侧的 crates/xberg/src/extractors/pdf/mod.rs 等提取器先解析页面文本与版面结构再由 Markdown 渲染器统一输出。这也是为什么同一个output_format配置可以跨 PDF、DOCX、HTML 等多种格式复用的原因——提取与渲染是两个解耦的环节。与 Markdown 输出相关的还有两个配置项值得留意定义于ExtractionConfig配置项默认值作用escape_markdowntrue控制提取文本中的 Markdown 特殊字符是否转义use_layout_for_markdownfalse是否利用版面分析结果增强 Markdown 排版如何运行与验证要实际运行该契约测试仓库提供了完整的 Dart E2E 环境见 e2e/dart/先构建并初始化 Dart 绑定所需的原生库对应 crates/xberg-node/ 与 packages/dart/ 中的构建流程。测试运行时通过CRAWLBERG_ALLOW_PRIVATE_NETWORKtrue与RUST_MIN_STACK16777216环境变量初始化原生运行时见 contract_test.dart。执行dart test运行contract_test.dart测试会自动生成 fixture 对应的输入并调用XbergBridge.extract最终以三条expect断言完成校验。如果你只想做快速验证也可以直接运行 e2e/dart/quick_test.mjs 或参考 e2e/dart/package.json 中定义的脚本。小结output_format_bytes_markdown契约测试完整覆盖了 xberg 一条核心能力链路Dart 构造 bytes 输入 → FFI 调用 Rust 内核 →output_format: markdown驱动 Markdown 渲染 → 结果与元数据回传 Dart。对开发者而言掌握这一模式即可举一反三将output_format切换为html、json、djot或doctags或改用extractBatch批量处理多个文档contract_test.dart 中展示了带每项独立 config 的批量 bytes 提取用例即可在同一套 API 上获得不同格式的提取结果。赞分享后端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 API 实战通过 bytes 输入将 PDF 提取为 Markdown 输出格式xberg C API 实战通过 bytes 输入将 PDF 提取为 Markdown 输出格式 本文基于 xberg 仓库中自动生成的 C 语言契约测试片段后端AI 应用NLPxberg C FFI 契约测试解析如何用 output_format: markdown 配置 Markdown 文档提取xberg C FFI 契约测试解析如何用 output_format: markdown 配置 Markdown 文档提取 xberg 以 Rust 内核提后端AI 应用NLPXberg C API 批量提取实战用 xberg_extract_batch 处理非法 MIME 的 bytes 输入Xberg C API 批量提取实战用 xberg_extract_batch 处理非法 MIME 的 bytes 输入 导读 本文聚焦 Xberg以 Ru后端AI 应用NLP上一篇first-contributions 中删除本地创建分支的完整指南git branch -d / -D 三种方式实战与差异解析下一篇MinecraftForge模组开发终极指南从零开始打造你的第一个模组创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考