抽出

概要

NextPDF\Pro\Extraction は、解析済みのドキュメント AST を走査し、それぞれが引用アンカー（ページインデックス、バウンディングボックス、ノード参照）を持つテキストおよびテーブルの ブロック を生成します。これは出所帰属パイプライン向けの決定的な構造抽出器であり、検索エンジンや理解エンジンではありません。

利用可能性とライセンス

この機能は NextPDF Pro（nextpdf/pro）に同梱され、Pro ティアのライセンスエンベロープで有効になります。そのエンタイトルメントを持たないデプロイでは、この機能のクラスはロードされません。ランタイムの機能フラグでこのモジュールがゲートされることはなく、nextpdf/pro がインストールされていれば Extraction のクラスは常に利用できます。エディションを比較してライセンスを取得する。

インストール

composer require nextpdf/pro:^3

概念の概要

どちらの抽出器も、Core の AST サブシステムが生成する解析済みドキュメントツリーである NextPDF\Ast\AstDocument を取ります。これらは生 PDF バイトを自身で解析することはありません。AST が入力の境界です。

• CitedTextExtractor はツリーを走査し、トリムしたテキストが最小長を満たす実質的な各テキストノード（段落、見出し、リスト項目、テーブルセル、コード、注釈）について CitedTextBlock を送出します。任意のトークン予算により、長いテキストを文の境界で分割します。各ブロックは、ノード ID、ページインデックス、バウンディングボックス、およびノードから読み取った信頼度（デフォルト 1.0）を持つ CitationAnchor を保持します。バウンディングボックスを持たないノードには、アンカーが常に有効であるよう面積ゼロのセンチネルボックスが与えられます。
• CitedTableExtractor は Table ノードを見つけ、その行とセルを読み取り、最も幅の広い行に合わせてパディングした行優先の矩形マトリックスを構築します。ネストされたテーブルには再帰しません。セルの信頼度は、ノードが明示的な値を持たない限り、デフォルトで 0.8 になります。

これらの抽出器が走査する構造階層は、ソースドキュメントがタグ付けされている場合、PDF の論理構造モデル（ISO 32000-2:2020 §14.7）およびテーブル構造要素（§14.8）に対応します。

なぜこの仕組みなのか

抽出器は生 PDF バイトではなく解析済みの AST を入力の境界とするため、解析のリスクが抽出ロジックから分離されたままになります。信頼度は 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 のフォールバック/代替手段

Core の AST サブシステムは、ここで消費される AstDocument を生成します。引用ブロックの抽出そのものに相当する Core の機能はありません。/modules/core/ast/ を参照してください。

Enterprise の境界に関する注意

このモジュールは構造抽出器に過ぎません。セマンティック検索、ベクトル埋め込み、類似度ランキング、ドキュメントインテリジェンスのいずれも行いません。それらの機能は本モジュールの一部ではなく、本モジュールがそれらを含意することもありません。

公開の境界

このページは、外部から観測可能な振る舞いと、サポートされる公開 API サーフェスのみを記述します。内部の名前空間パス、ヘルパークラス、機構テーブル、Runbook のファイル名、チケットのプレフィックスは範囲外です。

関連項目

• 抽出リファレンス
• 分類器
• 差分
• Core AST