智能分析

概览

NextPDF Enterprise Intelligence 将原始键值与表格数据转化为带类型、可选经 schema 校验的结构，并通过在扫描页面上驱动一个 OCR 后端来编排可搜索 PDF 的生成。它描述其所产出的结构；它不主张 OCR 准确性或抽取召回率。

可用性与授权

此能力随 NextPDF Enterprise（nextpdf/enterprise）发行，并通过一个 Enterprise 层级的许可证信封激活。一个没有该权益的部署不会加载此能力的类。一个没有生效 Enterprise 权益的部署不会加载这些类。对比各版本并获取授权。

安装

composer require nextpdf/enterprise:^3

概念概述

结构化抽取器接收原始键值对——由上游的加速器或启发式解析器产出——并发出带类型的对象对。当提供了 schema 时，它只保留键与某个 schema 字段匹配的对，并报告哪些必需字段缺失。一个没有显式置信度的对会获得一个固定的默认值。这是对已经抽取出的数据所做的类型化与校验步骤；它本身不是一个抽取或识别引擎，也不赋予任何计算出的精度。

表格抽取器接收原始行网格，并构建带类型的表格结果，其中含有按单元格的对象，以及由细分一个归一化页面区域而合成的、统一的边界框。较短的行会被补齐，使每一行都具有最宽的列数。一个没有行或没有列的表格会被跳过。这些边界框是统一网格的合成，而非测量出的版面。

可搜索叠加层编排器接受一个扫描或混合的 PDF，检测哪些页面缺少可用的文本层，驱动配置的 OCR 后端，并产出一个描述按页词数与平均置信度的结果。不可见文本是可搜索扫描页面的机制：一个文本显示操作符可以放置字形，同时文本渲染模式被设置为使文本既不填充也不描边——ISO 32000-2:2020 §9.3.3——而文本显示操作符在内容流中放置字形——ISO 32000-2:2020 §9.4。当源是带标签的时，逻辑结构层级会将内容映射到一个阅读顺序——ISO 32000-2:2020 §14.7，带标签的结构支持内容复用——ISO 32000-2:2020 §14.8，且表格结构元素描述行与单元格——ISO 32000-2:2020 §14.8。

实际的栅格化与不可见文本注入由一个独立的边车进程执行；PHP 表面编排该工作流并产出结果元数据。一次叠加层运行的输出是一个派生文档：任何现有签名都会失效，且合规状态需要重新校验。置信度值是透传值或固定默认值，而非有保证的准确度数字。

为何这样设计

此表面在结构化与识别之间划出一条硬性界线。类型化与 schema 校验在进程内运行，因为它们是确定性且廉价的。识别——栅格化与不可见文本注入——被委托给一个被注入的 OCR 后端与一个独立的边车，因为它是重量级的、后端特定的，且最好保持在 PHP 信任边界之外。这一拆分让部署可以选择文档图像与被识别文本在何处计算与存储，而无需改动调用代码。本模块还拒绝虚构一个精度数字：一个未标注的对会获得一个固定默认值，且所报告的置信度是被透传而非计算得出的。调用方永远不会被交予一个捏造的准确度数字。

设计背景：一个拒绝猜测的 API。

API 表面

类型	种类	角色	稳定性	自
StructuredExtractor	class	为原始键值对赋予类型；schema 过滤与必需字段检查	stable	2.2.0
ExtractionSchema / SchemaField	classes	字段定义与必需字段集合	stable	2.2.0
KeyValuePair	class	一个带置信度的、带类型的键值对	stable	2.2.0
TableExtractor	class	从原始行网格构建带类型的表格	stable	2.2.0
TableResult / TableCell	classes	表格形状，含按单元格的文本、置信度与边界框	stable	2.2.0
SearchableOverlay	class	编排由 OCR 支持的可搜索 PDF 生成	stable	2.2.0
OverlayConfig / OverlayQuality	classes	语言提示、DPI、质量预设、原生页面跳过	stable	2.2.0
SearchableOverlayResult / PageOverlayInfo	classes	按页词数与平均置信度	stable	2.2.0
ExtractionConfig / ExtractionStrategy	classes	启发式与 OCR 辅助策略以及 OCR 提示	stable	2.2.0

OCR 后端是一个被注入的契约。编排器不内嵌 OCR 模型；部署提供后端，并负责 OCR 在何处计算。

代码示例——快速开始

Type and schema-validate raw key-value pairs

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Intelligence\StructuredExtractor;
use NextPDF\Enterprise\Intelligence\ExtractionSchema;

/**
 * Type raw pairs against a schema and list any missing required fields.
 *
 * @param list<array{key: string, value: string, confidence?: float}> $rawPairs Upstream key-value data.
 *
 * @return list<string> Missing required field names (empty when compliant).
 */
function validate(array $rawPairs, ExtractionSchema $schema): array
{
    $extractor = new StructuredExtractor();
    $pairs = $extractor->extract($rawPairs, $schema);

    return $extractor->validateSchema($schema, $pairs);
}

该抽取器对一个上游步骤已经产出的数据赋予类型并进行过滤。它本身不执行任何识别。

代码示例——生产环境

Searchable-overlay orchestration with safe logging

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Accelerator\OcrStrategyInterface;
use NextPDF\Enterprise\Intelligence\OverlayConfig;
use NextPDF\Enterprise\Intelligence\SearchableOverlay;
use Psr\Log\LoggerInterface;

final readonly class OverlayJob
{
    public function __construct(
        private OcrStrategyInterface $ocr,
        private LoggerInterface $logger,
    ) {}

    /**
     * Generate a searchable PDF from a scanned input.
     *
     * @param string $pdfData Scanned or mixed PDF bytes.
     *
     * @return string The derived searchable PDF bytes.
     */
    public function run(string $pdfData): string
    {
        try {
            $result = (new SearchableOverlay($this->ocr))
                ->generate($pdfData, new OverlayConfig(language: 'eng'));

            $this->logger->info('Overlay complete', [
                'pages' => $result->pageCount,
                'words' => $result->wordCount,
            ]);

            return $result->pdfData;
        } catch (\Throwable $e) {
            $this->logger->error('Overlay failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }
}

日志只携带页数与词数。它不携带被识别的文本或文档字节。catch 会重新抛出；它不会吞掉失败。

边界情况与陷阱

• 结构化抽取器与表格抽取器消费的是已经抽取出的数据。它们不解析 PDF、不运行模型，也不测量精度。置信度是透传值或一个固定默认值。
• 合成的表格边界框是一种统一网格细分，而非测量出的版面。需要真实几何信息的调用方必须从别处获取。
• 可搜索叠加层是一个派生文档。任何现有的数字签名都会失效；叠加之后必须重新校验合规状态。
• 当 OCR 后端不可用时，受影响的页面贡献零词，而不是静默地让整次运行失败——请检查按页的结果。
• 一个已经具有可用原生文本层的页面默认会被跳过。如果你必须重新 OCR，请在配置中禁用该跳过。
• OCR 准确性完全取决于所提供的后端、输入质量与语言提示。NextPDF 不主张识别准确性或抽取召回率。

性能

结构化抽取与表格抽取在输入大小上是线性的。可搜索叠加层的成本主要由 OCR 后端与边车在配置 DPI 下的栅格化所主导；编排开销很小。页数与大小输入是有界的，溢出时失败即关闭。可复现性配置文件是 structural：对于固定输入，抽取是确定性的，而叠加层输出取决于 OCR 后端，并可能在不同后端或版本之间有所不同。

安全说明

抽取器是只读的结构化步骤。叠加层表面产出一个派生文档，并对输入大小与页数加以限定，溢出时失败即关闭。OCR 后端是一个集成点，而非信任边界的一部分；由部署选择并运营它。本模块中不发生任何密码学操作，因此它不作任何 FIPS 主张。

数据驻留与 PII 缓解

结构化抽取与表格抽取在宿主上的进程内运行。可搜索叠加层编排会驱动一个被注入的 OCR 后端：该后端在何处运行——进程内、本地边车或远程服务——以及由此而来的文档图像与被识别文本在何处计算与存储，是库边界之外的部署责任。如果输入包含个人数据，被识别的文本层也会包含；请相应地对待派生文档。

安全遥测与日志清洗

库会抛出带结构化消息的带类型异常，且不会将文档字节或被识别的文本放入异常文本。在此表面周围记录日志的部署应记录计数与配置——如生产环境示例所示——且不得将原始 PDF 载荷或被识别的文本记录到日志或 APM 后端。

FIPS 模式行为

本模块中不发生任何密码学操作，因此不存在 FIPS 模式特有的行为。

符合性

主张	标准	条款
文本渲染模式控制字形是被填充、被描边还是两者皆非（不可见 OCR 文本的基础）。	ISO 32000-2:2020	§9.3.3
文本显示操作符在内容流中放置字形。	ISO 32000-2:2020	§9.4
逻辑结构层级将内容映射到一个阅读顺序。	ISO 32000-2:2020	§14.7
带标签的结构支持内容复用。	ISO 32000-2:2020	§14.8
表格结构元素描述行与单元格。	ISO 32000-2:2020	§14.8
结构树将内容映射到一个阅读顺序。	ISO 32000-2:2020	§14.7

所有条款均为意译。NextPDF 不复现规范性文本。权威措辞请查阅已发布的标准。NextPDF 不作任何 OCR 准确性或抽取召回率主张；本页陈述的是所产出的结构与编排边界，而非质量保证。

行为契约

• 结构化抽取器与表格抽取器消费的是已经抽取出的数据；它们不解析 PDF、不运行模型，也不测量精度。置信度是透传值或一个固定默认值。
• 一个 schema 过滤器只保留键与某个 schema 字段匹配的对，并报告缺失的必需字段；合成的表格边界框是一种统一网格细分，而非测量出的版面。
• 可搜索叠加层是一个派生文档：任何现有的数字签名都会失效，且合规状态必须重新校验。
• 当 OCR 后端不可用时，受影响的页面贡献零词，而不是静默地让整次运行失败；一个具有可用原生文本层的页面默认会被跳过。
• 页数与大小输入是有界的，溢出时失败即关闭。对于固定输入，抽取是确定性的；叠加层输出取决于所提供的 OCR 后端。

发布边界

本页仅记录外部可观察的行为与受支持的公共 API 表面。内部命名空间路径、辅助类、机制表、运行手册文件名以及工单前缀不在范围内。

Core 回退

NextPDF Core（Apache-2.0）没有可搜索叠加层编排，也没有经 schema 校验的结构化表面——没有；此能力没有 Core 层级的等价物。Core AST 模型是已解析文档的基础，而非一个抽取或 OCR 表面。

Pro 回退

NextPDF Pro 发行面向已解析文档的、由结构化 AST 驱动的抽取；它不提供经 schema 校验的键值结构化、从原始网格重建表格，或由 OCR 支持的可搜索叠加层编排。那些仅发行于 nextpdf/enterprise 软件包中。

Enterprise 边界说明

结构化/表格抽取器与叠加层编排器在行为层面描述。实际的栅格化与不可见文本注入在一个独立的边车进程中运行；边车的内部实现、OCR 模型，以及任何内部编排细节不在公共表面的范围内。OCR 后端是一个由部署提供的、被注入的契约。

部署边界

部署提供并运营 OCR 后端，并选择 OCR 在何处计算（进程内、本地边车或远程服务）——以及由此而来的文档图像与被识别文本在何处计算与存储。NextPDF Enterprise 编排该工作流并产出结果元数据；它不内嵌 OCR 模型，也不保证识别准确性或抽取召回率。

法律合规边界

Intelligence 表面不适用任何出口管制限制。库不主张任何 OCR 准确性或抽取召回率保证，也不主张任何监管合规状态。本文档不是法律意见；请咨询你自己的合规与法律顾问。

另请参阅

• Intelligence 参考——此能力的深度 API 参考。
• Pro 抽取——由结构化 AST 驱动的引用块。
• Privacy——对抽取文本进行 PII 检测。
• NextPDF Enterprise——完整的 Enterprise 功能表面。
• Core AST——已解析文档模型。
• Tagged PDF · OCR · Searchable PDF——术语表条目。