Pro 版本

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`	無 token 預算；修整後不足 10 位元組的文字會被丟棄	`CitedTextExtractor`	不會拋出	`null` 預算代表每個節點一個區塊。
`CitedTextExtractor::extract()`	`AstDocument $document`	深度優先走訪；每個符合條件的文字節點一個區塊，並依 token 預算切分	`list<CitedTextBlock>`	不會拋出	決定性；`chunkIndex` 在每次呼叫時重設為 0。
`CitedTextBlock`	五個 readonly 欄位	不可變值物件；無序列化方法	—	不會拋出	`metadata` 鍵：`nodeType`、`pageIndex`，加上可選的 `structType`、`lang`、`alt`、`untagged`。
`CitedTextBlock::estimatedTokens()`	無	`ceil(byte length / 4)`	`int`	不會拋出	預算啟發式；並非 tokenizer。
`CitedTableExtractor::extract()`	`AstDocument $document`	以文件順序收集最外層的 `Table` 節點	`list<CitedTableBlock>`	不會拋出	絕不深入表格子樹。
`CitedTableBlock`	五個 readonly 欄位	不可變的矩形列主序儲存格矩陣	—	不會拋出	較短的列會在擷取時向右補齊。
`CitedTableBlock::toArray()`	無	序列化為 snake_case 純陣列	`array<string, mixed>`	不會拋出	巢狀儲存格透過 `CitedTableCell::toArray()` 序列化。
`CitedTableCell`	七個 readonly 欄位	帶有引用座標的不可變儲存格記錄	—	不會拋出	補齊用的儲存格帶有空的 `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 的內容雜湊。沒有定界框的節點會收到一個共用的零面積 sentinel，BoundingBox(0, 0, 0, 0)，因此錨點在結構上永遠有效。
文字信心值。 當節點的 confidence 屬性是 int 或 float 時，信心值即讀取自它；預設為 1.0。非數值的屬性值會回退為預設值。
區塊 metadata。 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() 方法都回傳空列表。
零面積定界框是一個共用的單例 sentinel。需要真實區域的呼叫端必須明確偵測它：width === 0.0 && height === 0.0。
所有長度檢查與切分都以位元組為基礎。當 200 位元組視窗內不存在句子邊界時，強制切斷可能落在一個多位元組 UTF-8 序列的中間。
每 token 4 位元組這個數字只是估算預算的啟發式值。它不是 tokenizer，也不符合任何特定模型的 tokenization。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 與其他多位元組文字，以位元組為基礎的啟發式會高估 token 數；請據此調整 maxTokensPerChunk 的大小。
CitedTableBlock::toArray() 與 CitedTableCell::toArray() 為 JSON 管線發出 snake_case 鍵。CitedTextBlock 沒有序列化方法；請自行編碼其欄位。
CitationAnchor 的 contentHash 欄位在此介面上一律為 null。當管線需要時，請在下游計算內容雜湊。

出版邊界

本頁僅記載外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表、runbook 檔名與工單前綴皆不在範圍內。