企业官网建设流程全解析

• 后端
• AI 应用
• NLP

本篇技术指南聚焦 xberg 项目中 PHP 语言绑定提供的批量文档提取接口extract_batch（PHP 端对应Xberg::extractBatch），以api_extract_batch_bytes契约文档为核心，完整讲解如何以内存中的字节数据（而非磁盘路径或 URL）批量提交文档、如何按输入单独覆写提取配置、如何读取返回的 MIME 类型与正文内容，并结合仓库中的契约夹具、端到端测试与 Rust 核心实现，帮助你直接写出可复制、可运行的批量提取代码。

背景：extract_batch是什么

xberg 是一个以 Rust 为核心的文档智能引擎，提供文本、元数据、图片、表格与结构化数据提取，支持 106 种格式、140 种文件扩展名，并对外提供 CLI、REST API、MCP Server 以及包括 PHP 在内的十五种语言绑定。PHP 绑定（packages/php）面向 PHP 8.2+，通过原生扩展暴露类型安全的 API。

在单文档场景，PHP 绑定使用Xberg::extract处理一个输入；当需要一次处理多份文档时，应使用extract_batch（PHP 中为Xberg::extractBatch）。它接收一个输入数组与一个全局ExtractionConfig，并返回一个包含结果列表与汇总统计的对象。仓库中的契约文档 api_extract_batch_bytes.md 专门验证了"以 bytes 形式提交输入"的批量提取路径，本文即围绕它展开。

环境准备：安装 PHP 绑定

在运行任何示例前，需要先通过 Composer 安装 PHP 包（packages/php的完整使用说明见 packages/php/README.md）：

composer require xberg-io/xberg

系统要求：

• PHP 8.2+（绑定强制要求）；
• 可选：ONNX Runtime 1.24+，用于依赖 ORT 的推理特性（如 embeddings）；
• 可选：Tesseract OCR，用于扫描件 OCR 功能。

所有示例都假设已经通过 Composer 生成vendor/autoload.php，并在脚本开头引入：

require_once __DIR__ . '/vendor/autoload.php';

契约核心：用 bytes 输入调用extractBatch

下面这段代码就是关联文档的核心示例，完整展示了 PHP 中批量字节提取的标准写法：

<?php declare(strict_types=1); require_once __DIR__ . '/vendor/autoload.php'; use Xberg\Xberg; use Xberg\ExtractInput; use Xberg\ExtractionConfig; $result = Xberg::extractBatch([ExtractInput::from_json('{"bytes":"pdf/fake_memo.pdf","filename":"fake_memo.pdf","kind":"bytes"}')], \Xberg\ExtractionConfig::from_json('{}')); var_dump($result->getResults()[0]->mimeType); var_dump($result->getResults()[0]->content);

逐行拆解其中的关键点：

• Xberg::extractBatch(array $inputs, ExtractionConfig $config)：批量提取入口，第一个参数是ExtractInput数组，第二个参数是全局配置；
• ExtractInput::from_json('...')：以 JSON 字符串构造输入对象。这里传入的 JSON 包含三个字段：
  • "kind":"bytes"：声明本次输入类型为字节流（区别于"kind":"uri"的 URL 输入）；
  • "bytes":"pdf/fake_memo.pdf"：契约夹具中用于表示字节数据的字段，真实场景下应替换为file_get_contents(...)读取的二进制内容（可结合mime_type字段声明媒体类型，如"mime_type":"application/pdf"）；
  • "filename":"fake_memo.pdf"：为字节数据提供文件名，供格式探测与结果溯源使用；
• ExtractionConfig::from_json('{}')：以空 JSON 构造全局配置，即使用默认提取行为；
• 读取结果：$result->getResults()返回结果数组，[0]取第一份文档的结果；->mimeType是探测出的 MIME 类型，->content是提取出的正文文本。

该契约对应的 JSON 夹具与断言

关联文档由 alef 自动生成（文档头部注释写明auto-generated by alef — DO NOT EDIT，可由alef e2e generate重新生成），其源头是仓库中的契约夹具 api_extract_batch_bytes.json。该夹具真实提交了一段 PDF 字节（%PDF-1.3开头的完整小文件），并在assertions中声明了三条验收断言：

也就是说，契约不仅验证"调用能成功"，还验证了格式探测准确、正文真实可读。这就是你在自己的 PHP 脚本中应该对mimeType与content做的断言。

按输入覆写配置：output_format等逐项控制

批量场景经常需要"同一批文档、不同输出格式"。契约文档 api_extract_batch_bytes_with_config.md 展示了在单个ExtractInput内嵌config字段的做法：

<?php declare(strict_types=1); require_once __DIR__ . '/vendor/autoload.php'; use Xberg\Xberg; use Xberg\ExtractInput; use Xberg\ExtractionConfig; $result = Xberg::extractBatch([ExtractInput::from_json('{"bytes":"pdf/fake_memo.pdf","config":{"output_format":"markdown"},"filename":"fake_memo.pdf","kind":"bytes"}')], \Xberg\ExtractionConfig::from_json('{}')); var_dump($result->getResults()[0]->mimeType); var_dump($result->getResults()[0]->content); var_dump($result->getResults()[0]->getMetadata()->outputFormat);

与第一个示例唯一的差异是ExtractInput的 JSON 中多了"config":{"output_format":"markdown"}：

• 该内嵌config只作用于当前这个输入，优先级高于传给extractBatch的全局配置，实现"批量任务中逐文档定制行为"；
• output_format: "markdown"指定输出格式为 Markdown。xberg 的 PHP 绑定支持六种输出格式：纯文本（text）、Markdown、Djot、HTML、JSON 树结构、Docling DocTags（见 packages/php/README.md 的 Key Capabilities）；
• 追加的$result->getResults()[0]->getMetadata()->outputFormat用于核对本次实际生效的输出格式，确认内嵌配置确实被应用。

对应的夹具 api_extract_batch_bytes_with_config.json 使用相同的一段 PDF 字节，标签为input_config，专门验证"per-input config"的合并语义。

混合输入与批内错误隔离：来自端到端测试的印证

仓库中的 PHP 端到端测试 BatchTest.php 覆盖了extract_batch更完整的边界行为，可作为你编写生产代码时的参考基线：

• 多格式混合输入（test_extract_batch_bytes_happy）：同一批提交text/plain与text/html两份字节输入，断言结果数>= 1；
• 空批次（test_extract_batch_empty_inputs）：传入空数组，断言返回的结果数为 0——空批次是合法输入，不会抛异常；
• 无效/不支持 MIME（test_extract_batch_bytes_invalid_mime、test_extract_batch_bytes_unsupported_mime）：提交无法识别的application/x-nonexistent、application/x-unknown字节，返回对象不为空，即错误被降级处理而不是中断整个批次；
• URI 批量与部分失败（test_extract_batch_uri_all_missing、test_extract_batch_uri_partial_failure）：当某个输入失败时，通过$result->getSummary()->results与$result->getSummary()->errors分别统计成功数与失败数。例如两份缺失 URI 时断言results == 0、errors == 2；一份有效 + 一份损坏 PDF 时断言results == 1、errors == 1。

这些测试从源码层面（e2e/php/tests/BatchTest.php）证实了extract_batch的逐输入错误隔离设计：单个输入失败不会拖垮整批，通过summary可以精确追踪成功/失败计数。配套的 fixtures 目录（fixtures/batch/）也提供了bytes_happy、bytes_mixed_format、empty_inputs、bytes_size_cap、extract_batch_uri_*等一批契约输入，便于离线复现各种行为。

真实场景：从字节到结构化结果的完整写法

把契约示例、内嵌配置与测试中的边界行为组合起来，可以得到一个可直接用于生产的 PHP 批量提取脚本：

<?php declare(strict_types=1); require_once __DIR__ . '/vendor/autoload.php'; use Xberg\Xberg; use Xberg\ExtractInput; use Xberg\ExtractionConfig; $inputs = [ // 1) 从内存字节提交：PDF 用 markdown 输出 ExtractInput::from_json(json_encode([ 'kind' => 'bytes', 'bytes' => base64_encode(file_get_contents('memo.pdf') ?: ''), 'filename' => 'memo.pdf', 'config' => ['output_format' => 'markdown'], ])), // 2) 从磁盘路径提交（uri 输入） ExtractInput::from_json(json_encode([ 'kind' => 'uri', 'uri' => 'report.docx', ])), // 3) 从内存字节提交文本文件，显式声明 mime_type ExtractInput::from_json(json_encode([ 'kind' => 'bytes', 'bytes' => base64_encode(file_get_contents('note.txt') ?: ''), 'filename' => 'note.txt', 'mime_type' => 'text/plain', ])), ]; $config = ExtractionConfig::from_json(json_encode([ 'extract_tables' => true, 'extract_images' => false, ])); $output = Xberg::extractBatch($inputs, $config); echo "成功处理: {$output->summary->results} 份，失败: {$output->summary->errors} 份\n"; foreach ($output->getResults() as $i => $result) { printf("[%d] %s (%s) — %d 字符\n", $i, $result->mimeType, $result->getMetadata()->outputFormat ?? 'text', strlen($result->content)); }

需要说明的细节：

• 关于bytes字段的编码：契约夹具中bytes直接给出字节数组（[37, 80, 68, 70, ...]即%PDF...的 ASCII 码）；在 PHP 端通过from_json构造时，请以你实际使用的绑定版本所接受的格式为准（字节数组或 base64 字符串均可尝试，务必以 packages/php/README.md 与vendor/下生成的类型声明为准）。更稳妥的面向对象写法是使用 README 展示的ExtractInput::fromBytes($content, 'text/plain', 'note.txt')与ExtractInput::fromUri('document.pdf')工厂方法；
• 全局配置extract_tables/extract_images控制是否提取表格与图片，与 README 中new ExtractionConfig(extractTables: true, extractImages: false)语义一致；
• 输出对象模型：$result->mimeType（MIME 类型）、$result->content（正文）、$result->getMetadata()（元数据，含outputFormat等）、$result->tables（表格数组，每个表格含markdown与pageNumber），以及$output->summary（批次汇总）。这些字段在 packages/php/README.md 的 Quick Start 与 Batch Processing 章节均有对应用法。

底层原理：字节输入的探测与并行处理

从源码结构看（crates/xberg-php/src/lib.rs 与 crates/xberg-php/src/Xberg.php 为 PHP 扩展的 Rust 桥接层），PHP 绑定的extractBatch与 Rust 核心的extract_batch能力一一对应：

• 格式探测：kind:"bytes"输入携带原始字节与可选mime_type。核心引擎会综合 MIME 声明、文件魔数（如%PDF-）与filename扩展名做智能探测——这正是契约断言中"字节是 PDF、探测结果必须是application/pdf"能被稳定验证的原因；
• 并行与隔离：批次内的多个输入由 Rust 核心并行调度处理，单个输入失败以错误条目计入summary.errors，不会中断其余输入（由 BatchTest.php 的 URI 部分失败测试印证）；
• 配置合并：ExtractInput内嵌的config覆盖全局ExtractionConfig，最终按"输入级优先于批次级"合并后执行；
• 预设（Preset）机制：PHP 绑定还暴露了Registry（见 crates/xberg-php/src/Registry.php），可加载编译期内嵌的预设或运行时目录中的预设文件，为ExtractInput/ExtractionConfig提供可复用的命名配置组合。

总结

通过Xberg::extractBatch，你可以在 PHP 中一次性提交多份字节输入（或 URI 输入）完成批量文档提取，并通过三个层次控制行为：输入类型（kind）、输入级配置（内嵌config）、批次级配置（ExtractionConfig）。契约夹具（fixtures/contract/api_extract_batch_bytes.json）与端到端测试（e2e/php/tests/BatchTest.php）共同保证了"格式探测准确、正文可读、单输入失败不拖垮整批"这三个核心承诺。对于需要高吞吐处理大量文档的 PHP 服务，extractBatch是比循环调用extract更高效、更健壮的批量入口。

• 后端
• AI 应用
• NLP