后端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_batch是 Xberg 多语言绑定中处理大批量文档的高层入口其核心设计原则是「单条失败不拖垮整批」。本文以 C# 绑定中「全部 URI 输入均指向不存在文件」的典型故障场景为例完整讲解ExtractBatchAsync的输入模型、Rust 内核的错误收集语义、ExtractionSummary计数解读以及如何据此编写健壮的批量任务代码。读完本文你将能够准确区分「批级错误」与「条目级错误」并正确消费Results/Errors统计来驱动重试与告警逻辑。场景定义全部 URI 缺失的 fixture在 Xberg 仓库的批量测试体系中fixtures/batch/extract_batch_uri_all_missing.json 定义了一个极具代表性的故障场景一次批量调用提交了两个uri类型的输入而这两个 URI 都指向不存在的本地路径{ id: extract_batch_uri_all_missing, category: batch, call: extract_batch, input: { inputs: [ { kind: uri, uri: /nonexistent/a.pdf }, { kind: uri, uri: /nonexistent/b.txt } ] }, assertions: [ { type: not_error }, { type: equals, field: summary.results, value: 0 }, { type: equals, field: summary.errors, value: 2 } ] }该 fixture 通过三条断言锁定了批量 API 的关键契约not_error即使所有输入都失败整个extract_batch调用本身不会抛出异常返回的仍然是正常的ExtractionResult对象summary.results 0没有任何一个输入产出提取结果summary.errors 2两个输入各自产生一条条目级错误被完整记录在结果中。也就是说Xberg 将「文件不存在」这类问题归类为可恢复的条目级失败per-input error而不是不可恢复的批级失败。C# 侧的最小复现代码与该 fixture 对应的 C# 端到端用例由 alef 自动生成完整实现位于 e2e/csharp/tests/BatchTests.cs同时自动生成的文档片段保存在 docs-site/src/snippets-generated/csharp/batch/extract_batch_uri_all_missing.md。核心代码如下using System; using System.Text.Json; using Xberg; var ConfigOptions new JsonSerializerOptions { PropertyNameCaseInsensitive true }; var result await XbergConverter.ExtractBatchAsync(new ListExtractInput() { JsonSerializer.DeserializeExtractInput({\kind\:\uri\,\uri\:\/nonexistent/a.pdf\}, ConfigOptions)!, JsonSerializer.DeserializeExtractInput({\kind\:\uri\,\uri\:\/nonexistent/b.txt\}, ConfigOptions)! }, new ExtractionConfig()); Console.WriteLine(result.Summary.Results); // 0 Console.WriteLine(result.Summary.Errors); // 2对应的 xUnit 断言版本在 BatchTests.cs 中写作[Fact] public async Task Test_ExtractBatchUriAllMissing() { // extract_batch with missing URI inputs var result await XbergConverter.ExtractBatchAsync(new ListExtractInput() { /* 两个不存在的 uri */ }, new ExtractionConfig()); Assert.True(result.Summary.Results 0); Assert.True(result.Summary.Errors 2); }输入模型ExtractInput 与 ExtractInputKind批量接口的输入是一个ListExtractInput。根据 packages/csharp/src/Xberg/ExtractInput.cs 的定义ExtractInput是一个sealed record包含以下字段字段JSON 属性说明Kindkind输入来源类型ExtractInputKind.Bytes或ExtractInputKind.UriBytesbytes当kind bytes时的原始字节内容Uriuri当kind uri时的本地路径、file://URI 或 HTTP(S) URLMimeTypemime_typeMIME 类型提示Filenamefilename用于 MIME 检测与元数据的文件名提示Configconfig针对单个输入覆盖的FileExtractionConfigExtractInputKindpackages/csharp/src/Xberg/ExtractInputKind.cs只有两个取值bytes内存原始字节与uri文件系统路径 /file://URI / HTTP(S) URL。其中 URI 的取值在ExtractInput的注释中明确限定为Local path,file://URI, or HTTP(S) URL—— 因此在本文场景中传入/nonexistent/a.pdf这类不存在的本地绝对路径是合法的输入形式解析失败而非入参校验失败正是需要测试覆盖的分支。除手写 JSON 反序列化外ExtractInput还提供了工厂方法ExtractInput.FromBytes(byte[] bytes, string mimeType, string? filename)与ExtractInput.FromUri(string uri)两者都会经由 FFI 层调用 Rust 侧构造输入再序列化回 C# 对象。调用链追踪从 C# 到 Rust 内核理解错误语义关键在于看清ExtractBatchAsync的底层实现。在 packages/csharp/src/Xberg/XbergConverter.cs 中将ListExtractInput与ExtractionConfig序列化为 JSON调用NativeMethods.ExtractBatch(inputsHandle, configHandle)进入 Rust FFI检查NativeMethods.LastErrorCode()仅在 FFI 层出现批级错误时抛出异常将返回的 JSON 反序列化为ExtractionResult。Rust 侧的入口位于 crates/xberg/src/core/extract/mod.rs自由函数extract_batch委托给进程级默认引擎DEFAULT_ENGINE.extract_batch(inputs, config).await。引擎实现crates/xberg/src/engine/extract_impl.rs展示了完整的执行骨架校验与取消检查先执行config.validate()与ensure_not_cancelled(config)这一阶段出错才会把整个批次作为Err返回批级失败内容缓存以输入与配置的哈希为 key 查询/写入缓存且仅当output.errors.is_empty()时才写入缓存——含有条目错误的批量结果不会被缓存避免把失败结果当作成功结果复用执行计划启用tokio-runtime且非 wasm32 目标时走extract_batch_concurrent并发路径否则退化为extract_batch_sequential顺序路径错误收集无论并发还是顺序路径单个条目的失败都会执行output.errors.push(error_item(index, source, error))然后继续处理下一个输入最后统一output.refresh_counts()刷新摘要计数。关键的容错语义就在这里条目级异常被“接住”并转换成ExtractionErrorItem追加到输出而不是向上抛出。这也是为什么两个 URI 全部缺失时调用方依然能得到一个正常的ExtractionResult其内部Errors列表包含两条错误记录。结果的三个层次Results、Errors 与 SummaryExtractBatchAsync返回的ExtractionResult包含三个主要组成部分见 packages/csharp/src/Xberg/ExtractionResult.csResults: ListExtractedDocument—— 成功提取出的文档对象列表Errors: ListExtractionErrorItem—— 条目级失败记录列表Summary: ExtractionSummary—— 一次调用粒度的统计摘要。ExtractionSummarypackages/csharp/src/Xberg/ExtractionSummary.cs共包含六个计数器本文场景下只有前三个非零字段JSON 属性含义本文场景值Inputsinputs调用方提交的输入总数2Resultsresults产出的提取结果数0Errorserrors条目级错误数2RemoteUrlsremote_urls解析为远程 HTTP(S) URL 的 URI 数0PagesCrawledpages_crawled被抓取/爬取的 HTML 页面数0DocumentsDownloadeddocuments_downloaded从 URL 下载的非 HTML 文档数0Errors中的每条ExtractionErrorItempackages/csharp/src/Xberg/ExtractionErrorItem.cs携带五个字段Index输入在原始请求中的下标、Code稳定数值错误码、ErrorType稳定的 snake_case 错误类型、Source尽力而为的来源标识如 URI 字符串、Message错误消息。利用Index可以把错误精确回映到入参列表中的第几个元素这是批量任务里做「按条目重试」的基础。错误矩阵同一批量 API 下的四种失败形态把 e2e/csharp/tests/BatchTests.cs 中同属 batch 分类的用例放在一起对比可以更清晰地把握批量接口的容错边界fixture输入构成期望结果extract_batch_uri_all_missing2 个不存在的 URIresults 0、errors 2extract_batch_uri_not_found1 个不存在的 URIresults 0、errors 1extract_batch_uri_partial_failure1 个有效文本 1 个损坏 PDFresults 1、errors 1extract_batch_empty_inputs空列表results为空Assert.Emptyextract_batch_bytes_invalid_mimebytes 输入 不存在的 MIME调用不抛异常结果对象非空其中extract_batch_uri_partial_failure其 fixture 定义在 fixtures/batch/extract_batch_uri_partial_failure.json是「部分成功、部分失败」的经典形态mock 服务器返回一个正常的text/plain文档和一个内容被截断的 PDF最终results 1、errors 1成功与失败结果并存于同一个返回对象中。这些用例共同印证了 Xberg 批量 API 的三大设计约定失败是常态不是异常——批量任务中任何单条失败都不应中断整批处理统计驱动决策——业务代码应通过Summary.Results与Summary.Errors的比值判断批次健康度而不是依赖异常捕获错误可回映——每条ExtractionErrorItem都带有原始输入下标便于精准定位与局部重试。实战建议如何消费批量提取结果基于上述契约在 C# 业务代码中处理批量提取建议遵循以下模式var result await XbergConverter.ExtractBatchAsync(inputs, new ExtractionConfig()); if (result.Summary.Errors 0) { // 全批成功直接消费 result.Results foreach (var doc in result.Results) { /* 入库、索引或下游处理 */ } } else if (result.Summary.Results 0) { // 全批失败记录每条错误的 index / source / message触发告警与重试 foreach (var err in result.Errors) Console.WriteLine($#{err.Index} [{err.ErrorType}] {err.Source}: {err.Message}); } else { // 部分成功成功结果照常处理失败条目单独重试 var failedIndexes result.Errors.Select(e e.Index).ToHashSet(); }需要注意的边界条件URI 的合法形态uri字段支持本地路径、file://URI 与 HTTP(S) URL但无论哪种形态只要解析/下载失败都会被记为条目级错误而非让整批调用失败缓存副作用含错误的批次不会写入内容缓存见 crates/xberg/src/engine/extract_impl.rs 的缓存写入条件因此失败批次重试时不会命中「错误缓存」并发与顺序启用tokio-runtime的非 wasm32 平台默认走并发路径crates/xberg/src/engine/extract_impl.rs大量输入时单条失败不会阻塞其余条目完成批级错误依然存在配置校验失败、取消令牌触发等场景仍会把整个批次作为Err返回并抛出XbergException派生的异常这与条目级错误是两种完全不同的失败层级调试时务必先区分错误来自异常还是Errors列表。小结Xberg 的extract_batch通过「批级失败抛异常、条目级失败进列表」的双层错误模型为大规模文档处理提供了稳定的容错底座。当全部 URI 输入都缺失时C# 调用方会得到Summary.Results 0、Summary.Errors 2的完整统计与逐条错误明细从而能够在不中断批处理的前提下实现精确的告警、定位与重试。从 fixtures/batch 目录下的批量 fixture、e2e/csharp/tests/BatchTests.cs 的端到端用例到 crates/xberg/src/engine/extract_impl.rs 的引擎实现整条链路都贯彻了这一设计可作为你编写生产级批量提取任务的直接参考。赞分享后端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 批量 URI 提取错误处理实战extract_batch 对不存在 URI 的容错语义xberg C FFI 批量 URI 提取错误处理实战extract_batch 对不存在 URI 的容错语义 本篇技术指南聚焦 xberg 的 C FFI后端AI 应用NLPUvicorn 安装完全指南从最小依赖到 standard 可选依赖包的实战解析Uvicorn 安装完全指南从最小依赖到 standard 可选依赖包的实战解析 Uvicorn 是一款基于 Python 的 ASGI Web 服务器安装后端AI 应用NLPxberg C API 实战使用 extract_batch 批量提取远程 URI 文档xberg C API 实战使用 extract_batch 批量提取远程 URI 文档 导读 本文围绕 xberg C 绑定中 xberg_extract_后端AI 应用NLP上一篇为什么 Modular 代码库选择 Bazel从我的机器上能跑到任何机器都能构建下一篇Kornia 起源与定位从 torchgeometry 到可微分计算机视觉库以及与 OpenCV 的关系辨析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
