Classifier — pełna dokumentacja referencyjna

W skrócie

Ta strona to referencja na poziomie kontraktu dla klasyfikatora dokumentów NextPDF Pro. Powierzchnię tworzy jeden orkiestrator, NextPDF\Pro\Classifier\DocumentClassifier, oraz jego współpracownicy: StructureAnalyzer, LanguageDetector i strategia ClassifierInterface z domyślnym HeuristicClassifier. Wyniki przychodzą jako niemutowalny ClassificationResult niosący DocumentType, pewność w zakresie [0.0, 1.0], wykryte wartości ClassificationFeature oraz kod języka ISO 639-1. Klasyfikacja jest oparta na regułach i deterministyczna: bez wnioskowania modelu, bez losowości, bez wywołań sieciowych, bez dostępu do systemu plików. Ta strona opisuje publiczne API, kontrakt obserwowalnego zachowania oraz tryby awarii.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się z kopertą licencji poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Żadna flaga funkcji czasu wykonania nie bramkuje tego modułu. Klasy klasyfikatora są dostępne, gdy tylko zainstalowano nextpdf/pro.

Powierzchnia publicznego API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
DocumentClassifier	konstruktor: StructureAnalyzer, LanguageDetector, ClassifierInterface	Orkiestruje analizę struktury, klasyfikację strategii i wykrywanie języka	—	—	final; wstrzykuj współpracowników tylko dla niestandardowych strategii
DocumentClassifier::create()	brak	Buduje domyślnych współpracowników z HeuristicClassifier jako strategią	self	—	Deterministyczna konfiguracja domyślna
DocumentClassifier::classifyFromText()	$text, $pdfData = ''	Puste $pdfData używa pustej struktury; niepuste surowe bajty dodają sygnały strukturalne	ClassificationResult	Nie zgłasza wyjątków; ubogie wejście obniża pewność	Wykrywanie języka zawsze działa na $text
DocumentClassifier::classifyFromFile()	string $pdfData	Skanuje strumienie zawartości, odzyskuje tekst z §9.4, analizuje strukturę, klasyfikuje	ClassificationResult	Nie zgłasza wyjątków; nieczytelne strumienie zmniejszają ilość odzyskanego tekstu	Ograniczone skanowanie bajtów, nie pełne parsowanie PDF
ClassifierInterface::classify()	$text, StructureAnalysis $structure	Kontrakt strategii konsumowany przez orkiestratora	ClassificationResult	Zdefiniowane przez implementację	Punkt rozszerzenia dla niestandardowych strategii klasyfikacji
ClassifierInterface::supports()	string $contentType	Sonda typu zawartości dla klasyfikatorów złożonych	bool	—	Otrzymuje typ MIME lub deskryptor zawartości
HeuristicClassifier	brak	Strategia domyślna: słowniki słów kluczowych plus heurystyki strukturalne	—	Nie zgłasza wyjątków	final; supports() akceptuje application/pdf i text/plain
StructureAnalyzer::analyze()	string $pdfData	Skanowanie surowych bajtów wyrażeniami regularnymi; bez pełnego parsowania PDF	StructureAnalysis	Nie zgłasza wyjątków	Liczy strony, obrazy, czcionki; wykrywa pola formularzy i podpisów
LanguageDetector::detect()	string $text	Dopasowanie profilu trigramów ze wstępnym sprawdzeniem zakresu pisma CJK	kod ISO 639-1 typu non-empty-string	Nie zgłasza wyjątków	Poniżej progu akceptacji wraca do en
LanguageDetector::detectWithConfidence()	string $text	Jak detect(), z ujawnioną pewnością	array{language: non-empty-string, confidence: float}	Nie zgłasza wyjątków	Krótki tekst zwraca en z pewnością 0.0
ClassificationResult	konstruktor: $type, $confidence, $features, $language, $metadata = []	Niemutowalny obiekt wartości	—	—	final readonly; metadata niesie scores i method
ClassificationResult::isConfident()	float $threshold = 0.7	Porównuje pewność z progiem	bool	—	Udokumentowana brama dla kierowania do ręcznej weryfikacji
StructureAnalysis	konstruktor: $pageCount, $imageCount, $fontCount, $hasFormFields, $hasSignatureFields, $imageDensity, $detectedFeatures	Niemutowalny obiekt wartości tworzony przez StructureAnalyzer	—	—	final readonly; imageDensity to liczba obrazów na stronę
DocumentType	enum oparty na string, 12 przypadków	Przypadki: Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other	wartości bazowe invoice … other	—	label() zwraca czytelną dla człowieka nazwę
ClassificationFeature	enum oparty na string, 7 przypadków	Przypadki: HasTables, HasHeaders, HasSignatures, HasLogos, HasBarcodes, HasForms, IsScanned	wartości bazowe has_tables … is_scanned	—	Sygnały strukturalne podawane do klasyfikacji

Sygnatury punktów wejścia

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

Kontrakt zachowania

Kolejność potoku

DocumentClassifier uruchamia analizę struktury, następnie klasyfikację strategii, następnie wykrywanie języka i składa ClassificationResult. Strategia dostarcza typ, pewność, cechy i metadane; detektor dostarcza język. classifyFromText() bez bajtów PDF podstawia pustą strukturę: zero stron, zerowe liczby, brak cech. classifyFromFile() wyprowadza zarówno strukturę, jak i tekst z tych samych surowych bajtów.

Ocenianie heurystyczne

HeuristicClassifier ocenia zamieniony na małe litery tekst względem słowników słów kluczowych dla poszczególnych typów dokumentów, znormalizowanych względem długości tekstu. Konkretne słowniki, wagi i progi to szczegół implementacji i nie są publikowane. Sygnały strukturalne następnie korygują wyniki: pasujące wartości ClassificationFeature podnoszą powiązane z nimi typy; dokumenty powyżej progu liczby stron są odchylane od Letter i Receipt; wielostronicowe dokumenty z nagłówkami i tabelami otrzymują premię Report; wykryta cecha formularza dodaje silny sygnał Form. Najwyższy wynik wygrywa i mapuje się na DocumentType. Ograniczona normalizacja odwzorowuje surowy wynik na zakres [0.0, 1.0]. Wynik poniżej minimum daje DocumentType::Other z małą, niezerową dolną granicą pewności. metadata wyniku niesie mapę scores dla poszczególnych typów oraz method: heuristic. Sam HeuristicClassifier raportuje język en; DocumentClassifier nadpisuje go wynikiem detektora.

Wykrywanie języka

Sprawdzenie zakresu pisma dla tekstu CJK działa przed ocenianiem trigramów. Dominacja hangul wybiera ko; jakakolwiek kana wybiera ja; w przeciwnym razie wystarczający udział ideogramów wybiera zh. Cały pozostały tekst jest oceniany według częstości trigramów znakowych względem dziesięciu wbudowanych profili. Możliwe wartości zwracane to kody ISO 639-1 en, zh, ja, ko, de, fr, es, pt, it oraz nl. Tekst poniżej minimalnej długości zwraca en z pewnością 0.0. Wynik poniżej progu akceptacji z wąskim marginesem również zwraca en. Pewność odzwierciedla margines między najlepszym a drugim najlepszym wynikiem profilu.

Odzyskiwanie tekstu z pliku

classifyFromFile() skanuje surowe bajty w poszukiwaniu segmentów stream/endstream. Każdy segment jest próbowany jako dane Flate w ramach ograniczonego pułapu inflacji; przy niepowodzeniu używane są surowe bajty segmentu. Gdy sąsiadujący słownik strumienia deklaruje predyktor PNG w /DecodeParms, odwrócenie honoruje parametry Predictor, Columns, Colors oraz BitsPerComponent zgodnie z ISO 32000-2:2020 §7.4.4.4, korzystając z klas DecodeParms i PngPredictor modułu Filter. Tekst jest następnie odzyskiwany z operatorów pokazywania tekstu z §9.4: literałów łańcuchowych pokazywanych za pomocą Tj oraz literałów łańcuchowych wewnątrz tablic TJ. Klasyfikator ocenia odzyskany tekst; nie zależy od układu wizualnego.

Analiza struktury

StructureAnalyzer::analyze() liczy tokeny stron, obrazów i czcionek w surowych bajtach, wykrywa /AcroForm oraz pola podpisów i wyprowadza gęstość obrazów. Wykrywanie cech jest heurystyczne: powtarzające się rysowanie prostokątów sugeruje tabele, deklaracje dużego rozmiaru czcionki sugerują nagłówki, a wysoka gęstość obrazów przy niewielu czcionkach sugeruje dokument skanowany. Liczby odzwierciedlają tokeny widoczne w surowych bajtach; struktury serializowane wewnątrz skompresowanych strumieni obiektów nie są liczone.

Determinizm

Cały potok jest czystą funkcją swoich bajtów wejściowych. Identyczne wejście daje identyczny ClassificationResult. Nie ma wnioskowania modelu, losowości, wywołań sieciowych ani dostępu do systemu plików.

Przypadki brzegowe i tryby awarii

• Pusty lub niemal pusty tekst z założenia daje DocumentType::Other o niskiej pewności. Rozgałęziaj na isConfident(), a nie na samym typie.
• Żadna publiczna metoda tego modułu nie zgłasza wyjątków. Strumienie, których dekompresja się nie powiedzie, są skanowane w postaci surowej; nieprawidłowe lub nieobsługiwane parametry predyktora wracają do niefiltrowanych bajtów.
• Odzyskiwanie tekstu dopasowuje tylko formy literałów łańcuchowych Tj i TJ. Ciągi szesnastkowe, tekst wewnątrz zaszyfrowanej zawartości oraz operatory podzielone między strumienie nie są odzyskiwane, co zmniejsza ilość tekstu dostępnego do oceniania.
• Pułap dekompresji ogranicza pamięć podczas inflacji strumienia i opiera się wejściu typu bomba dekompresyjna. Zawartość poza pułapem nie jest poddawana inflacji.
• Pliki PDF zawierające wyłącznie obrazy lub silnie skompresowane odzyskują mało tekstu; spodziewaj się wyników o niskiej pewności i kieruj je do ręcznej weryfikacji.
• Wykrywanie języka poniżej minimalnej długości tekstu zwraca en z pewnością 0.0; bardzo krótkie łańcuchy nigdy nie dają wyniku innego niż angielski.
• Dwanaście typów dokumentów i dziesięć profili językowych jest stałych dla tego wydania. Rozszerzenie odbywa się przez niestandardową implementację ClassifierInterface, a nie przez edycję wbudowanych danych.
• W tym module nie zachodzi żadna operacja kryptograficzna, więc nie ma zachowania specyficznego dla trybu FIPS.

Zgodność

Twierdzenie	Standard	Klauzula
Klasyfikacja pliku odzyskuje tekst pokazany operatorem Tj.	ISO 32000-2:2020	§9.4
Klasyfikacja pliku odzyskuje literały łańcuchowe wewnątrz operatorów tablicowych TJ.	ISO 32000-2:2020	§9.4
Odwrócenie predyktora PNG honoruje parametry filtra Predictor, Columns, Colors i BitsPerComponent.	ISO 32000-2:2020	§7.4.4.4

Kody języków są zgodne z ISO 639-1; jest to oparte na produkcie stwierdzenie o formacie wyjściowym, a nie cytowane twierdzenie o zgodności. Wszystkie klauzule są parafrazowane; NextPDF nie reprodukuje tekstu normatywnego. To są stwierdzenia o możliwościach, nie certyfikaty. NextPDF nie posiada żadnego certyfikatu i żadnego nie udziela. Klasyfikacja jest heurystyczna i realizowana z najlepszą starannością: moduł zapewnia determinizm, a nie dokładność, a wywołujący są właścicielami progu decyzji.

Uwagi programistyczne

• Dostępne od nextpdf/pro 2.2.0; aktualne w nextpdf/pro 3.1.0.
• Użyj DocumentClassifier::create() dla domyślnego potoku. Wstrzykuj współpracowników tylko po to, by dostarczyć niestandardową strategię ClassifierInterface.
• Traktuj wyniki poniżej progu jako niepewne i kieruj je do ręcznej weryfikacji; isConfident() z domyślnym 0.7 to udokumentowana brama.
• Moduł niczego nie przechowuje, nie emituje telemetrii i nie loguje wejścia. Jeśli wywołujący utrwalają metadata, najpierw sprawdźcie je względem własnej polityki przetwarzania danych.
• Ocenianie słów kluczowych i zliczanie trigramów jest liniowe względem długości tekstu. Analiza struktury jest liniowa względem długości PDF w bajtach w ramach ograniczonego pułapu dekompresji. Budżet strony to 1000 ms czasu zegarowego i 64 MB szczytowego zużycia pamięci.

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 i prefiksy zgłoszeń są poza zakresem.

Zobacz także

• Classifier (funkcja) — instalacja, szybki start i przykłady kierowania produkcyjnego.
• Extraction — pełna dokumentacja referencyjna — pełna powierzchnia ekstrakcji tekstu dla bogatszego tekstu wejściowego.
• Filter — pełna dokumentacja referencyjna — DecodeParms i PngPredictor, używane podczas klasyfikacji pliku.
• Diff — pełna dokumentacja referencyjna — pokrewna powierzchnia porównywania dokumentów na poziomie bajtów.