Xberg C 元素级提取实战：用 ResultFormat.ElementBased 解析 DOCX 语义元素类型

后端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# 契约测试片段docs-site/src/snippets-generated/csharp/contract/config_element_types.md为骨架系统讲解如何在 .NET 中通过XbergConverter.ExtractAsync以element_based元素级结果格式提取 DOCX 文档并逐元素断言其ElementType语义类型。读完本文你将掌握ResultFormat与OutputFormat的职责区别、12 种ElementType语义分类的完整清单、Element数据结构以及该行为在 Rust 核心与 C# 绑定中的实现依据可直接用于搭建 Unstructured 风格的语义级文档解析管线。一、背景两种结果格式的定位差异在 Xberg 中提取结果有两种形状shape由ExtractionConfig.ResultFormat控制。核心定义位于 Rust 端 crates/xberg/src/types/extraction.rs#[serde(rename_all snake_case)] pub enum ResultFormat { /// Unified format with all content in content field #[default] Unified, /// Element-based format with semantic element extraction ElementBased, }Unified默认所有内容以单一content字段纯文本、Markdown 或 HTML整体返回适合直接落库、全文检索等场景ElementBased将文档拆解为带有语义分类的Element序列每个元素携带element_type、text、metadata与 Unstructured 文档的元素模型兼容适合做结构化解析、RAG 前处理。需要特别强调的是ResultFormat与OutputFormat是两个正交的维度。C# 绑定中 ResultFormat.cs 的注释对此有明确说明Distinct fromOutputFormat(which controls rendering — Plain, Markdown, HTML, etc.).ResultFormatcontrols theshapeof the result: a unified content blob vs. an element-based decomposition.即OutputFormat控制的是渲染形式纯文本、Markdown、HTML而ResultFormat控制的是返回结构整体内容块 vs. 元素级拆分。两者可以独立组合使用。二、核心代码以 element_based 格式提取 DOCX 并遍历元素契约测试片段给出了最精简的完整调用范式。原文档的 C# 代码经整理并补全注释后如下using System; using System.Text.Json; using Xberg; // 大小写不敏感的 JSON 反序列化选项用于解析枚举与输入对象 var ConfigOptions new JsonSerializerOptions { PropertyNameCaseInsensitive true }; // 1. 构造输入通过 URI 指定远程 DOCX 文档 var result await XbergConverter.ExtractAsync( new ExtractInput { Kind JsonSerializer.DeserializeExtractInputKind(\uri\, ConfigOptions)!, Uri https://example.com/docx/unit_test_headers.docx }, new ExtractionConfig { // 2. 关键配置切换到元素级结果格式 ResultFormat JsonSerializer.DeserializeResultFormat(\element_based\, ConfigOptions)! }); // 3. 遍历结果中的每一个语义元素输出其类型与文本 foreach (var element in result.Results[0].Elements!) { Console.WriteLine(element.ElementType); Console.WriteLine(element.Text); }代码执行逻辑分三步构造输入ExtractInput.Kind通过 JSON 字符串uri反序列化为ExtractInputKind.Uri配合Uri字段指向待提取文档契约测试中由 mock server 提供unit_test_headers.docx切换结果格式ExtractionConfig.ResultFormat以 JSON 枚举名element_based反序列化为ResultFormat.ElementBased。ExtractionConfig的完整定义位于 packages/csharp/src/Xberg/ExtractionConfig.cs其result_format字段默认值为ResultFormat.Unified即不显式配置时默认返回整体内容遍历元素从result.Results[0].Elements中逐个读取ElementType与Text。注意Elements属性在 C# 绑定中是可空集合IReadOnlyListElement?仅在ElementBased格式下被填充——Rust 端 extraction.rs 的注释明确说明When result_format is set to ElementBased, this field contains semantic elements。三、语义元素模型ElementType、Element 与 ElementMetadata3.1 十二种语义元素类型ElementType枚举定义了文档内容被归类成的语义单元Rust 核心定义于 crates/xberg/src/types/extraction.rsC# 绑定镜像于 packages/csharp/src/Xberg/ElementType.cs。两者均使用 snake_case JSON 序列化如narrative_text且 C# 侧通过ElementTypeJsonConverter完成字符串与枚举的互转。完整清单如下JSON 枚举值C# 枚举成员语义说明titleTitle文档标题narrative_textNarrativeText正文叙述文本headingHeading章节标题list_itemListItem列表项项目符号、编号等tableTable表格元素imageImage图片元素page_breakPageBreak分页符标记code_blockCodeBlock代码块formulaFormula数学公式text字段存放 LaTeX 源码block_quoteBlockQuote块引用footerFooter页脚文本headerHeader页眉文本从源码注释可见这套分类Supports the element types commonly found in Unstructured documents即有意与 Unstructured 生态的元素类型对齐便于既有 RAG/文档解析管线的平滑迁移。3.2 Element 结构类型、文本、元数据三位一体每个Element由四个字段构成Rust 定义于 extraction.rspub struct Element { pub element_id: String, // 确定性元素标识符 pub element_type: ElementType, // 语义类型 pub text: String, // 元素文本内容 pub metadata: ElementMetadata, // 来源与位置元数据 }C# 侧对应 packages/csharp/src/Xberg/Element.cs 的Elementrecord并提供Element.FromJson(string)静态方法用于从 JSON 字符串反序列化单个元素内部使用 snake_case 枚举转换器。ElementMetadata提供元素溯源信息Rust 端 extraction.rs字段类型含义page_numberOptionu32页码1 起始filenameOptionString来源文件名或文档名coordinatesOptionBoundingBox可用时的边界框坐标x0/y0/x1/y1element_indexOptionusize元素序列中的位置索引additionalHashMapString, String自定义附加元数据四、契约测试拆解config_element_types.json 的完整断言仓库中的 fixtures/contract/config_element_types.json 是本文核心代码片段的契约定义它详细规定了测试的输入、配置与断言可作为理解该用法的权威参考{ id: config_element_types, description: Tests element-based result format with element type assertions on DOCX, call: extract, input: { mock_responses: [ { path: /docx/unit_test_headers.docx, status_code: 200, headers: { content-type: application/octet-stream }, body_file: ../test_documents/docx/unit_test_headers.docx } ], extract_input: { kind: uri, uri: $mock_url/docx/unit_test_headers.docx } }, config: { result_format: element_based }, assertions: [ { type: contains_any, field: results[0].mime_type, values: [application/vnd.openxmlformats-officedocument.wordprocessingml.document] }, { type: count_min, field: results[0].elements, value: 1 } ] }关键信息提炼如下测试载体docx/unit_test_headers.docx是仓库内置的 DOCX 测试样本位于 test_documents 区域被 crates/xberg/tests/issue_1112_docx_element_order.rs 与 crates/xberg/tests/docx_formatting_test.rs 等多个 Rust 集成测试引用从命名与用途推断它专门用于验证标题headers类元素在 DOCX 中的识别与顺序断言一MIME 类型结果results[0].mime_type必须命中application/vnd.openxmlformats-officedocument.wordprocessingml.document即标准 DOCX 的 MIME 类型断言二元素数量results[0].elements数量至少为 1保证在element_based格式下确实产出语义元素展示操作presentation契约还声明了迭代路径results[0].elements逐项输出element_type与text两个字段——这正是前文 C# 代码中foreach循环的依据来源。五、运行前提与使用建议5.1 适用环境该用法面向C# / .NET 绑定XbergConverter类仓库同时为 15 种语言生成等价绑定Rust、Python、Go、Java、TypeScript、Swift、Ruby、PHP、Elixir、Dart、Kotlin-Android、Zig、C、WASM 等同一契约在 docs-site/src/snippets-generated 下均有对应语言版本测试片段依赖本地运行中的 Xberg 服务契约元数据side_effect: server由 mock server 返回unit_test_headers.docx实际应用中请将Uri替换为真实可访问的文档地址或改用ExtractInputKind.Bytes直接提交字节流。5.2 实战建议默认值提醒ResultFormat默认是Unified需要元素级结果时必须显式设置ElementBased配合后处理ElementMetadata.page_number、coordinates可辅助版面定位结合ContentFilterConfig可决定页眉/页脚元素是否进入结果与结构化输出组合include_document_structure与result_format相互独立见 ExtractionConfig.cs可同时启用以同时获得元素序列与层级文档树服务不同下游消费方排查顺序若遍历Elements为空优先确认ResultFormat是否生效、文档 MIME 是否为 DOCX、以及远程 URI 是否可访问。六、小结通过ResultFormat.ElementBasedXberg 在保持Unified整体内容返回能力的同时提供了一条 Unstructured 兼容的语义元素提取路径ElementType的 12 种分类覆盖标题、正文、表格、图片、公式、页眉页脚等常见版面单元Element携带的element_id与metadata又为溯源与去重提供了支撑。本文所述的全部行为均可追溯到仓库源码Rust 核心类型在 crates/xberg/src/types/extraction.rsC# 绑定在 packages/csharp/src/Xberg契约定义在 fixtures/contract/config_element_types.json读者可按此路径进一步深入源码验证与扩展。赞分享后端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 元素级提取结果格式Element-Based实战result_format 配置、element_type 断言与 C FFI 契约测试Xberg 元素级提取结果格式Element Based实战result_format 配置、element_type 断言与 C FFI 契约测试 本篇后端AI 应用NLPXberg C FFI 提取独立 DOCX 文档xberg_extract 与 ExtractInput 实战解析Xberg C FFI 提取独立 DOCX 文档xberg_extract 与 ExtractInput 实战解析 本篇技术指南围绕 Xberg 开源仓库中的后端AI 应用NLPThe Concise TypeScript Book 实战解读命名元组类型Labeled Tuple——为元组元素添加语义标签The Concise TypeScript Book 实战解读命名元组类型Labeled Tuple——为元组元素添加语义标签 本篇技术指南围绕《The文档教程上一篇记忆化搜索终极指南从递归到高效动态规划的完美转换下一篇TradingAgents-CN基于多智能体协作的金融分析平台技术架构与部署指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考