Classifier

速覽

NextPDF\Pro\Classifier 會以對文件文字與結構的決定性啟發法，指派一個文件類型（發票、合約、報告等等）與一個偵測到的語言。它以規則為基礎，而非機器學習模型。

可用性與授權

此能力隨 NextPDF Pro（nextpdf/pro）提供，並以 Pro 層級授權封套啟用。未持有該授權的部署不會載入此能力的類別。比較各版本並取得授權。

沒有任何執行階段能力旗標閘控此模組。只要安裝了 nextpdf/pro，Classifier 類別即可使用。

安裝

composer require nextpdf/pro:^3

概念總覽

DocumentClassifier 協調三個協作者：

• StructureAnalyzer 會檢視 PDF 的頁數、影像與字型數量，以及表單/簽章欄位，產生一個 StructureAnalysis。
• HeuristicClassifier（預設的 ClassifierInterface）會依各類型的關鍵字字典為文字評分，並套用結構啟發法（例如，短文件會偏離「報告」），產出一個 DocumentType 與一個信賴度。
• LanguageDetector 會以十種語言的字元三連音（trigram）頻率分佈來辨識語言，在低於信賴度門檻時回退到英文。

classifyFromText() 接受已抽取的文字（並可選擇性附帶原始 PDF 位元組以判定結構）；classifyFromFile() 接受原始 PDF 位元組，並透過直接剖析 §9.4 文字顯示運算子來抽取文字。

為何這樣設計

其中承重的決策，是以決定性啟發法而非機器學習模型進行分類。以規則為基礎的管線是其輸入的純函數：相同的位元組永遠產出相同的類型、信賴度與語言，沒有模型漂移，也沒有網路呼叫。這樣的決定性讓結果得以揭露一個明確的信賴度、一個 isConfident() 閘門，以及一個依類型分列的 scores 對應表，因此本模組會展示它如何做出判斷，而非把選擇藏在模型背後。呼叫端因而能依合約將低信賴度文件路由至人工審查，而過短、無法評分的文字則在同一條固定規則下回退為 en。這是刻意的取捨：準確度受限於固定的關鍵字與三連音分佈，以換取可重現性、可檢視性，以及一個完全在行程內執行的分類器。

設計背景：一個拒絕臆測的 API。

行為合約

• 輸入。 已抽取的文字（classifyFromText）或原始 PDF 位元組（classifyFromFile）。空輸入是有效的，會產生低信賴度結果，通常是 DocumentType::Other。
• 輸出。 一個 ClassificationResult，內含 DocumentType、一個位於 [0.0, 1.0] 的信賴度、偵測到的結構特徵、一個 ISO 639-1 語言代碼，以及中繼資料。isConfident(0.7) 是已記載的門檻輔助方法。
• 決定性。 分類與語言偵測都是輸入的純函數 —— 相同輸入、相同結果，無隨機性，無網路。
• 範圍。 十二種文件類型與十種語言分佈，兩者在此版本中皆為固定。可透過 ClassifierInterface 提供自訂策略。

公開 API 介面

型別	種類	主要成員
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 cases (Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other); label(): string

程式碼範例 —— 快速上手

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

程式碼範例 —— 正式環境

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

邊界案例與陷阱

• 信賴度是啟發式的。請將低於門檻的結果視為「不確定」，並如正式環境範例所示，路由到人工審查。
• 語言偵測需要足夠的文字；極短的字串依設計會回退到英文。
• classifyFromFile() 使用有界限的位元組層級文字抽取；高度壓縮或僅含影像的 PDF 會減少可供評分的文字。
• 文件類型與語言集合在此版本中為固定；請以實作 ClassifierInterface 的方式擴充分類，而非變動內建字典。

資料落地與 PII 緩解措施

分類在行程內執行，沒有網路呼叫，也不儲存輸入。結果包含一個 DocumentType 與語言代碼，而非原始文字。若呼叫端要保存 metadata，請在儲存前檢視其中是否夾帶偶發性的 PII。

安全遙測與日誌清洗

本模組不發出任何遙測，也不記錄任何輸入。新增日誌的呼叫端應只記錄產生的 DocumentType 與語言代碼，絕不記錄被分類的文字。

效能

關鍵字評分與三連音計數與文字長度呈線性關係。結構分析與 PDF 位元組長度呈線性關係，並設有解壓縮上限。請參閱 performance_budget。

安全注意事項

classifyFromFile() 以有界限的掃描與解壓縮大小上限剖析不受信任的 PDF 位元組，以抵禦解壓縮炸彈輸入。不會執行任何嵌入的指令稿。

一致性

聲明	規範條款	狀態
為檔案分類而透過 Tj 復原文字	ISO 32000-2:2020 §9.4	已驗證（單元測試套件）
為檔案分類而透過 TJ 復原文字	ISO 32000-2:2020 §9.4	已驗證（單元測試套件）
機器學習/以模型為基礎的分類	—	不支援（僅啟發式）

Core 回退/替代方案

文件分類或語言偵測沒有任何 Core 對應方案。

Enterprise 邊界註記

此分類器以規則為基礎且具決定性。它不執行任何嵌入（embedding）、向量相似度、模型推論或語意理解。那些能力不屬於本模組的一部分，本模組也不暗示它們。

發布邊界

本頁僅描述外部可觀察的行為，以及支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、維運手冊檔名與工單前綴皆不在範圍內。

另請參閱

• Classifier — Deep Reference —— 完整的公開 API 介面、管線順序與失敗模式。
• Extraction
• Filter
• Diff