コンテンツにスキップ
NextPDF
getnextpdf.com

Pro エディション

Extraction — 詳細リファレンス

概要

「概要」という見出しのセクション

このページは NextPDF\Pro\Extraction のコントラクトレベルのリファレンスです。本モジュールには 5 つの公開シンボルがあります。2 つのエクストラクター（CitedTextExtractor、CitedTableExtractor）と、3 つのイミュータブルな値オブジェクト（CitedTextBlock、CitedTableBlock、CitedTableCell）です。どちらのエクストラクターも解析済みの NextPDF\Ast\AstDocument を入力とし、生の PDF バイト列を読み取ることはありません。抽出は決定論的かつ構造的です。本モジュールのどこにも、セマンティック、埋め込み、ランキングのステップは存在しません。タスク指向のビューはケーパビリティページにあります。

提供状況とライセンス

「提供状況とライセンス」という見出しのセクション

この機能は NextPDF Pro（nextpdf/pro）に含まれ、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントがないデプロイメントでは、本機能のクラスはロードされません。エディションを比較してライセンスを入手。

このモジュールをゲートするランタイムのケーパビリティフラグはありません。クラスは、nextpdf/pro がインストールされ、ライセンスされている限り利用可能です。

公開 API サーフェス

「公開 API サーフェス」という見出しのセクション
シンボルパラメーター既定の挙動戻り値スロー/失敗条件補足
CitedTextExtractor::__construct()?int $maxTokensPerChunk = null, int $minChunkLength = 10トークン予算なし。トリム後 10 バイト未満のテキストは破棄CitedTextExtractorスローしないnull 予算は 1 ノードにつき 1 ブロックを意味します。
CitedTextExtractor::extract()AstDocument $document深さ優先で走査。条件を満たすテキストノードごとに 1 ブロックを生成し、トークン予算で分割list<CitedTextBlock>スローしない決定論的。chunkIndex は呼び出しごとに 0 にリセットされます。
CitedTextBlock5 つの readonly フィールドイミュータブルな値オブジェクト。シリアライザーメソッドなし—スローしないmetadata のキー: nodeType、pageIndex、加えてオプションの structType、lang、alt、untagged。
CitedTextBlock::estimatedTokens()なしceil(byte length / 4)intスローしない予算ヒューリスティック。トークナイザーではありません。
CitedTableExtractor::extract()AstDocument $document最も外側の Table ノードをドキュメント順に収集list<CitedTableBlock>スローしないテーブルのサブツリーへは決して降りません。
CitedTableBlock5 つの readonly フィールドイミュータブルな矩形の行優先セルマトリクス—スローしない短い行は抽出時に右詰めでパディングされます。
CitedTableBlock::toArray()なしsnake_case のプレーン配列にシリアライズarray<string, mixed>スローしないネストされたセルは CitedTableCell::toArray() を介してシリアライズされます。
CitedTableCell7 つの readonly フィールド引用座標を持つイミュータブルなセルレコード—スローしないパディングセルは空の nodeId と信頼度 0.0 を持ちます。
CitedTableCell::toArray()なしsnake_case のプレーン配列にシリアライズ。bbox はネストするか nullarray<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 が未設定の場合、各ノードは 1 ブロックを生成します。設定されている場合、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 は全行にわたるセル数の最大値です。短い行は、合成セル（空の nodeId、null テキスト、null bbox、テーブルのページインデックス、信頼度 0.0）で colCount まで右詰めでパディングされます。行または列のないテーブルはブロックを生成しません。
  • セルの信頼度。 実セルの信頼度は、その confidence 属性が int または float である場合にそれを読み取ります。既定は 0.8 です。テキストブロックの既定は 1.0、テーブルセルの既定は 0.8 です。
  • 構造マッピング。 走査される階層は、PDF の論理構造モデル（ISO 32000-2:2020 §14.7）に対応します。ソースがタグ付きである場合、テーブルの行は TR 構造要素（§14.8）に対応します。

エッジケースと障害モード

「エッジケースと障害モード」という見出しのセクション
  • この API サーフェスでは何もスローしません。どちらの extract() メソッドも、条件を満たすノードがないドキュメントに対しては空のリストを返します。
  • ゼロ面積のバウンディングボックスは共有のシングルトンのセンチネルです。実際の領域を必要とする呼び出し側は、これを明示的に検出する必要があります: width === 0.0 && height === 0.0。
  • すべての長さチェックと分割はバイトベースです。200 バイトのウィンドウ内に文の区切りが存在しない場合、ハードブレイクがマルチバイトの UTF-8 シーケンスの内部に入ることがあります。
  • トークンあたり 4 バイトという数値は予算算定のためのヒューリスティックにすぎません。トークナイザーではなく、特定のモデルのトークン化と一致するものでもありません。estimatedTokens() は同じヒューリスティックを使用します。
  • confidence 属性内の数値文字列は型変換されず、既定が適用されます。int と float の値のみが有効とみなされます。
  • 切断後の空白スキップは、通常のスペースのみを除去します。チャンク先頭のタブと改行は保持されます。
  • TableCell のテキストは設計上 2 回抽出されます。CitedTextExtractor によるテキストブロックとして、また CitedTableExtractor によるマトリクス内としてです。1 つのドキュメントに対して両方のエクストラクターを実行する場合は、下流で重複排除してください。
  • パディングセルは、空の nodeId と信頼度 0.0 で識別できます。実在するが空のセルは、空でない nodeId を保持します。
  • このモジュールでは暗号操作は一切行われないため、FIPS モード固有の挙動はありません。

適合性

「適合性」という見出しのセクション

ソースドキュメントがタグ付きである場合、AST は ISO 32000-2:2020 §14.7 の論理構造階層を反映し、Table/TableRow ノードは §14.8 の Table/TR 構造要素に対応します。抽出品質はタグ付け品質によって制約されます。タグ付けされていないコンテンツは、より少ない、あるいはより粗いノードを生成します。

これらは構造的な整合性に関する記述であり、適合性テストの結果ではありません。NextPDF はいかなる認証も保有しておらず、また付与もしません。 本モジュールはそれ自体で適合性を主張することはなく、Core AST サブシステムが生成した構造をそのまま消費します。

開発上の注意

「開発上の注意」という見出しのセクション
  • 1 つの CitedTextExtractor インスタンスを複数のドキュメントで再利用することは、逐次的であれば安全です。extract() は各ウォークの前に chunkIndex をリセットします。
  • minChunkLength を調整して、ノイズノード（ページ番号、孤立したグリフの連なり）をチャンク分割の後ではなく前にフィルタリングしてください。
  • CJK やその他のマルチバイト文字では、バイトベースのヒューリスティックはトークンを過大にカウントします。それに応じて maxTokensPerChunk を設定してください。
  • CitedTableBlock::toArray() と CitedTableCell::toArray() は、JSON パイプライン向けに snake_case のキーを出力します。CitedTextBlock にはシリアライザーがありません。そのフィールドは自分でエンコードしてください。
  • CitationAnchor の contentHash フィールドは、この API サーフェスでは常に null です。パイプラインが必要とする場合は、コンテンツハッシュを下流で計算してください。

公開範囲

「公開範囲」という見出しのセクション

このページは、外部から観測可能な挙動とサポートされる公開 API サーフェスのみを記載しています。内部の名前空間パス、ヘルパークラス、メカニズムの一覧表、ランブックのファイル名、チケットのプレフィックスは対象外です。

関連項目

「関連項目」という見出しのセクション