Pro edycja

Extraction — szczegółowa dokumentacja referencyjna

W skrócie

Ta strona jest referencją na poziomie kontraktu dla NextPDF\Pro\Extraction. Moduł zawiera pięć publicznych symboli: dwa ekstraktory (CitedTextExtractor, CitedTableExtractor) oraz trzy niezmienne obiekty wartości (CitedTextBlock, CitedTableBlock, CitedTableCell). Oba ekstraktory przyjmują sparsowany NextPDF\Ast\AstDocument; żaden nie odczytuje surowych bajtów PDF. Ekstrakcja jest deterministyczna i strukturalna. W tym module nie istnieje nigdzie żaden krok semantyczny, osadzania (embedding) ani rankingu. Widok zorientowany na zadania znajduje się na stronie możliwości.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej możliwości. Porównaj edycje i uzyskaj licencję.

Tego modułu nie obejmuje brama żadnej flagi możliwości w czasie działania. Klasy są dostępne zawsze, gdy nextpdf/pro jest zainstalowany i objęty licencją.

Powierzchnia publicznego API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Rzuca lub zawodzi z	Uwagi
`CitedTextExtractor::__construct()`	`?int $maxTokensPerChunk = null`, `int $minChunkLength = 10`	Brak budżetu tokenów; przycięty tekst poniżej 10 bajtów jest odrzucany	`CitedTextExtractor`	Nie rzuca	Budżet `null` oznacza jeden blok na węzeł.
`CitedTextExtractor::extract()`	`AstDocument $document`	Przejście w głąb (depth-first); jeden blok na kwalifikujący się węzeł tekstowy, dzielony według budżetu tokenów	`list<CitedTextBlock>`	Nie rzuca	Deterministyczne; `chunkIndex` jest zerowany przy każdym wywołaniu.
`CitedTextBlock`	pięć pól readonly	Niezmienny obiekt wartości; brak metody serializującej	—	Nie rzuca	Klucze `metadata`: `nodeType`, `pageIndex`, oraz opcjonalnie `structType`, `lang`, `alt`, `untagged`.
`CitedTextBlock::estimatedTokens()`	brak	`ceil(byte length / 4)`	`int`	Nie rzuca	Heurystyka budżetu; nie tokenizator.
`CitedTableExtractor::extract()`	`AstDocument $document`	Zbiera najbardziej zewnętrzne węzły `Table` w kolejności dokumentu	`list<CitedTableBlock>`	Nie rzuca	Nigdy nie schodzi w głąb poddrzewa tabeli.
`CitedTableBlock`	pięć pól readonly	Niezmienna prostokątna macierz komórek w porządku wierszowym	—	Nie rzuca	Krótkie wiersze są uzupełniane z prawej strony w trakcie ekstrakcji.
`CitedTableBlock::toArray()`	brak	Serializuje do zwykłej tablicy w konwencji snake_case	`array<string, mixed>`	Nie rzuca	Zagnieżdżone komórki serializują się przez `CitedTableCell::toArray()`.
`CitedTableCell`	siedem pól readonly	Niezmienny rekord komórki ze współrzędnymi cytowania	—	Nie rzuca	Komórki wypełniające niosą pusty `nodeId` i ufność 0.0.
`CitedTableCell::toArray()`	brak	Serializuje do zwykłej tablicy w konwencji snake_case; `bbox` zagnieżdża się lub jest `null`	`array<string, mixed>`	Nie rzuca	—

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

Kontrakt zachowania

Wybór węzłów. CitedTextExtractor emituje bloki dla węzłów, których typem jest Paragraph, Heading, ListItem, TableCell, Code lub Annotation. Węzeł z tekstem null jest pomijany. Węzeł jest emitowany tylko wtedy, gdy długość jego przyciętego tekstu wynosi co najmniej minChunkLength (domyślnie 10). Wszystkie długości są długościami w bajtach.
Kolejność przechodzenia. Przejście odbywa się w głąb (depth-first) od korzenia dokumentu. Kwalifikujący się węzeł jest emitowany przed odwiedzeniem jego potomków. chunkIndex zwiększa się w obrębie całego przejścia po dokumencie i jest zerowany przy każdym wywołaniu extract().
Podział na fragmenty. Gdy maxTokensPerChunk nie jest ustawiony, każdy węzeł daje jeden blok. Gdy jest ustawiony, tekst dłuższy niż maxTokensPerChunk * 4 bajtów jest dzielony. Mechanizm dzielenia preferuje granicę zdania — znak nowej linii lub kropkę, po której następuje spacja — znalezioną przez skanowanie wstecz o co najwyżej 200 bajtów od preferowanego punktu cięcia. W przeciwnym razie następuje twarde łamanie na granicy budżetu. Spacje po cięciu są pomijane; puste fragmenty są odrzucane.
Kotwica cytowania. CitationAnchor każdego bloku niesie identyfikator węzła, indeks strony, ramkę ograniczającą, ufność oraz null jako skrót zawartości. Węzły bez ramki ograniczającej otrzymują współdzielony wartownik o zerowym polu, BoundingBox(0, 0, 0, 0), dzięki czemu kotwica jest zawsze strukturalnie poprawna.
Ufność tekstu. Ufność jest odczytywana z atrybutu confidence węzła, gdy jest to int lub float; wartością domyślną jest 1.0. Nieliczbowe wartości atrybutu powracają do wartości domyślnej.
Metadane bloku. metadata zawsze niesie nodeType i pageIndex. structType, lang oraz alt są kopiowane, gdy występują na węźle. untagged jest ustawiane na true, gdy węzeł niesie atrybut untagged.
Wybór tabel. CitedTableExtractor zbiera tylko najbardziej zewnętrzne węzły Table, w kolejności dokumentu. Po przetworzeniu węzła Table jego poddrzewo nie jest ponownie badane; tabele zagnieżdżone nie są obsługiwane.
Kształt macierzy. Wiersze pochodzą z potomków TableRow; komórki pochodzą z ich potomków TableCell. Pozostałe typy potomków są ignorowane. colCount to maksymalna liczba komórek we wszystkich wierszach. Krótkie wiersze są uzupełniane z prawej strony do colCount syntetycznymi komórkami: pusty nodeId, tekst null, bbox równy null, indeks strony tabeli, ufność 0.0. Tabela bez wierszy lub bez kolumn nie daje żadnego bloku.
Ufność komórki. Ufność rzeczywistej komórki jest odczytywana z jej atrybutu confidence, gdy jest to int lub float; wartością domyślną jest 0.8. Bloki tekstu domyślnie mają 1.0; komórki tabeli domyślnie 0.8.
Odwzorowanie struktury. Przechodzona hierarchia odwzorowuje model struktury logicznej PDF (ISO 32000-2:2020 §14.7). Wiersze tabeli odwzorowują element struktury TR (§14.8), gdy źródło jest otagowane.

Przypadki brzegowe i tryby awarii

Nic na tej powierzchni nie rzuca wyjątków. Obie metody extract() zwracają pustą listę dla dokumentu bez kwalifikujących się węzłów.
Ramka ograniczająca o zerowym polu jest współdzielonym wartownikiem singleton. Wywołujący, którzy potrzebują rzeczywistego obszaru, muszą wykryć ją jawnie: width === 0.0 && height === 0.0.
Wszystkie sprawdzenia długości i podziały są oparte na bajtach. Gdy w oknie 200 bajtów nie istnieje żadna granica zdania, twarde łamanie może wypaść wewnątrz wielobajtowej sekwencji UTF-8.
Wartość 4 bajtów na token jest wyłącznie heurystyką budżetowania. Nie jest to tokenizator i nie odpowiada tokenizacji żadnego konkretnego modelu. estimatedTokens() używa tej samej heurystyki.
Łańcuch liczbowy w atrybucie confidence nie jest rzutowany; stosowana jest wartość domyślna. Honorowane są wyłącznie wartości int i float.
Pomijanie białych znaków po cięciu usuwa jedynie zwykłe spacje. Tabulatory i znaki nowej linii na początku fragmentu są zachowywane.
Tekst TableCell jest z założenia ekstrahowany dwukrotnie: jako bloki tekstu przez CitedTextExtractor oraz wewnątrz macierzy przez CitedTableExtractor. Usuń duplikaty na dalszym etapie, gdy oba ekstraktory działają na jednym dokumencie.
Komórki wypełniające można rozpoznać po pustym nodeId i ufności 0.0. Rzeczywista, lecz pusta komórka zachowuje swój niepusty nodeId.
W tym module nie zachodzi żadna operacja kryptograficzna, więc nie ma zachowania specyficznego dla trybu FIPS.

Zgodność ze standardami

Gdy dokument źródłowy jest otagowany, AST odzwierciedla hierarchię struktury logicznej z ISO 32000-2:2020 §14.7, a węzły Table/TableRow odpowiadają elementom struktury Table/TR z §14.8. Jakość ekstrakcji jest ograniczona jakością tagowania; treść nieotagowana daje mniej lub bardziej zgrubne węzły.

Są to stwierdzenia o zgodności strukturalnej, a nie wyniki testów zgodności. NextPDF nie posiada żadnej certyfikacji ani jej nie udziela. Ten moduł nie formułuje własnych roszczeń o zgodności; konsumuje dowolną strukturę wytworzoną przez podsystem Core AST.

Uwagi dla programistów

Ponowne użycie jednej instancji CitedTextExtractor dla wielu dokumentów jest bezpieczne sekwencyjnie; extract() zeruje chunkIndex przed każdym przejściem.
Dostrój minChunkLength, aby odfiltrować węzły szumu (numery stron, przypadkowe ciągi glifów) przed podziałem na fragmenty, a nie po nim.
W przypadku pisma CJK i innych pism wielobajtowych heurystyka oparta na bajtach zawyża liczbę tokenów; odpowiednio dobierz maxTokensPerChunk.
CitedTableBlock::toArray() i CitedTableCell::toArray() emitują klucze snake_case dla potoków JSON. CitedTextBlock nie ma serializatora; zakoduj jego pola samodzielnie.
Pole contentHash obiektu CitationAnchor jest na tej powierzchni zawsze null. Oblicz skróty zawartości na dalszym etapie, gdy potok ich potrzebuje.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz obsługiwaną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.