Extraction — 深度参考

速览

本页是 NextPDF\Pro\Extraction 的契约级参考。该模块包含五个公共符号：两个提取器（CitedTextExtractor、CitedTableExtractor）和三个不可变值对象（CitedTextBlock、CitedTableBlock、CitedTableCell）。两个提取器都消费一个已解析的 NextPDF\Ast\AstDocument；两者都不读取原始 PDF 字节。提取是确定性且结构化的。本模块任何位置都不存在语义、嵌入或排序步骤。面向任务的视图见能力页。

可用性与授权

此能力随 NextPDF Pro（nextpdf/pro）提供，并通过 Pro 级授权信封激活。没有该权益的部署不会加载此能力的类。比较版本并获取授权。

没有任何运行时能力标记对本模块进行门控。只要安装并授权了 nextpdf/pro，这些类即可用。

公共 API 接口面

符号	参数	默认行为	返回	抛出或失败于	说明
CitedTextExtractor::__construct()	?int $maxTokensPerChunk = null, int $minChunkLength = 10	无令牌预算；去除首尾空白后不足 10 字节的文本会被丢弃	CitedTextExtractor	不抛出	null 预算意味着每个节点一个块。
CitedTextExtractor::extract()	AstDocument $document	深度优先遍历；每个符合条件的文本节点一个块，按令牌预算切分	list<CitedTextBlock>	不抛出	确定性；chunkIndex 在每次调用时重置为 0。
CitedTextBlock	五个只读字段	不可变值对象；无序列化方法	—	不抛出	metadata 键：nodeType、pageIndex，以及可选的 structType、lang、alt、untagged。
CitedTextBlock::estimatedTokens()	无	ceil(byte length / 4)	int	不抛出	预算启发式；不是分词器。
CitedTableExtractor::extract()	AstDocument $document	按文档顺序收集最外层 Table 节点	list<CitedTableBlock>	不抛出	绝不深入表格子树。
CitedTableBlock	五个只读字段	不可变的矩形行主序单元格矩阵	—	不抛出	较短的行在提取时向右补齐。
CitedTableBlock::toArray()	无	序列化为 snake_case 普通数组	array<string, mixed>	不抛出	嵌套单元格通过 CitedTableCell::toArray() 序列化。
CitedTableCell	七个只读字段	带引用坐标的不可变单元格记录	—	不抛出	补齐单元格带有空的 nodeId 和置信度 0.0。
CitedTableCell::toArray()	无	序列化为 snake_case 普通数组；bbox 嵌套或为 null	array<string, mixed>	不抛出	—

final class CitedTextExtractor

public function __construct(
    private readonly ?int $maxTokensPerChunk = null,
    private readonly int $minChunkLength = 10,
)

public function extract(AstDocument $document): array

final class CitedTableExtractor

public function extract(AstDocument $document): array

final readonly class CitedTextBlock

public function __construct(
    public string $text,
    public CitationAnchor $anchor,
    public float $confidence,
    public int $chunkIndex,
    public array $metadata,
)

public function estimatedTokens(): int

final readonly class CitedTableBlock

public function __construct(
    public readonly string $nodeId,
    public readonly int    $pageIndex,
    public readonly int    $rowCount,
    public readonly int    $colCount,
    public readonly array  $matrix,
)

public function toArray(): array

final readonly class CitedTableCell

public function __construct(
    public readonly string       $nodeId,
    public readonly int          $row,
    public readonly int          $col,
    public readonly ?string      $textContent,
    public readonly ?BoundingBox $bbox,
    public readonly int          $pageIndex,
    public readonly float        $confidence,
)

public function toArray(): array

行为契约

• 节点选择。 CitedTextExtractor 为类型是 Paragraph、Heading、ListItem、TableCell、Code 或 Annotation 的节点发出块。文本为 null 的节点会被跳过。仅当节点去除首尾空白后的文本长度至少为 minChunkLength（默认 10）时才会被发出。所有长度均为字节长度。
• 遍历顺序。 遍历从文档根开始进行深度优先。符合条件的节点会在其子节点被访问之前被发出。chunkIndex 在整个文档遍历过程中递增，并在每次 extract() 调用时重置为 0。
• 分块。 未设置 maxTokensPerChunk 时，每个节点产出一个块。设置时，长度超过 maxTokensPerChunk * 4 字节的文本会被切分。切分器优先选择句子边界——一个换行符，或一个句点后跟一个空格——通过从首选切分点向后最多扫描 200 字节来查找。否则它会在预算处强制断开。切分点之后的空格会被跳过；空块会被丢弃。
• 引用锚点。 每个块的 CitationAnchor 携带节点 id、页索引、一个边界框、一个置信度，以及一个 null 内容哈希。没有边界框的节点会获得一个共享的零面积哨兵值 BoundingBox(0, 0, 0, 0)，因此锚点在结构上始终有效。
• 文本置信度。 当节点的 confidence 属性为 int 或 float 时，置信度读取该属性；默认为 1.0。非数值的属性值回退到默认值。
• 块元数据。 metadata 始终携带 nodeType 和 pageIndex。当节点上存在 structType、lang 和 alt 时会被复制。当节点携带 untagged 属性时，untagged 会被设为 true。
• 表格选择。 CitedTableExtractor 仅按文档顺序收集最外层的 Table 节点。一旦处理了某个 Table 节点，其子树不会被重新检查；不支持嵌套表格。
• 矩阵形状。 行来自 TableRow 子节点；单元格来自它们的 TableCell 子节点。其他子类型会被忽略。colCount 是所有行中的最大单元格数。较短的行会用合成单元格向右补齐到 colCount：空 nodeId、null 文本、null bbox、表格的页索引、置信度 0.0。没有任何行或没有任何列的表格不会产出块。
• 单元格置信度。 当真实单元格的 confidence 属性为 int 或 float 时，其置信度读取该属性；默认为 0.8。文本块默认为 1.0；表格单元格默认为 0.8。
• 结构映射。 被遍历的层级映射到 PDF 逻辑结构模型（ISO 32000-2:2020 §14.7）。当源文件已添加标签时，表格行映射到 TR 结构元素（§14.8）。

边界情形与失败模式

• 此接口面上没有任何东西会抛出。对于没有符合条件节点的文档，两个 extract() 方法都返回空列表。
• 零面积边界框是一个共享的单例哨兵值。需要真实区域的调用方必须显式检测它：width === 0.0 && height === 0.0。
• 所有长度检查和切分都基于字节。当 200 字节窗口内不存在句子边界时，强制断开可能落在一个多字节 UTF-8 序列内部。
• 每令牌 4 字节这一数字仅是用于预算的启发式。它不是分词器，也不匹配任何特定模型的分词方式。estimatedTokens() 使用相同的启发式。
• confidence 属性中的数值字符串不会被强制转换；将采用默认值。仅 int 和 float 值会被采纳。
• 切分之后的空白跳过仅移除普通空格。块起始处的制表符和换行符会被保留。
• TableCell 文本按设计会被提取两次：由 CitedTextExtractor 作为文本块提取，以及由 CitedTableExtractor 在矩阵内部提取。当对同一文档运行两个提取器时，请在下游去重。
• 补齐单元格可通过空 nodeId 和置信度 0.0 来识别。真实但为空的单元格保留其非空的 nodeId。
• 本模块任何位置都不发生密码学操作，因此没有 FIPS 模式特定行为。

一致性

当源文档已添加标签时，AST 会镜像 ISO 32000-2:2020 §14.7 的逻辑结构层级，且 Table/TableRow 节点对应于 §14.8 的 Table/TR 结构元素。提取质量受标签质量限制；未添加标签的内容会产生更少或更粗粒度的节点。

这些是结构对齐声明，而非一致性测试结果。NextPDF 不持有任何认证，也不授予任何认证。 本模块本身不作任何一致性声明；它消费 Core AST 子系统所产生的任何结构。

开发说明

• 顺序地跨文档复用同一个 CitedTextExtractor 实例是安全的；extract() 会在每次遍历前重置 chunkIndex。
• 调整 minChunkLength 以在分块之前（而非之后）过滤噪声节点（页码、零散的字形串）。
• 对于 CJK 和其他多字节文字，基于字节的启发式会高估令牌数；请相应地设置 maxTokensPerChunk 的大小。
• CitedTableBlock::toArray() 和 CitedTableCell::toArray() 为 JSON 管道发出 snake_case 键。CitedTextBlock 没有序列化方法；请自行编码其字段。
• 在此接口面上，CitationAnchor 的 contentHash 字段始终为 null。当管道需要时，请在下游计算内容哈希。

发布边界

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

另请参阅

• Extraction — 能力页
• Classifier — 深度参考（Pro）
• Core AST