Extraktion

Auf einen Blick

NextPDF\Pro\Extraction durchläuft einen geparsten Dokument-AST und erzeugt Text- und Tabellen-Blöcke, von denen jeder einen Zitationsanker (Seitenindex, Begrenzungsrahmen, Knotenreferenz) trägt. Es ist ein deterministischer struktureller Extraktor für Quellenangaben-Pipelines, keine Such- oder Verständnis-Engine.

Verfügbarkeit & Lizenzierung

Diese Funktion ist in NextPDF Pro (nextpdf/pro) enthalten und wird mit einem Lizenzumschlag der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Kein Laufzeit-Fähigkeits-Flag schaltet dieses Modul; die Extraction-Klassen sind verfügbar, sobald nextpdf/pro installiert ist. Editionen vergleichen und Lizenz erwerben.

Installation

composer require nextpdf/pro:^3

Konzeptioneller Überblick

Beide Extraktoren nehmen ein NextPDF\Ast\AstDocument entgegen — einen geparsten Dokumentbaum, der vom Core-AST-Subsystem erzeugt wird. Sie parsen selbst keine rohen PDF-Bytes; der AST ist die Eingabegrenze.

• CitedTextExtractor durchläuft den Baum und gibt für jeden substanziellen Textknoten (Absatz, Überschrift, Listenelement, Tabellenzelle, Code, Annotation), dessen getrimmter Text eine Mindestlänge erreicht, einen CitedTextBlock aus. Ein optionales Token-Budget teilt langen Text an Satzgrenzen. Jeder Block trägt einen CitationAnchor mit Knoten-ID, Seitenindex, Begrenzungsrahmen und einer aus dem Knoten gelesenen Konfidenz (Standard 1.0). Knoten ohne Begrenzungsrahmen erhalten einen flächenlosen Sentinel-Rahmen, sodass der Anker stets gültig ist.
• CitedTableExtractor findet Table-Knoten, liest ihre Zeilen und Zellen und baut eine rechteckige zeilenweise Matrix, die auf die breiteste Zeile aufgefüllt ist. Verschachtelte Tabellen werden nicht rekursiv durchlaufen. Die Zellkonfidenz beträgt standardmäßig 0.8, sofern der Knoten keinen expliziten Wert trägt.

Die strukturelle Hierarchie, die diese Extraktoren durchlaufen, entspricht dem logischen Strukturmodell des PDF (ISO 32000-2:2020 §14.7) und den Tabellenstruktur-Elementen (§14.8), wenn das Quelldokument getaggt ist.

Warum es so funktioniert

Der Extraktor nimmt einen geparsten AST als Eingabegrenze entgegen, keine rohen PDF-Bytes, sodass das Parsing-Risiko von der Extraktionslogik getrennt bleibt. Die Konfidenz wird direkt aus dem AST-Knoten gelesen und unverändert durchgereicht; das Modul berechnet, bewertet oder verbessert sie niemals. Die Ausgabe bleibt in Dokumentreihenfolge, nicht in Relevanzreihenfolge, denn Quellenangaben benötigen eine überprüfbare Herkunft statt einer heuristischen Vermutung, die der Extraktor nicht verteidigen kann. Jeder Block trägt einen Zitationsanker — Knoten-ID, Seitenindex, Begrenzungsrahmen —, sodass eine nachgelagerte Pipeline jedes Zitat bis zu seinem Ursprung zurückverfolgen kann. Dies hält das Modul bewusst als deterministischen strukturellen Extraktor: Es meldet, was der AST behauptet, und lehnt es ab, etwas zu erfinden, das das Dokument nicht aussagt.

Design-Hintergrund: Eine API, die sich weigert zu raten.

Verhaltensvertrag

• Eingabe. Ein NextPDF\Ast\AstDocument. Das Modul akzeptiert keine rohen PDF-Bytes; erzeugen Sie den AST zuerst mit dem Core-AST-Subsystem.
• Ausgabe. list<CitedTextBlock> oder list<CitedTableBlock> in Dokumentreihenfolge.
• Konfidenz ist Durchreichung. Sie wird aus den Attributen des AST-Knotens (oder einem festen Standard) gelesen. Dieses Modul berechnet oder verbessert keine Konfidenz.
• Keine semantische Verarbeitung. Der Extraktor führt kein Embedding, keine Vektorähnlichkeit, kein Ranking und kein Dokumentenverständnis durch. Die Ausgabereihenfolge ist Dokumentreihenfolge, nicht Relevanzreihenfolge.
• Determinismus. Für einen identischen AST sind die erzeugten Blöcke, Anker und Chunk-Indizes stabil.

Öffentliche API-Oberfläche

Typ	Art	Wichtige Mitglieder
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

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

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

Randfälle & Fallstricke

• Nicht getaggte oder schlecht getaggte Dokumente liefern weniger Textknoten; die AST-Qualität ist die Obergrenze der Extraktionsqualität.
• Knoten ohne Begrenzungsrahmen erhalten einen flächenlosen Sentinel BoundingBox(0,0,0,0) — erkennen Sie ihn über width === 0.0 && height === 0.0, falls eine echte Region erforderlich ist.
• Verschachtelte Tabellen werden nicht rekursiv durchlaufen; nur der äußerste Table-Knoten wird ausgegeben.
• Kurze Zeilen werden mit synthetischen Zellen mit Konfidenz null aufgefüllt, sodass jede Zeile dieselbe Spaltenanzahl hat.

Datenresidenz & PII-Maßnahmen

Dieses Modul verarbeitet den Text, den der bereitgestellte AST enthält, und gibt ihn unverändert innerhalb der Blöcke zurück. Es führt keine Netzwerkaufrufe, keine externe Speicherung und kein Protokollieren extrahierter Inhalte durch. PII-Behandlung, Schwärzung und Residenzkontrollen liegen für die erzeugten Blöcke in der Verantwortung des Aufrufers. Siehe den Core-Leitfaden zur PII-Behandlung.

Sichere Telemetrie & Log-Bereinigung

Der Extraktor gibt keine Telemetrie aus und protokolliert keinen extrahierten Text. Wenn ein Aufrufer ihn mit Logging umgibt, bereinigen Sie text, metadata und jeglichen Zellinhalt, bevor Sie Logs ausgeben.

Performance

Die Extraktion ist ein einziger Baumdurchlauf, linear in der Knotenanzahl. Das Chunk-Splitting fügt Arbeit proportional zur Textlänge hinzu. Siehe performance_budget.

Sicherheitshinweise

Die Eingabe ist ein vorab geparster AST, daher parst dieses Modul keine feindlichen PDF-Bytes selbst. Behandeln Sie extrahierten Text als nicht vertrauenswürdig und escapen Sie ihn für sein Ziel.

Konformität

Aussage	Spezifikationsklausel	Status
Traversierung logischer Strukturknoten	ISO 32000-2:2020 §14.7	Verifiziert (Unit-Suite, getaggter AST)
Tabellenzeilen-/Zellenextraktion	ISO 32000-2:2020 §14.8	Verifiziert (Unit-Suite)
Semantische Suche / Embeddings	—	Nicht unterstützt (außerhalb des Umfangs)

Core-Rückfalloption / Alternative

Das Core-AST-Subsystem erzeugt das hier verarbeitete AstDocument; für die Zitationsblock-Extraktion selbst gibt es kein Core-Äquivalent. Siehe /modules/core/ast/.

Hinweis zur Enterprise-Abgrenzung

Dieses Modul ist ausschließlich ein struktureller Extraktor. Es führt keine semantische Suche, kein Vektor-Embedding, kein Ähnlichkeits-Ranking und keine Dokumenten-Intelligenz durch. Diese Fähigkeiten sind nicht Teil dieses Moduls und werden von ihm nicht impliziert.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.

Siehe auch

• Extraktions-Referenz
• Classifier
• Diff
• Core AST