Ekstrakcja

W skrócie

NextPDF\Pro\Extraction przechodzi sparsowane AST dokumentu i wytwarza bloki tekstu i tabel, z których każdy niesie kotwicę cytowania (indeks strony, prostokąt ograniczający, odniesienie do węzła). Jest to deterministyczny ekstraktor strukturalny do potoków przypisania źródła, a nie silnik wyszukiwania ani rozumienia.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się licencyjną kopertą poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Żadna flaga możliwości w czasie wykonywania nie bramkuje tego modułu; klasy Extraction są dostępne zawsze, gdy zainstalowano nextpdf/pro. Porównaj edycje i uzyskaj licencję.

Instalacja

composer require nextpdf/pro:^3

Przegląd koncepcyjny

Oba ekstraktory przyjmują NextPDF\Ast\AstDocument — sparsowane drzewo dokumentu wytworzone przez podsystem AST z Core. Same nie parsują surowych bajtów PDF; AST to granica wejścia.

• CitedTextExtractor przechodzi drzewo i emituje CitedTextBlock dla każdego znaczącego węzła tekstu (akapit, nagłówek, element listy, komórka tabeli, kod, adnotacja), którego przycięty tekst osiąga minimalną długość. Opcjonalny budżet tokenów dzieli długi tekst na granicach zdań. Każdy blok niesie CitationAnchor z identyfikatorem węzła, indeksem strony, prostokątem ograniczającym oraz pewnością odczytaną z węzła (domyślnie 1.0). Węzły bez prostokąta ograniczającego otrzymują wartownicze pudełko o zerowej powierzchni, aby kotwica była zawsze prawidłowa.
• CitedTableExtractor znajduje węzły Table, odczytuje ich wiersze i komórki oraz buduje prostokątną macierz wierszowo-główną dopełnioną do najszerszego wiersza. Zagnieżdżone tabele nie są przeszukiwane rekurencyjnie. Pewność komórki domyślnie wynosi 0.8, chyba że węzeł niesie jawną wartość.

Hierarchia strukturalna, którą przechodzą te ekstraktory, odpowiada modelowi struktury logicznej PDF (ISO 32000-2:2020 §14.7) oraz elementom struktury tabel (§14.8), gdy dokument źródłowy jest otagowany.

Dlaczego działa to w ten sposób

Ekstraktor przyjmuje jako granicę wejścia sparsowane AST, a nie surowe bajty PDF, dzięki czemu ryzyko parsowania pozostaje oddzielone od logiki ekstrakcji. Pewność jest odczytywana wprost z węzła AST i przekazywana bez zmian; moduł nigdy jej nie oblicza, nie rankuje ani nie poprawia. Wyjście pozostaje w kolejności dokumentu, a nie kolejności według trafności, ponieważ przypisanie źródła wymaga weryfikowalnego pochodzenia, a nie heurystycznego domysłu, którego ekstraktor nie potrafiłby obronić. Każdy blok niesie kotwicę cytowania — identyfikator węzła, indeks strony, prostokąt ograniczający — dzięki czemu potok w dół strumienia może prześledzić każdy cytat z powrotem do jego źródła. To celowo utrzymuje moduł jako deterministyczny ekstraktor strukturalny: raportuje to, co stwierdza AST, i odmawia wymyślania czegokolwiek, czego dokument nie stwierdza.

Tło projektowe: API, które odmawia zgadywania.

Kontrakt zachowania

• Wejście. NextPDF\Ast\AstDocument. Moduł nie przyjmuje surowych bajtów PDF; najpierw wytwórz AST za pomocą podsystemu AST z Core.
• Wyjście. list<CitedTextBlock> lub list<CitedTableBlock> w kolejności dokumentu.
• Pewność jest przekazywana bez zmian. Jest odczytywana z atrybutów węzła AST (lub ustalonej wartości domyślnej). Ten moduł nie oblicza ani nie poprawia pewności.
• Brak przetwarzania semantycznego. Ekstraktor nie wykonuje osadzania, podobieństwa wektorowego, rankingu ani rozumienia dokumentu. Kolejność wyjścia to kolejność dokumentu, a nie kolejność według trafności.
• Determinizm. Dla identycznego AST wytworzone bloki, kotwice oraz indeksy fragmentów są stabilne.

Publiczna powierzchnia API

Typ	Rodzaj	Kluczowe składowe
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

Przykład kodu — Szybki start

<?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,
    );
}

Przykład kodu — Produkcja

<?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;
}

Przypadki brzegowe i pułapki

• Dokumenty nieotagowane lub słabo otagowane dają mniej węzłów tekstu; jakość AST jest górną granicą jakości ekstrakcji.
• Węzły bez prostokąta ograniczającego otrzymują wartowniczy BoundingBox(0,0,0,0) o zerowej powierzchni — wykryj go przez width === 0.0 && height === 0.0, jeśli wymagany jest rzeczywisty region.
• Zagnieżdżone tabele nie są przeszukiwane rekurencyjnie; emitowany jest tylko najbardziej zewnętrzny węzeł Table.
• Krótkie wiersze są dopełniane syntetycznymi komórkami o zerowej pewności, aby każdy wiersz miał tę samą liczbę kolumn.

Lokalizacja danych i ograniczanie PII

Ten moduł przetwarza dowolny tekst zawarty w dostarczonym AST i zwraca go bez zmian wewnątrz bloków. Nie wykonuje wywołań sieciowych, nie korzysta z zewnętrznego przechowywania i nie loguje wyodrębnionej zawartości. Obsługa PII, redakcja oraz kontrole lokalizacji to odpowiedzialność wywołującego względem wytworzonych bloków. Zobacz wytyczne dotyczące obsługi PII w Core.

Bezpieczna telemetria i oczyszczanie logów

Ekstraktor nie emituje żadnej telemetrii i nie loguje wyodrębnionego tekstu. Jeśli wywołujący owinie go logowaniem, oczyść text, metadata oraz dowolną zawartość komórek przed emisją logów.

Wydajność

Ekstrakcja to pojedyncze przejście drzewa, liniowe względem liczby węzłów. Dzielenie na fragmenty dodaje pracę proporcjonalną do długości tekstu. Zobacz performance_budget.

Uwagi dotyczące bezpieczeństwa

Wejście to wstępnie sparsowane AST, więc ten moduł sam nie parsuje wrogich bajtów PDF. Traktuj wyodrębniony tekst jako niezaufany i poddaj go ucieczce odpowiednio do celu.

Konformancja

Twierdzenie	Klauzula specyfikacji	Status
Przejście węzłów struktury logicznej	ISO 32000-2:2020 §14.7	Verified (unit suite, tagged AST)
Ekstrakcja wierszy/komórek tabeli	ISO 32000-2:2020 §14.8	Verified (unit suite)
Wyszukiwanie semantyczne / osadzenia	—	Not supported (out of scope)

Rozwiązanie awaryjne / alternatywa w Core

Podsystem AST z Core wytwarza AstDocument konsumowany tutaj; nie istnieje odpowiednik w Core dla samej ekstrakcji bloków cytowań. Zobacz /modules/core/ast/.

Nota o granicy Enterprise

Ten moduł to wyłącznie ekstraktor strukturalny. Nie wykonuje wyszukiwania semantycznego, osadzania wektorowego, rankingu podobieństwa ani inteligencji dokumentowej. Te możliwości nie są częścią tego modułu i nie są przez niego implikowane.

Granica publikacji

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

Zobacz też

• Dokumentacja Extraction
• Classifier
• Diff
• Core AST