Classifier — 深入參考

速覽

本頁是 NextPDF Pro 文件分類器的合約層級參考。其介面是一個協調器 NextPDF\Pro\Classifier\DocumentClassifier，以及它的協作者：StructureAnalyzer、LanguageDetector，還有帶預設 HeuristicClassifier 的 ClassifierInterface 策略。結果會以不可變的 ClassificationResult 送出，其中帶有一個 DocumentType、一個介於 [0.0, 1.0] 的信心值、偵測到的 ClassificationFeature 值，以及一個 ISO 639-1 語言代碼。分類是基於規則且確定性的：沒有模型推論、沒有隨機性、沒有網路呼叫、沒有檔案系統存取。本頁陳述公開 API、可觀察的行為合約，以及失敗模式。

可用性與授權

此能力隨 NextPDF Pro（nextpdf/pro）出貨，並以 Pro 層級的授權信封啟用。缺少該權利的部署不會載入此能力的類別。比較版本並取得授權。

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

公開 API 介面

符號	參數	預設行為	回傳	拋出或失敗於	備註
DocumentClassifier	建構子：StructureAnalyzer、LanguageDetector、ClassifierInterface	協調結構分析、策略分類與語言偵測	—	—	final；僅為自訂策略注入協作者
DocumentClassifier::create()	無	以 HeuristicClassifier 作為策略建立預設協作者	self	—	確定性的預設組態
DocumentClassifier::classifyFromText()	$text、$pdfData = ''	空的 $pdfData 使用空結構；非空的原始位元組會加入結構性訊號	ClassificationResult	不拋出例外；稀疏輸入會降低信心	語言偵測一律對 $text 執行
DocumentClassifier::classifyFromFile()	string $pdfData	掃描內容串流、回復 §9.4 文字、分析結構並分類	ClassificationResult	不拋出例外；無法讀取的串流會減少回復的文字	有界的位元組掃描，而非完整 PDF 剖析
ClassifierInterface::classify()	$text、StructureAnalysis $structure	由協調器使用的策略合約	ClassificationResult	由實作定義	自訂分類策略的擴充點
ClassifierInterface::supports()	string $contentType	用於複合分類器的內容類型探測	bool	—	接收 MIME 類型或內容描述子
HeuristicClassifier	無	預設策略：關鍵字字典加上結構性啟發式	—	不拋出例外	final；supports() 接受 application/pdf 與 text/plain
StructureAnalyzer::analyze()	string $pdfData	對原始位元組進行正規表示式掃描；不做完整 PDF 剖析	StructureAnalysis	不拋出例外	計數頁面、影像、字型；偵測表單與簽章欄位
LanguageDetector::detect()	string $text	三連詞設定檔比對，並帶有 CJK 文字範圍預檢	non-empty-string ISO 639-1 代碼	不拋出例外	低於接受門檻時退回 en
LanguageDetector::detectWithConfidence()	string $text	同 detect()，但公開信心值	array{language: non-empty-string, confidence: float}	不拋出例外	短文字回傳 en，信心為 0.0
ClassificationResult	建構子：$type、$confidence、$features、$language、$metadata = []	不可變值物件	—	—	final readonly；metadata 帶有 scores 與 method
ClassificationResult::isConfident()	float $threshold = 0.7	將信心值與門檻比較	bool	—	用於人工複審路由的公開判準
StructureAnalysis	建構子：$pageCount、$imageCount、$fontCount、$hasFormFields、$hasSignatureFields、$imageDensity、$detectedFeatures	由 StructureAnalyzer 產生的不可變值物件	—	—	final readonly；imageDensity 為每頁影像數
DocumentType	字串支撐列舉，12 個案例	案例：Invoice、Contract、Form、Report、Letter、Receipt、Legal、Medical、Financial、Technical、Academic、Other	支撐值 invoice … other	—	label() 回傳人類可讀的名稱
ClassificationFeature	字串支撐列舉，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。策略提供類型、信心值、特徵與中繼資料；偵測器提供語言。classifyFromText() 在沒有 PDF 位元組時會以空結構替代：零頁面、零計數、無特徵。classifyFromFile() 會從相同的原始位元組推導出結構與文字。

啟發式評分

HeuristicClassifier 會對照各文件類型的關鍵字字典為轉為小寫的文字評分，並依文字長度正規化。具體的字典、權重與門檻屬於實作細節，並不公開。結構性訊號接著會調整分數：相符的 ClassificationFeature 值會提升其關聯類型；超過頁數門檻的文件會偏離 Letter 與 Receipt；帶有標題與表格的多頁文件會獲得 Report 加分；偵測到的表單特徵會加入強烈的 Form 訊號。分數最高者勝出並映射到一個 DocumentType。有界的正規化會將原始分數映射到 [0.0, 1.0]。低於最小值的分數會產生 DocumentType::Other，並帶有一個小的非零信心下限。結果的 metadata 帶有各類型的 scores 對應與 method: heuristic。HeuristicClassifier 單獨使用時回報語言 en；DocumentClassifier 會以偵測器輸出覆寫它。

語言偵測

在三連詞評分之前，會先對 CJK 文字執行文字範圍檢查。諺文佔優會選擇 ko；出現任何假名會選擇 ja；否則足夠的表意文字比例會選擇 zh。其餘所有文字會以字元三連詞頻率對照十個內建設定檔評分。可能的回傳值為 ISO 639-1 代碼 en、zh、ja、ko、de、fr、es、pt、it 與 nl。低於最小長度的文字會回傳 en，信心為 0.0。低於接受門檻且差距狹窄的結果也會回傳 en。信心值反映最佳與次佳設定檔分數之間的差距。

檔案文字回復

classifyFromFile() 會在原始位元組中掃描 stream/endstream 區段。每個區段都會在有界的膨脹上限下嘗試作為 Flate 資料；失敗時則使用原始區段位元組。當相鄰的串流字典在 /DecodeParms 中宣告 PNG predictor 時，反轉會依 ISO 32000-2:2020 §7.4.4.4 遵循 Predictor、Columns、Colors 與 BitsPerComponent 參數，並使用 Filter 模組的 DecodeParms 與 PngPredictor 類別。接著會從 §9.4 文字呈現運算子回復文字：以 Tj 呈現的字面字串，以及 TJ 陣列內的字面字串。分類器會對回復的文字評分；它不依賴視覺版面。

結構分析

StructureAnalyzer::analyze() 會在原始位元組中計數頁面、影像與字型權杖，偵測 /AcroForm 與簽章欄位，並推導出影像密度。特徵偵測是啟發式的：重複的矩形繪製暗示表格，大字級宣告暗示標題，而高影像密度加上少量字型暗示掃描文件。計數反映原始位元組中可見的權杖；序列化在壓縮物件串流內的結構不會被計數。

確定性

整條管線是其輸入位元組的純函式。相同的輸入會產生相同的 ClassificationResult。沒有模型推論、沒有隨機性、沒有網路呼叫，也沒有檔案系統存取。

邊界案例與失敗模式

• 空白或近乎空白的文字依設計會產生一個低信心的 DocumentType::Other。請依 isConfident() 分支，而非僅依類型。
• 此模組沒有任何公開方法會拋出例外。解壓縮失敗的串流會以原始形式掃描；格式錯誤或不支援的 predictor 參數會退回未經篩選的位元組。
• 文字回復僅比對字面字串的 Tj 與 TJ 形式。十六進位字串、加密內容內的文字，以及跨串流分割的運算子都不會被回復，這會減少可供評分的文字。
• 解壓縮上限會在串流膨脹期間限制記憶體，並抵抗解壓縮炸彈輸入。超過上限的內容不會被膨脹。
• 純影像或高度壓縮的 PDF 只能回復少量文字；請預期低信心結果並將其導向人工複審。
• 低於最小文字長度的語言偵測會回傳 en，信心為 0.0；非常短的字串永遠不會產生非英文的結果。
• 這十二種文件類型與十個語言設定檔在本次發行中是固定的。延伸要透過自訂的 ClassifierInterface 實作，而非編輯內建資料。
• 此模組不發生任何密碼學作業，因此沒有 FIPS 模式專屬行為。

一致性

主張	標準	條款
檔案分類會回復以 Tj 運算子呈現的文字。	ISO 32000-2:2020	§9.4
檔案分類會回復 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 策略時才注入協作者。
• 請將低於門檻的結果視為不確定並導向人工複審；帶有 0.7 預設值的 isConfident() 即為公開判準。
• 此模組不儲存任何內容、不發出遙測，也不記錄任何輸入。若呼叫端持久化 metadata，請先依其自身的資料處理政策審視。
• 關鍵字評分與三連詞計數的複雜度與文字長度成線性。結構分析在有界解壓縮上限下與 PDF 位元組長度成線性。本頁的預算為 1000 ms 掛鐘時間與 64 MB 峰值記憶體。

發布邊界

本頁僅記載外部可觀察的行為與支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、runbook 檔名，以及票證前綴皆不在範圍內。

另請參閱

• Classifier（能力） — 安裝、快速開始，以及生產環境路由範例。
• Extraction — 深度參考 — 用於更豐富輸入文字的完整文字擷取介面。
• Filter — 深度參考 — DecodeParms 與 PngPredictor，用於檔案分類期間。
• Diff — 深度參考 — 姊妹的位元組層級文件比較介面。