Classifier — Riferimento approfondito

In breve

Questa pagina è il riferimento a livello di contratto per il classifier di documenti di NextPDF Pro. La superficie è un unico orchestratore, NextPDF\Pro\Classifier\DocumentClassifier, e i suoi collaboratori: StructureAnalyzer, LanguageDetector e la strategia ClassifierInterface con il suo HeuristicClassifier predefinito. I risultati arrivano come un ClassificationResult immutabile che trasporta un DocumentType, una confidenza in [0.0, 1.0], i valori ClassificationFeature rilevati e un codice di lingua ISO 639-1. La classificazione è basata su regole e deterministica: nessuna inferenza di modello, nessuna casualità, nessuna chiamata di rete, nessun accesso al filesystem. Questa pagina illustra l’API pubblica, il contratto di comportamento osservabile e le modalità di errore.

Disponibilità e licenza

Questa capability è 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 capability. Confronta le edizioni e ottieni una licenza.

Nessun flag di capability a runtime controlla questo modulo. Le classi del classifier sono disponibili ogni volta che nextpdf/pro è installato.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
DocumentClassifier	costruttore: StructureAnalyzer, LanguageDetector, ClassifierInterface	Orchestra l’analisi della struttura, la classificazione con strategia e il rilevamento della lingua	—	—	final; iniettare i collaboratori solo per strategie personalizzate
DocumentClassifier::create()	nessuno	Costruisce i collaboratori predefiniti con HeuristicClassifier come strategia	self	—	Configurazione predefinita deterministica
DocumentClassifier::classifyFromText()	$text, $pdfData = ''	Un $pdfData vuoto usa una struttura vuota; byte grezzi non vuoti aggiungono segnali strutturali	ClassificationResult	Non solleva; input scarso riduce la confidenza	Il rilevamento della lingua viene sempre eseguito su $text
DocumentClassifier::classifyFromFile()	string $pdfData	Scansiona i content stream, recupera il testo del §9.4, analizza la struttura, classifica	ClassificationResult	Non solleva; stream illeggibili riducono il testo recuperato	Scansione di byte vincolata, non un parsing completo del PDF
ClassifierInterface::classify()	$text, StructureAnalysis $structure	Contratto di strategia consumato dall’orchestratore	ClassificationResult	Definito dall’implementazione	Punto di estensione per strategie di classificazione personalizzate
ClassifierInterface::supports()	string $contentType	Sonda del content-type per classifier compositi	bool	—	Riceve un tipo MIME o un descrittore di contenuto
HeuristicClassifier	nessuno	Strategia predefinita: dizionari di parole chiave più euristiche strutturali	—	Non solleva	final; supports() accetta application/pdf e text/plain
StructureAnalyzer::analyze()	string $pdfData	Scansione regex dei byte grezzi; nessun parsing completo del PDF	StructureAnalysis	Non solleva	Conta pagine, immagini, font; rileva i campi modulo e i campi firma
LanguageDetector::detect()	string $text	Corrispondenza per profilo di trigrammi con pre-controllo dell’intervallo di script CJK	codice ISO 639-1 non-empty-string	Non solleva	Ripiega su en al di sotto della soglia di accettazione
LanguageDetector::detectWithConfidence()	string $text	Come detect(), con la confidenza esposta	array{language: non-empty-string, confidence: float}	Non solleva	Un testo breve restituisce en con confidenza 0.0
ClassificationResult	costruttore: $type, $confidence, $features, $language, $metadata = []	Value object immutabile	—	—	final readonly; metadata trasporta scores e method
ClassificationResult::isConfident()	float $threshold = 0.7	Confronta la confidenza con la soglia	bool	—	Gate documentato per l’instradamento alla revisione manuale
StructureAnalysis	costruttore: $pageCount, $imageCount, $fontCount, $hasFormFields, $hasSignatureFields, $imageDensity, $detectedFeatures	Value object immutabile prodotto da StructureAnalyzer	—	—	final readonly; imageDensity è il numero di immagini per pagina
DocumentType	enum con backing string, 12 casi	Casi: Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other	valori di backing invoice … other	—	label() restituisce un nome leggibile
ClassificationFeature	enum con backing string, 7 casi	Casi: HasTables, HasHeaders, HasSignatures, HasLogos, HasBarcodes, HasForms, IsScanned	valori di backing has_tables … is_scanned	—	Segnali strutturali forniti alla classificazione

Firme dei punti di ingresso

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

Contratto di comportamento

Ordine della pipeline

DocumentClassifier esegue l’analisi della struttura, poi la classificazione con strategia, poi il rilevamento della lingua, e assembla un ClassificationResult. La strategia fornisce il tipo, la confidenza, le feature e i metadati; il detector fornisce la lingua. classifyFromText() senza byte PDF sostituisce una struttura vuota: zero pagine, zero conteggi, nessuna feature. classifyFromFile() deriva sia la struttura sia il testo dagli stessi byte grezzi.

Scoring euristico

HeuristicClassifier valuta il testo reso minuscolo rispetto a dizionari di parole chiave per ciascun tipo di documento, normalizzati in base alla lunghezza del testo. I dizionari, i pesi e le soglie specifici sono dettaglio di implementazione e non vengono pubblicati. I segnali strutturali regolano poi i punteggi: i valori ClassificationFeature corrispondenti incrementano i tipi a essi associati; i documenti al di sopra di una soglia di pagine si allontanano da Letter e Receipt; i documenti multipagina con intestazioni e tabelle ricevono un incremento verso Report; una feature modulo rilevata aggiunge un forte segnale Form. Il punteggio più alto vince e viene mappato su un DocumentType. Una normalizzazione vincolata mappa il punteggio grezzo in [0.0, 1.0]. Un punteggio inferiore al minimo produce DocumentType::Other con un piccolo valore minimo di confidenza diverso da zero. I metadata del risultato trasportano la mappa scores per tipo e method: heuristic. HeuristicClassifier da solo riporta la lingua en; DocumentClassifier la sovrascrive con l’output del detector.

Rilevamento della lingua

Un controllo dell’intervallo di script per il testo CJK viene eseguito prima dello scoring dei trigrammi. La predominanza dell’hangul seleziona ko; la presenza di qualsiasi kana seleziona ja; altrimenti un rapporto sufficiente di ideogrammi seleziona zh. Tutto il resto del testo viene valutato in base alla frequenza dei trigrammi di caratteri rispetto a dieci profili integrati. I valori di ritorno possibili sono i codici ISO 639-1 en, zh, ja, ko, de, fr, es, pt, it e nl. Un testo al di sotto di una lunghezza minima restituisce en con confidenza 0.0. Anche un risultato al di sotto della soglia di accettazione con un margine ristretto restituisce en. La confidenza riflette il margine tra il punteggio del profilo migliore e quello del secondo migliore.

Recupero del testo dai file

classifyFromFile() scansiona i byte grezzi alla ricerca di segmenti stream/endstream. Ogni segmento viene provato come dati Flate sotto un limite di inflazione vincolato; in caso di fallimento vengono usati i byte grezzi del segmento. Quando il dizionario dello stream adiacente dichiara un predittore PNG in /DecodeParms, l’inversione rispetta i parametri Predictor, Columns, Colors e BitsPerComponent secondo la ISO 32000-2:2020 §7.4.4.4, usando le classi DecodeParms e PngPredictor del modulo Filter. Il testo viene quindi recuperato dagli operatori di mostra del testo del §9.4: le stringhe letterali mostrate con Tj e le stringhe letterali all’interno degli array TJ. Il classifier valuta il testo recuperato; non dipende dal layout visivo.

Analisi della struttura

StructureAnalyzer::analyze() conta i token di pagina, immagine e font nei byte grezzi, rileva i campi /AcroForm e i campi firma, e deriva la densità delle immagini. Il rilevamento delle feature è euristico: il disegno ripetuto di rettangoli suggerisce tabelle, le dichiarazioni di font di grandi dimensioni suggeriscono intestazioni, e un’elevata densità di immagini con pochi font suggerisce un documento scansionato. I conteggi riflettono i token visibili nei byte grezzi; le strutture serializzate all’interno di object stream compressi non vengono conteggiate.

Determinismo

L’intera pipeline è una funzione pura dei suoi byte di input. Un input identico produce un ClassificationResult identico. Non c’è inferenza di modello, né casualità, né chiamata di rete, né accesso al filesystem.

Casi limite e modalità di errore

• Un testo vuoto o quasi vuoto produce per progettazione un DocumentType::Other a bassa confidenza. Ramificare su isConfident() anziché sul solo tipo.
• Nessun metodo pubblico di questo modulo solleva eccezioni. Gli stream la cui decompressione fallisce vengono scansionati grezzi; i parametri del predittore malformati o non supportati ripiegano sui byte non filtrati.
• Il recupero del testo corrisponde solo alle forme Tj e TJ con stringhe letterali. Le stringhe esadecimali, il testo all’interno di contenuti cifrati e gli operatori suddivisi tra più stream non vengono recuperati, il che riduce il testo disponibile per lo scoring.
• Il limite di decompressione vincola la memoria durante l’inflazione degli stream e resiste agli input di tipo decompression-bomb. Il contenuto oltre il limite non viene inflazionato.
• I PDF composti solo da immagini o fortemente compressi recuperano poco testo; aspettarsi risultati a bassa confidenza e instradarli alla revisione manuale.
• Il rilevamento della lingua al di sotto della lunghezza minima del testo restituisce en con confidenza 0.0; le stringhe molto brevi non producono mai un risultato diverso dall’inglese.
• I dodici tipi di documento e i dieci profili di lingua sono fissi per questa release. L’estensione avviene tramite un’implementazione personalizzata di ClassifierInterface, non modificando i dati integrati.
• In questo modulo non avviene alcuna operazione crittografica, quindi non esiste alcun comportamento specifico per la modalità FIPS.

Conformità

Affermazione	Standard	Clausola
La classificazione dei file recupera il testo mostrato con l’operatore Tj.	ISO 32000-2:2020	§9.4
La classificazione dei file recupera le stringhe letterali all’interno degli operatori array TJ.	ISO 32000-2:2020	§9.4
L’inversione del predittore PNG rispetta i parametri del filtro Predictor, Columns, Colors e BitsPerComponent.	ISO 32000-2:2020	§7.4.4.4

I codici di lingua seguono la ISO 639-1; si tratta di una dichiarazione fondata sul prodotto riguardo al formato di output, non di un’affermazione di conformità citata. Tutte le clausole sono parafrasate; NextPDF non riproduce il testo normativo. Queste sono dichiarazioni di capability, non certificazioni. NextPDF non detiene alcuna certificazione e non ne concede alcuna. La classificazione è euristica e best-effort: il modulo garantisce il determinismo, non l’accuratezza, e la soglia di decisione è responsabilità dei chiamanti.

Note di sviluppo

• Disponibile da nextpdf/pro 2.2.0; attuale in nextpdf/pro 3.1.0.
• Usare DocumentClassifier::create() per la pipeline predefinita. Iniettare i collaboratori solo per fornire una strategia ClassifierInterface personalizzata.
• Trattare i risultati al di sotto della soglia come incerti e instradarli alla revisione manuale; isConfident() con il suo valore predefinito 0.7 è il gate documentato.
• Il modulo non memorizza nulla, non emette telemetria e non registra alcun input. Se i chiamanti rendono persistenti i metadata, dovrebbero prima verificarli rispetto alla propria policy di gestione dei dati.
• Lo scoring delle parole chiave e il conteggio dei trigrammi sono lineari rispetto alla lunghezza del testo. L’analisi della struttura è lineare rispetto alla lunghezza in byte del PDF sotto il limite di decompressione vincolato. Il budget della pagina è di 1000 ms di wall time e 64 MB di memoria di picco.

Confine di pubblicazione

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

Vedere anche

• Classifier (capability) — installazione, avvio rapido ed esempi di instradamento in produzione.
• Extraction — Riferimento approfondito — la superficie completa di estrazione del testo per un testo di input più ricco.
• Filter — Riferimento approfondito — DecodeParms e PngPredictor, usati durante la classificazione dei file.
• Diff — Riferimento approfondito — la superficie affine di confronto di documenti a livello di byte.