Klasyfikator

W skrócie

NextPDF\Pro\Classifier przypisuje typ dokumentu (faktura, umowa, raport i tak dalej) oraz wykryty język za pomocą deterministycznych heurystyk nad tekstem i strukturą dokumentu. Działa w oparciu o reguły, a nie o model uczenia maszynowego.

Dostępność i licencjonowanie

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

Żadna flaga możliwości w czasie wykonywania nie bramkuje tego modułu. Klasy Classifier są dostępne zawsze, gdy zainstalowano nextpdf/pro.

Instalacja

composer require nextpdf/pro:^3

Przegląd koncepcyjny

DocumentClassifier koordynuje trzech współpracowników:

• StructureAnalyzer sprawdza w pliku PDF liczbę stron, liczbę obrazów i czcionek oraz pola formularzy/podpisów, wytwarzając StructureAnalysis.
• HeuristicClassifier (domyślny ClassifierInterface) ocenia tekst względem słowników słów kluczowych dla poszczególnych typów i stosuje heurystyki strukturalne (na przykład krótkie dokumenty oddalają od typu „report”), wytwarzając DocumentType oraz poziom pewności.
• LanguageDetector identyfikuje język na podstawie profili częstotliwości trigramów znaków dla dziesięciu języków, wycofując się do angielskiego poniżej progu pewności.

classifyFromText() przyjmuje już wyodrębniony tekst (z opcjonalnymi surowymi bajtami PDF na potrzeby struktury); classifyFromFile() przyjmuje surowe bajty PDF i wyodrębnia tekst, parsując bezpośrednio operatory pokazywania tekstu z §9.4.

Dlaczego działa w ten sposób

Nośna decyzja to klasyfikowanie za pomocą deterministycznych heurystyk, a nie modelu uczenia maszynowego. Potok oparty na regułach jest czystą funkcją swojego wejścia: identyczne bajty zawsze dają identyczny typ, poziom pewności i język, bez dryfu modelu i bez wywołania sieciowego. Ten determinizm pozwala wynikowi ujawnić jawny poziom pewności, bramkę isConfident() oraz mapę scores dla poszczególnych typów, dzięki czemu moduł pokazuje, jak zadecydował, zamiast ukrywać wybór za modelem. Wywołujący kierują zatem dokumenty o niskiej pewności do ręcznego przeglądu zgodnie z kontraktem, a tekst zbyt krótki, by go ocenić, wycofuje się do en według tej samej stałej reguły. Kompromis jest zamierzony: dokładność jest ograniczona przez stałe profile słów kluczowych i trigramów w zamian za odtwarzalność, możliwość inspekcji oraz klasyfikator działający w całości w procesie.

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

Kontrakt zachowania

• Wejście. Wyodrębniony tekst (classifyFromText) lub surowe bajty PDF (classifyFromFile). Puste wejście jest prawidłowe i daje wynik o niskiej pewności, zwykle DocumentType::Other.
• Wyjście. ClassificationResult z DocumentType, poziomem pewności w [0.0, 1.0], wykrytymi cechami strukturalnymi, kodem języka ISO 639-1 oraz metadanymi. isConfident(0.7) to udokumentowany pomocnik progu.
• Determinizm. Klasyfikacja i wykrywanie języka są czystymi funkcjami wejścia — to samo wejście, ten sam wynik, bez losowości, bez sieci.
• Zakres. Dwanaście typów dokumentów i dziesięć profili językowych, oba ustalone w tym wydaniu. Niestandardowe strategie można dostarczyć przez ClassifierInterface.

Publiczna powierzchnia API

Typ	Rodzaj	Kluczowe składowe
NextPDF\Pro\Classifier\DocumentClassifier	final class	static create(): self, classifyFromText(string $text, string $pdfData = ''): ClassificationResult, classifyFromFile(string $pdfData): ClassificationResult
NextPDF\Pro\Classifier\ClassifierInterface	interface	classify(string $text, StructureAnalysis $structure): ClassificationResult, supports(string $contentType): bool
NextPDF\Pro\Classifier\HeuristicClassifier	final class	implements ClassifierInterface
NextPDF\Pro\Classifier\StructureAnalyzer	final class	analyze(string $pdfData): StructureAnalysis
NextPDF\Pro\Classifier\LanguageDetector	final class	detect(string $text): string
NextPDF\Pro\Classifier\ClassificationResult	final readonly class	DocumentType $type, float $confidence, array $features, string $language, isConfident(float $threshold = 0.7): bool
NextPDF\Pro\Classifier\DocumentType	enum	12 cases (Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other); label(): string

Przykład kodu — Szybki start

<?php

declare(strict_types=1);

use NextPDF\Pro\Classifier\DocumentClassifier;

$result = DocumentClassifier::create()
    ->classifyFromText('Invoice #4471 — Amount due: $1,200.00');

printf(
    "%s (%.0f%% confidence), lang=%s\n",
    $result->type->label(),
    $result->confidence * 100,
    $result->language,
);

Przykład kodu — Produkcja

<?php

declare(strict_types=1);

use NextPDF\Pro\Classifier\DocumentClassifier;
use NextPDF\Pro\Classifier\DocumentType;

function routeDocument(string $pdfBytes): string
{
    $result = DocumentClassifier::create()->classifyFromFile($pdfBytes);

    if (! $result->isConfident(0.7)) {
        return 'manual-review';
    }

    return match ($result->type) {
        DocumentType::Invoice, DocumentType::Receipt => 'accounts-payable',
        DocumentType::Contract, DocumentType::Legal   => 'legal-intake',
        default                                       => 'general-inbox',
    };
}

Przypadki brzegowe i pułapki

• Pewność jest heurystyczna. Traktuj wyniki poniżej progu jako „niepewne” i kieruj do ręcznego przeglądu, jak robi to przykład produkcyjny.
• Wykrywanie języka wymaga wystarczającej ilości tekstu; bardzo krótkie ciągi z założenia wycofują się do angielskiego.
• classifyFromFile() używa ograniczonej ekstrakcji tekstu na poziomie bajtów; silnie skompresowane lub wyłącznie obrazowe pliki PDF zmniejszają ilość tekstu dostępnego do oceny.
• Zestawy typów dokumentów i języków są ustalone w tym wydaniu; rozszerzaj klasyfikację, implementując ClassifierInterface, a nie modyfikując wbudowane słowniki.

Lokalizacja danych i ograniczanie PII

Klasyfikacja przebiega w procesie, bez wywołań sieciowych i bez przechowywania wejścia. Wynik zawiera DocumentType oraz kod języka, a nie tekst źródłowy. Jeśli wywołujący utrwalają metadata, przejrzyj je pod kątem przypadkowych PII przed zapisaniem.

Bezpieczna telemetria i oczyszczanie logów

Moduł nie emituje żadnej telemetrii i nie loguje wejścia. Wywołujący dodający logowanie powinni zapisywać wyłącznie wynikowy DocumentType oraz kod języka, nigdy klasyfikowanego tekstu.

Wydajność

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 bajtów PDF z ograniczonym limitem dekompresji. Zobacz performance_budget.

Uwagi dotyczące bezpieczeństwa

classifyFromFile() parsuje niezaufane bajty PDF z ograniczonym skanowaniem oraz limitem rozmiaru dekompresji, aby odeprzeć wejście typu bomba dekompresyjna. Żadne osadzone skrypty nie są wykonywane.

Konformancja

Twierdzenie	Klauzula specyfikacji	Status
Tekst odzyskany przez Tj do klasyfikacji pliku	ISO 32000-2:2020 §9.4	Verified (unit suite)
Tekst odzyskany przez TJ do klasyfikacji pliku	ISO 32000-2:2020 §9.4	Verified (unit suite)
Klasyfikacja oparta na uczeniu maszynowym / modelu	—	Not supported (heuristic only)

Rozwiązanie awaryjne / alternatywa w Core

Nie istnieje odpowiednik w Core dla klasyfikacji dokumentów ani wykrywania języka.

Nota o granicy Enterprise

Ten klasyfikator działa w oparciu o reguły i jest deterministyczny. Nie wykonuje osadzania, podobieństwa wektorowego, inferencji modelu ani rozumienia semantycznego. 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 obsługiwaną 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ż

• Klasyfikator — Głęboka referencja — pełna publiczna powierzchnia API, kolejność potoku oraz tryby awarii.
• Extraction
• Filter
• Diff