Pro エディション

分類器

概要

NextPDF\Pro\Classifier は、ドキュメントのテキストと構造に対する決定的なヒューリスティックを用いて、ドキュメントの種類（請求書、契約書、レポートなど）と検出した言語を割り当てます。これはルールベースであり、機械学習モデルではありません。

提供状況とライセンス

この機能は NextPDF Pro（nextpdf/pro）に同梱され、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイでは、この機能のクラスは読み込まれません。エディションを比較してライセンスを取得する。

このモジュールをゲートするランタイムの機能フラグはありません。分類器のクラスは、nextpdf/pro がインストールされていれば常に利用できます。

インストール

composer require nextpdf/pro:^3

概念の概要

DocumentClassifier は、3 つのコラボレーターを統括します。

StructureAnalyzer は、ページ数、画像とフォントの数、フォーム/署名フィールドについて PDF を検査し、StructureAnalysis を生成します。
HeuristicClassifier（デフォルトの ClassifierInterface）は、種類ごとのキーワード辞書に照らしてテキストをスコアリングし、構造的ヒューリスティック（たとえば、短いドキュメントは「report」から外れる方向にバイアスがかかる）を適用して、DocumentType と信頼度を導き出します。
LanguageDetector は、10 言語の文字トリグラム頻度プロファイルから言語を識別し、信頼度のしきい値を下回る場合は英語にフォールバックします。

classifyFromText() は抽出済みのテキスト（構造用に任意の生 PDF バイトを伴う）を受け取ります。classifyFromFile() は生 PDF バイトを受け取り、§9.4 のテキスト表示演算子を直接解析してテキストを抽出します。

なぜこの仕組みなのか

肝となる決定は、機械学習モデルではなく決定的なヒューリスティックで分類するという点です。ルールベースのパイプラインは、その入力の純粋関数です。同一のバイトは常に同一の種類、信頼度、言語を返し、モデルのドリフトもネットワーク呼び出しもありません。その決定性により、結果は明示的な信頼度、isConfident() ゲート、種類ごとの scores マップを公開できるため、モデルの背後に選択を隠すのではなく、どのように判断したかをモジュールが示します。したがって呼び出し側は、契約として低信頼度のドキュメントを手動レビューへルーティングし、スコアリングするには短すぎるテキストは同じ固定ルールのもとで en にフォールバックします。このトレードオフは意図的なものです。精度は固定のキーワードとトリグラムのプロファイルによって制限されますが、その代わりに再現性、検査可能性、そして完全にプロセス内で動作する分類器が得られます。

設計の背景: 推測を拒否する API。

振る舞いの契約

入力。 抽出済みテキスト（classifyFromText）または生 PDF バイト（classifyFromFile）。空の入力は有効であり、通常は DocumentType::Other の低信頼度の結果になります。
出力。 DocumentType、[0.0, 1.0] の範囲の信頼度、検出された構造的特徴、ISO 639-1 言語コード、メタデータを持つ ClassificationResult。isConfident(0.7) が、文書化されたしきい値ヘルパーです。
決定性。 分類と言語検出は入力の純粋関数です。同じ入力なら同じ結果であり、ランダム性もネットワークもありません。
スコープ。 12 種類のドキュメントタイプと 10 種類の言語プロファイルで、いずれも本リリースで固定です。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 のケース（`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 の境界に関する注意

この分類器はルールベースで決定的です。埋め込み、ベクトル類似度、モデル推論、セマンティック理解のいずれも行いません。それらの機能は本モジュールの一部ではなく、本モジュールがそれらを含意することもありません。

公開範囲の境界

このページは、外部から観測可能な振る舞いとサポートされる公開 API サーフェスのみを記述します。内部の名前空間パス、ヘルパークラス、メカニズムの表、Runbook のファイル名、チケットのプレフィックスは対象外です。