xberg 文档提取元数据访问实战：基于 C FFI 读取通用与格式特定元数据

后端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 是一套以 Rust 为核心的文档智能提取引擎能够从 106 种格式、140 种文件扩展名中抽取文本、元数据、图片、表格与结构化数据。本文聚焦其中最容易忽略却极其实用的一环——通过 C FFI 访问提取结果的元数据metadata以仓库中自动生成的契约测试文档 metadata_access.md 为骨架结合 元数据类型定义 与 契约测试夹具带你完整掌握如何用 4 个 C 函数完成一次文档提取、如何读懂results[0].metadata的 JSON 结构以及通用元数据字段与format判别联合discriminated union中 HTML 等格式特定元数据的深层含义。读完本文你可以在自己的 C/C 项目中直接套用这套调用模式并准确解析任意格式的提取结果元数据。背景元数据在文档提取管线中的位置xberg 的extract与extract_batch入口返回的每个文档结果都携带一份Metadata。这份元数据分为两层通用common字段所有格式共有的信息如标题、作者、语言、时间戳、页面结构等格式特定format-specific字段以内部标签判别联合internally tagged enumJSON 中体现为format对象及其format_type判别字段承载每种格式有独立的元数据模型。仓库中的metadata_access契约测试正是为验证这一能力而生它通过 C 绑定发起一次对 HTML 文档的提取随后断言results[0].metadata.format.html.title等字段的值。该文档位于 docs-site/src/snippets-generated/c/contract/metadata_access.md属于 alef 自动生成的 e2e 契约片段level 为typecheckside effect 为server即它在编译期校验 C 头文件 API 可用并在运行时连接 mock 服务器验证元数据访问契约。最小可运行示例4 个 C API 完成元数据访问原文档给出了一个完整、可编译的 C 主程序核心思路是把输入与配置以 JSON 字符串形式传入由xberg_extract返回句柄最后统一释放。#include assert.h #include stdint.h #include stdio.h #include stdlib.h #include string.h #include xberg.h int main(void) { XBERGAlefHandle input_handle xberg_extract_input_from_json({\kind\:\uri\,\mime_type\:\text/html\,\uri\:\https://example.com/html/simple_table.html\}); XBERGAlefHandle config_handle xberg_extraction_config_from_json({}); XBERGAlefHandle result xberg_extract(input_handle, config_handle); xberg_extract_input_free(input_handle); xberg_extraction_config_free(config_handle); xberg_extraction_result_free(result); return EXIT_SUCCESS; }逐行拆解这段代码xberg_extract_input_from_json接收一个 JSON 字符串构造ExtractInput。示例中声明了kind: uri按 URI 提取、mime_type: text/html与uri指向的远程地址。ExtractInputKind还支持其他来源类型例如直接传入文件字节。xberg_extraction_config_from_json接收提取配置 JSON。示例传入{}即全部采用默认配置这正符合仅验证元数据访问的契约目标。xberg_extract执行提取返回ExtractionResult句柄。结果中results[0].metadata即为本文主角。三个*_free调用分别释放输入、配置与结果句柄——这是 C FFI 的内存管理约定任何跳过释放的实现都会造成泄漏。xberg_extract_input_from_json与xberg_extraction_config_from_json的实现位于 crates/xberg-ffi/src/lib.rs如xberg_extract_input_from_json在第 22626 行附近而所有函数签名、不透明句柄类型与 Cargo feature 宏如XBERG_FEATURE_API、XBERG_FEATURE_HTML由 cbindgen 自动生成到 crates/xberg-ffi/include/xberg.h。这意味着头文件与 Rust 侧 API 始终保持同步你无需手写胶水层。契约测试断言元数据如何被访问原文档对应的契约测试夹具是 fixtures/contract/metadata_access.json它精确描述了元数据访问到底验证什么{ id: metadata_access, description: Accesses common and HTML-specific extraction metadata, docs: { presentation: { operations: [ { op: show, path: results[0].metadata }, { op: show, path: results[0].metadata.format.html.title } ] } }, call: extract, input: { mock_responses: [ { path: /html/simple_table.html, status_code: 200, headers: { content-type: text/html } } ], extract_input: { kind: uri, uri: $mock_url/html/simple_table.html, mime_type: text/html } }, assertions: [ { type: equals, field: results[0].mime_type, value: text/html }, { type: equals, field: results[0].metadata.format.html.title, value: Simple Table Test }, { type: count_min, field: results[0].metadata.format.html.headers, value: 2 } ] }从夹具中可以读出三条关键信息断言路径即元数据访问路径results[0].metadata.format.html.title表明通用结果外层是results数组每个元素含mime_type与metadatametadata.format是格式特定部分html判别其后接格式字段。测试方式契约测试通过 mock 服务器响应/html/simple_table.htmlContent-Type: text/htmlC 程序用uri输入提取该页面因此无需真实网络。期望结果HTML 文档标题为Simple Table Test且headers数量至少为 2——这验证了 xberg 不仅抽取正文还会抽取 HTML 的标题层级结构。通用元数据字段全景契约测试展示的metadata在 Rust 侧对应 crates/xberg/src/types/metadata.rs 中的Metadata结构。其通用字段所有格式均可能出现值为Option时缺省省略序列化如下字段类型含义titleOptionString文档标题subjectOptionString主题或描述authorsOptionVecString作者列表keywordsOptionVecString关键词/标签languageOptionString主语言ISO 639 代码created_at/modified_atOptionString创建/修改时间ISO 8601created_by/modified_byOptionString创建者/修改者pagesOptionPageStructure页/幻灯片/工作表结构与边界formatOptionFormatMetadata格式特定元数据判别联合image_preprocessingOption...OCR 预处理信息json_schemaOptionValue结构化数据提取的 JSON SchemaerrorOptionErrorMetadata批量操作错误信息extraction_duration_msOptionu64提取耗时批量场景填充供基准测试category/tags/document_version/abstract_textOption...来自 frontmatter 或分类的字段output_formatOptionString输出格式标识如markdownocr_usedbool是否实际启用了 OCR 后端additionalMapString, Value后处理器postprocessor写入的自定义字段两点值得注意的实现细节additional采用AHashMapCowstatic, str, Value作为内存表示序列化时转为普通HashMapString, Value从而避免静态字符串键的重复分配同时保持线上格式稳定见 metadata.rs 中additional_serde模块。ocr_used是一个#[serde(default)]的布尔字段凡管线中真正运行过 OCR 后端Tesseract、PaddleOCR、VLM 等并以其输出作为主文本或回退文本时置为true完全使用原生文本提取时为false。格式特定元数据format判别联合metadata.format在 JSON 中是一个带format_type内部标签的对象Rust 侧对应FormatMetadata枚举。从 metadata.rs 的定义可见其设计原则每次提取结果只能有一种格式类型Only one format type can exist per extraction result因此采用#[serde(tag format_type, rename_all snake_case)]序列化杜绝嵌套 Option 的混乱。目前支持的判别分支随 Cargo feature 条件编译包括format_type承载结构典型字段pdfPdfMetadataPDF 专有信息featurepdfdocxDocxMetadatacore/app/custom 属性featureofficeexcelExcelMetadatasheet_count、sheet_namesemailEmailMetadata发件人、收件人、message_id、附件pptxPptxMetadataslide_count、slide_names、图片/表格数archiveArchiveMetadataformat、file_count、file_list、total_sizeimageImageMetadatawidth、height、format、EXIFxmlXmlMetadataelement_count、unique_elementstextTextMetadataline_count、word_count、character_count及 Markdown 的headers/links/code_blockshtmlHtmlMetadata见下节ocrOcrMetadata语言、PSM、输出格式、表格统计csvCsvMetadatarow_count、column_count、delimiter、列类型推断bibtexBibtexMetadata条目数、citation keys、年份范围citationCitationMetadata记录数、DOI、关键词fiction_bookFictionBookMetadata体裁、系列、注解dbfDbfMetadata记录数与字段描述符jatsJatsMetadata版权、许可、历史日期、贡献者角色epubEpubMetadataDublin Core 扩展字段pstPstMetadata邮件消息数audioAudioMetadata时长、编码、采样率、声道、码率featuretranscription-typescodeCodeMetadatatree-sitter 结构块函数/类/模块边界与数据树featuretree-sitter从 metadata.rs 的FormatMetadata实现还可看到枚举提供了便捷访问器如html()、excel()并且apifeature 下通过 utoipa 生成带Discriminator映射的 OpenAPI 联合 schema——这意味着 REST API 文档中每个格式分支都有独立可引用的组件 schema。HTML 格式特定元数据详解契约测试断言的主角是metadata.format.html其对应HtmlMetadata同样定义在 metadata.rs。它远不止一个标题字段完整结构如下文档级信息titletitle标签、descriptionmeta namedescription、keywords按逗号拆分、authormeta nameauthor、canonical_urllink relcanonical、base_hrefbase href用于解析相对 URL、languagelang属性、text_directionltr/rtl/auto。社交与扩展元数据open_graphog:*、twitter_cardtwitter:*均以有序BTreeMapString, String保存meta_tags兜底收录未被专门字段覆盖的 meta 标签。结构抽取结果headers: VecHeaderMetadatalevel1–6、规范化text、id、文档树depth、原始 HTML 中的html_offsetlinks: VecLinkMetadatahref、text、title、link_typeanchor/internal/external/email/phone/other、rel及附加属性images: VecImageMetadataTypesrc、alt、title、dimensions、image_typedata-uri/inline-svg/external/relative与附加属性structured_data: VecStructuredDataJSON-LD / Microdata / RDFa 结构化数据块及其原始 JSON。HtmlMetadata的填充并非手工逐字段赋值#[cfg(feature html)]下实现了Fromhtml_to_markdown_rs::HtmlMetadata转换metadata.rs 第 1164 行起将底层 html-to-markdown 引擎解析出的文档信息、标题层级、链接、图片与结构化数据整体映射到 xberg 自有类型。这也是为什么契约测试中headers能被断言至少 2 个——提取器会真正解析页面里的h1–h6结构。实战建议与常见用法先看metadata.format的format_type再决定读取哪个分支。因为判别联合保证一次结果只对应一种格式解析端应优先 switch 判别字段避免按字段名猜测。区分通用字段与格式字段的落点。例如 HTML 文档的title同时出现在顶层metadata.title通用与metadata.format.html.title格式特定契约测试特意同时展示results[0].metadata与深层路径results[0].metadata.format.html.title正是为了让调用方理解这两层的关系。善用metadata.additional。后处理器postprocessor产生的自定义字段统一收纳于此不会被丢弃也不会污染顶层结构读取时需用字符串键访问。配合output_format与ocr_used做链路审计。判断文本是原生提取还是 OCR 兜底、最终输出格式是什么无需回看请求配置。进一步探索契约测试源文档docs-site/src/snippets-generated/c/contract/metadata_access.mdalef 自动生成勿手工编辑用alef e2e generate再生成、alef verify校验新鲜度元数据类型全集与序列化细节crates/xberg/src/types/metadata.rsC 头文件cbindgen 自动生成crates/xberg-ffi/include/xberg.hFFI 实现入口crates/xberg-ffi/src/lib.rs更多契约夹具OCR 配置、质量开关、输出格式等fixtures/contract/语言绑定测试目录可对照各语言调用方式e2e/c/ 与 packages/csharp/Xberg/src 等绑定源码。赞分享后端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 FFI 实战PNG 图片元数据提取冒烟测试smoke_image_png全链路解析xberg C FFI 实战PNG 图片元数据提取冒烟测试smoke_image_png全链路解析 本篇基于 xberg 仓库中的 C 语言冒烟测试片段后端AI 应用NLP使用 xberg C FFI 提取文档表格结构化单元格遍历与 Markdown 输出指南使用 xberg C FFI 提取文档表格结构化单元格遍历与 Markdown 输出指南 本文围绕 xberg 开源文档智能引擎的 C 语言 FFI 绑定讲后端AI 应用NLPXberg C FFI 实战用 xberg_extract 从远程 URL 提取文本文档Xberg C FFI 实战用 xberg_extract 从远程 URL 提取文本文档 本文以 Xberg 仓库中自动生成的 C 语言 E2E 片段 url后端AI 应用NLP上一篇GraphRAG-Local-UI 使用与启动教程下一篇3dtiles 项目安装与配置指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考