Classifier — Referensi Mendalam

Sekilas pandang

Halaman ini adalah referensi tingkat kontrak untuk classifier dokumen NextPDF Pro. Permukaannya adalah satu orchestrator, NextPDF\Pro\Classifier\DocumentClassifier, beserta kolaboratornya: StructureAnalyzer, LanguageDetector, dan strategi ClassifierInterface dengan HeuristicClassifier bawaannya. Hasil datang sebagai objek ClassificationResult yang immutable yang membawa DocumentType, confidence dalam [0.0, 1.0], nilai ClassificationFeature yang terdeteksi, dan kode bahasa ISO 639-1. Klasifikasi berbasis aturan dan deterministik: tanpa inferensi model, tanpa keacakan, tanpa panggilan jaringan, tanpa akses filesystem. Halaman ini menyatakan API publik, kontrak perilaku yang teramati, dan mode kegagalan.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Pro (nextpdf/pro) dan diaktifkan dengan envelope lisensi tier Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada flag kapabilitas runtime yang menggerbangi modul ini. Kelas-kelas classifier tersedia kapan pun nextpdf/pro terpasang.

Permukaan API publik

Simbol	Parameter	Perilaku bawaan	Mengembalikan	Melempar atau gagal dengan	Catatan
DocumentClassifier	constructor: StructureAnalyzer, LanguageDetector, ClassifierInterface	Mengorkestrasi analisis struktur, klasifikasi strategi, dan deteksi bahasa	—	—	final; injeksi kolaborator hanya untuk strategi kustom
DocumentClassifier::create()	tidak ada	Membangun kolaborator bawaan dengan HeuristicClassifier sebagai strateginya	self	—	Konfigurasi bawaan yang deterministik
DocumentClassifier::classifyFromText()	$text, $pdfData = ''	$pdfData kosong menggunakan struktur kosong; byte mentah non-kosong menambah sinyal struktural	ClassificationResult	Tidak melempar; input yang sparse menurunkan confidence	Deteksi bahasa selalu berjalan pada $text
DocumentClassifier::classifyFromFile()	string $pdfData	Memindai content stream, memulihkan teks §9.4, menganalisis struktur, mengklasifikasi	ClassificationResult	Tidak melempar; stream yang tidak terbaca mengurangi teks yang dipulihkan	Pemindaian byte terbatas, bukan parse PDF penuh
ClassifierInterface::classify()	$text, StructureAnalysis $structure	Kontrak strategi yang dikonsumsi oleh orchestrator	ClassificationResult	Ditentukan oleh implementasi	Titik ekstensi untuk strategi klasifikasi kustom
ClassifierInterface::supports()	string $contentType	Probe content-type untuk classifier komposit	bool	—	Menerima MIME type atau deskriptor konten
HeuristicClassifier	tidak ada	Strategi bawaan: kamus keyword ditambah heuristik struktural	—	Tidak melempar	final; supports() menerima application/pdf dan text/plain
StructureAnalyzer::analyze()	string $pdfData	Pemindaian regex atas byte mentah; tanpa parse PDF penuh	StructureAnalysis	Tidak melempar	Menghitung halaman, gambar, font; mendeteksi field form dan signature
LanguageDetector::detect()	string $text	Pencocokan profil trigram dengan pra-pemeriksaan rentang skrip CJK	kode ISO 639-1 non-empty-string	Tidak melempar	Jatuh kembali ke en di bawah ambang penerimaan
LanguageDetector::detectWithConfidence()	string $text	Seperti detect(), dengan confidence yang diekspos	array{language: non-empty-string, confidence: float}	Tidak melempar	Teks pendek mengembalikan en dengan confidence 0.0
ClassificationResult	constructor: $type, $confidence, $features, $language, $metadata = []	Objek nilai yang immutable	—	—	final readonly; metadata membawa scores dan method
ClassificationResult::isConfident()	float $threshold = 0.7	Membandingkan confidence terhadap ambang	bool	—	Gerbang terdokumentasi untuk perutean tinjauan manual
StructureAnalysis	constructor: $pageCount, $imageCount, $fontCount, $hasFormFields, $hasSignatureFields, $imageDensity, $detectedFeatures	Objek nilai immutable yang dihasilkan oleh StructureAnalyzer	—	—	final readonly; imageDensity adalah gambar per halaman
DocumentType	enum berbasis string, 12 case	Case: Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other	nilai backing invoice … other	—	label() mengembalikan nama yang dapat dibaca manusia
ClassificationFeature	enum berbasis string, 7 case	Case: HasTables, HasHeaders, HasSignatures, HasLogos, HasBarcodes, HasForms, IsScanned	nilai backing has_tables … is_scanned	—	Sinyal struktural yang diumpankan ke klasifikasi

Tanda tangan entry-point

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

Kontrak perilaku

Urutan pipeline

DocumentClassifier menjalankan analisis struktur, lalu klasifikasi strategi, lalu deteksi bahasa, dan merakit sebuah ClassificationResult. Strategi memasok tipe, confidence, features, dan metadata; detektor memasok bahasa. classifyFromText() tanpa byte PDF menggantikan dengan struktur kosong: nol halaman, nol hitungan, tanpa features. classifyFromFile() menurunkan baik struktur maupun teks dari byte mentah yang sama.

Penilaian heuristik

HeuristicClassifier menilai teks yang telah dijadikan huruf kecil terhadap kamus keyword per-tipe-dokumen, dinormalisasi berdasarkan panjang teks. Kamus, bobot, dan ambang spesifik adalah detail implementasi dan tidak dipublikasikan. Sinyal struktural kemudian menyesuaikan skor: nilai ClassificationFeature yang cocok mendorong tipe yang terkait dengannya; dokumen di atas ambang halaman condong menjauh dari Letter dan Receipt; dokumen multi-halaman dengan header dan tabel menerima dorongan Report; feature form yang terdeteksi menambah sinyal Form yang kuat. Skor tertinggi menang dan dipetakan ke sebuah DocumentType. Normalisasi terbatas memetakan skor mentah ke [0.0, 1.0]. Skor di bawah minimum menghasilkan DocumentType::Other dengan lantai confidence non-nol yang kecil. metadata hasil membawa peta scores per-tipe dan method: heuristic. HeuristicClassifier sendiri melaporkan bahasa en; DocumentClassifier menimpanya dengan keluaran detektor.

Deteksi bahasa

Pemeriksaan rentang skrip untuk teks CJK berjalan sebelum penilaian trigram. Dominasi Hangul memilih ko; kana apa pun memilih ja; jika tidak, rasio ideograph yang cukup memilih zh. Semua teks lain dinilai berdasarkan frekuensi trigram karakter terhadap sepuluh profil bawaan. Nilai kembalian yang mungkin adalah kode ISO 639-1 en, zh, ja, ko, de, fr, es, pt, it, dan nl. Teks di bawah panjang minimum mengembalikan en dengan confidence 0.0. Hasil di bawah ambang penerimaan dengan margin sempit juga mengembalikan en. Confidence mencerminkan margin antara skor profil terbaik dan terbaik kedua.

Pemulihan teks file

classifyFromFile() memindai byte mentah untuk segmen stream/endstream. Setiap segmen dicoba sebagai data Flate di bawah batas inflasi terbatas; pada kegagalan, byte segmen mentah digunakan. Ketika kamus stream yang berdekatan mendeklarasikan PNG predictor di /DecodeParms, pembalikan menghormati parameter Predictor, Columns, Colors, dan BitsPerComponent sesuai ISO 32000-2:2020 §7.4.4.4, menggunakan kelas DecodeParms dan PngPredictor dari modul Filter. Teks kemudian dipulihkan dari operator penampil teks §9.4: string literal yang ditampilkan dengan Tj dan string literal di dalam array TJ. Classifier menilai teks yang dipulihkan; ia tidak bergantung pada tata letak visual.

Analisis struktur

StructureAnalyzer::analyze() menghitung token halaman, gambar, dan font dalam byte mentah, mendeteksi /AcroForm dan field signature, serta menurunkan densitas gambar. Deteksi feature bersifat heuristik: penggambaran rectangle berulang mengindikasikan tabel, deklarasi ukuran font besar mengindikasikan header, dan densitas gambar tinggi dengan sedikit font mengindikasikan dokumen hasil pindai. Hitungan mencerminkan token yang terlihat dalam byte mentah; struktur yang diserialkan di dalam compressed object stream tidak dihitung.

Determinisme

Seluruh pipeline adalah fungsi murni dari byte inputnya. Input yang identik menghasilkan ClassificationResult yang identik. Tidak ada inferensi model, tidak ada keacakan, tidak ada panggilan jaringan, dan tidak ada akses filesystem.

Kasus tepi & mode kegagalan

• Teks kosong atau nyaris kosong menghasilkan DocumentType::Other dengan confidence rendah secara desain. Bercabanglah pada isConfident() alih-alih pada tipe saja.
• Tidak ada metode publik dari modul ini yang melempar. Stream yang gagal didekompresi dipindai secara mentah; parameter predictor yang malformed atau tidak didukung jatuh kembali ke byte yang tidak difilter.
• Pemulihan teks hanya mencocokkan bentuk string literal Tj dan TJ. String heksadesimal, teks di dalam konten terenkripsi, dan operator yang terpecah antar-stream tidak dipulihkan, yang mengurangi teks yang tersedia untuk dinilai.
• Batas dekompresi membatasi memori selama inflasi stream dan menahan input decompression-bomb. Konten di luar batas tidak diinflasi.
• PDF yang hanya berisi gambar atau yang terkompresi berat memulihkan sedikit teks; harapkan hasil confidence rendah dan rutekan ke tinjauan manual.
• Deteksi bahasa di bawah panjang teks minimum mengembalikan en dengan confidence 0.0; string yang sangat pendek tidak pernah menghasilkan hasil non-Inggris.
• Dua belas tipe dokumen dan sepuluh profil bahasa bersifat tetap untuk rilis ini. Ekstensi dilakukan melalui implementasi ClassifierInterface kustom, bukan dengan menyunting data bawaan.
• Tidak ada operasi kriptografis yang terjadi dalam modul ini, sehingga tidak ada perilaku khusus mode FIPS.

Konformansi

Klaim	Standar	Klausa
Klasifikasi file memulihkan teks yang ditampilkan dengan operator Tj.	ISO 32000-2:2020	§9.4
Klasifikasi file memulihkan string literal di dalam operator array TJ.	ISO 32000-2:2020	§9.4
Pembalikan PNG-predictor menghormati parameter filter Predictor, Columns, Colors, dan BitsPerComponent.	ISO 32000-2:2020	§7.4.4.4

Kode bahasa mengikuti ISO 639-1; ini adalah pernyataan format keluaran yang berbasis produk, bukan klaim konformansi yang dikutip. Semua klausa diparafrasekan; NextPDF tidak mereproduksi teks normatif. Ini adalah pernyataan kapabilitas, bukan sertifikasi. NextPDF tidak memegang sertifikasi apa pun dan tidak memberikan apa pun. Klasifikasi bersifat heuristik dan best-effort: modul menegaskan determinisme, bukan akurasi, dan pemanggil memiliki ambang keputusannya sendiri.

Catatan pengembangan

• Tersedia sejak nextpdf/pro 2.2.0; berlaku saat ini di nextpdf/pro 3.1.0.
• Gunakan DocumentClassifier::create() untuk pipeline bawaan. Injeksi kolaborator hanya untuk memasok strategi ClassifierInterface kustom.
• Perlakukan hasil di bawah ambang sebagai tidak pasti dan rutekan ke tinjauan manual; isConfident() dengan bawaan 0.7-nya adalah gerbang yang terdokumentasi.
• Modul tidak menyimpan apa pun, tidak memancarkan telemetri, dan tidak mencatat input. Jika pemanggil mempersistenkan metadata, tinjau terlebih dahulu terhadap kebijakan penanganan data mereka sendiri.
• Penilaian keyword dan penghitungan trigram bersifat linier terhadap panjang teks. Analisis struktur bersifat linier terhadap panjang byte PDF di bawah batas dekompresi terbatas. Anggaran halaman adalah 1000 ms wall time dan 64 MB memori puncak.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang teramati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas pembantu, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Classifier (kapabilitas) — pemasangan, mulai cepat, dan sampel perutean produksi.
• Extraction — Referensi Mendalam — permukaan ekstraksi teks lengkap untuk teks input yang lebih kaya.
• Filter — Referensi Mendalam — DecodeParms dan PngPredictor, digunakan selama klasifikasi file.
• Diff — Referensi Mendalam — permukaan pembandingan dokumen tingkat byte yang bersaudara.