后端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点击查看免费下载本篇技术指南围绕 XbergRust 核心的 Polyglot 文档智能引擎的 C 语言绑定讲解如何仅用xberg_extract_input_from_json与xberg_extract两个函数完成 HWPXHangul Word Processor XML文档的独立standalone提取。读者将掌握 C 侧 ExtractInput 的 JSON 契约、HWPX 的 MIME 与格式识别规则、底层HwpxExtractor对正文/标题/表格/公式/图片/脚注的完整解析链路以及如何在测试夹具中验证提取结果。示例代码可直接复制编译运行。HWPX 是什么Xberg 如何支持它HWPX.hwpxOpen HWPML是韩国 Hancom 公司韩文办公套件 HWP 的 XML 格式是二进制 HWP 5.0 的 ZIP 容器后继者。与 DOCX/OOXML 类似HWPX 是一个以Contents/content.hpf为清单、以Contents/section*.xml承载正文分节的 ZIP 包。Xberg 通过 HwpxExtractor 插件支持该格式其supported_mime_types()返回两个值application/haansofthwpx—— 对外标准 MIME也是最常用的输入标识application/hwpzip—— HWPX 包内mimetype条目自声明的媒体类型。该提取器注册优先级为50插件名hwpx-extractor见 插件接口实现 与 注册测试。在格式识别层面core/mime.rs 做了双层探测扩展名.hwpx直接映射到application/haansofthwpx对字节内容则检测 ZIP 内是否存在Contents/content.hpf清单文件或读取包内未压缩mimetype条目是否为application/hwpzip且伴随清单存在从而把这类包从普通 ZIP 路由中接管过来。最小可运行的 C 示例关联文档 format_hwpx_standalone.md 给出了一段完整的、可编译运行的 C 程序——这也是本指南的核心骨架。它通过 JSON 构造一个uri类型的输入然后以默认配置调用提取#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({\filename\:\simple.hwpx\,\kind\:\uri\,\mime_type\:\application/haansofthwpx\,\uri\:\https://example.com/hwpx/simple.hwpx\}); XBERGAlefHandle result xberg_extract(input_handle, 0); xberg_extract_input_free(input_handle); xberg_extraction_result_free(result); return EXIT_SUCCESS; }要点拆解#include xberg.h来自 C 绑定头文件 include/xberg.h其中XBERGAlefHandle定义为uint64_t类型句柄见该文件第 3042 行附近所有对象都以不透明句柄形式传递。xberg_extract_input_from_json(const char *json)从 JSON 构造输入对象声明见 xberg_extract_input_from_json返回值必须用xberg_extract_input_free释放。xberg_extract(XBERGAlefHandle input, XBERGAlefHandle config)为单文档提取入口声明见 xberg_extract。第二个参数传0表示使用默认提取配置等价于xberg_extraction_config_default()。xberg_extraction_result_free释放结果句柄对应 xberg_extraction_result_free结果内容可通过xberg_extraction_result_results(handle)声明或xberg_extraction_result_to_json(handle)声明取出。这段示例是独立提取standalone语义的典型用法输入直接指向一个 HWPX 文档 URI不依赖任何前置的 MIME 探测或格式判别流程——调用方显式声明 MIME 后即可一次性拿到提取结果。更完整的 C 侧生命周期范例含错误分支与字符串释放可以参考 xberg-ffi/README.md 中的xberg_extract_input_from_uri示例。ExtractInput 的 JSON 契约xberg_extract_input_from_json接受的 JSON 在本例中共五个字段其含义与底层ExtractInput一一对应字段访问器见 xberg_extract_input_kind / _uri / _mime_type / _filename字段取值示例说明kinduri输入类型。除uri外还支持bytes等类型uri接受本地路径、file://URI 或 HTTP(S) URLurihttps://example.com/hwpx/simple.hwpx文档地址。示例中指向由测试桩返回的simple.hwpxmime_typeapplication/haansofthwpx显式声明的媒体类型。对 HWPX 声明此值可跳过内容嗅探直接路由到HwpxExtractorfilenamesimple.hwpx文件名提示用于辅助格式判定与结果元数据config省略可选本例用xberg_extract的第二个参数传0代替等价地C 侧也可用xberg_extract_input_from_uri(uri)快速构造输入声明或对字节流使用xberg_extract_input_from_bytes(bytes, len, mime_type, filename)声明后者适合从内存缓冲区直接读取 .hwpx 文件内容。测试夹具如何验证一次成功的 HWPX 提取仓库中与本文档配套的夹具 fixtures/format_specific/format_hwpx_standalone.json 完整定义了一次extract调用的服务端模拟与断言条件可以当作可运行的验收标准来理解{ id: format_hwpx_standalone, category: format_specific, call: extract, input: { mock_responses: [ { path: /hwpx/simple.hwpx, status_code: 200, headers: { content-type: application/haansofthwpx }, body_file: ../test_documents/hwpx/simple.hwpx } ], extract_input: { kind: uri, uri: $mock_url/hwpx/simple.hwpx, mime_type: application/haansofthwpx, filename: simple.hwpx } }, assertions: [ { type: not_error }, { type: min_length, field: results[0].content, value: 20 }, { type: contains, field: results[0].content, value: Hello from HWPX } ] }三个断言依次验证调用不报错提取出的文本内容长度至少 20 字符且内容包含真实文档正文Hello from HWPX。真实样本文件位于test_documents/hwpx/simple.hwpx提取器自身的端到端单测test_hwpx_extract_real_document也直接读取该文件并断言文本包含Hello from HWPX document见 hwpx.rs 测试与本夹具互相印证。底层解析链路HwpxExtractor 做了什么当输入被路由到 HwpxExtractor 后extract_content 实现 依次执行安全预检检查文件总大小是否超过security_limits.max_archive_size再以ZipBombValidator校验压缩比与包内文件数防止恶意 ZIP 包耗尽内存详见下文安全边界一节公式预扫描collect_section_formulas逐节读取Contents/section*.xml把文档内所有数学公式的 HWP EQEdit 脚本收集起来细节见下文公式小节正式解析调用unhwp::parse_bytes(content)生成结构化的Document模型标题、作者、正文分节、表格、资源表等构建内部文档build_hwpx_internal_document将模型转换为统一的InternalDocument供后续渲染 Markdown、抽取表格/图片/元数据等下游环节使用。元数据提取从doc.metadata中映射标题、作者、主题、关键词、创建/修改时间并把creator_app创建程序、format_version分别写入additional与document_version字段见 元数据构建。这意味着 HWPX 的文档属性会原样出现在提取结果的 metadata 中。正文、标题与页眉页脚解析按节section遍历每一节的正文块分为段落与表格两类带标题样式的段落p.style.is_heading()推入 heading 元素并保留标题层级普通非空段落推入 paragraph 元素每节的header/footer页眉页脚段落被完整读取并通过ContentLayer::Header/ContentLayer::Footer打上内容层标记见 push_header_footer_paragraphs这样下游include_headers/include_footers过滤配置可以精确控制是否输出。对应测试test_section_header_and_footer_are_extracted验证了页眉页脚文本确实进入输出测试。公式EQEdit 脚本到 LaTeX这是 HWPX 提取中最有特色的部分。HWP 的公式使用独立的 EQEdit 脚本 DSL而非 MathML/OMML且 Hancom 会把公式写进 run 内常规解析会将其丢弃。Xberg 采用预扫描 二次回填策略collect_section_formulas用EntityReader解析节 XML保证amp;这类实体引用被正确还原——矩阵列分隔符就是定位hp:equation/hp:eqEdit内的hp:script文本通过unhwp::equation::to_latex将脚本转换为 LaTeX公式以独立的 Formula 元素输出并保证其紧跟在引入它的段落之后公式回填逻辑。相关测试覆盖公式跟随其段落test_a_section_formula_follows_its_paragraph、run 内公式可被发现test_scan_reads_an_equation_inside_a_run、amp;实体必须还原test_scan_resolves_entity_references_in_a_script、公式移出后句子只保留一个空格test_removing_an_equation_leaves_one_space、纯公式段落不丢失数学内容test_equation_only_paragraph_keeps_its_math。这些测试全部位于 hwpx.rs 测试模块。表格表格块被展平为单元格网格每个单元格内的段落文本用\n连接并仍然走build_paragraph_content因此单元格内的脚注、链接、公式不会被丢弃cell_plain_text。表格输出同时包含cells网格与渲染好的 Markdown当unhwp报告存在表头行时第一行会被写入columns字段push_table。测试test_table_header_row_populates_columns_and_cell_content与test_table_cell_footnote_is_extracted_not_dropped分别验证了这两点。图片与资源段落内联的图片引用通过doc.resources资源表解析二进制数据并按 MIME 映射输出格式。mime_to_format特别处理了 HWPX 中常见的矢量/旧式 Windows 图元文件image/svgxml→svg、image/x-wmf→wmf、image/x-emf→emf其余回退为bin见 mime_to_format。若某个图片引用的 id 在资源表中不存在会输出带hwpx来源标识的处理警告而不会静默崩溃警告逻辑。注意表格单元格内的图片当前不提取并会给出明确警告相关测试。脚注与链接脚注在正文中以[^n]标记占位同时以独立FootnoteDefinition元素输出正文内容并标记为ContentLayer::Footnote层超链接则被记录为带起始/结束字节偏移的Link注解且偏移量在段落文本 trim 后会被重算确保始终与最终文本对齐build_paragraph_content、trim_text_and_annotations。测试test_footnote_produces_marker_and_definition与test_link_produces_link_annotation_with_correct_offsets给出了具体断言。安全边界防 ZipBomb 与大小限制HWPX 本质是 ZIP 包因此 Xberg 在解包前做多层防护实现见 extract_content 的预检段防护项依据默认行为归档总大小security_limits.max_archive_size超限即返回validation错误压缩比 / 文件数ZipBombValidator::validate依据 central directory 声明值校验超阈值拒绝单节 XML 读取上限MAX_HWPX_MEMBER_SIZE 100 * 1024 * 1024公式预扫描用Read::take硬性封顶读入字节数不信任声明值其中MAX_HWPX_MEMBER_SIZE的注释明确指出ZipBombValidator只检查 ZIP 中央目录的声明大小从不解压恶意条目可以低估声明大小而让 deflate 流远超声明因此预扫描阶段必须自行用Read::take限制读取常量与注释。测试test_scan_bounds_the_read_of_an_oversized_section_member用超过上限的 XML 注释填充验证了该边界。此外损坏的非 ZIP 输入会返回解析错误而不是 panictest_hwpx_extract_corrupted_returns_err保证 C 侧调用方拿到的是可诊断的错误而非进程崩溃。结果读取与资源释放提取完成后C 调用方应通过xberg_extraction_result_results或xberg_extraction_result_to_json读取结果并严格遵守谁创建、谁释放的句柄生命周期约定xberg_extract_input_free(input_handle)释放输入xberg_extraction_result_free(result)释放结果若通过字符串访问器取回char *需用xberg_free_string释放参见 xberg_extract_input_uri 的注释约定。扩展阅读关联文档本文骨架来源C 版 HWPX standalone 提取片段同一主题还生成了 Rust、Python、Go 等十余种语言版本可直接对照学习各自语言的 FFI 惯用法提取器源码crates/xberg/src/extractors/hwpx.rs含 1300 余行实现与测试格式识别crates/xberg/src/core/mime.rs.hwpx扩展名、content.hpf清单、包内mimetype三重识别C ABI 头文件与用法crates/xberg-ffi/include/xberg.h、crates/xberg-ffi/README.md验收夹具fixtures/format_specific/format_hwpx_standalone.json 与真实样本test_documents/hwpx/simple.hwpx。至此你已经掌握了一条完整的 HWPX 独立提取链路从 C 侧 JSON 输入契约到提取器的逐节解析与公式/表格/图片处理再到安全校验与结果释放。将此模式迁移到 bytes 输入、批量提取xberg_extract_batch或其他 106 种支持格式只是替换输入类型与 MIME 的问题。赞分享后端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点击查看免费下载相关推荐如何使用extract-text-webpack-plugin5步快速提取CSS到独立文件如何使用extract text webpack plugin5步快速提取CSS到独立文件 extract text webpack plugin是webpa开发工具Docz Monorepo 独立文档包实战用单独 docs 包为同级 peer 组件生成 API 文档Docz Monorepo 独立文档包实战用单独 docs 包为同级 peer 组件生成 API 文档 Docz 官方示例 monorepo separate文档静态站点开发工具在 ASP.NET Core 中配置多个 Scalar API References独立端点与独立 OpenAPI 文档实战在 ASP.NET Core 中配置多个 Scalar API References独立端点与独立 OpenAPI 文档实战 本篇技术指南讲解如何基于 Sca开发工具API 工具前端上一篇Firefox Send终极开发指南从环境搭建到代码调试完整流程下一篇brpc 版本演进全解析从 0.9.0 到 0.9.7 的核心特性、源码实现与升级路径创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考