Classifier

Tổng quan nhanh

NextPDF\Pro\Classifier gán một loại tài liệu (hóa đơn, hợp đồng, báo cáo, v.v.) và một ngôn ngữ được phát hiện bằng các heuristic tất định trên văn bản và cấu trúc của tài liệu. Đây là phương pháp dựa trên quy tắc, không phải một mô hình học máy.

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

Năng lực này có trong NextPDF Pro (nextpdf/pro) và kích hoạt bằng một license envelope hạng Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và nhận 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 có sẵn bất cứ khi nào nextpdf/pro được cài đặt.

Cài đặt

composer require nextpdf/pro:^3

Tổng quan khái niệm

DocumentClassifier điều phối ba thành phần cộng tác:

• StructureAnalyzer soi xét PDF để biết số trang, số lượng hình ảnh và phông chữ, cùng các trường biểu mẫu/chữ ký, tạo ra một StructureAnalysis.
• HeuristicClassifier (mặc định của ClassifierInterface) chấm điểm văn bản dựa trên các từ điển từ khóa theo từng loại và áp dụng các heuristic về cấu trúc (ví dụ, tài liệu ngắn thì thiên về xa “báo cáo”), cho ra một DocumentType và một độ tin cậy.
• LanguageDetector nhận diện ngôn ngữ từ các hồ sơ tần suất character- trigram cho mười ngôn ngữ, lùi về tiếng Anh khi dưới một ngưỡng tin cậy.

classifyFromText() nhận văn bản đã trích xuất sẵn (kèm các byte PDF thô tùy chọn để phân tích cấu trúc); classifyFromFile() nhận các byte PDF thô và trích xuất văn bản bằng cách phân tích trực tiếp các toán tử hiển thị văn bản ở §9.4.

Vì sao nó hoạt động theo cách này

Quyết định trọng yếu là phân loại bằng các heuristic tất định, không phải một mô hình học máy. Một pipeline dựa trên quy tắc là một hàm thuần túy của đầu vào: các byte giống hệt nhau luôn cho ra cùng một loại, độ tin cậy và ngôn ngữ, không có model drift và không có lời gọi mạng. Tính tất định đó cho phép kết quả phơi bày một độ tin cậy tường minh, một cổng isConfident() và một map scores theo từng loại, để module cho thấy nó đã quyết định như thế nào thay vì che giấu lựa chọn sau một mô hình. Do đó, theo hợp đồng, bên gọi định tuyến các tài liệu có độ tin cậy thấp tới rà soát thủ công, và văn bản quá ngắn để chấm điểm sẽ lùi về en theo cùng một quy tắc cố định. Sự đánh đổi là có chủ đích: độ chính xác bị giới hạn bởi các hồ sơ từ khóa và trigram cố định, đổi lại là khả năng tái lập, khả năng kiểm tra, và một bộ phân loại chạy hoàn toàn trong tiến trình.

Bối cảnh thiết kế: Một API từ chối đoán.

Hợp đồng hành vi

• Đầu vào. Văn bản đã trích xuất (classifyFromText) hoặc các byte PDF thô (classifyFromFile). Đầu vào rỗng là hợp lệ và cho ra một kết quả có độ tin cậy thấp, thường là DocumentType::Other.
• Đầu ra. Một ClassificationResult với DocumentType, một độ tin cậy trong [0.0, 1.0], các đặc trưng cấu trúc được phát hiện, một mã ngôn ngữ ISO 639-1 và metadata. isConfident(0.7) là trợ giúp ngưỡng đã được ghi tài liệu.
• Tính tất định. Phân loại và phát hiện ngôn ngữ là các hàm thuần túy của đầu vào — cùng đầu vào, cùng kết quả, không ngẫu nhiên, không mạng.
• Phạm vi. Mười hai loại tài liệu và mười hồ sơ ngôn ngữ, cả hai đều cố định trong bản phát hành này. Bạn có thể cung cấp các chiến lược tùy chỉnh qua ClassifierInterface.

Bề mặt API công khai

Kiểu	Loại	Thành viên chính
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 trường hợp (Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other); label(): string

Mẫu mã — Khởi đầu nhanh

<?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,
);

Mẫu mã — Production

<?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',
    };
}

Trường hợp biên & lưu ý

• Độ tin cậy mang tính heuristic. Hãy xem các kết quả dưới ngưỡng là “không chắc chắn” và định tuyến tới rà soát thủ công, như mẫu production làm.
• Phát hiện ngôn ngữ cần đủ văn bản; các chuỗi rất ngắn sẽ lùi về tiếng Anh theo thiết kế.
• classifyFromFile() dùng trích xuất văn bản ở mức byte có giới hạn; các PDF nén nặng hoặc chỉ-hình-ảnh làm giảm lượng văn bản có sẵn để chấm điểm.
• Tập loại tài liệu và ngôn ngữ là cố định trong bản phát hành này; hãy mở rộng việc phân loại bằng cách triển khai ClassifierInterface, chứ không phải bằng cách thay đổi các từ điển tích hợp sẵn.

Lưu trú dữ liệu & giảm thiểu PII

Việc phân loại chạy trong tiến trình, không có lời gọi mạng và không lưu trữ đầu vào. Kết quả bao gồm một DocumentType và mã ngôn ngữ, không phải văn bản nguồn. Nếu bên gọi lưu lại metadata, hãy rà soát nó để tìm PII vô tình trước khi lưu trữ.

Telemetry an toàn & làm sạch log

Module không phát ra telemetry và không ghi log đầu vào. Bên gọi khi thêm việc ghi log chỉ nên ghi lại DocumentType và mã ngôn ngữ kết quả, không bao giờ ghi văn bản đã phân loại.

Hiệu năng

Chấm điểm từ khóa và đếm trigram là tuyến tính theo độ dài văn bản. Phân tích cấu trúc là tuyến tính theo độ dài byte của PDF với một mức giới hạn giải nén. Xem performance_budget.

Ghi chú bảo mật

classifyFromFile() phân tích các byte PDF không tin cậy với quét có giới hạn và một mức trần kích thước giải nén để chống lại đầu vào dạng bom giải nén. Không có script nhúng nào được thực thi.

Sự phù hợp tiêu chuẩn

Tuyên bố	Điều khoản tiêu chuẩn	Trạng thái
Văn bản được khôi phục qua Tj để phân loại tệp	ISO 32000-2:2020 §9.4	Đã xác minh (bộ kiểm thử đơn vị)
Văn bản được khôi phục qua TJ để phân loại tệp	ISO 32000-2:2020 §9.4	Đã xác minh (bộ kiểm thử đơn vị)
Phân loại bằng học máy / dựa trên mô hình	—	Không hỗ trợ (chỉ heuristic)

Phương án dự phòng / thay thế trong Core

Không có tương đương trong Core cho việc phân loại tài liệu hay phát hiện ngôn ngữ.

Ghi chú ranh giới Enterprise

Bộ phân loại này dựa trên quy tắc và tất định. Nó không thực hiện embedding, tương đồng vector, suy luận mô hình hay hiểu ngữ nghĩa. Những năng lực đó không thuộc về module này và không được ngụ ý bởi nó.

Ranh giới công bố

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

Xem thêm

• Classifier — Tham chiếu chuyên sâu — toàn bộ bề mặt API công khai, thứ tự pipeline và các chế độ lỗi.
• Extraction
• Filter
• Diff