后端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 的config_security_limits契约测试为切入点讲解如何在 Python 绑定中通过ExtractionConfig.from_json注入security_limits配置对 ZIP 归档类文档的抽取施加自定义安全限制压缩比、总大小、文件数等并结合 Rust 核心中SecurityLimits与ZipBombValidator的真实实现说明这些参数在底层如何参与防 ZIP 炸弹、防深度嵌套、防迭代爆炸等校验帮助你在处理不可信文档源时正确配置并调优这套安全边界。1. 契约测试场景带自定义安全限制的归档抽取本文的原始素材是自动生成的契约测试片段 config_security_limits.md由 alef 从契约定义生成文件头注明alef e2e generate可再生成、alef verify可校验时效。该契约验证的核心命题是当调用方显式传入自定义security_limits时配置能够生效且正常的归档文档仍能成功抽取而不是被过严的默认值误杀或被忽略掉退回默认值。契约定义文件是 config_security_limits.json其中包含三部分关键信息{ id: config_security_limits, call: extract, input: { mock_responses: [ { path: /archives/documents.zip, status_code: 200, headers: { content-type: application/octet-stream }, body_file: ../test_documents/archives/documents.zip } ], extract_input: { kind: uri, uri: $mock_url/archives/documents.zip } }, assertions: [ { type: contains_any, field: results[0].mime_type, values: [application/zip, application/x-zip-compressed] }, { type: min_length, field: results[0].content, value: 10 } ], config: { security_limits: { max_archive_size: 104857600, max_compression_ratio: 50, max_files_in_archive: 100 } } }从源码结构看该契约的执行方式为测试环境启动一个本地 mock HTTP 服务器将test_documents目录下的真实documents.zip固定文档以/archives/documents.zip路径暴露出来$mock_url占位符在运行时被替换为实际地址。断言要求results[0].mime_type命中application/zip或application/x-zip-compressed且content长度至少为 10——即抽取不仅没被安全限制拦截还成功产出了非空内容。这套契约同时以 15 种语言生成对应片段与测试例如 Python 版本为 test_contract.py 中的test_config_security_limits。测试代码与片段一致构造 URI 输入、以 JSON 字符串形式构造配置、调用extract断言 MIME 与内容长度。由于 mock 输入是固定文档该测试在 CI 中可完全可复现地验证自定义安全限制 正常归档 → 成功抽取这一路径。2. Python 侧用法ExtractionConfig.from_json 注入 security_limits片段给出的最小可运行示例typecheck 级需先安装 Python 绑定xberg包import asyncio from xberg import extract, ExtractInput, ExtractInputKind from xberg._xberg import ExtractionConfig async def main() - None: input ExtractInput(kindExtractInputKind(uri), urihttps://example.com/archives/documents.zip) config ExtractionConfig.from_json({\security_limits\:{\max_archive_size\:104857600,\max_compression_ratio\:50,\max_files_in_archive\:100}}) result await extract(input, config) print(result.results[0].mime_type) print(result.results[0].content) asyncio.run(main())要点拆解ExtractionConfig.from_json是原生产出xberg._xberg模块提供的静态方法接受完整配置的 JSON 字符串字段与 Rust 核心ExtractionConfig的 serde 定义对齐示例中 URI 为演示用占位地址真实复现契约测试时应使用 mock 服务器地址对应契约中的$mock_url/archives/documents.zipsecurity_limits支持部分覆盖本例只给了 3 个字段其余字段自动回落默认值。这一点由 Rust 端SecurityLimits结构上的#[serde(default, deny_unknown_fields)]属性保证——缺省字段取Default实现未知字段直接报错而非静默忽略。Python 绑定中该类型的完整定义见 options.py 的SecurityLimitsdataclass以及类型声明 xberg.pyi。ExtractionConfig的security_limits字段为OptionSecurityLimits不传时整包使用默认限制传入时按字段覆盖。配置参考文档 configuration.md 对该字段的官方描述是它控制归档抽取的最大归档大小、压缩比、文件数等阈值以防止解压炸弹攻击同时对嵌套深度、迭代次数、实体/令牌长度、内容总大小、解码图像分配和表格单元格数施加上限当为None时使用默认限制。另一个值得注意的边界参考文档同时指出security_limits不允许按文件覆盖——在批量抽取中FileExtractionConfig明确把security_limits列为全局安全策略字段与max_concurrent_extractions、use_cache、acceleration同列整个批次共用一份策略避免批次内不同文件各自放宽限制。3. 参数全解SecurityLimits 的十个字段与默认值以下默认值取自 Rust 核心的SecurityLimits::default()实现与 types.md 的字段表二者一致字段类型默认值作用与适用位置max_archive_sizeusize524288000500 MB归档解压后总大小上限。ZipBombValidator在遍历中央目录时逐条累加并在每条之后比较max_compression_ratiousize100100:1压缩比上限。同时作用于单个成员有前置条件与整个归档的聚合比max_files_in_archiveusize10000归档条目数上限超即在验证起始处报TooManyFilesmax_nesting_depthusize1024通用嵌套深度protobuf/iWork、JSON 等与max_xml_depth取两者较小值生效于SecurityBudgetmax_entity_lengthusize10485761 MiB单个 XML 实体/属性/令牌的长度上限按 token 计不是总量拦截 billion-laughs 类单实体膨胀max_content_sizeusize104857600100 MB字符串增长与解码图像分配的上限按操作计如逐页 pass 按批计账跨页栅格总量由max_pages兜底max_iterationsusize10000000解析循环迭代上限XML 事件循环、HTML 分词、JSON 解析等对外部 redaction findings 只能下调、不能突破 10,000 条的硬顶max_xml_depthusize1024XML 元素嵌套深度上限max_table_cellsusize100000全文档聚合表格单元格上限防声称几十亿空单元格耗尽内存可信的大表格输入可显式调高max_pagesOptionNone不限页数/幻灯片数/帧数上限。仅在能廉价计数的格式上强制PDF、PPTX、Keynote、ODP 及开启ocrfeature 后的多帧 TIFF对 DOCX/ODT/XLSX 等页数非存储值的格式是静默 no-op理解这套参数设计的关键是源码注释里反复强调的定位所有默认值刻意保守以防 DoS 攻击的同时兼容合法文档。契约测试里max_archive_size: 104857600100 MiB、max_compression_ratio: 50、max_files_in_archive: 100三个值都严于默认值正好构成更严格策略下正常文档仍可通过的正向验证。4. 底层实现ZipBombValidator 如何执行这三个限制契约中配置的三个字段恰好对应 security.rs 中ZipBombValidator::validate的完整检查链。逐条对照源码行为文件数先行validate首先取archive.len()若file_count max_files_in_archive立即返回SecurityError::TooManyFiles。这是最廉价的检查不碰任何条目。逐条累加与逐条判顶对每个条目通过by_index_raw解析头部拿到compressed_size/uncompressed_size——该方式不构建解压器因此使用不支持的压缩方式或需要密码的条目同样计入总量不会从账目里消失。累加使用saturating_add且每加一条就与max_archive_size比较一次。注释特别说明原因声明大小直接来自攻击者可控的 ZIP64 头单条可接近u64::MAX无保护的会回绕成小值从而放过整个归档对应的回归测试见 issue_197_archive_size_accounting_overflow.rs。单成员压缩比带地板保护只有当compressed_size 0且uncompressed_size 0视为无限比值或解压后尺寸达到MEMBER_RATIO_FLOOR1 MiB时才计算单成员比值并与max_compression_ratio比较。地板值存在的理由是千字节级的成员无论比值多大都无法耗尽内存而空白页 JPEG、空样式表、大量空白填充的页面 routinely 就能压过 100:1——无地板会让合法办公文档批量误伤。总量上限与整包聚合比值仍兜住总量。整包聚合比值收尾遍历结束后若total_compressed 0再算一次total_uncompressed / total_compressed超比即报ZipBombDetected { compressed_size, uncompressed_size, ratio }。不可读条目上报而非跳过某条目头读不出来时返回SecurityError::UnreadableEntry { index, reason }。注释的逻辑是一个未被计账的条目会让所有聚合总量不可信因此宁可整体失败也不能让该条目隐身通过。每个SecurityError变体还带有人类可读的Display实现与处置建议。例如TooManyCells的报错文案直接告诉你如果该输入可信请调高security_limits.max_table_cells否则缩小或拆分表格TooManyPages同理。这对生产排障很有价值——被限制拦截时错误信息本身就指明该调哪个旋钮。除归档路径外同一模块还提供了一组预算验证器供各解析器复用StringGrowthValidator对max_content_size记账防二次拼接/实体膨胀式 OOM、IterationValidator对max_iterations记账、DepthValidator深度进出栈饱和运算防不平衡输入下溢、EntityValidator单实体长度、TableValidator表格单元格。SecurityBudget::from_limits会把配置中的限制打包成一个预算对象注入解析器其中深度上限取max_xml_depth.min(max_nesting_depth)的更严格者——注释指出若取更宽松值会悄悄丢弃调用方通过任一旋钮收紧嵌套的意图。SecurityBudget::from_config则演示了ExtractionConfig.security_limits为None时回落SecurityLimits::default()的机制与 Python 侧不传即用默认的语义完全对应。5. 安全限制不止管归档同一份配置辐射到更多抽取路径从源码与参考文档看ExtractionConfig.security_limits是唯一的全局安全策略源头它至少辐射到归档容器ZIP 类文档DOCX/XLSX/PPTX/EPUB 等 OOXML/容器格式在打开时先过ZipBombValidator这是本文契约覆盖的路径OCR 图像解码参考文档说明OcrConfig.security_limits会在每次process_image前从ExtractionConfig.security_limits注入用于约束原始图像字节解码时的分配。相关回归测试 issue_1651_ocr_security_limits.rs 验证了调用方配置能真正到达 Tesseract 后端的解码环节且在两处ExtractionConfig与OcrConfig直接设置时不会互相漂移XML/HTML/表格解析嵌套深度、迭代次数、实体长度、表格单元格数由各解析器按SecurityBudget逐步计账例如 EPUB 加固测试epub_security_and_char_boundary_tests.rs分别构造了单条压缩比超限与条目数超max_files_in_archive两种恶意归档验证拦截行为。因此配置security_limits时应按最坏输入来源整体考虑同一服务既收用户上传的 ZIP 又做 PDF OCR 的话max_archive_size、max_compression_ratio、max_content_size、max_pages会同时成为多道闸门的阈值。6. 调参建议与验证方式结合默认值来源与契约测试结构给出可操作的调参思路默认值即生产基线不设置security_limits时你已拥有 500 MB / 100:1 / 10,000 文件 / 100 MB 内容 / 100,000 表格单元格这套保守基线绝大多数场景无需改动收紧场景面向完全不可信来源、资源受限像契约那样把max_archive_size、max_compression_ratio、max_files_in_archive调小。注意压缩比是比值而非字节数调到 50 以下时留意空白填充类正常文档可能触顶单成员有 1 MiB 地板缓解但整包聚合比值无此豁免放宽场景受信的大表格、大分页文档优先只调max_table_cells或max_pages这类针对性旋钮错误信息中也会提示对应字段名max_pages需理解其仅对可廉价计数的格式生效的限制DOCX/XLSX 上设置它不会有约束效果部分覆盖是安全的只写需要的字段其余回落默认且拼错字段名会得到deny_unknown_fields错误而非静默失效验证方式以 config_security_limits.json 为模板——固定一份正常文档作为 mock 输入断言自定义限制 合法文档 → 成功且产出非空内容反向用例可参考 EPUB 加固测试里超比归档必须被拒的构造方式双向确认限制真的生效、且不会误杀合法输入。7. 小结xberg 把文档安全做成了一个显式的配置面而非隐式魔数ExtractionConfig.security_limits在 Python以及其余各语言绑定中以 JSON 或类型化对象注入映射到 Rust 核心的SecurityLimits再由ZipBombValidator、SecurityBudget及其四个配套验证器在归档、XML、表格、OCR 解码等路径上逐条计账执行。契约测试 config_security_limits.json 所验证的自定义限制可生效且不误杀正是这条链路的端到端保证当你需要为不可信文档源定制安全策略时按第 3 节的字段表选旋钮、按第 4 节的执行链理解每道闸门的触发条件即可做出既安全又不过度拒绝的配置决策。赞分享后端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 Kotlin/Android 绑定实战用 security_limits 安全配置归档文件提取与 ZIP 炸弹防护xberg Kotlin/Android 绑定实战用 security_limits 安全配置归档文件提取与 ZIP 炸弹防护 本文围绕 xberg 项目 K后端AI 应用NLPXberg Dart 绑定独立 DOCX 提取实战用 XbergBridge.extract 从 Word 文档抽取全文内容Xberg Dart 绑定独立 DOCX 提取实战用 XbergBridge.extract 从 Word 文档抽取全文内容 导读 本文聚焦 xberg 项目后端AI 应用NLPXberg Java 绑定实战用 extract 完成 HWPX 文档的独立文本抽取Xberg Java 绑定实战用 extract 完成 HWPX 文档的独立文本抽取 导读 本文围绕 Xberg 提供的 HWPXHangul Word P后端AI 应用NLP上一篇开口就能面试interview-guide实时语音模拟面试功能完整指南基于Qwen3 ASR/TTS下一篇Radar代码架构深潜:Go单二进制如何支撑数万Pod实时K8s UI(informer缓存SSE推送原理)创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考