Xberg C 提取配置冲突解析：ForceOcr 与 DisableOcr 同时启用时如何被校验拒绝

后端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 核心、多语言绑定中的一类典型错误场景展开当调用方在提取配置中**同时开启force_ocr强制 OCR与disable_ocr禁用 OCR**时提取请求会在进入真正的解析管线之前被校验层拦截并抛出异常。读者将掌握force_ocr、disable_ocr、ocr_strategy等 OCR 相关配置的语义与优先级、冲突校验的源码级实现路径以及 C# 绑定中正确触发、捕获和处理该错误的完整实战写法。一、错误场景概述什么是 extract forcedisable OCR该错误对应仓库中的官方测试夹具 error_extract_input_conflicting_ocr.json其定位是error/validation类别的输入校验场景。夹具的核心内容如下调用入口extract文档内容提取输入方式bytes类型内存字节数组配合mime_type: text/plain与文件名fake_text.txt配置{force_ocr: true, disable_ocr: true}—— 两个互斥开关同时被打开断言assertions中声明该请求必须返回错误type: error也就是说这是一条预期失败的用例配置自相矛盾时引擎不应静默地忽略某个开关而应在入口处给出明确的校验错误把问题暴露给调用方。对应的自动生成文档 error_extract_input_conflicting_ocr.md由 alef 工具链从夹具自动生成用于跨语言场景演示用 C# 展示了同样的调用方式本文后续会逐步拆解这段代码。二、两个互斥配置项force_ocr 与 disable_ocr 的语义与默认值要理解冲突校验先要准确掌握这两个配置项各自的语义。它们的定义位于 Rust 核心的 core.rsExtractionConfig结构体配置项类型/默认值语义force_ocrbool默认false强制 OCR即使 PDF 本身带有可搜索文本层也要执行 OCR。disable_ocrbool默认false完全禁用 OCR对所有文档类型生效图片只返回元数据尺寸、格式、EXIF而不做文字识别PDF 仅使用原生文本提取、不做 OCR 回退。ocr_strategyOcrStrategy默认Auto既未设置force_ocr也未设置force_ocr_pages时决定哪些页走 OCR默认Auto只对原生文本质量检查未通过的页做 OCR仅适用于 PDF。force_ocr_pagesOptionVecu32默认None仅对指定页从 1 开始计数强制 OCR未列出的页使用原生文本提取force_ocr为true时该项被忽略。关键约束在disable_ocr的字段文档中写得很明确Cannot betruesimultaneously withforce_ocr不能与force_ocr同时为true。这正是冲突校验的直接依据。此外还有一个容易忽视的等效通道ExtractionConfig::effective_disable_ocr()core.rs#L1090-L1092把ocr.enabled falseOcrConfig上的开关也视为disable_ocr true并称其为是否跳过 OCR 的唯一事实来源。这意味着顶层disable_ocr: true会禁用 OCR配置块ocr: { enabled: false }同样等效于禁用 OCR二者任何一个生效都会参与下面的冲突判定。三、校验时机与源码实现错误在 MIME 检测阶段就被拦截冲突校验并非发生在某个深层提取模块而是被安排在文件/字节提取流程的最早阶段——MIME 类型检测之前。实现位于 file.rs#[derive(Clone, Copy)] struct FileDetectionChecks { force_ocr_conflict: bool, scanned_pages_ocr_conflict: bool, } fn detect_file_mime_blocking( path: Path, mime_type: Optionstr, policy: MimeDetectionPolicy, checks: FileDetectionChecks, ) - ResultString { let mut file open_regular_file(path)?; if checks.force_ocr_conflict { return Err(XbergError::validation( force_ocr and disable_ocr cannot both be true.to_string(), )); } if checks.scanned_pages_ocr_conflict { return Err(XbergError::validation( ocr_strategy selects scanned pages for OCR, but disable_ocr is true.to_string(), )); } crate::core::mime::detect_or_validate_file(path, mut file, mime_type, policy) }而这两个布尔标志是在上层extract_file中、基于配置计算出来的file.rs#L203-L212let ocr_disabled config.effective_disable_ocr(); let checks FileDetectionChecks { force_ocr_conflict: config.force_ocr ocr_disabled, scanned_pages_ocr_conflict: matches!( config.ocr_strategy, crate::core::config::OcrStrategy::ScannedPages { .. } ) ocr_disabled, }; let detected_mime detect_file_mime(path, mime_type, config.mime_detection_policy, checks).await?;由此可以得到两个明确的实现事实force_ocr effective_disable_ocr()即冲突。注意右侧用的是effective_disable_ocr()而非裸的disable_ocr所以通过ocr.enabled false关闭 OCR 时同样会触发冲突。错误类型是校验错误XbergError::validation错误消息为force_ocr and disable_ocr cannot both be true。这意味着该错误在语义上属于调用方配置非法而非提取过程中的格式/超时类错误应当由调用方修复配置后重试。extract_file是文件路径提取的入口file.rs#L167字节bytes提取路径同样复用这套FileDetectionChecks判定逻辑因此两种输入方式的行为一致。四、C# 侧的正确触发写法ExtractAsync 与三层配置回到自动生成文档中的 C# 示例。它展示了在绑定层构造冲突配置并期待抛错的完整写法using System; using System.Text.Json; using Xberg; var ConfigOptions new JsonSerializerOptions { PropertyNameCaseInsensitive true }; try { var result await XbergConverter.ExtractAsync(new ExtractInput { Bytes System.IO.File.ReadAllBytes(text/fake_text.txt), Config new FileExtractionConfig { DisableOcr true, ForceOcr true }, Filename fake_text.txt, Kind JsonSerializer.DeserializeExtractInputKind(\bytes\, ConfigOptions)!, MimeType text/plain }, new ExtractionConfig { DisableOcr true, ForceOcr true }); } catch (Exception error) { Console.Error.WriteLine(${error.GetType().Name}: {error.Message}); }这段代码包含 C# 绑定中提取调用的三个关键层次ExtractInput描述提取什么。这里Kind反序列化为bytes字节输入Bytes从本地文件读取并显式给出MimeType text/plain与Filename。FileExtractionConfig每文件配置位于ExtractInput.Config用于覆盖单个文件的提取参数。它内部ForceOcr与DisableOcr都是bool?可空类型见 FileExtractionConfig.csnull表示沿用批处理默认值。这里显式同时设置为true构成冲突。ExtractionConfig全局配置ExtractAsync的第二个参数作用于整批/整次调用。其ForceOcr与DisableOcr均为非空bool、默认false见 ExtractionConfig.cs这里同样同时设为true。两层配置同时给出冲突值是为了测试引擎在最严格路径上的表现。C# 绑定层的 JSON 字段名与 Rust 端一一对应force_ocr→ForceOcrdisable_ocr→DisableOcr通过[JsonPropertyName]标注因此也可以直接用ExtractInput.FromJson(...)传入原始 JSON 配置。捕获到异常后示例打印error.GetType().Name与error.Message即可得到类似XbergException: force_ocr and disable_ocr cannot both be true的输出——异常类型取决于绑定对 Rust 校验错误的映射封装。五、测试验证E2E 层如何锁定该行为该错误场景不止有文档与夹具还有真实的跨语言端到端测试覆盖。在 C# 的 E2E 测试 ErrorTests.cs 中[Fact] public async Task Test_ErrorExtractInputConflictingOcr() { // extract forcedisable OCR await Assert.ThrowsAnyAsyncXbergException(async () { await XbergConverter.ExtractAsync( ExtractInput.FromJson({\bytes\:[...],\config\:{\disable_ocr\:true,\force_ocr\:true},\filename\:\fake_text.txt\,\kind\:\bytes\,\mime_type\:\text/plain\}), ExtractionConfig.FromJson({\disable_ocr\:true,\force_ocr\:true})); }); }测试要点使用Assert.ThrowsAnyAsyncXbergException断言必定抛出异常验证校验层确实在调用链中生效字节内容即夹具 JSON 中bytes数组对应的纯文本This is a test document...与text/plainMIME 一致说明冲突校验发生在内容解析之前——即使文档本身完全可解析配置非法也会先行拒绝该测试与夹具assertions: [{ type: error }]相互印证构成夹具定义预期 → 绑定测试执行断言的闭环。同文件中的Test_ErrorEmptyMime、Test_ErrorInvalidMimeFormat、Test_ErrorUnsupportedMime展示了同一套错误断言模式在其他校验场景下的复用。六、更广的冲突面ScannedPages 策略与 disable_ocr除force_ocr之外还有第二类会被入口校验拒绝的 OCR 冲突ocr_strategy选择ScannedPages扫描页 OCR时disable_ocr同时为true。这在 file.rs#L80-L83 中有独立分支错误消息为ocr_strategy selects scanned pages for OCR, but disable_ocr is true其设计意图在ocr_strategy的字段文档core.rs#L65-L71中有所交代Cannot beOcrStrategy::ScannedPageswhiledisable_ocristrue。也就是说凡是在语义上要求执行 OCR的设置force_ocr、ScannedPages策略、force_ocr_pages页面列表与禁用 OCR的设置同时出现时引擎都会以明确的校验错误拒绝而不是自行裁决优先级——这保证了配置行为的可预期性。七、正确用法与避坑指南结合上述语义与校验规则可以总结出实践中正确配置 OCR 的几条准则二选一不要同时设置。要么走 OCRforce_ocr: true或ocr_strategy: scanned_pages或指定force_ocr_pages要么明确关闭disable_ocr: true或ocr: { enabled: false }。两组开关互斥混用必然报错。注意等效禁用通道。通过ocr.enabled false关闭 OCR 与disable_ocr true等效同样会与force_ocr冲突排查问题时不要只看顶层disable_ocr一个字段。区分配置层级。FileExtractionConfig中的ForceOcr/DisableOcr是可空的覆盖项null表示不覆盖批处理默认而ExtractionConfig中的同名字段有明确默认值false未设置与显式 false在覆盖语义上不同批量场景下应留意继承关系。按错误类型处理。这类冲突返回的是校验类错误validation属于调用方配置问题应修复配置后重试而不是重试同一份错误请求。仅 PDF 相关的策略不要误用于其他格式。ocr_strategy与force_ocr_pages仅对 PDF 生效参见 core.rs#L65-L81 的字段注释对其他格式设置这些项不会产生预期效果。如果调用方需要能搜到文本就不 OCR、搜不到再兜底的行为应依赖默认的ocr_strategy: Auto或显式ocr_near_empty_fallback相关开关见 core.rs#L93-L108而不是同时打开两个互斥开关去碰运气。总结force_ocr与disable_ocr的冲突校验是 Xberg 输入验证体系中的一个典型切片它由夹具 error_extract_input_conflicting_ocr.json 定义预期、由 Rust 核心 file.rs 在 MIME 检测阶段提前拦截、由 C# 绑定 ExtractionConfig.cs 与 FileExtractionConfig.cs 暴露配置面、并由 E2E 测试 ErrorTests.cs 锁定行为。理解这条从配置语义 → 校验实现 → 绑定写法 → 测试断言的完整链路不仅能帮你在 C# 等语言中正确规避此类错误也能举一反三地把握 Xberg 对其他互斥配置如ScannedPages与disable_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 错误处理指南空 MIME 类型如何被一致拒绝并优雅处理Xberg C 错误处理指南空 MIME 类型如何被一致拒绝并优雅处理 导读 本文聚焦 XbergRust 核心的多语言文档智能提取引擎C 绑定中一个常见后端AI 应用NLPxberg C FFI 契约测试解析如何用 output_format: markdown 配置 Markdown 文档提取xberg C FFI 契约测试解析如何用 output_format: markdown 配置 Markdown 文档提取 xberg 以 Rust 内核提后端AI 应用NLPxberg 中空 MIME 类型的拒绝机制从 C FFI 调用到 Rust 内核的完整校验链路xberg 中空 MIME 类型的拒绝机制从 C FFI 调用到 Rust 内核的完整校验链路 本文以 xberg 的 error_empty_mime 错误后端AI 应用NLP上一篇终极指南如何快速上手Oracle Docker镜像下一篇终极指南如何使用Keras预训练深度学习模型进行图像分类创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考