后端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 绑定错误示例error_extract_input_conflicting_ocr为切入点完整讲解 xbergRust 核心、多语言绑定的文档智能提取引擎在force_ocr与disable_ocr同时为真时如何触发参数校验错误并结合仓库源码剖析该校验在字节提取、文件提取、配置检查与 CLI 覆盖层的实现位置与行为。读完本文你将掌握 OCR 相关配置项的语义、冲突组合的排查方法以及如何在 C、Rust、CLI 等调用方式下写出不会被参数校验拒绝的正确提取配置。一、这个错误示例要验证什么在 xberg 的端到端契约测试体系alef中每个fixture都是一段可复现的真实调用场景。error_extract_input_conflicting_ocr属于category: error其唯一断言就是“调用必须返回错误”assertions: [{ type: error }]用于验证引擎对非法配置组合的防御能力。其 fixture 定义位于 fixtures/error/error_extract_input_conflicting_ocr.json{ id: error_extract_input_conflicting_ocr, category: error, description: extract forcedisable OCR, call: extract, input: { kind: bytes, bytes: [84, 104, 105, 115, ...], mime_type: text/plain, filename: fake_text.txt }, assertions: [{ type: error }], config: { force_ocr: true, disable_ocr: true } }输入是一个text/plain字节数组内容为 “This is a test document to use for unit tests. Doylestown, PA 18901 ...”而配置同时设置了force_ocr: true与disable_ocr: true—— 两个语义完全相反的开关。该 fixture 的核心意图是确认当调用方给出自相矛盾的 OCR 配置时引擎必须在执行任何实际提取工作之前快速失败fail fast而不是带着混乱的配置继续运行。对应生成的语言示例位于 docs-site/src/snippets-generated/c/error/error_extract_input_conflicting_ocr.md同一场景在仓库中还有 C#、Python、Rust、Go、Java、Node/TypeScript、PHP、Ruby、Swift、Dart、Kotlin、Elixir、Zig、WASM 等十余种绑定语言的同构版本说明该校验是跨语言一致的引擎级行为而非某个绑定特有的逻辑。二、C 绑定调用示例逐步拆解原文档提供了一段完整的 C 示例它通过 xberg 的 C FFI见 crates/xberg-ffi构造字节输入并调用提取接口期望得到冲突校验错误。下面保留完整代码并逐段说明其职责#include assert.h #include stdint.h #include stdio.h #include stdlib.h #include string.h #include xberg.h int main(void) { const char *input_json_base {\bytes\:\__ALEF_DOC_FILE_0__\,\config\:{\disable_ocr\:true,\force_ocr\:true},\filename\:\fake_text.txt\,\kind\:\bytes\,\mime_type\:\text/plain\}; FILE *input_file_0 fopen(text/fake_text.txt, rb); if (input_file_0 NULL) return EXIT_FAILURE; fseek(input_file_0, 0, SEEK_END); long input_size_0 ftell(input_file_0); if (input_size_0 0) { fclose(input_file_0); return EXIT_FAILURE; } rewind(input_file_0); uint8_t *input_bytes_0 malloc(input_size_0 0 ? (size_t)input_size_0 : 1); if (input_bytes_0 NULL) { fclose(input_file_0); return EXIT_FAILURE; } if (fread(input_bytes_0, 1, (size_t)input_size_0, input_file_0) ! (size_t)input_size_0) { free(input_bytes_0); fclose(input_file_0); return EXIT_FAILURE; } fclose(input_file_0); char *input_bytes_json_0 malloc((size_t)input_size_0 * 4 3); if (input_bytes_json_0 NULL) { free(input_bytes_0); return EXIT_FAILURE; } size_t input_offset_0 0; input_bytes_json_0[input_offset_0] [; for (long i 0; i input_size_0; i) { input_offset_0 (size_t)snprintf(input_bytes_json_0 input_offset_0, 5, %s%u, i 0 ? : ,, input_bytes_0[i]); } input_bytes_json_0[input_offset_0] ]; input_bytes_json_0[input_offset_0] \0; free(input_bytes_0); const char *input_marker_0 \__ALEF_DOC_FILE_0__\; const char *input_position_0 strstr(input_json_base, input_marker_0); if (input_position_0 NULL) { free(input_bytes_json_0); return EXIT_FAILURE; } size_t input_prefix_0 (size_t)(input_position_0 - input_json_base); size_t input_json_size_0 strlen(input_json_base) - strlen(input_marker_0) strlen(input_bytes_json_0) 1; char *input_json_0 malloc(input_json_size_0); if (input_json_0 NULL) { free(input_bytes_json_0); return EXIT_FAILURE; } snprintf(input_json_0, input_json_size_0, %.*s%s%s, (int)input_prefix_0, input_json_base, input_bytes_json_0, input_position_0 strlen(input_marker_0)); free(input_bytes_json_0); XBERGAlefHandle input_handle xberg_extract_input_from_json(input_json_0); free(input_json_0); XBERGAlefHandle config_handle xberg_extraction_config_from_json({\disable_ocr\:true,\force_ocr\:true}); XBERGAlefHandle result xberg_extract(input_handle, config_handle); if (result ! 0) { return EXIT_FAILURE; } xberg_extract_input_free(input_handle); xberg_extraction_config_free(config_handle); return EXIT_SUCCESS; }这段代码的关键步骤可归纳为构造输入 JSONinput_json_base中通过占位符__ALEF_DOC_FILE_0__预留文件字节位置随后读取text/fake_text.txt将其每个字节转换为无符号十进制数组[84, 104, 105, ...]并替换占位符最终得到完整的输入 JSON。注意input_json_base的config字段内已经写入了disable_ocr:true,force_ocr:true这对冲突配置它会被一起序列化进输入句柄。创建输入句柄xberg_extract_input_from_json(input_json_0)将上述 JSON 解析为提取输入kind 为bytes、MIME 为text/plain、文件名为fake_text.txt。创建配置句柄xberg_extraction_config_from_json({\disable_ocr\:true,\force_ocr\:true})单独构造携带冲突配置的ExtractionConfig。执行提取xberg_extract(input_handle, config_handle)返回非零值即代表校验失败——本示例中返回值非 0 导致main返回EXIT_FAILURE这正是“断言该调用必须出错”的 C 语言表达方式。清理句柄通过xberg_extract_input_free/xberg_extraction_config_free释放资源避免泄漏。这段代码同样可以作为手写 C 程序的模板当你需要以字节数组方式而非文件路径调用 xberg 时构造kind: bytesbytes: [...]mime_typefilename的输入 JSON再用xberg_extraction_config_from_json传入配置即可。唯一需要注意的是生产代码不应像本例一样故意传入冲突配置——除非你正在编写错误处理路径的测试。三、底层校验逻辑冲突为何必然失败为什么force_ocr: true与disable_ocr: true组合必然被拒绝原因在于这两个字段的语义force_ocr无论文档本身是否有可用的文本层都强制对所有页面/图片运行 OCRdisable_ocr完全关闭 OCR提取只依赖文档原生文本层。两者同时为真会让提取管线无法决定是否调用 OCR 引擎属于无解的矛盾。xberg 在引擎层面对此做了显式防御且在校验发生的位置上处于提取管线的非常靠前阶段。3.1 字节提取入口字节提取的入口实现位于 crates/xberg/src/core/extractor/bytes.rsif config.force_ocr config.effective_disable_ocr() { return Err(crate::XbergError::Validation { message: force_ocr and disable_ocr cannot both be true.to_string(), source: None, }); } if matches!( config.ocr_strategy, crate::core::config::OcrStrategy::ScannedPages { .. } ) config.effective_disable_ocr() { return Err(crate::XbergError::Validation { message: ocr_strategy selects scanned pages for OCR, but disable_ocr is true.to_string(), source: None, }); }除了本主题的force_ocr disable_ocr冲突这里还揭示了第二类相关的非法组合ocr_strategy被设置为ScannedPages按扫描置信度额外 OCR 扫描页同时又显式关闭 OCR同样会被Validation错误拒绝错误信息为 “ocr_strategy selects scanned pages for OCR, but disable_ocr is true”。3.2 文件提取入口文件路径提取走的是 crates/xberg/src/core/extractor/file.rs在 MIME 检测阶段之前就执行同样的校验。该校验被封装在FileDetectionChecks结构体中force_ocr_conflict/scanned_pages_ocr_conflict两个布尔标志见 file.rs并在detect_file_mime_blocking的开头触发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(), )); }两个标志在extract_file中根据配置计算得出file.rslet 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, };3.3 “是否关闭 OCR”的单一事实来源注意上面两处校验使用的都是effective_disable_ocr()而不是直接读disable_ocr字段。这个方法是“是否跳过 OCR”的唯一权威判断实现在 crates/xberg/src/core/config/extraction/core.rs/// Returns the effective disable-OCR value, accounting for both the top-level /// disable_ocr flag and the ocr.enabled shorthand on [OcrConfig]. pub(crate) fn effective_disable_ocr(self) - bool { self.disable_ocr || self.ocr.as_ref().is_some_and(|o| !o.enabled) }也就是说两种写法都会让 OCR 整体关闭顶层disable_ocr: true嵌套ocr.enabled: false这是disable_ocr的等价简写参见 crates/xberg/src/core/config/ocr.rs 中OcrConfig::enabled的文档说明设置为false时图像仅返回元数据PDF 仅使用原生文本提取、不做 OCR 回退且“所有其他 OCR 设置都被忽略”。因此即使你没有直接设置disable_ocr只要ocr.enabled被设为false再搭配force_ocr: true依然会触发冲突校验。这是最容易踩到的一个隐蔽场景。3.4 配置检查命令doctor中的同样校验xberg 提供了doctor配置体检工具其配置 lint 逻辑同样识别这对冲突。见 crates/xberg/src/doctor/config_lint.rsif config.force_ocr config.effective_disable_ocr() { // force_ocr and disable_ocr cannot both be true }这意味着在真正运行提取之前你还可以用xberg doctor静态检查配置文件提前暴露这类错误而不是等到提取请求时才失败。四、CLI 层的预校验更早发现错误除了引擎内部校验xberg 的 CLI见 crates/xberg-cli还会在命令行参数解析阶段提前拦截冲突让你在进程启动时就能得到清晰的报错信息。相关实现位于 crates/xberg-cli/src/commands/overrides/ocr.rs 的validate_ocr方法中if self.ocr Some(false) self.ocr_scanned_pages { bail!(--ocr false cannot be combined with --ocr-scanned-pages); } if self.ocr Some(false) self.force_ocr Some(true) { bail!(--ocr false cannot be combined with --force-ocr true); } if let (Some(ocr), Some(disable_ocr)) (self.ocr, self.disable_ocr) ocr disable_ocr { bail!(--ocr and --disable-ocr specify contradictory values); } if self.ocr_scanned_pages self.disable_ocr Some(true) { bail!(--ocr-scanned-pages cannot be combined with --disable-ocr); } if self.force_ocr Some(true) self.disable_ocr Some(true) { bail!(--force-ocr and --disable-ocr cannot both be true); }CLI 层对“OCR 开关”的校验覆盖面比引擎层更广包含四组互斥组合CLI 组合报错信息--ocr false--ocr-scanned-pages--ocr false cannot be combined with --ocr-scanned-pages--ocr false--force-ocr true--ocr false cannot be combined with --force-ocr true--ocr与--disable-ocr值相同同为 true 或同为 false--ocr and --disable-ocr specify contradictory values--force-ocr true--disable-ocr true--force-ocr and --disable-ocr cannot both be true--ocr-scanned-pages--disable-ocr--ocr-scanned-pages cannot be combined with --disable-ocrCLI 的参数覆盖逻辑位于 crates/xberg-cli/src/commands/overrides/ocr.rs 的apply_ocr例如--ocr false会同时将config.ocr置为None、disable_ocr置为true、force_ocr置为false、ocr_strategy重置为Auto而--force-ocr与--disable-ocr只各自改写对应的顶层字段互不知晓因此才需要前置的validate_ocr保证二者不会同时落进最终配置。对应的一组单元测试位于 crates/xberg-cli/src/commands/overrides/tests/ocr_precedence.rs。五、相关 OCR 配置项速查理解冲突校验后梳理一下与之关联的核心 OCR 配置项会很有帮助。以下字段均可在提取配置 JSON 中直接使用结构化定义见 crates/xberg/src/core/config/ocr.rs配置项类型/默认值语义disable_ocrbool默认false顶层字段完全关闭 OCR只使用原生文本层force_ocrbool默认false顶层字段强制对全部内容运行 OCRforce_ocr_pages页码列表默认空仅对指定页面强制 OCRPDFocr_strategyauto默认或{mode:scanned_pages,min_confidence:0.70}选择哪些页面参与 OCRScannedPages模式下低于min_confidence默认DEFAULT_SCANNED_MIN_CONFIDENCE 0.70见 ocr.rs的页面不 OCRocr.enabledbool默认truefalse等价于顶层disable_ocr: trueocr.backend字符串默认tesseractOCR 后端tesseract、paddle-ocr、sceptre、vlm及 candle 系列等CLI 的合法值列表见 ocr.rsocr.language字符串或数组默认[eng]识别语言接受eng、engdeu或[eng,deu]三种写法一个常见误区是既然force_ocr与ocr_strategy都会推动 OCR 的执行是否可以让force_ocr: true与ocr_strategy.scanned_pages并存答案是可以——引擎只禁止“关闭 OCR 的同时要求 OCR 参与”的矛盾组合force_ocr与ScannedPages策略并不冲突二者可以叠加使用。六、正确的实践方式综合以上分析编写 xberg 提取调用时请遵循以下要点同一请求内只表达一个 OCR 意图要么disable_ocr: true或ocr.enabled: false明确跳过 OCR要么通过force_ocr/ocr_strategy/force_ocr_pages明确启用 OCR绝不同时设置。善用 CLI 预校验命令行场景下优先让validate_ocr帮你拦截再配合xberg doctor的配置 lintcrates/xberg/src/doctor/config_lint.rs做静态检查。理解effective_disable_ocr的双通道语义顶层disable_ocr与嵌套ocr.enabled: false都会被计入“OCR 已关闭”因此排查冲突时两个字段都要检查。以非零返回作为错误信号在 C FFI 调用中xberg_extract返回非零表示失败本示例即依赖这一点断言错误在 Rust 侧则表现为XbergError::Validation { message: force_ocr and disable_ocr cannot both be true, .. }见 bytes.rs。七、小结error_extract_input_conflicting_ocr这个看似简单的错误 fixture实际串联起了 xberg 配置校验的完整链路C 绑定通过xberg_extract_input_from_json/xberg_extraction_config_from_json/xberg_extract三件套构造并执行请求引擎在字节与文件两条提取路径的最前端通过effective_disable_ocr()统一判定 OCR 是否关闭并对force_ocr冲突与ScannedPages冲突分别返回明确的Validation错误CLI 层则更进一步在参数解析阶段拦截包括--ocr false在内的多组互斥组合doctor命令还能在运行前静态发现同一问题。掌握这条“快速失败”的设计思路你就能在任意绑定语言中写出语义清晰、绝不会触发这类校验错误的提取配置。赞分享后端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点击查看免费下载相关推荐Musicdl高级技巧如何利用API批量解析网易、咪咕等平台完整歌单Musicdl高级技巧如何利用API批量解析网易、咪咕等平台完整歌单 Musicdl是一款轻量级的纯Python音乐下载工具支持批量解析网易云音乐、咪咕音乐网页爬虫音频处理xberg C FFI 实战用 force_ocr 强制对每一页 PDF 执行 OCRxberg C FFI 实战用 force_ocr 强制对每一页 PDF 执行 OCR 本篇技术指南基于仓库中的 C 语言示例 ocr_force_all_p后端AI 应用NLPxberg C 绑定实战用 xberg_list_validators 枚举已注册的校验器插件xberg C 绑定实战用 xberg_list_validators 枚举已注册的校验器插件 本篇指南围绕 xberg 的 C FFI 接口 xberg_l后端AI 应用NLP上一篇Fusion 360 Gallery数据集仿写Prompt下一篇NodeGraphQt现代化节点图界面开发框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考