Pro 版本

擷取

速覽

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，產生的區塊、錨點與 chunk 索引是穩定的。

公開 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 與任何儲存格內容。

效能

抽取是單趟樹走訪，與節點數量呈線性關係。Chunk 切分會增加與文字長度成比例的工作量。請參閱 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 檔名與工單前綴均不在範圍內。