Pro エディション

Classifier — 詳細リファレンス

概要

本ページは、NextPDF Pro ドキュメント分類器の契約レベルのリファレンスです。サーフェスは 1 つのオーケストレーター 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}`	スローしない	短いテキストは信頼度 `0.0` で `en` を返す
`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`	文字列バック enum、12 ケース	ケース: `Invoice`、`Contract`、`Form`、`Report`、`Letter`、`Receipt`、`Legal`、`Medical`、`Financial`、`Technical`、`Academic`、`Other`	バッキング値 `invoice` … `other`	—	`label()` は人間可読な名前を返す
`ClassificationFeature`	文字列バック enum、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 を組み立てます。ストラテジーが種別・信頼度・特徴・メタデータを供給し、検出器が言語を供給します。PDF バイトを伴わない classifyFromText() は空の構造で代替します。ページ数はゼロ、各種カウントはゼロ、特徴はありません。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 を選択します。その他すべてのテキストは、10 の組み込みプロファイルに対して文字トライグラムの頻度でスコアリングされます。返される可能性のある値は、ISO 639-1 コードの en、zh、ja、ko、de、fr、es、pt、it、nl です。最小長を下回るテキストは、信頼度 0.0 で en を返します。受理しきい値を下回り、かつマージンが狭い結果も en を返します。信頼度は、最良と次点のプロファイルスコア間のマージンを反映します。

ファイルテキストの復元

classifyFromFile() は生バイトから stream/endstream セグメントをスキャンします。各セグメントは境界付きのインフレーション上限のもとで Flate データとして試行され、失敗した場合はセグメントの生バイトが使用されます。隣接するストリーム辞書が /DecodeParms で PNG プレディクターを宣言している場合、逆変換は Filter モジュールの DecodeParms および PngPredictor クラスを用いて、ISO 32000-2:2020 §7.4.4.4 に従い Predictor、Columns、Colors、BitsPerComponent パラメーターを尊重します。続いてテキストが §9.4 のテキスト表示演算子から復元されます。Tj で表示されるリテラル文字列と、TJ 配列内のリテラル文字列です。分類器は復元されたテキストをスコアリングします。視覚的なレイアウトには依存しません。

構造分析

StructureAnalyzer::analyze() は、生バイト内のページ・画像・フォントのトークンを数え、/AcroForm と署名フィールドを検出し、画像密度を導出します。特徴検出はヒューリスティックです。矩形描画の繰り返しはテーブルを示唆し、大きなフォントサイズの宣言はヘッダーを示唆し、フォントが少なく画像密度が高い場合はスキャンされたドキュメントを示唆します。カウントは生バイト内で可視のトークンを反映します。圧縮オブジェクトストリーム内にシリアライズされた構造はカウントされません。

決定論性

パイプライン全体は入力バイトの純粋関数です。同一の入力は同一の ClassificationResult を生成します。モデル推論、ランダム性、ネットワーク呼び出し、ファイルシステムアクセスは一切ありません。

エッジケースと失敗モード

空または空に近いテキストは、設計上、低信頼度の DocumentType::Other を生成します。種別だけでなく isConfident() で分岐してください。
このモジュールの公開メソッドはいずれもスローしません。展開に失敗したストリームは生のままスキャンされ、不正または未対応のプレディクターパラメーターはフィルター前のバイトにフォールバックします。
テキストの復元は、リテラル文字列の Tj および TJ 形式のみに一致します。16 進数文字列、暗号化コンテンツ内のテキスト、ストリームをまたいで分割された演算子は復元されず、スコアリング可能なテキストが減少します。
展開上限はストリームインフレーション中のメモリを制限し、展開爆弾（decompression bomb）入力に耐性を持ちます。上限を超えるコンテンツは展開されません。
画像のみ、または高度に圧縮された PDF は復元できるテキストがほとんどありません。低信頼度の結果を想定し、手動レビューに振り分けてください。
最小テキスト長を下回る言語検出は、信頼度 0.0 で en を返します。非常に短い文字列が英語以外の結果を生成することはありません。
12 のドキュメント種別と 10 の言語プロファイルは、このリリースでは固定です。拡張は、組み込みデータの編集ではなく、カスタムの ClassifierInterface 実装を介して行います。
このモジュールでは暗号操作は一切行われないため、FIPS モード固有の挙動はありません。

準拠

主張	標準	条項
ファイル分類は `Tj` 演算子で表示されたテキストを復元。	ISO 32000-2:2020	§9.4
ファイル分類は `TJ` 配列演算子内のリテラル文字列を復元。	ISO 32000-2:2020	§9.4
PNG プレディクター逆変換は `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 サーフェスのみを文書化します。内部の名前空間パス、ヘルパークラス、メカニズム表、ランブックのファイル名、チケットの接頭辞は対象外です。