Xberg Dart 绑定独立 DOCX 提取实战：用 XbergBridge.extract 从 Word 文档抽取全文内容-育师

后端
AI 应用
NLP

【免费下载链接】xberg

Polyglot 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 语言绑定中最常见的独立 DOCX 提取场景：通过XbergBridge.extract将一份.docxWord 文档的正文内容整体抽取出来。你将掌握 Dart 侧完整的 API 调用范式——初始化RustLib、用 JSON 构造ExtractInput与ExtractionConfig、调用提取接口、读取results[0].content并正确释放原生运行时，同时结合 e2e 测试、fixture 与 Rust 核心源码，理解 DOCX 提取的底层调用链与配置含义。

场景与前置准备

xberg 是一个以 Rust 为核心的多语言文档智能引擎，Dart 绑定通过flutter_rust_bridge（FRB）将原生能力封装成 Dart 可用的 Future/Stream API，既可用于 Flutter 应用，也可用于纯 Dart 服务端场景（参见 Dart 绑定说明）。"Standalone DOCX extraction"（独立 DOCX 提取）指的就是：不依赖任何服务端进程、直接在宿主应用内完成对单个 Word 文档的抽取。

安装依赖：

dart pub add xberg

Flutter 项目则使用flutter pub add xberg。包内通过 flutter_rust_bridge 2.x 交付各平台原生运行库，包清单见 packages/dart/pubspec.yaml。

完整代码示例

关联文档docs-site/src/snippets-generated/dart/format_specific/format_docx_standalone.md给出了一个可直接运行的完整示例，核心如下（原样继承并补充说明）：

import 'dart:io'; import 'package:xberg/xberg.dart'; import 'package:xberg/src/xberg_bridge_generated/frb_generated.dart' show RustLib; Future<void> main() async { await RustLib.init(); try { final input = await createExtractInputFromJson(json: '{"filename":"fake.docx","kind":"uri","mime_type":"application/vnd.openxmlformats-officedocument.wordprocessingml.document","uri":"https://example.com/docx/fake.docx"}'); final config = await createExtractionConfigFromJson(json: '{}'); final result = await XbergBridge.extract(input, config: config); stdout.writeln(result.results[0].content); } finally { RustLib.dispose(); } }

这段代码完成四件事：加载原生运行时 → 构造输入与配置 → 执行提取 → 输出正文并释放运行时。下面逐段拆解。

代码逐段拆解

1. 初始化与释放原生运行时

await RustLib.init();

RustLib由 flutter_rust_bridge 代码生成器产生，位于packages/dart/lib/src/xberg_bridge_generated/frb_generated.dart，负责加载并初始化打包在 xberg 包内的 Rust 原生库。提取结束后的清理同样关键：

finally { RustLib.dispose(); }

用try/finally保证无论提取是否抛错，原生运行时都能被正确释放，避免在长期运行的服务中泄漏资源。

2. 构造 ExtractInput（输入描述）

createExtractInputFromJson是 FRB 生成的便捷构造器，将 JSON 字符串解析为 Dart 侧的ExtractInput对象。示例中的 JSON 声明了一个"远程 URI 输入"：

{ "filename": "fake.docx", "kind": "uri", "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "uri": "https://example.com/docx/fake.docx" }

各字段含义如下：

字段	取值示例	说明
`kind`	`uri`	输入来源类型。`uri`表示按地址拉取文档；还支持`bytes`（直接内联二进制字节数组）等其他种类
`uri`	`https://example.com/docx/fake.docx`	文档地址。fixture 场景下会指向 mock 服务器；实际使用中可指向远程 URL，也可以配置为本地可访问的地址
`mime_type`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	标准 Office Open XML Word 文档 MIME 类型，帮助引擎正确路由到 DOCX 提取器
`filename`	`fake.docx`	文件名提示，参与格式识别与元数据产出

对应地，e2e 测试中还会把uri中的$mock_url占位符替换为 mock 服务器地址（见 e2e/dart/test/format_specific_test.dart），确认这套输入结构在真实 HTTP 拉取路径下同样成立。

3. 构造 ExtractionConfig（提取配置）

final config = await createExtractionConfigFromJson(json: '{}');

createExtractionConfigFromJson将 JSON 映射为 Dart 侧的ExtractionConfig。传{}表示全部采用引擎侧默认值——对独立 DOCX 提取而言，默认配置已经足够：引擎会自动选择文本提取路径，产出结构化正文。需要说明的是，ExtractionConfig是一个无默认值的生成数据类，所有被省略的字段都会保持 Rust 侧的默认设置（参见 packages/dart/README.md 中"build it from JSON"的用法说明）。

4. 调用 extract 并读取结果

final result = await XbergBridge.extract(input, config: config); stdout.writeln(result.results[0].content);

XbergBridge.extract返回一个结果对象，其中results数组按输入顺序对应每份文档的抽取结果。单文档场景固定取results[0]，其content字段即为抽取出的正文。提取结果还包含mimeType等元信息（e2e 测试中会断言result.results[0].mimeType等于输入 MIME，见 e2e/dart/test/extract_test.dart）。

通过配置控制 DOCX 提取细节

空配置是起点，但不是唯一选项。xberg 支持六种输出格式（纯文本、Markdown、Djot、HTML、JSON 树、Docling DocTags），DOCX 提取器会依据OutputFormat决定正文渲染形态。同一批 e2e 测试展示了带格式配置的用法（见 e2e/dart/test/format_specific_test.dart）：

final config = await createExtractionConfigFromJson( json: '{"output_format":"markdown"}', ); final result = await XbergBridge.extract(input, config: config); expect(result.results[0].content, contains(r'$'));

这条测试验证的是：DOCX 中的公式以 LaTeX 数学形式输出到 Markdown 正文中（content含$分隔符）。如果你处理的是含公式、表格或图片的 Word 文档，可以按需组合output_format、extract_tables、extract_images等字段；对扫描版 Word 转 PDF 场景，还可叠加force_ocr与ocr.backend（如tesseract）。

底层调用链：从 Dart 到 Rust DOCX 解析器

理解调用链有助于排查问题。Dart 侧XbergBridge.extract经由 FRB 落到 Rust 侧后，依次经过：

API 处理层：extract_handler统一接收输入与配置，合并默认配置并执行 URI 策略校验（见 crates/xberg/src/api/handlers.rs）。校验不通过的本地 URI 会被拒绝，这解释了为什么 e2e 测试需要通过CRAWLBERG_ALLOW_PRIVATE_NETWORK环境变量放行 mock 服务器（见 e2e/dart/test/format_specific_test.dart）。
批量提取入口：extract_unified_inputs将ApiExtractInput转换为核心ExtractInput后调用extract_batch（见 crates/xberg/src/api/handlers.rs）；extract_batch最终交由全局默认引擎执行（见 crates/xberg/src/core/extract/mod.rs）。
DOCX 专用提取器：引擎按 MIME/格式识别结果路由到crates/xberg/src/extractors/docx.rs，其核心函数parse_docx_core调用crates/xberg/src/extraction/docx/parser的parse_document，一次性产出文本、表格、页面边界、绘图（含图片关系）以及内部文档结构（见 crates/xberg/src/extractors/docx.rs）。这意味着一次extract调用拿到的content不只是裸文本——表格、图片占位、页眉页脚等都会被按输出格式组织进正文。

测试与断言：如何验证提取成功

关联场景在仓库中有三层可验证证据：

e2e 断言：format_specific_test.dart中对应测试断言result.results[0].content.length大于等于 20（见 e2e/dart/test/format_specific_test.dart），即"提取不报错且确实产出了非空正文"。

fixture 定义：fixtures/format_specific/format_docx_standalone.json定义了该场景的 mock 行为——/docx/fake.docx返回 200 与 DOCX MIME 头，正文来自test_documents/docx/fake.docx，断言为not_error+content最小长度 20（见 fixtures/format_specific/format_docx_standalone.json）。mock 服务器由 e2e/dart/test/e2e_helpers.dart 中的startMockServer启动。

Rust 侧单测：DOCX 解析器的解析、预算控制与安全限制等细节可在crates/xberg/src/extractors/docx.rs及其对应测试中继续深挖。

运行与验证

在仓库内运行该 e2e 用例的方式与仓库其他 Dart 测试一致：启动 mock 服务器（或通过MOCK_SERVER_URL/SUT_URL指向现成被测服务），然后执行dart test。作为快速验证，也可以把上文完整示例保存为main.dart，在配置好原生库的 Dart 环境中直接运行，观察标准输出中的正文内容。

需要注意的是：本文示例中的uri指向https://example.com/docx/fake.docx，这是 fixture 的占位地址；在实际项目中应替换为真实的文档地址，并确保该地址在CRAWLBERG_ALLOW_PRIVATE_NETWORK允许的访问策略范围内（默认仅允许公网 URI，本地地址需显式放行）。