Pro edizione

Extraction — Riferimento approfondito

In breve

Questa pagina è il riferimento a livello di contratto per NextPDF\Pro\Extraction. Il modulo contiene cinque simboli pubblici: due estrattori (CitedTextExtractor, CitedTableExtractor) e tre value object immutabili (CitedTextBlock, CitedTableBlock, CitedTableCell). Entrambi gli estrattori consumano un NextPDF\Ast\AstDocument già analizzato; nessuno dei due legge i byte grezzi del PDF. L’estrazione è deterministica e strutturale. In questo modulo non esiste alcun passo semantico, di embedding o di ranking. La vista orientata alle attività si trova nella pagina della funzionalità.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Nessun flag di capacità a runtime applica un gate a questo modulo. Le classi sono disponibili ogni volta che nextpdf/pro è installato e provvisto di licenza.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
`CitedTextExtractor::__construct()`	`?int $maxTokensPerChunk = null`, `int $minChunkLength = 10`	Nessun budget di token; il testo ripulito inferiore a 10 byte viene scartato	`CitedTextExtractor`	Non solleva eccezioni	Un budget `null` significa un blocco per nodo.
`CitedTextExtractor::extract()`	`AstDocument $document`	Percorrenza in profondità; un blocco per ogni nodo di testo idoneo, suddiviso secondo il budget di token	`list<CitedTextBlock>`	Non solleva eccezioni	Deterministico; `chunkIndex` viene azzerato a 0 a ogni chiamata.
`CitedTextBlock`	cinque campi readonly	Value object immutabile; nessun metodo serializzatore	—	Non solleva eccezioni	Chiavi di `metadata`: `nodeType`, `pageIndex`, più le opzionali `structType`, `lang`, `alt`, `untagged`.
`CitedTextBlock::estimatedTokens()`	nessuno	`ceil(byte length / 4)`	`int`	Non solleva eccezioni	Euristica di budget; non è un tokenizzatore.
`CitedTableExtractor::extract()`	`AstDocument $document`	Raccoglie i nodi `Table` più esterni nell’ordine del documento	`list<CitedTableBlock>`	Non solleva eccezioni	Non discende mai in un sottoalbero di tabella.
`CitedTableBlock`	cinque campi readonly	Matrice di celle immutabile, rettangolare, in ordine row-major	—	Non solleva eccezioni	Le righe corte vengono riempite a destra al momento dell’estrazione.
`CitedTableBlock::toArray()`	nessuno	Serializza in un array semplice con chiavi snake_case	`array<string, mixed>`	Non solleva eccezioni	Le celle annidate vengono serializzate tramite `CitedTableCell::toArray()`.
`CitedTableCell`	sette campi readonly	Record di cella immutabile con coordinate di citazione	—	Non solleva eccezioni	Le celle di riempimento hanno un `nodeId` vuoto e confidenza 0.0.
`CitedTableCell::toArray()`	nessuno	Serializza in un array semplice con chiavi snake_case; `bbox` è annidato oppure `null`	`array<string, mixed>`	Non solleva eccezioni	—

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

Contratto di comportamento

Selezione dei nodi. CitedTextExtractor emette blocchi per i nodi il cui tipo è Paragraph, Heading, ListItem, TableCell, Code o Annotation. Un nodo con testo null viene ignorato. Un nodo viene emesso solo quando la lunghezza del suo testo ripulito è almeno pari a minChunkLength (valore predefinito 10). Tutte le lunghezze sono lunghezze in byte.
Ordine di percorrenza. La percorrenza è in profondità a partire dalla radice del documento. Un nodo idoneo viene emesso prima che vengano visitati i suoi figli. chunkIndex si incrementa lungo l’intera percorrenza del documento e viene azzerato a 0 a ogni chiamata di extract().
Suddivisione in chunk. Con maxTokensPerChunk non impostato, ogni nodo produce un blocco. Quando è impostato, il testo più lungo di maxTokensPerChunk * 4 byte viene suddiviso. Il divisore preferisce un confine di frase — un ritorno a capo, oppure un punto seguito da uno spazio — individuato scansionando all’indietro al massimo 200 byte dal punto di taglio preferito. In caso contrario interrompe in modo netto in corrispondenza del budget. Gli spazi dopo un taglio vengono saltati; i chunk vuoti vengono scartati.
Ancoraggio di citazione. Il CitationAnchor di ciascun blocco riporta l’id del nodo, l’indice di pagina, un riquadro di delimitazione, una confidenza e un hash di contenuto null. I nodi privi di riquadro di delimitazione ricevono un sentinella condiviso ad area zero, BoundingBox(0, 0, 0, 0), così che l’ancoraggio sia sempre strutturalmente valido.
Confidenza del testo. La confidenza legge l’attributo confidence del nodo quando è un int o un float; il valore predefinito è 1.0. I valori di attributo non numerici ricadono sul valore predefinito.
Metadati del blocco. metadata riporta sempre nodeType e pageIndex. structType, lang e alt vengono copiati quando presenti sul nodo. untagged viene impostato a true quando il nodo porta un attributo untagged.
Selezione delle tabelle. CitedTableExtractor raccoglie solo i nodi Table più esterni, nell’ordine del documento. Una volta elaborato un nodo Table, il suo sottoalbero non viene riesaminato; le tabelle annidate non sono supportate.
Forma della matrice. Le righe provengono dai figli TableRow; le celle provengono dai loro figli TableCell. Gli altri tipi di figlio vengono ignorati. colCount è il numero massimo di celle su tutte le righe. Le righe corte vengono riempite a destra fino a colCount con celle sintetiche: nodeId vuoto, testo null, bbox null, l’indice di pagina della tabella, confidenza 0.0. Una tabella senza righe o senza colonne non produce alcun blocco.
Confidenza delle celle. La confidenza di una cella reale legge il suo attributo confidence quando è un int o un float; il valore predefinito è 0.8. I blocchi di testo hanno come predefinito 1.0; le celle di tabella hanno come predefinito 0.8.
Mappatura della struttura. La gerarchia percorsa è mappata sul modello di struttura logica del PDF (ISO 32000-2:2020 §14.7). Le righe della tabella sono mappate sull’elemento di struttura TR (§14.8) quando l’origine è tagged.

Casi limite e modalità di errore

Nulla in questa superficie solleva eccezioni. Entrambi i metodi extract() restituiscono una lista vuota per un documento privo di nodi idonei.
Il riquadro di delimitazione ad area zero è un sentinella singleton condiviso. Chi effettua la chiamata e necessita di una regione reale deve rilevarlo esplicitamente: width === 0.0 && height === 0.0.
Tutti i controlli di lunghezza e le suddivisioni sono basati sui byte. Quando non esiste alcun confine di frase entro la finestra di 200 byte, un’interruzione netta può cadere all’interno di una sequenza UTF-8 multibyte.
Il valore di 4 byte per token è solo un’euristica di budget. Non è un tokenizzatore e non corrisponde alla tokenizzazione di alcun modello specifico. estimatedTokens() utilizza la stessa euristica.
Una stringa numerica in un attributo confidence non viene convertita; si applica il valore predefinito. Vengono considerati solo i valori int e float.
Il salto degli spazi dopo un taglio rimuove solo gli spazi semplici. I tab e i ritorni a capo all’inizio di un chunk vengono preservati.
Il testo di TableCell viene estratto due volte per scelta progettuale: come blocchi di testo da CitedTextExtractor e all’interno delle matrici da CitedTableExtractor. Deduplica a valle quando si eseguono entrambi gli estrattori sullo stesso documento.
Le celle di riempimento sono identificabili da un nodeId vuoto e da una confidenza 0.0. Una cella reale ma vuota mantiene il suo nodeId non vuoto.
In questo modulo non avviene alcuna operazione crittografica, quindi non vi è alcun comportamento specifico della modalità FIPS.

Conformità

Quando il documento di origine è tagged, l’AST rispecchia la gerarchia di struttura logica di ISO 32000-2:2020 §14.7, e i nodi Table/TableRow corrispondono agli elementi di struttura Table/TR del §14.8. La qualità dell’estrazione è limitata dalla qualità del tagging; il contenuto non tagged produce nodi meno numerosi o più grossolani.

Si tratta di dichiarazioni di allineamento strutturale, non di risultati di test di conformità. NextPDF non detiene alcuna certificazione e non ne concede alcuna. Questo modulo non avanza alcuna rivendicazione di conformità propria; consuma qualsiasi struttura abbia prodotto il sottosistema Core AST.

Note di sviluppo

Riutilizzare una singola istanza di CitedTextExtractor tra documenti è sicuro in modo sequenziale; extract() azzera chunkIndex prima di ogni percorrenza.
Regola minChunkLength per filtrare i nodi di rumore (numeri di pagina, sequenze di glifi sparse) prima della suddivisione in chunk, non dopo.
Per il CJK e altri script multibyte l’euristica basata sui byte sovrastima i token; dimensiona maxTokensPerChunk di conseguenza.
CitedTableBlock::toArray() e CitedTableCell::toArray() emettono chiavi snake_case per le pipeline JSON. CitedTextBlock non ha serializzatore; codifica i suoi campi autonomamente.
Il campo contentHash di CitationAnchor è sempre null in questa superficie. Calcola gli hash di contenuto a valle quando la pipeline ne ha bisogno.

Ambito di pubblicazione

Questa pagina documenta solo il comportamento osservabile esternamente e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle di meccanismo, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.