使用 Xberg C 绑定提取 DOCX 文档文本：Smoke 测试示例与底层实现解析

后端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 仓库中docs-site/src/snippets-generated/csharp/smoke/smoke_docx_basic.md这份 C# 冒烟测试文档为核心完整讲解如何通过 .NET 绑定调用XbergConverter.ExtractAsync从远程 URI 提取 DOCX 文档的纯文本与 MIME 类型。你将掌握ExtractInput的构造方式、ExtractionResult结果结构、MIME 类型提示的作用以及该调用背后由 Rust 核心负责的 DOCX 流式解析原理并能直接落地到自己的 .NET 文档解析管线中。一、文档场景C# 侧 DOCX 冒烟测试在做什么原文档smoke_docx_basic.md是 alef仓库的多语言绑定生成器为 C# 绑定自动生成的一类level: typecheck冒烟测试片段目标是验证带格式文本的 DOCX 文档这条最基础的提取链路在 C# 侧可用。它对应的 fixture 声明位于 fixtures/smoke/docx_basic.jsoncategory: smoke、tags: [smoke, office, docx]说明它属于全语言共享的冒烟用例side_effects: server表明测试依赖一个本地 mock HTTP 服务器提供样例文档输入为kind: uri的 DOCX 文档MIME 类型为application/vnd.openxmlformats-officedocument.wordprocessingml.document断言内容results[0].mime_type等于 DOCX 的 MIME 值、results[0].content长度不小于 20且包含Lorem/ipsum/document/text中至少一个词。也就是说这份文档教你的是用最少的 C# 代码把一个 DOCX 文档本地路径、file:// 或 HTTP URL 皆可送入 Xberg 提取管线然后读取提取结果中的 MIME 类型与纯文本内容。二、环境准备安装 NuGet 包在仓库中C# 绑定的官方使用说明位于 packages/csharp/README.md安装方式为 NuGetdotnet add package XbergIo.Xberg或使用 NuGet 包管理器控制台Install-Package XbergIo.Xberg系统要求.NET 10.0README 明确标注的兼容版本下限可选ONNX Runtime 1.24用于依赖 ORT 的推理类功能如嵌入向量可选Tesseract OCR用于扫描件 OCR 功能。对纯文本 DOCX 提取而言只需要基础包即可无需额外安装上述可选依赖。仓库对应的 .NET 测试工程可参考 e2e/csharp/Xberg.E2eTests.csproj。三、核心代码逐行解析原文档给出的完整 C# 示例代码如下using System; using System.Text.Json; using Xberg; var ConfigOptions new JsonSerializerOptions { PropertyNameCaseInsensitive true }; var result await XbergConverter.ExtractAsync(new ExtractInput { Kind JsonSerializer.DeserializeExtractInputKind(\uri\, ConfigOptions)!, MimeType application/vnd.openxmlformats-officedocument.wordprocessingml.document, Uri https://example.com/docx/fake.docx }, new ExtractionConfig()); Console.WriteLine(result.Results[0].MimeType); Console.WriteLine(result.Results[0].Content);3.1 输入构造ExtractInputExtractInput是 Xberg 所有公开提取入口的统一输入类型源码定义在 packages/csharp/src/Xberg/ExtractInput.cs包含以下字段字段JSON 属性名类型说明KindkindExtractInputKind输入来源类型bytes需配合Bytesuri需配合Uri默认UriBytesbytesbyte[]?kind bytes时的原始字节Uriuristring?kind uri时的本地路径、file://URI 或 HTTP(S) URLMimeTypemime_typestring?MIME 类型提示Filenamefilenamestring?用于 MIME 探测与元数据的文件名提示ConfigconfigFileExtractionConfig?单输入级提取覆盖项ExtractInputKind定义于 packages/csharp/src/Xberg/ExtractInputKind.cs是Bytes/Uri两个变体的枚举JSON 序列化时使用 snake_case 名称bytes、uri。示例代码中通过JsonSerializer.DeserializeExtractInputKind(\uri\, ConfigOptions)手动从字符串uri反序列化枚举值是为了演示 JSON 字符串到类型化输入对象的转换路径——日常开发中你也可以直接用枚举字面量ExtractInputKind.Uri效果完全一致。3.2 调用入口XbergConverter.ExtractAsyncXbergConverter是 C# 绑定的静态门面类ExtractAsync的实现位于 packages/csharp/src/Xberg/XbergConverter.cs。它的工作流程是将ExtractInput与ExtractionConfig序列化为 JSON通过NativeMethods.ExtractInputFromJson/ExtractionConfigFromJson在 FFI 边界构造原生句柄在Task.Run中调用 Rust 侧NativeMethods.Extract将文档处理放入后台线程不阻塞调用方 UI 线程把原生结果ExtractionResultToJson反序列化为类型安全的ExtractionResult在finally中释放所有原生句柄ExtractInputFree/ExtractionConfigFree避免内存泄漏。这解释了示例代码为什么是await调用——整个绑定是 async/await 风格且每次调用都有完善的句柄生命周期管理。3.3 读取结果ExtractionResult 与 ExtractedDocumentExtractAsync返回的ExtractionResult定义见 packages/csharp/src/Xberg/ExtractionResult.cs是一个统一结果信封Results按发现顺序排列的ExtractedDocument列表Errors非致命性单输入错误Summary本次操作的聚合统计CrawlFinalUrls、CrawlRedirectCount、CrawlUniqueNormalizedUrlsURL 抓取过程中的重定向与归一化信息。示例代码读取的result.Results[0]是第一个也是唯一一个ExtractedDocument定义见 packages/csharp/src/Xberg/ExtractedDocument.cs其中与本示例直接相关的字段Content提取出的纯文本内容即 DOCX 正文所有段落、列表、表格文本的拼接MimeType源文档的 MIME 类型本场景应为application/vnd.openxmlformats-officedocument.wordprocessingml.documentMetadata文档级元数据作者、标题、日期等格式特有字段Tables、Counts、DetectedLanguages表格、结构计数、语言检测等进阶字段本示例未使用。四、更符合日常习惯的等价写法示例文档刻意展示了通过 JSON 反序列化构造枚举的写法以覆盖生成绑定的 typecheck 需求实际工程中ExtractInput还提供了两个便捷静态工厂见 packages/csharp/src/Xberg/ExtractInput.csusing Xberg; // 方式一本地文件路径或 URL var input1 ExtractInput.FromUri(document.docx); var input1b ExtractInput.FromUri(https://example.com/docx/fake.docx); // 方式二内存字节 MIME 文件名提示 byte[] bytes File.ReadAllBytes(document.docx); var input2 ExtractInput.FromBytes(bytes, application/vnd.openxmlformats-officedocument.wordprocessingml.document, document.docx); var config new ExtractionConfig(); // 默认配置即可完成基础文本提取 var result (await XbergConverter.ExtractAsync(input1, config)).Results[0]; Console.WriteLine($MIME Type: {result.MimeType}); Console.WriteLine(result.Content);两种方式最终都会走到同一套 FFI 序列化路径区别仅在于字节来源FromBytes通过GCHandle钉住托管数组直接传递原始字节FromUri则只传字符串路径/URL由 Rust 侧负责读取。五、MIME 类型提示的作用示例代码显式传入了MimeType application/vnd.openxmlformats-officedocument.wordprocessingml.document。MIME 类型在这里是一个**提示hint**而非强制声明Xberg 核心会优先使用它来定位对应格式的文档提取器同时仍会结合文件内容做实际探测保证提示与真实格式不一致时结果依然可信。当提示缺失时核心会根据文件扩展名或内容签名自动判定格式只是多一步探测开销。这一点在 Rust 核心的格式注册机制中体现得很明显ListSupportedFormatsC# 侧见 XbergConverter.cs会把内置的EXT_TO_MIME静态表与运行时已注册的文档提取器求交集只公布当前构建里真正可用的格式。换言之传入正确的 MIME 提示能让提取器选择路径最直接、开销最低。六、冒烟测试验证从 fixture 到断言这份 C# 文档片段不是孤立的示例它与全语言共享的测试契约一一对应。仓库里的 e2e/csharp/tests/SmokeTests.cs 中生成了同名测试Test_SmokeDocxBasic其行为完全复刻文档代码并加了断言var Input_MockBaseUrl Environment.GetEnvironmentVariable(MOCK_SERVER_SMOKE_DOCX_BASIC) ?? Environment.GetEnvironmentVariable(MOCK_SERVER_URL) /fixtures/smoke_docx_basic; var Input_Json {\kind\:\uri\,\mime_type\:\application/vnd.openxmlformats-officedocument.wordprocessingml.document\,\uri\:\$mock_url/docx/fake.docx\} .Replace($mock_url, Input_MockBaseUrl); var result await XbergConverter.ExtractAsync(ExtractInput.FromJson(Input_Json), ExtractionConfig.FromJson({})); Assert.Equal(application/vnd.openxmlformats-officedocument.wordprocessingml.document, result.Results[0].MimeType); Assert.True(result.Results[0].Content.Length 20); Assert.True(result.Results[0].Content.ToString().Contains(Lorem) || result.Results[0].Content.ToString().Contains(ipsum) || result.Results[0].Content.ToString().Contains(document) || result.Results[0].Content.ToString().Contains(text));对应的 mock 响应在 fixtures/smoke/docx_basic.json 中声明/docx/fake.docx路径返回200、content-type: application/octet-stream正文指向test_documents/docx/fake.docx样例文件见 crates/xberg/test_documents。三条断言分别验证MIME 回显正确——提取器确认了输入格式内容非空且足够长——Content.Length 20保证文本确实被解出内容语义正确——包含 DOCX 样例中的占位文本Lorem/ipsum/document/text证明提取的是文档正文而非空壳。七、底层原理Rust 侧 DOCX 提取器如何工作示例代码能一行await拿到文本背后是 Rust 核心的 DOCX 提取器。其实现位于 crates/xberg/src/extractors/docx.rs文档注释明确说明了设计目标通过流式 XML 解析实现高速文本提取——DOCX 本质是 OOXML 压缩包zip 内的word/document.xml等部件提取器无需解压全部内容即可顺序读取正文 XML全面的元数据提取——读取core.xml核心属性、app.xml应用属性、custom.xml自定义属性产出DocxMetadata等格式特有元数据结构富文档结构还原——build_internal_document会构建扁平元素列表涵盖标题、段落、列表、表格、图片、脚注/尾注带关系与超链接作为InternalLink关系并可注入图片占位符元素细节保真——例如drawing_alt_text会优先使用wp:docPr/descr作者填写的描述缺失时回退到name确保图片 alt 文本不丢失源码注释引用了 issue #81。这些结构随后进入统一的提取管线最终在ExtractedDocument.Content中呈现为纯文本在Tables中呈现为结构化表格。也就是说本文的 C# 示例虽只打印了两个字段但同一条调用链上已经完成了表格、图片、元数据、链接等全量信息的解析C# 侧只需按需取字段即可。八、进阶用配置控制提取行为示例中传入的是new ExtractionConfig()空配置仅完成基础文本提取。当 DOCX 是扫描件、或需要更多输出维度时可以复用 packages/csharp/README.md 中的配置模式。例如开启 OCR适用于 DOCX 内嵌扫描图片页using Xberg; var config new ExtractionConfig { Ocr new OcrConfig { Backend tesseract, Language [eng, deu, fra], TesseractConfig new TesseractConfig { Psm 3 } } }; var result (await XbergConverter.ExtractAsync(ExtractInput.FromUri(scanned.docx), config)).Results[0]; Console.WriteLine(result.Content);批量处理多个 DOCX 文件时既可以循环调用ExtractAsync也可以利用XbergConverter.ExtractBatchAsync见 XbergConverter.cs一次性提交ListExtractInput由核心并行处理并在同一ExtractionResult信封内返回全部结果。九、注意事项小结.NET 10.0是绑定版本下限低于该版本需先升级运行时Kind必须与数据源匹配uri配Uri、bytes配Bytes两者错配会在 FFI 边界产生校验错误远程 URL 提取依赖网络示例文档与冒烟测试都通过 mock server 提供样例文件真实使用 HTTP(S) URL 时应确保目标可达ExtractionConfig中可配置提取超时等安全限制结果始终是信封结构即使单个输入也需通过Results[0]取文档不要假设ExtractAsync直接返回文档对象文本长度断言是冒烟级校验生产环境建议结合Counts、Tables、Metadata等字段做更细的完整性校验。至此你已经可以从smoke_docx_basic这段不到十行的 C# 代码出发完成 Xberg .NET 绑定下的 DOCX 文本提取并能进一步延伸到 OCR、表格、批量与配置化提取场景。赞分享后端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 绑定实战使用 ExtractAsync 独立提取 DOCX 文档内容xberg C 绑定实战使用 ExtractAsync 独立提取 DOCX 文档内容 本文是一份面向 .NET / C 开发者的实操指南围绕 xberg 提后端AI 应用NLPXberg C 绑定 PDF 文本提取 Smoke 测试全解析从 URI 输入到断言验证Xberg C 绑定 PDF 文本提取 Smoke 测试全解析从 URI 输入到断言验证 导读 本文围绕 Xberg 仓库中 C 语言绑定的首个 PDF 冒烟后端AI 应用NLPxberg C FFI 实战DOCX 文档提取的冒烟测试全解析xberg C FFI 实战DOCX 文档提取的冒烟测试全解析 本文围绕 xberg 仓库中一条自动生成的 C 语言冒烟测试样例展开它演示了如何通过 C F后端AI 应用NLP上一篇Google Indexing Script与个人博客提升内容曝光率的方法下一篇Effect Cluster EntityManager 缺陷恢复机制在途请求重放原理与实现解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考