Classifier — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF Pro belge sınıflandırıcısı için sözleşme düzeyinde başvurudur. Yüzey, tek bir orkestratörden — NextPDF\Pro\Classifier\DocumentClassifier — ve işbirlikçilerinden oluşur: StructureAnalyzer, LanguageDetector ve varsayılan HeuristicClassifier’ı olan ClassifierInterface stratejisi. Sonuçlar; bir DocumentType, [0.0, 1.0] aralığında bir güven değeri, algılanan ClassificationFeature değerleri ve bir ISO 639-1 dil kodu taşıyan, değiştirilemez bir ClassificationResult olarak gelir. Sınıflandırma kural tabanlı ve belirleyicidir: model çıkarımı yok, rastgelelik yok, ağ çağrısı yok, dosya sistemi erişimi yok. Bu sayfa herkese açık API’yi, gözlemlenebilir davranış sözleşmesini ve başarısızlık modlarını belirtir.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile gelir ve bir Pro katmanı lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Bu modülü hiçbir çalışma zamanı yetenek bayrağı kapamaz. Sınıflandırıcı sınıfları, nextpdf/pro yüklü olduğunda kullanılabilir.

Herkese açık API yüzeyi

Sembol	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
DocumentClassifier	kurucu: StructureAnalyzer, LanguageDetector, ClassifierInterface	Yapı analizini, strateji sınıflandırmasını ve dil algılamayı orkestre eder	—	—	final; işbirlikçileri yalnızca özel stratejiler için enjekte edin
DocumentClassifier::create()	yok	Strateji olarak HeuristicClassifier ile varsayılan işbirlikçileri oluşturur	self	—	Belirleyici varsayılan yapılandırma
DocumentClassifier::classifyFromText()	$text, $pdfData = ''	Boş $pdfData boş bir yapı kullanır; boş olmayan ham baytlar yapısal sinyaller ekler	ClassificationResult	Fırlatmaz; seyrek girdi güveni düşürür	Dil algılama her zaman $text üzerinde çalışır
DocumentClassifier::classifyFromFile()	string $pdfData	İçerik akışlarını tarar, §9.4 metnini kurtarır, yapıyı analiz eder, sınıflandırır	ClassificationResult	Fırlatmaz; okunamayan akışlar kurtarılan metni azaltır	Sınırlı bayt taraması, tam bir PDF ayrıştırması değil
ClassifierInterface::classify()	$text, StructureAnalysis $structure	Orkestratör tarafından tüketilen strateji sözleşmesi	ClassificationResult	Uygulama tanımlı	Özel sınıflandırma stratejileri için genişletme noktası
ClassifierInterface::supports()	string $contentType	Bileşik sınıflandırıcılar için içerik türü sondası	bool	—	Bir MIME türü veya içerik tanımlayıcısı alır
HeuristicClassifier	yok	Varsayılan strateji: anahtar sözcük sözlükleri artı yapısal sezgiseller	—	Fırlatmaz	final; supports(), application/pdf ve text/plain kabul eder
StructureAnalyzer::analyze()	string $pdfData	Ham baytların regex taraması; tam PDF ayrıştırması yok	StructureAnalysis	Fırlatmaz	Sayfaları, görüntüleri, yazı tiplerini sayar; form ve imza alanlarını algılar
LanguageDetector::detect()	string $text	CJK betik aralığı ön kontrolüyle trigram profili eşleşmesi	non-empty-string ISO 639-1 kodu	Fırlatmaz	Kabul eşiğinin altında en’e geri döner
LanguageDetector::detectWithConfidence()	string $text	detect() gibi, ancak güven değeri açığa çıkarılır	array{language: non-empty-string, confidence: float}	Fırlatmaz	Kısa metin, 0.0 güveniyle en döndürür
ClassificationResult	kurucu: $type, $confidence, $features, $language, $metadata = []	Değiştirilemez değer nesnesi	—	—	final readonly; metadata, scores ve method taşır
ClassificationResult::isConfident()	float $threshold = 0.7	Güveni eşiğe karşı karşılaştırır	bool	—	Manuel inceleme yönlendirmesi için belgelenmiş kapı
StructureAnalysis	kurucu: $pageCount, $imageCount, $fontCount, $hasFormFields, $hasSignatureFields, $imageDensity, $detectedFeatures	StructureAnalyzer tarafından üretilen değiştirilemez değer nesnesi	—	—	final readonly; imageDensity, sayfa başına görüntü sayısıdır
DocumentType	dize destekli enum, 12 durum	Durumlar: Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other	destek değerleri invoice … other	—	label(), insan tarafından okunabilir bir ad döndürür
ClassificationFeature	dize destekli enum, 7 durum	Durumlar: HasTables, HasHeaders, HasSignatures, HasLogos, HasBarcodes, HasForms, IsScanned	destek değerleri has_tables … is_scanned	—	Sınıflandırmaya beslenen yapısal sinyaller

Giriş noktası imzaları

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

Davranış sözleşmesi

İşlem hattı sırası

DocumentClassifier, yapı analizini, ardından strateji sınıflandırmasını, ardından dil algılamayı çalıştırır ve bir ClassificationResult oluşturur. Strateji; türü, güveni, öznitelikleri ve meta veriyi sağlar; algılayıcı ise dili sağlar. PDF baytı olmayan classifyFromText(), boş bir yapı ikame eder: sıfır sayfa, sıfır sayım, öznitelik yok. classifyFromFile(), hem yapıyı hem de metni aynı ham baytlardan türetir.

Sezgisel puanlama

HeuristicClassifier, küçük harfe çevrilmiş metni, metin uzunluğuna göre normalleştirerek belge türü başına anahtar sözcük sözlüklerine karşı puanlar. Belirli sözlükler, ağırlıklar ve eşikler uygulama ayrıntısıdır ve yayımlanmaz. Ardından yapısal sinyaller puanları ayarlar: eşleşen ClassificationFeature değerleri, ilişkili türlerini artırır; bir sayfa eşiğinin üzerindeki belgeler Letter ve Receipt’ten uzaklaşmaya eğilim gösterir; başlıkları ve tabloları olan çok sayfalı belgeler bir Report artışı alır; algılanan bir form özniteliği güçlü bir Form sinyali ekler. En yüksek puan kazanır ve bir DocumentType’a eşlenir. Sınırlı bir normalleştirme, ham puanı [0.0, 1.0] aralığına eşler. Asgari altı bir puan, küçük ve sıfırdan farklı bir güven tabanıyla DocumentType::Other verir. Sonuç metadata’sı, tür başına scores haritasını ve method: heuristic taşır. HeuristicClassifier tek başına en dilini bildirir; DocumentClassifier, bunu algılayıcı çıktısıyla geçersiz kılar.

Dil algılama

Trigram puanlamasından önce CJK metni için bir betik aralığı kontrolü çalışır. Hangul baskınlığı ko’yu seçer; herhangi bir kana ja’yı seçer; aksi takdirde yeterli bir ideogram oranı zh’yi seçer. Diğer tüm metin, on yerleşik profile karşı karakter-trigram sıklığıyla puanlanır. Olası dönüş değerleri; en, zh, ja, ko, de, fr, es, pt, it ve nl ISO 639-1 kodlarıdır. Asgari uzunluğun altındaki metin, 0.0 güveniyle en döndürür. Dar bir farkla kabul eşiğinin altında kalan bir sonuç da en döndürür. Güven, en iyi ve ikinci en iyi profil puanları arasındaki farkı yansıtır.

Dosya metni kurtarma

classifyFromFile(), ham baytları stream/endstream segmentleri için tarar. Her segment, sınırlı bir şişirme tavanı altında Flate verisi olarak denenir; başarısızlık durumunda ham segment baytları kullanılır. Bitişik akış sözlüğü /DecodeParms içinde bir PNG tahmin edicisi bildirdiğinde, tersine çevirme; Filter modülünün DecodeParms ve PngPredictor sınıflarını kullanarak ISO 32000-2:2020 §7.4.4.4 uyarınca Predictor, Columns, Colors ve BitsPerComponent parametrelerine uyar. Metin daha sonra §9.4 metin gösterme operatörlerinden kurtarılır: Tj ile gösterilen değişmez dizeler ve TJ dizileri içindeki değişmez dizeler. Sınıflandırıcı, kurtarılan metni puanlar; görsel yerleşime bağlı değildir.

Yapı analizi

StructureAnalyzer::analyze(), ham baytlardaki sayfa, görüntü ve yazı tipi belirteçlerini sayar, /AcroForm ve imza alanlarını algılar ve görüntü yoğunluğunu türetir. Öznitelik algılama sezgiseldir: tekrar eden dikdörtgen çizimi tabloları düşündürür, büyük yazı tipi boyutu bildirimleri başlıkları düşündürür ve az yazı tipiyle yüksek görüntü yoğunluğu taranmış bir belgeyi düşündürür. Sayımlar, ham baytlarda görünen belirteçleri yansıtır; sıkıştırılmış nesne akışları içinde serileştirilmiş yapılar sayılmaz.

Belirlilik

İşlem hattının tamamı, girdi baytlarının saf bir fonksiyonudur. Özdeş girdi, özdeş bir ClassificationResult üretir. Model çıkarımı, rastgelelik, ağ çağrısı ve dosya sistemi erişimi yoktur.

Uç durumlar ve başarısızlık modları

• Boş veya neredeyse boş metin, tasarım gereği düşük güvenli bir DocumentType::Other verir. Yalnızca türe göre değil, isConfident() üzerinde dallanın.
• Bu modülün hiçbir herkese açık yöntemi fırlatmaz. Açma işlemi başarısız olan akışlar ham olarak taranır; hatalı biçimlendirilmiş veya desteklenmeyen tahmin edici parametreleri, süzülmemiş baytlara geri döner.
• Metin kurtarma yalnızca değişmez dize Tj ve TJ biçimlerini eşler. Onaltılık dizeler, şifrelenmiş içerik içindeki metin ve akışlar arasında bölünmüş operatörler kurtarılmaz; bu da puanlanacak mevcut metni azaltır.
• Açma tavanı, akış şişirmesi sırasında belleği sınırlar ve açma bombası girdisine direnir. Tavanın ötesindeki içerik şişirilmez.
• Yalnızca görüntü içeren veya yoğun sıkıştırılmış PDF’ler az metin kurtarır; düşük güvenli sonuçlar bekleyin ve bunları manuel incelemeye yönlendirin.
• Asgari metin uzunluğunun altındaki dil algılama, 0.0 güveniyle en döndürür; çok kısa dizeler asla İngilizce dışında bir sonuç üretmez.
• On iki belge türü ve on dil profili, bu sürüm için sabittir. Genişletme, yerleşik veriyi düzenleyerek değil, özel bir ClassifierInterface uygulaması aracılığıyla yapılır.
• Bu modülde hiçbir kriptografik işlem gerçekleşmez; bu nedenle FIPS moduna özgü hiçbir davranış yoktur.

Uygunluk

İddia	Standart	Madde
Dosya sınıflandırma, Tj operatörüyle gösterilen metni kurtarır.	ISO 32000-2:2020	§9.4
Dosya sınıflandırma, TJ dizi operatörleri içindeki değişmez dizeleri kurtarır.	ISO 32000-2:2020	§9.4
PNG tahmin edici tersine çevirme, Predictor, Columns, Colors ve BitsPerComponent süzgeç parametrelerine uyar.	ISO 32000-2:2020	§7.4.4.4

Dil kodları ISO 639-1’i izler; bu, alıntılanan bir uygunluk iddiası değil, çıktı biçiminin ürün temelli bir ifadesidir. Tüm maddeler başka sözcüklerle ifade edilmiştir; NextPDF, normatif metni yeniden üretmez. Bunlar yetenek ifadeleridir, sertifikalar değildir. NextPDF hiçbir sertifikaya sahip değildir ve hiçbirini vermez. Sınıflandırma sezgisel ve en iyi çabaya dayalıdır: modül doğruluğu değil belirliliği öne sürer ve karar eşiği çağıranların sorumluluğundadır.

Geliştirme notları

• nextpdf/pro 2.2.0’dan beri kullanılabilir; nextpdf/pro 3.1.0’da güncel.
• Varsayılan işlem hattı için DocumentClassifier::create() kullanın. İşbirlikçileri yalnızca özel bir ClassifierInterface stratejisi sağlamak için enjekte edin.
• Eşik altı sonuçları belirsiz olarak ele alın ve bunları manuel incelemeye yönlendirin; 0.7 varsayılanıyla isConfident(), belgelenmiş kapıdır.
• Modül hiçbir şey saklamaz, hiçbir telemetri yaymaz ve hiçbir girdiyi günlüğe kaydetmez. Çağıranlar metadata’yı kalıcılaştırırsa, önce bunu kendi veri işleme politikalarına karşı gözden geçirin.
• Anahtar sözcük puanlaması ve trigram sayımı, metin uzunluğunda doğrusaldır. Yapı analizi, sınırlı açma tavanı altında PDF bayt uzunluğunda doğrusaldır. Sayfa bütçesi, 1000 ms duvar saati ve 64 MB tepe bellektir.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen herkese açık API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, çalışma kılavuzu dosya adları ve talep önekleri kapsam dışıdır.

Ayrıca bkz.

• Classifier (yetenek) — kurulum, hızlı başlangıç ve üretim yönlendirme örnekleri.
• Extraction — Derinlemesine başvuru — daha zengin girdi metni için tam metin çıkarma yüzeyi.
• Filter — Derinlemesine başvuru — dosya sınıflandırma sırasında kullanılan DecodeParms ve PngPredictor.
• Diff — Derinlemesine başvuru — kardeş bayt düzeyinde belge karşılaştırma yüzeyi.