Extraction

速览

NextPDF\Pro\Extraction 遍历一棵已解析的文档 AST，并产出文本块和表格块，每个块都携带一个引用锚点（页索引、边界框、节点引用）。它是一个面向来源归属流水线的确定性结构化提取器，而不是搜索或理解引擎。

可用性与授权

此能力随 NextPDF Pro（nextpdf/pro）一同发布，并通过 Pro 层级的授权信封激活。缺少该授权的部署不会加载此能力的类。没有任何运行时能力标志对该模块进行门控；只要安装了 nextpdf/pro，Extraction 类即可用。对比各版本并获取授权。

安装

composer require nextpdf/pro:^3

概念概述

两个提取器都接受一个 NextPDF\Ast\AstDocument —— 一棵由 Core AST 子系统产出的已解析文档树。它们本身不解析原始 PDF 字节；AST 就是输入边界。

• CitedTextExtractor 遍历树，并为每个实质性文本节点（段落、标题、列表项、表格单元格、代码、注解）发出一个 CitedTextBlock，前提是其去除首尾空白后的文本达到最小长度。一个可选的 token 预算会在句子边界处切分长文本。每个块都携带一个 CitationAnchor，包含节点 id、页索引、边界框，以及一个从节点读取的置信度（默认 1.0）。没有边界框的节点会获得一个零面积的哨兵框，因此锚点始终有效。
• CitedTableExtractor 查找 Table 节点，读取其行与单元格，并构建一个补齐到最宽行的矩形行优先矩阵。不会递归进入嵌套表格。单元格置信度默认为 0.8，除非节点携带显式值。

当源文档已打标签时，这些提取器所遍历的结构层次对应于 PDF 逻辑结构模型（ISO 32000-2:2020 §14.7）和表格结构元素（§14.8）。

为何如此设计

提取器以一棵已解析的 AST 作为其输入边界，而非原始 PDF 字节，因此解析风险与提取逻辑彼此分离。置信度直接从 AST 节点读取并原样透传；本模块从不计算、排序或改进它。输出保持文档顺序，而非相关性顺序，因为来源归属需要的是可验证的溯源，而不是提取器无法为之辩护的启发式猜测。每个块都携带一个引用锚点 —— 节点 id、页索引、边界框 —— 从而让下游流水线能够将每一处引文追溯到其源头。这有意让本模块保持为一个确定性结构化提取器：它报告 AST 所断言的内容，并拒绝臆造文档未曾陈述的任何东西。

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

行为契约

• 输入。 一个 NextPDF\Ast\AstDocument。该模块不接受原始 PDF 字节；请先用 Core AST 子系统产出 AST。
• 输出。 按文档顺序排列的 list<CitedTextBlock> 或 list<CitedTableBlock>。
• 置信度为透传。 它从 AST 节点属性读取（或取固定默认值）。本模块不计算或改进置信度。
• 不进行语义处理。 提取器不执行任何嵌入、向量相似度、排序或文档理解。输出顺序是文档顺序，而非相关性顺序。
• 确定性。 对于相同的 AST，所产出的块、锚点和分块索引是稳定的。

公共 API 接口

类型	种类	关键成员
NextPDF\Pro\Extraction\CitedTextExtractor	final class	__construct(?int $maxTokensPerChunk = null, int $minChunkLength = 10), extract(AstDocument $document): list<CitedTextBlock>
NextPDF\Pro\Extraction\CitedTableExtractor	final class	extract(AstDocument $document): list<CitedTableBlock>
NextPDF\Pro\Extraction\CitedTextBlock	final readonly class	string $text, CitationAnchor $anchor, float $confidence, int $chunkIndex, array $metadata, estimatedTokens(): int
NextPDF\Pro\Extraction\CitedTableBlock	final readonly class	string $nodeId, int $pageIndex, int $rowCount, int $colCount, array $matrix
NextPDF\Pro\Extraction\CitedTableCell	final readonly class	int $row, int $col, ?string $textContent, float $confidence

代码示例 —— 快速上手

<?php

declare(strict_types=1);

use NextPDF\Pro\Extraction\CitedTextExtractor;

/** @var \NextPDF\Ast\AstDocument $ast */
$blocks = (new CitedTextExtractor())->extract($ast);

foreach ($blocks as $block) {
    printf(
        "p%d chunk#%d (%d tokens): %s\n",
        $block->anchor->pageIndex,
        $block->chunkIndex,
        $block->estimatedTokens(),
        $block->text,
    );
}

代码示例 —— 生产环境

<?php

declare(strict_types=1);

use NextPDF\Pro\Extraction\CitedTextExtractor;

function chunkForCitation(\NextPDF\Ast\AstDocument $ast): array
{
    // Token-bounded chunks for downstream citation storage.
    $extractor = new CitedTextExtractor(
        maxTokensPerChunk: 400,
        minChunkLength: 16,
    );

    $rows = [];
    foreach ($extractor->extract($ast) as $block) {
        $rows[] = [
            'text'      => $block->text,
            'page'      => $block->anchor->pageIndex,
            'node_id'   => $block->anchor->nodeId,
            'chunk'     => $block->chunkIndex,
        ];
    }

    return $rows;
}

边界情况与注意事项

• 未打标签或打标签质量较差的文档会产出较少的文本节点；AST 质量是提取质量的上限。
• 没有边界框的节点会获得一个零面积的哨兵 BoundingBox(0,0,0,0) —— 若需要真实区域，请通过 width === 0.0 && height === 0.0 检测它。
• 不会递归嵌套表格；只发出最外层的 Table 节点。
• 短行会用合成的零置信度单元格补齐，使每一行具有相同的列数。

数据驻留与 PII 缓解措施

本模块处理所提供 AST 中所含的任何文本，并在块内原样返回。它不进行任何网络调用、外部存储，也不记录所提取的内容。PII 处理、脱敏和驻留控制是调用方在所产出的块上的责任。参见 Core 的 PII 处理指南。

安全遥测与日志清洗

提取器不发出任何遥测数据，也不记录所提取的文本。如果调用方在其外层包裹日志记录，请在发出日志前清洗 text、metadata 以及任何单元格内容。

性能

提取是一次单趟树遍历，随节点数量呈线性。分块切分增加的工作量与文本长度成正比。参见 performance_budget。

安全说明

输入是一棵已预先解析的 AST，因此本模块本身不解析恶意 PDF 字节。请将提取出的文本视为不受信任，并针对其目的地进行转义。

一致性

主张	规范条款	状态
逻辑结构节点遍历	ISO 32000-2:2020 §14.7	已验证（单元测试套件，已打标签的 AST）
表格行/单元格提取	ISO 32000-2:2020 §14.8	已验证（单元测试套件）
语义搜索/嵌入	—	不支持（不在范围内）

Core 回退/替代方案

这里所消费的 AstDocument 由 Core AST 子系统产出；而引用块提取本身没有 Core 等价物。参见 /modules/core/ast/。

Enterprise 边界说明

本模块仅是一个结构化提取器。它不执行语义搜索、向量嵌入、相似度排序或文档智能分析。这些能力不属于本模块，也不为本模块所暗示。

发布边界

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

另请参阅

• Extraction reference
• Classifier
• Diff
• Core AST