Classifier — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tài liệu tham chiếu ở cấp hợp đồng cho bộ phân loại tài liệu NextPDF Pro. Bề mặt là một orchestrator, NextPDF\Pro\Classifier\DocumentClassifier, cùng các collaborator của nó: StructureAnalyzer, LanguageDetector, và chiến lược ClassifierInterface với HeuristicClassifier mặc định. Kết quả trả về dưới dạng một ClassificationResult bất biến mang theo một DocumentType, một độ tin cậy trong [0.0, 1.0], các giá trị ClassificationFeature phát hiện được, và một mã ngôn ngữ ISO 639-1. Việc phân loại dựa trên quy tắc và có tính tất định: không suy luận model, không ngẫu nhiên, không gọi mạng, không truy cập hệ thống tệp. Trang này nêu rõ public API, hợp đồng hành vi có thể quan sát, và các chế độ lỗi.

Tính khả dụng & cấp phép

Năng lực này đi kèm trong NextPDF Pro (nextpdf/pro) và kích hoạt với một envelope giấy phép cấp Pro. Một bản triển khai không có quyền đó sẽ không nạp các lớp của năng lực. So sánh các phiên bản và lấy giấy phép.

Không có cờ năng lực lúc chạy nào kiểm soát module này. Các lớp classifier khả dụng bất cứ khi nào nextpdf/pro được cài đặt.

Bề mặt public API

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
DocumentClassifier	hàm dựng: StructureAnalyzer, LanguageDetector, ClassifierInterface	Điều phối phân tích cấu trúc, phân loại theo chiến lược, và phát hiện ngôn ngữ	—	—	final; chỉ tiêm các collaborator cho các chiến lược tùy chỉnh
DocumentClassifier::create()	không có	Dựng các collaborator mặc định với HeuristicClassifier làm chiến lược	self	—	Cấu hình mặc định tất định
DocumentClassifier::classifyFromText()	$text, $pdfData = ''	$pdfData rỗng dùng một cấu trúc rỗng; các byte thô không rỗng thêm tín hiệu cấu trúc	ClassificationResult	Không ném; đầu vào thưa làm giảm độ tin cậy	Phát hiện ngôn ngữ luôn chạy trên $text
DocumentClassifier::classifyFromFile()	string $pdfData	Quét các content stream, khôi phục văn bản §9.4, phân tích cấu trúc, phân loại	ClassificationResult	Không ném; các stream không đọc được làm giảm văn bản khôi phục được	Quét byte có giới hạn, không phải phân tích cú pháp PDF đầy đủ
ClassifierInterface::classify()	$text, StructureAnalysis $structure	Hợp đồng chiến lược được orchestrator tiêu thụ	ClassificationResult	Do hiện thực định nghĩa	Điểm mở rộng cho các chiến lược phân loại tùy chỉnh
ClassifierInterface::supports()	string $contentType	Thăm dò content-type cho các classifier tổ hợp	bool	—	Nhận một kiểu MIME hoặc mô tả nội dung
HeuristicClassifier	không có	Chiến lược mặc định: các từ điển từ khóa cùng các suy nghiệm cấu trúc	—	Không ném	final; supports() chấp nhận application/pdf và text/plain
StructureAnalyzer::analyze()	string $pdfData	Quét regex trên byte thô; không phân tích cú pháp PDF đầy đủ	StructureAnalysis	Không ném	Đếm trang, ảnh, font; phát hiện các trường form và chữ ký
LanguageDetector::detect()	string $text	So khớp hồ sơ trigram với kiểm tra trước phạm vi chữ viết CJK	mã ISO 639-1 non-empty-string	Không ném	Lùi về en khi dưới ngưỡng chấp nhận
LanguageDetector::detectWithConfidence()	string $text	Như detect(), nhưng lộ ra độ tin cậy	array{language: non-empty-string, confidence: float}	Không ném	Văn bản ngắn trả về en với độ tin cậy 0.0
ClassificationResult	hàm dựng: $type, $confidence, $features, $language, $metadata = []	Value object bất biến	—	—	final readonly; metadata mang scores và method
ClassificationResult::isConfident()	float $threshold = 0.7	So sánh độ tin cậy với ngưỡng	bool	—	Cổng được ghi tài liệu để định tuyến rà soát thủ công
StructureAnalysis	hàm dựng: $pageCount, $imageCount, $fontCount, $hasFormFields, $hasSignatureFields, $imageDensity, $detectedFeatures	Value object bất biến do StructureAnalyzer tạo ra	—	—	final readonly; imageDensity là số ảnh trên mỗi trang
DocumentType	enum nền string, 12 case	Các case: Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other	giá trị nền invoice … other	—	label() trả về một tên dễ đọc
ClassificationFeature	enum nền string, 7 case	Các case: HasTables, HasHeaders, HasSignatures, HasLogos, HasBarcodes, HasForms, IsScanned	giá trị nền has_tables … is_scanned	—	Các tín hiệu cấu trúc đưa vào phân loại

Chữ ký điểm vào

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

Hợp đồng hành vi

Thứ tự pipeline

DocumentClassifier chạy phân tích cấu trúc, rồi phân loại theo chiến lược, rồi phát hiện ngôn ngữ, và lắp ráp một ClassificationResult. Chiến lược cung cấp kiểu, độ tin cậy, các đặc trưng, và metadata; bộ phát hiện cung cấp ngôn ngữ. classifyFromText() khi không có byte PDF sẽ thay bằng một cấu trúc rỗng: không trang, không đếm, không đặc trưng. classifyFromFile() suy ra cả cấu trúc lẫn văn bản từ cùng các byte thô.

Chấm điểm suy nghiệm

HeuristicClassifier chấm điểm văn bản đã viết thường theo các từ điển từ khóa theo từng loại tài liệu, chuẩn hóa theo độ dài văn bản. Các từ điển, trọng số, và ngưỡng cụ thể là chi tiết hiện thực và không được công bố. Các tín hiệu cấu trúc sau đó điều chỉnh điểm: các giá trị ClassificationFeature khớp sẽ tăng điểm cho các kiểu liên quan; các tài liệu vượt một ngưỡng số trang thiên lệch ra xa khỏi Letter và Receipt; các tài liệu nhiều trang có tiêu đề và bảng nhận một mức tăng Report; một đặc trưng form phát hiện được thêm một tín hiệu Form mạnh. Điểm cao nhất thắng và ánh xạ tới một DocumentType. Một chuẩn hóa có giới hạn ánh xạ điểm thô vào [0.0, 1.0]. Một điểm dưới mức tối thiểu tạo ra DocumentType::Other với một sàn độ tin cậy nhỏ khác không. metadata của kết quả mang bản đồ scores theo từng kiểu và method: heuristic. Riêng HeuristicClassifier báo cáo ngôn ngữ en; DocumentClassifier ghi đè nó bằng đầu ra của bộ phát hiện.

Phát hiện ngôn ngữ

Một kiểm tra phạm vi chữ viết cho văn bản CJK chạy trước khi chấm điểm trigram. Hangul chiếm ưu thế chọn ko; bất kỳ kana nào chọn ja; nếu không, một tỷ lệ chữ tượng hình đủ lớn chọn zh. Mọi văn bản khác được chấm điểm theo tần suất character-trigram so với mười hồ sơ dựng sẵn. Các giá trị trả về khả dĩ là các mã ISO 639-1 en, zh, ja, ko, de, fr, es, pt, it, và nl. Văn bản dưới một độ dài tối thiểu trả về en với độ tin cậy 0.0. Một kết quả dưới ngưỡng chấp nhận với biên hẹp cũng trả về en. Độ tin cậy phản ánh biên giữa điểm hồ sơ tốt nhất và tốt nhì.

Khôi phục văn bản từ tệp

classifyFromFile() quét các byte thô để tìm các đoạn stream/endstream. Mỗi đoạn được thử như dữ liệu Flate dưới một trần inflation có giới hạn; khi thất bại thì dùng các byte thô của đoạn. Khi từ điển stream liền kề khai báo một PNG predictor trong /DecodeParms, việc đảo ngược tôn trọng các tham số Predictor, Columns, Colors, và BitsPerComponent theo ISO 32000-2:2020 §7.4.4.4, dùng các lớp DecodeParms và PngPredictor của module Filter. Văn bản sau đó được khôi phục từ các toán tử text-showing §9.4: các chuỗi literal hiển thị bằng Tj và các chuỗi literal bên trong các mảng TJ. Bộ classifier chấm điểm văn bản khôi phục được; nó không phụ thuộc vào bố cục trực quan.

Phân tích cấu trúc

StructureAnalyzer::analyze() đếm các token trang, ảnh, và font trong các byte thô, phát hiện các trường /AcroForm và chữ ký, và suy ra mật độ ảnh. Việc phát hiện đặc trưng mang tính suy nghiệm: vẽ hình chữ nhật lặp lại gợi ý các bảng, các khai báo cỡ font lớn gợi ý các tiêu đề, và mật độ ảnh cao với ít font gợi ý một tài liệu được quét. Số đếm phản ánh các token thấy được trong các byte thô; các cấu trúc được tuần tự hóa bên trong các compressed object stream không được đếm.

Tính tất định

Toàn bộ pipeline là một hàm thuần túy của các byte đầu vào. Đầu vào giống hệt tạo ra một ClassificationResult giống hệt. Không có suy luận model, không có ngẫu nhiên, không có lời gọi mạng, và không có truy cập hệ thống tệp.

Trường hợp ngoại lệ & chế độ lỗi

• Văn bản rỗng hoặc gần rỗng tạo ra một DocumentType::Other độ-tin-cậy-thấp theo thiết kế. Hãy rẽ nhánh theo isConfident() thay vì chỉ theo kiểu.
• Không phương thức công khai nào của module này ném. Các stream giải nén thất bại được quét ở dạng thô; các tham số predictor sai định dạng hoặc không được hỗ trợ sẽ lùi về các byte chưa lọc.
• Việc khôi phục văn bản chỉ khớp các dạng chuỗi-literal Tj và TJ. Các chuỗi thập lục phân, văn bản bên trong nội dung mã hóa, và các toán tử bị chia tách qua nhiều stream không được khôi phục, điều này làm giảm văn bản có sẵn để chấm điểm.
• Trần giải nén giới hạn bộ nhớ trong quá trình inflation stream và kháng lại đầu vào decompression-bomb. Nội dung vượt trần không được inflate.
• Các PDF chỉ có ảnh hoặc bị nén nặng khôi phục được ít văn bản; hãy chờ đợi các kết quả độ-tin-cậy-thấp và định tuyến chúng tới rà soát thủ công.
• Phát hiện ngôn ngữ dưới độ dài văn bản tối thiểu trả về en với độ tin cậy 0.0; các chuỗi rất ngắn không bao giờ tạo ra một kết quả không phải tiếng Anh.
• Mười hai loại tài liệu và mười hồ sơ ngôn ngữ là cố định cho bản phát hành này. Việc mở rộng là qua một hiện thực ClassifierInterface tùy chỉnh, không phải bằng cách chỉnh sửa dữ liệu dựng sẵn.
• Không có thao tác mật mã nào xảy ra trong module này, nên không có hành vi riêng cho chế độ FIPS.

Tính phù hợp

Tuyên bố	Tiêu chuẩn	Điều khoản
Phân loại tệp khôi phục văn bản được hiển thị bằng toán tử Tj.	ISO 32000-2:2020	§9.4
Phân loại tệp khôi phục các chuỗi literal bên trong các toán tử mảng TJ.	ISO 32000-2:2020	§9.4
Việc đảo PNG-predictor tôn trọng các tham số filter Predictor, Columns, Colors, và BitsPerComponent.	ISO 32000-2:2020	§7.4.4.4

Các mã ngôn ngữ tuân theo ISO 639-1; đây là một tuyên bố dựa trên sản phẩm về định dạng đầu ra, không phải một tuyên bố phù hợp có trích dẫn. Mọi điều khoản đều được diễn giải lại; NextPDF không tái tạo văn bản quy phạm. Đây là các tuyên bố về năng lực, không phải chứng nhận. NextPDF không nắm giữ chứng nhận nào và không cấp chứng nhận nào. Việc phân loại là suy nghiệm và nỗ lực tối đa: module khẳng định tính tất định, không phải độ chính xác, và các bên gọi tự chịu trách nhiệm về ngưỡng quyết định.

Ghi chú phát triển

• Có sẵn từ nextpdf/pro 2.2.0; hiện hành trong nextpdf/pro 3.1.0.
• Dùng DocumentClassifier::create() cho pipeline mặc định. Chỉ tiêm các collaborator để cung cấp một chiến lược ClassifierInterface tùy chỉnh.
• Coi các kết quả dưới ngưỡng là không chắc chắn và định tuyến chúng tới rà soát thủ công; isConfident() với mặc định 0.7 là cổng được ghi tài liệu.
• Module không lưu trữ gì, không phát telemetry, và không ghi log đầu vào. Nếu các bên gọi lưu bền metadata, hãy rà soát nó theo chính sách xử lý dữ liệu của riêng họ trước.
• Chấm điểm từ khóa và đếm trigram tuyến tính theo độ dài văn bản. Phân tích cấu trúc tuyến tính theo độ dài byte PDF dưới trần giải nén có giới hạn. Ngân sách của trang là 1000 ms thời gian thực và 64 MB bộ nhớ đỉnh.

Ranh giới công bố

Trang này chỉ ghi tài liệu hành vi có thể quan sát từ bên ngoài và bề mặt public API được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp trợ giúp, các bảng cơ chế, các tên tệp runbook, và các tiền tố ticket nằm ngoài phạm vi.

Xem thêm

• Classifier (năng lực) — cài đặt, bắt đầu nhanh, và các mẫu định tuyến sản xuất.
• Extraction — Tài liệu tham chiếu chuyên sâu — bề mặt trích xuất văn bản đầy đủ cho văn bản đầu vào phong phú hơn.
• Filter — Tài liệu tham chiếu chuyên sâu — DecodeParms và PngPredictor, được dùng trong khi phân loại tệp.
• Diff — Tài liệu tham chiếu chuyên sâu — bề mặt so sánh tài liệu ở cấp byte anh em.