Classifier — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die Referenz auf Vertragsebene für den NextPDF Pro Dokumentklassifikator. Die Oberfläche besteht aus einem Orchestrator, NextPDF\Pro\Classifier\DocumentClassifier, und seinen Kollaboratoren: StructureAnalyzer, LanguageDetector sowie der ClassifierInterface-Strategie mit ihrem Standard HeuristicClassifier. Ergebnisse kommen als unveränderliches ClassificationResult, das einen DocumentType, eine Konfidenz in [0.0, 1.0], erkannte ClassificationFeature-Werte und einen ISO-639-1-Sprachcode trägt. Die Klassifizierung ist regelbasiert und deterministisch: keine Modellinferenz, keine Zufälligkeit, kein Netzwerkaufruf, kein Dateisystemzugriff. Diese Seite beschreibt die öffentliche API, den beobachtbaren Verhaltensvertrag und die Fehlermodi.

Verfügbarkeit & Lizenzierung

Diese Funktion ist in NextPDF Pro (nextpdf/pro) enthalten und wird mit einem Lizenz-Envelope der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und Lizenz erwerben.

Kein Laufzeit-Capability-Flag steuert dieses Modul. Die Klassifikator-Klassen sind verfügbar, sobald nextpdf/pro installiert ist.

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Löst aus oder scheitert mit	Hinweise
DocumentClassifier	Konstruktor: StructureAnalyzer, LanguageDetector, ClassifierInterface	Orchestriert Strukturanalyse, Strategie-Klassifizierung und Spracherkennung	—	—	final; Kollaboratoren nur für benutzerdefinierte Strategien injizieren
DocumentClassifier::create()	keine	Erstellt Standard-Kollaboratoren mit HeuristicClassifier als Strategie	self	—	Deterministische Standardkonfiguration
DocumentClassifier::classifyFromText()	$text, $pdfData = ''	Leeres $pdfData verwendet eine leere Struktur; nicht-leere Rohbytes fügen strukturelle Signale hinzu	ClassificationResult	Löst nicht aus; spärliche Eingabe senkt die Konfidenz	Die Spracherkennung läuft immer auf $text
DocumentClassifier::classifyFromFile()	string $pdfData	Scannt Content-Streams, stellt §9.4-Text wieder her, analysiert die Struktur, klassifiziert	ClassificationResult	Löst nicht aus; unlesbare Streams verringern den wiederhergestellten Text	Begrenzter Byte-Scan, kein vollständiges PDF-Parsing
ClassifierInterface::classify()	$text, StructureAnalysis $structure	Strategie-Vertrag, den der Orchestrator konsumiert	ClassificationResult	Implementierungsabhängig	Erweiterungspunkt für benutzerdefinierte Klassifizierungsstrategien
ClassifierInterface::supports()	string $contentType	Content-Type-Prüfung für zusammengesetzte Klassifikatoren	bool	—	Erhält einen MIME-Typ oder Content-Deskriptor
HeuristicClassifier	keine	Standardstrategie: Schlüsselwort-Wörterbücher plus strukturelle Heuristiken	—	Löst nicht aus	final; supports() akzeptiert application/pdf und text/plain
StructureAnalyzer::analyze()	string $pdfData	Regex-Scan der Rohbytes; kein vollständiges PDF-Parsing	StructureAnalysis	Löst nicht aus	Zählt Seiten, Bilder, Schriftarten; erkennt Formular- und Signaturfelder
LanguageDetector::detect()	string $text	Trigramm-Profil-Abgleich mit CJK-Skriptbereich-Vorprüfung	non-empty-string ISO-639-1-Code	Löst nicht aus	Fällt unterhalb der Akzeptanzschwelle auf en zurück
LanguageDetector::detectWithConfidence()	string $text	Wie detect(), jedoch mit offengelegter Konfidenz	array{language: non-empty-string, confidence: float}	Löst nicht aus	Kurzer Text gibt en mit Konfidenz 0.0 zurück
ClassificationResult	Konstruktor: $type, $confidence, $features, $language, $metadata = []	Unveränderliches Wertobjekt	—	—	final readonly; metadata trägt scores und method
ClassificationResult::isConfident()	float $threshold = 0.7	Vergleicht die Konfidenz mit dem Schwellenwert	bool	—	Dokumentiertes Gate für das Routing zur manuellen Prüfung
StructureAnalysis	Konstruktor: $pageCount, $imageCount, $fontCount, $hasFormFields, $hasSignatureFields, $imageDensity, $detectedFeatures	Unveränderliches Wertobjekt, erzeugt von StructureAnalyzer	—	—	final readonly; imageDensity ist Bilder pro Seite
DocumentType	String-basiertes Enum, 12 Fälle	Fälle: Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other	Backing-Werte invoice … other	—	label() gibt einen menschenlesbaren Namen zurück
ClassificationFeature	String-basiertes Enum, 7 Fälle	Fälle: HasTables, HasHeaders, HasSignatures, HasLogos, HasBarcodes, HasForms, IsScanned	Backing-Werte has_tables … is_scanned	—	Strukturelle Signale, die in die Klassifizierung einfließen

Einstiegspunkt-Signaturen

public static function create(): self

public function classifyFromText(string $text, string $pdfData = ''): ClassificationResult

public function classifyFromFile(string $pdfData): ClassificationResult

public function classify(string $text, StructureAnalysis $structure): ClassificationResult;

public function supports(string $contentType): bool;

public function analyze(string $pdfData): StructureAnalysis

public function detect(string $text): string

public function detectWithConfidence(string $text): array

public function __construct(
    public DocumentType $type,
    public float $confidence,
    public array $features,
    public string $language,
    public array $metadata = [],
) {}

public function isConfident(float $threshold = 0.7): bool

Verhaltensvertrag

Pipeline-Reihenfolge

DocumentClassifier führt zunächst die Strukturanalyse aus, dann die Strategie-Klassifizierung, dann die Spracherkennung, und setzt daraus ein ClassificationResult zusammen. Die Strategie liefert Typ, Konfidenz, Merkmale und Metadaten; der Detektor liefert die Sprache. classifyFromText() ohne PDF-Bytes setzt eine leere Struktur ein: null Seiten, null Zählwerte, keine Merkmale. classifyFromFile() leitet sowohl die Struktur als auch den Text aus denselben Rohbytes ab.

Heuristisches Scoring

HeuristicClassifier bewertet kleingeschriebenen Text anhand von Schlüsselwort-Wörterbüchern pro Dokumenttyp, normalisiert über die Textlänge. Die konkreten Wörterbücher, Gewichte und Schwellenwerte sind Implementierungsdetail und werden nicht veröffentlicht. Strukturelle Signale passen die Punktwerte anschließend an: übereinstimmende ClassificationFeature-Werte verstärken ihre zugehörigen Typen; Dokumente oberhalb einer Seitenschwelle tendieren weg von Letter und Receipt; mehrseitige Dokumente mit Überschriften und Tabellen erhalten einen Report-Zuschlag; ein erkanntes Formularmerkmal fügt ein starkes Form-Signal hinzu. Der höchste Punktwert gewinnt und wird auf einen DocumentType abgebildet. Eine begrenzte Normalisierung bildet den Rohwert in [0.0, 1.0] ab. Ein Wert unterhalb des Minimums ergibt DocumentType::Other mit einer kleinen, von null verschiedenen Konfidenz-Untergrenze. Die metadata des Ergebnisses trägt die typweise scores-Map und method: heuristic. HeuristicClassifier allein meldet die Sprache en; DocumentClassifier überschreibt sie mit der Ausgabe des Detektors.

Spracherkennung

Eine Skriptbereich-Prüfung für CJK-Text läuft vor dem Trigramm-Scoring. Hangul-Dominanz wählt ko; jegliches Kana wählt ja; andernfalls wählt ein ausreichender Ideogramm-Anteil zh. Aller übrige Text wird anhand der Zeichen-Trigramm-Häufigkeit gegen zehn eingebaute Profile bewertet. Die möglichen Rückgabewerte sind die ISO-639-1-Codes en, zh, ja, ko, de, fr, es, pt, it und nl. Text unterhalb einer Mindestlänge gibt en mit Konfidenz 0.0 zurück. Ein Ergebnis unterhalb der Akzeptanzschwelle mit geringem Abstand gibt ebenfalls en zurück. Die Konfidenz spiegelt den Abstand zwischen dem besten und dem zweitbesten Profilwert wider.

Textwiederherstellung aus Dateien

classifyFromFile() durchsucht die Rohbytes nach stream/endstream-Segmenten. Jedes Segment wird unter einer begrenzten Inflations-Obergrenze als Flate-Daten versucht; bei Fehlschlag werden die rohen Segmentbytes verwendet. Wenn das benachbarte Stream-Dictionary einen PNG-Prädiktor in /DecodeParms deklariert, berücksichtigt die Umkehrung die Parameter Predictor, Columns, Colors und BitsPerComponent gemäß ISO 32000-2:2020 §7.4.4.4, unter Verwendung der Klassen DecodeParms und PngPredictor des Filter-Moduls. Anschließend wird Text aus den §9.4-Text-Showing-Operatoren wiederhergestellt: literale Zeichenketten, die mit Tj dargestellt werden, und literale Zeichenketten innerhalb von TJ-Arrays. Der Klassifikator bewertet den wiederhergestellten Text; er hängt nicht vom visuellen Layout ab.

Strukturanalyse

StructureAnalyzer::analyze() zählt Seiten-, Bild- und Schriftart-Token in den Rohbytes, erkennt /AcroForm- und Signaturfelder und leitet die Bilddichte ab. Die Merkmalserkennung ist heuristisch: wiederholtes Zeichnen von Rechtecken deutet auf Tabellen hin, große Schriftgrößen-Deklarationen deuten auf Überschriften hin, und eine hohe Bilddichte bei wenigen Schriftarten deutet auf ein gescanntes Dokument hin. Die Zählwerte spiegeln die in den Rohbytes sichtbaren Token wider; Strukturen, die in komprimierten Objekt-Streams serialisiert sind, werden nicht gezählt.

Determinismus

Die gesamte Pipeline ist eine reine Funktion ihrer Eingabebytes. Identische Eingabe erzeugt ein identisches ClassificationResult. Es gibt keine Modellinferenz, keine Zufälligkeit, keinen Netzwerkaufruf und keinen Dateisystemzugriff.

Grenzfälle & Fehlermodi

• Leerer oder nahezu leerer Text ergibt bewusst ein DocumentType::Other mit geringer Konfidenz. Verzweigen Sie über isConfident() statt allein über den Typ.
• Keine öffentliche Methode dieses Moduls löst eine Ausnahme aus. Streams, deren Dekomprimierung fehlschlägt, werden roh gescannt; fehlerhafte oder nicht unterstützte Prädiktor-Parameter fallen auf die ungefilterten Bytes zurück.
• Die Textwiederherstellung erfasst nur literale Zeichenketten in Tj- und TJ-Formen. Hexadezimale Zeichenketten, Text innerhalb verschlüsselter Inhalte und über Streams hinweg aufgeteilte Operatoren werden nicht wiederhergestellt, was den zur Bewertung verfügbaren Text verringert.
• Die Dekomprimierungs-Obergrenze begrenzt den Speicher während der Stream-Inflation und widersteht Decompression-Bomb-Eingaben. Inhalt jenseits der Obergrenze wird nicht dekomprimiert.
• Reine Bild-PDFs oder stark komprimierte PDFs stellen wenig Text wieder her; rechnen Sie mit Ergebnissen geringer Konfidenz und leiten Sie diese zur manuellen Prüfung weiter.
• Spracherkennung unterhalb der Mindesttextlänge gibt en mit Konfidenz 0.0 zurück; sehr kurze Zeichenketten erzeugen niemals ein nicht-englisches Ergebnis.
• Die zwölf Dokumenttypen und zehn Sprachprofile sind für dieses Release festgelegt. Die Erweiterung erfolgt über eine benutzerdefinierte ClassifierInterface-Implementierung, nicht durch Bearbeiten eingebauter Daten.
• In diesem Modul findet keine kryptografische Operation statt, daher gibt es kein FIPS-Modus-spezifisches Verhalten.

Konformität

Aussage	Standard	Klausel
Die Dateiklassifizierung stellt Text wieder her, der mit dem Tj-Operator dargestellt wird.	ISO 32000-2:2020	§9.4
Die Dateiklassifizierung stellt literale Zeichenketten innerhalb von TJ-Array-Operatoren wieder her.	ISO 32000-2:2020	§9.4
Die Umkehrung des PNG-Prädiktors berücksichtigt die Filterparameter Predictor, Columns, Colors und BitsPerComponent.	ISO 32000-2:2020	§7.4.4.4

Sprachcodes folgen ISO 639-1; dies ist eine produktbezogene Aussage über das Ausgabeformat, keine zitierte Konformitätsaussage. Alle Klauseln sind paraphrasiert; NextPDF gibt keinen normativen Text wieder. Dies sind Funktionsaussagen, keine Zertifizierungen. NextPDF besitzt keine Zertifizierung und erteilt keine. Die Klassifizierung ist heuristisch und nach bestem Bemühen: Das Modul sichert Determinismus zu, nicht Genauigkeit, und die Aufrufer verantworten den Entscheidungsschwellenwert.

Entwicklungshinweise

• Verfügbar seit nextpdf/pro 2.2.0; aktuell in nextpdf/pro 3.1.0.
• Verwenden Sie DocumentClassifier::create() für die Standard-Pipeline. Injizieren Sie Kollaboratoren nur, um eine benutzerdefinierte ClassifierInterface-Strategie bereitzustellen.
• Behandeln Sie Ergebnisse unterhalb des Schwellenwerts als unsicher und leiten Sie sie zur manuellen Prüfung weiter; isConfident() mit seinem Standardwert 0.7 ist das dokumentierte Gate.
• Das Modul speichert nichts, sendet keine Telemetrie und protokolliert keine Eingaben. Wenn Aufrufer metadata persistieren, prüfen Sie diese zunächst gegen ihre eigene Datenverarbeitungsrichtlinie.
• Schlüsselwort-Scoring und Trigramm-Zählung sind linear in der Textlänge. Die Strukturanalyse ist unter der begrenzten Dekomprimierungs-Obergrenze linear in der PDF-Bytelänge. Das Seitenbudget beträgt 1000 ms Wall-Time und 64 MB Spitzenspeicher.

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 Geltungsbereichs.

Siehe auch

• Classifier (Capability) — Installation, Schnellstart und Beispiele für Produktions-Routing.
• Extraction — Ausführliche Referenz — die vollständige Textextraktions-Oberfläche für reichhaltigeren Eingabetext.
• Filter — Ausführliche Referenz — DecodeParms und PngPredictor, verwendet während der Dateiklassifizierung.
• Diff — Ausführliche Referenz — die verwandte Byte-Level-Dokumentvergleichs-Oberfläche.