Classifier — การอ้างอิงเชิงลึก

ภาพรวมโดยสังเขป

หน้านี้เป็นเอกสารอ้างอิงระดับสัญญาสำหรับ document classifier ของ NextPDF Pro พื้นผิวประกอบด้วย orchestrator หนึ่งตัวคือ NextPDF\Pro\Classifier\DocumentClassifier และผู้ทำงานร่วมของมันได้แก่ StructureAnalyzer, LanguageDetector และกลยุทธ์ ClassifierInterface พร้อมค่าเริ่มต้น HeuristicClassifier ผลลัพธ์จะมาในรูปของ ClassificationResult ที่ไม่เปลี่ยนแปลงได้ ซึ่งบรรจุ DocumentType, ค่าความเชื่อมั่นในช่วง [0.0, 1.0], ค่า ClassificationFeature ที่ตรวจพบ และรหัสภาษา ISO 639-1 การจำแนกอิงกฎและเป็นแบบกำหนดผลแน่นอน คือไม่มีการอนุมานของโมเดล ไม่มีความสุ่ม ไม่มีการเรียกเครือข่าย และไม่มีการเข้าถึงระบบไฟล์ หน้านี้ระบุ public API, สัญญาพฤติกรรมที่สังเกตได้ และโหมดความล้มเหลว

ความพร้อมใช้งานและการอนุญาต

ความสามารถนี้มาพร้อมกับ NextPDF Pro (nextpdf/pro) และเปิดใช้งานด้วย license envelope ระดับ Pro การติดตั้งที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและขอรับใบอนุญาต

ไม่มีแฟล็กความสามารถในขณะรันไทม์มาเกตโมดูลนี้ คลาส classifier พร้อมใช้งานเมื่อใดก็ตามที่ติดตั้ง nextpdf/pro แล้ว

พื้นผิว public API

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
DocumentClassifier	ตัวสร้าง: StructureAnalyzer, LanguageDetector, ClassifierInterface	ประสานการวิเคราะห์โครงสร้าง การจำแนกด้วยกลยุทธ์ และการตรวจจับภาษา	—	—	final; แทรกผู้ทำงานร่วมเฉพาะเพื่อกลยุทธ์แบบกำหนดเอง
DocumentClassifier::create()	ไม่มี	สร้างผู้ทำงานร่วมเริ่มต้นโดยใช้ HeuristicClassifier เป็นกลยุทธ์	self	—	การกำหนดค่าเริ่มต้นแบบกำหนดผลแน่นอน
DocumentClassifier::classifyFromText()	$text, $pdfData = ''	$pdfData ที่ว่างใช้โครงสร้างว่าง raw bytes ที่ไม่ว่างเพิ่มสัญญาณเชิงโครงสร้าง	ClassificationResult	ไม่โยนข้อผิดพลาด อินพุตที่เบาบางลดความเชื่อมั่น	การตรวจจับภาษาทำงานบน $text เสมอ
DocumentClassifier::classifyFromFile()	string $pdfData	สแกน content stream กู้คืนข้อความ §9.4 วิเคราะห์โครงสร้าง แล้วจำแนก	ClassificationResult	ไม่โยนข้อผิดพลาด stream ที่อ่านไม่ได้ลดข้อความที่กู้คืน	การสแกนไบต์แบบมีขอบเขต ไม่ใช่การแจง PDF เต็มรูปแบบ
ClassifierInterface::classify()	$text, StructureAnalysis $structure	สัญญากลยุทธ์ที่ orchestrator เรียกใช้	ClassificationResult	กำหนดโดยการนำไปใช้	จุดขยายสำหรับกลยุทธ์การจำแนกแบบกำหนดเอง
ClassifierInterface::supports()	string $contentType	การตรวจสอบ content-type สำหรับ classifier แบบผสม	bool	—	รับ MIME type หรือ content descriptor
HeuristicClassifier	ไม่มี	กลยุทธ์เริ่มต้น: พจนานุกรมคำสำคัญร่วมกับฮิวริสติกเชิงโครงสร้าง	—	ไม่โยนข้อผิดพลาด	final; supports() รับ application/pdf และ text/plain
StructureAnalyzer::analyze()	string $pdfData	สแกน raw bytes ด้วย regex ไม่แจง PDF เต็มรูปแบบ	StructureAnalysis	ไม่โยนข้อผิดพลาด	นับหน้า ภาพ ฟอนต์ ตรวจจับฟิลด์ฟอร์มและลายเซ็น
LanguageDetector::detect()	string $text	จับคู่โปรไฟล์ trigram พร้อมการตรวจช่วงสคริปต์ CJK ล่วงหน้า	รหัส ISO 639-1 แบบ non-empty-string	ไม่โยนข้อผิดพลาด	ถอยกลับไปเป็น en เมื่อต่ำกว่าเกณฑ์การยอมรับ
LanguageDetector::detectWithConfidence()	string $text	เช่นเดียวกับ detect() แต่เปิดเผยค่าความเชื่อมั่น	array{language: non-empty-string, confidence: float}	ไม่โยนข้อผิดพลาด	ข้อความสั้นคืนค่า en ด้วยความเชื่อมั่น 0.0
ClassificationResult	ตัวสร้าง: $type, $confidence, $features, $language, $metadata = []	value object ที่ไม่เปลี่ยนแปลงได้	—	—	final readonly; metadata บรรจุ scores และ method
ClassificationResult::isConfident()	float $threshold = 0.7	เปรียบเทียบความเชื่อมั่นกับเกณฑ์	bool	—	เกตที่มีเอกสารกำกับสำหรับกำหนดเส้นทางการตรวจทานด้วยมือ
StructureAnalysis	ตัวสร้าง: $pageCount, $imageCount, $fontCount, $hasFormFields, $hasSignatureFields, $imageDensity, $detectedFeatures	value object ที่ไม่เปลี่ยนแปลงได้ซึ่งสร้างโดย StructureAnalyzer	—	—	final readonly; imageDensity คือจำนวนภาพต่อหน้า
DocumentType	enum ที่หนุนด้วย string, 12 เคส	เคส: Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other	ค่าหนุน invoice … other	—	label() คืนชื่อที่มนุษย์อ่านได้
ClassificationFeature	enum ที่หนุนด้วย string, 7 เคส	เคส: HasTables, HasHeaders, HasSignatures, HasLogos, HasBarcodes, HasForms, IsScanned	ค่าหนุน has_tables … is_scanned	—	สัญญาณเชิงโครงสร้างที่ป้อนเข้าสู่การจำแนก

ลายเซ็นจุดเข้าใช้งาน

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

สัญญาพฤติกรรม

ลำดับไปป์ไลน์

DocumentClassifier รันการวิเคราะห์โครงสร้าง จากนั้นการจำแนกด้วยกลยุทธ์ จากนั้นการตรวจจับภาษา แล้วประกอบ ClassificationResult กลยุทธ์เป็นผู้จัดหาชนิด ความเชื่อมั่น ฟีเจอร์ และ metadata ส่วนตัวตรวจจับเป็นผู้จัดหาภาษา classifyFromText() ที่ไม่มีไบต์ PDF จะแทนที่ด้วยโครงสร้างว่าง คือศูนย์หน้า ศูนย์จำนวนนับ ไม่มีฟีเจอร์ classifyFromFile() ได้มาทั้งโครงสร้างและข้อความจาก raw bytes ชุดเดียวกัน

การให้คะแนนแบบฮิวริสติก

HeuristicClassifier ให้คะแนนข้อความที่แปลงเป็นตัวพิมพ์เล็กเทียบกับพจนานุกรมคำสำคัญต่อชนิดเอกสาร โดยปรับให้เป็นมาตรฐานตามความยาวข้อความ พจนานุกรม น้ำหนัก และเกณฑ์เฉพาะเป็นรายละเอียดการนำไปใช้และไม่ได้เผยแพร่ จากนั้นสัญญาณเชิงโครงสร้างจะปรับคะแนน คือค่า ClassificationFeature ที่ตรงกันจะเพิ่มคะแนนให้ชนิดที่เกี่ยวข้อง เอกสารที่เกินเกณฑ์จำนวนหน้าจะเอนออกจาก Letter และ Receipt เอกสารหลายหน้าที่มีหัวเรื่องและตารางจะได้รับการเพิ่มคะแนน Report และฟีเจอร์ฟอร์มที่ตรวจพบจะเพิ่มสัญญาณ Form ที่หนักแน่น คะแนนสูงสุดเป็นผู้ชนะและแมปไปยัง DocumentType การปรับให้เป็นมาตรฐานแบบมีขอบเขตแมปคะแนนดิบไปยัง [0.0, 1.0] คะแนนที่ต่ำกว่าขั้นต่ำให้ผล DocumentType::Other พร้อมพื้นความเชื่อมั่นที่ไม่เป็นศูนย์เล็กน้อย metadata ของผลลัพธ์บรรจุแมป scores ต่อชนิดและ method: heuristic HeuristicClassifier เพียงลำพังรายงานภาษา en ส่วน DocumentClassifier เขียนทับด้วยเอาต์พุตของตัวตรวจจับ

การตรวจจับภาษา

การตรวจช่วงสคริปต์สำหรับข้อความ CJK ทำงานก่อนการให้คะแนน trigram ความเด่นของ Hangul จะเลือก ko คานะใด ๆ จะเลือก ja มิฉะนั้นอัตราส่วนอักษรภาพที่เพียงพอจะเลือก zh ข้อความอื่นทั้งหมดจะให้คะแนนด้วยความถี่ character-trigram เทียบกับสิบโปรไฟล์ในตัว ค่าที่คืนได้คือรหัส ISO 639-1 ได้แก่ en, zh, ja, ko, de, fr, es, pt, it และ nl ข้อความที่ต่ำกว่าความยาวขั้นต่ำจะคืนค่า en ด้วยความเชื่อมั่น 0.0 ผลลัพธ์ที่ต่ำกว่าเกณฑ์การยอมรับด้วยส่วนต่างที่แคบก็จะคืนค่า en เช่นกัน ความเชื่อมั่นสะท้อนส่วนต่างระหว่างคะแนนโปรไฟล์ที่ดีที่สุดและดีที่สุดอันดับสอง

การกู้คืนข้อความจากไฟล์

classifyFromFile() สแกน raw bytes หาเซกเมนต์ stream/endstream แต่ละเซกเมนต์จะถูกลองเป็นข้อมูล Flate ภายใต้เพดาน inflation ที่จำกัด เมื่อล้มเหลวจะใช้ไบต์ดิบของเซกเมนต์ เมื่อ stream dictionary ที่อยู่ติดกันประกาศ PNG predictor ใน /DecodeParms การย้อนกลับจะเคารพพารามิเตอร์ Predictor, Columns, Colors และ BitsPerComponent ตาม ISO 32000-2:2020 §7.4.4.4 โดยใช้คลาส DecodeParms และ PngPredictor ของโมดูล Filter จากนั้นข้อความจะถูกกู้คืนจาก operator การแสดงข้อความ §9.4 คือสตริงตัวอักษรที่แสดงด้วย Tj และสตริงตัวอักษรภายในอาเรย์ TJ classifier ให้คะแนนข้อความที่กู้คืน ไม่ได้ขึ้นอยู่กับเค้าโครงเชิงภาพ

การวิเคราะห์โครงสร้าง

StructureAnalyzer::analyze() นับโทเคนของหน้า ภาพ และฟอนต์ใน raw bytes ตรวจจับ /AcroForm และฟิลด์ลายเซ็น และหาความหนาแน่นของภาพ การตรวจจับฟีเจอร์เป็นแบบฮิวริสติก คือการวาดสี่เหลี่ยมซ้ำ ๆ บ่งชี้ตาราง การประกาศขนาดฟอนต์ใหญ่บ่งชี้หัวเรื่อง และความหนาแน่นของภาพสูงพร้อมฟอนต์น้อยบ่งชี้เอกสารที่สแกนมา จำนวนนับสะท้อนโทเคนที่มองเห็นได้ใน raw bytes โครงสร้างที่ทำให้เป็นอนุกรมภายใน compressed object stream จะไม่ถูกนับ

ความเป็นแบบกำหนดผลแน่นอน

ไปป์ไลน์ทั้งหมดเป็นฟังก์ชันบริสุทธิ์ของไบต์อินพุต อินพุตที่เหมือนกันให้ ClassificationResult ที่เหมือนกัน ไม่มีการอนุมานของโมเดล ไม่มีความสุ่ม ไม่มีการเรียกเครือข่าย และไม่มีการเข้าถึงระบบไฟล์

กรณีขอบและโหมดความล้มเหลว

• ข้อความที่ว่างเปล่าหรือเกือบว่างเปล่าให้ผล DocumentType::Other ที่ความเชื่อมั่นต่ำโดยการออกแบบ ควรแยกสาขาบน isConfident() แทนที่จะพึ่งเฉพาะชนิด
• ไม่มีเมธอดสาธารณะของโมดูลนี้ที่โยนข้อผิดพลาด stream ที่คลายการบีบอัดล้มเหลวจะถูกสแกนแบบดิบ พารามิเตอร์ predictor ที่ผิดรูปหรือไม่รองรับจะถอยกลับไปใช้ไบต์ที่ไม่ผ่านตัวกรอง
• การกู้คืนข้อความจับคู่เฉพาะรูปแบบสตริงตัวอักษร Tj และ TJ เท่านั้น สตริงฐานสิบหก ข้อความภายในเนื้อหาที่เข้ารหัส และ operator ที่ถูกแบ่งข้าม stream จะไม่ถูกกู้คืน ซึ่งลดข้อความที่มีให้ให้คะแนน
• เพดานการคลายการบีบอัดจำกัดหน่วยความจำระหว่าง inflation ของ stream และต้านทานอินพุตแบบ decompression-bomb เนื้อหาที่เกินเพดานจะไม่ถูก inflate
• PDF ที่มีแต่ภาพหรือถูกบีบอัดอย่างหนักจะกู้คืนข้อความได้น้อย คาดว่าจะได้ผลลัพธ์ที่ความเชื่อมั่นต่ำและควรกำหนดเส้นทางไปยังการตรวจทานด้วยมือ
• การตรวจจับภาษาที่ต่ำกว่าความยาวข้อความขั้นต่ำจะคืนค่า en ด้วยความเชื่อมั่น 0.0 สตริงที่สั้นมากจะไม่ให้ผลลัพธ์ที่ไม่ใช่ภาษาอังกฤษเลย
• ชนิดเอกสารสิบสองชนิดและโปรไฟล์ภาษาสิบโปรไฟล์ตายตัวสำหรับรุ่นนี้ การขยายทำผ่านการนำ ClassifierInterface ไปใช้แบบกำหนดเอง ไม่ใช่โดยการแก้ไขข้อมูลในตัว
• ไม่มีการดำเนินการเข้ารหัสลับในโมดูลนี้ จึงไม่มีพฤติกรรมเฉพาะโหมด FIPS

การเป็นไปตามข้อกำหนด

ข้อกล่าวอ้าง	มาตรฐาน	ข้อ
การจำแนกไฟล์กู้คืนข้อความที่แสดงด้วย operator Tj	ISO 32000-2:2020	§9.4
การจำแนกไฟล์กู้คืนสตริงตัวอักษรภายใน operator อาเรย์ TJ	ISO 32000-2:2020	§9.4
การย้อนกลับ PNG-predictor เคารพพารามิเตอร์ตัวกรอง Predictor, Columns, Colors และ BitsPerComponent	ISO 32000-2:2020	§7.4.4.4

รหัสภาษาเป็นไปตาม ISO 639-1 นี่เป็นการระบุรูปแบบเอาต์พุตที่อิงตัวผลิตภัณฑ์ ไม่ใช่ข้อกล่าวอ้างการเป็นไปตามข้อกำหนดที่มีการอ้างอิง ทุกข้อกำหนดเป็นการถอดความ NextPDF ไม่ได้ทำซ้ำข้อความเชิงบรรทัดฐาน สิ่งเหล่านี้เป็นการระบุความสามารถ ไม่ใช่การรับรอง NextPDF ไม่ถือการรับรองใด ๆ และไม่มอบการรับรองใด ๆ การจำแนกเป็นแบบฮิวริสติกและใช้ความพยายามอย่างดีที่สุด คือโมดูลยืนยันความเป็นแบบกำหนดผลแน่นอน ไม่ใช่ความแม่นยำ และผู้เรียกใช้เป็นเจ้าของเกณฑ์การตัดสินใจ

บันทึกการพัฒนา

• พร้อมใช้งานตั้งแต่ nextpdf/pro 2.2.0 ปัจจุบันอยู่ที่ nextpdf/pro 3.1.0
• ใช้ DocumentClassifier::create() สำหรับไปป์ไลน์เริ่มต้น แทรกผู้ทำงานร่วมเฉพาะเพื่อจัดหากลยุทธ์ ClassifierInterface แบบกำหนดเอง
• ถือว่าผลลัพธ์ที่ต่ำกว่าเกณฑ์เป็นสิ่งไม่แน่นอนและกำหนดเส้นทางไปยังการตรวจทานด้วยมือ isConfident() พร้อมค่าเริ่มต้น 0.7 คือเกตที่มีเอกสารกำกับ
• โมดูลไม่จัดเก็บอะไร ไม่ส่ง telemetry และไม่บันทึกอินพุต หากผู้เรียกใช้เก็บ metadata ไว้ ควรตรวจทานเทียบกับนโยบายการจัดการข้อมูลของตนเองก่อน
• การให้คะแนนคำสำคัญและการนับ trigram เป็นเชิงเส้นตามความยาวข้อความ การวิเคราะห์โครงสร้างเป็นเชิงเส้นตามความยาวไบต์ PDF ภายใต้เพดานการคลายการบีบอัดที่มีขอบเขต งบประมาณของหน้าคือเวลา wall 1000 ms และหน่วยความจำสูงสุด 64 MB

ขอบเขตการเผยแพร่

หน้านี้จัดทำเอกสารเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว public API ที่รองรับเท่านั้น พาธ namespace ภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้าตั๋วอยู่นอกขอบเขต

ดูเพิ่มเติม

• Classifier (ความสามารถ) — การติดตั้ง การเริ่มต้นอย่างรวดเร็ว และตัวอย่างการกำหนดเส้นทางในการใช้งานจริง
• Extraction — การอ้างอิงเชิงลึก — พื้นผิวการสกัดข้อความเต็มรูปแบบสำหรับข้อความอินพุตที่สมบูรณ์ยิ่งขึ้น
• Filter — การอ้างอิงเชิงลึก — DecodeParms และ PngPredictor ที่ใช้ระหว่างการจำแนกไฟล์
• Diff — การอ้างอิงเชิงลึก — พื้นผิวการเปรียบเทียบเอกสารระดับไบต์ซึ่งเป็นพี่น้องกัน