Classifier

Краткий обзор

NextPDF\Pro\Classifier присваивает документу тип (счёт, договор, отчёт и так далее) и определяет язык с помощью детерминированных эвристик по тексту и структуре документа. Модуль основан на правилах, а не на модели машинного обучения.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без этого права доступа не загружает классы этой возможности. Сравнить редакции и получить лицензию.

Ни один флаг возможности времени выполнения не ограничивает этот модуль. Классы Classifier доступны всегда, когда установлен nextpdf/pro.

Установка

composer require nextpdf/pro:^3

Концептуальный обзор

DocumentClassifier оркеструет трёх участников:

• StructureAnalyzer анализирует PDF на число страниц, число изображений и шрифтов, а также поля форм и подписей, формируя StructureAnalysis.
• HeuristicClassifier (стандартный ClassifierInterface) оценивает текст по словарям ключевых слов для каждого типа и применяет структурные эвристики (например, короткие документы смещают оценку прочь от «отчёта»), давая DocumentType и уверенность.
• LanguageDetector определяет язык по частотным профилям символьных триграмм для десяти языков, переходя к английскому ниже порога уверенности.

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 или PDF только из изображений уменьшают объём доступного для оценки текста.
• Наборы типов документов и языков фиксированы в этом выпуске; расширяйте классификацию реализацией ClassifierInterface, а не изменением встроенных словарей.

Размещение данных и меры по защите ПДн

Классификация выполняется внутри процесса без сетевых вызовов и без сохранения ввода. Результат содержит DocumentType и код языка, а не исходный текст. Если вызывающий код сохраняет metadata, проверьте их на случайные ПДн перед хранением.

Безопасная телеметрия и очистка журналов

Модуль не отправляет телеметрию и не записывает в журнал ввод. Вызывающий код, добавляющий журналирование, должен записывать только итоговый 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 и префиксы тикетов выходят за рамки.

См. также

• Classifier — подробный справочник — полная поверхность публичного API, порядок конвейера и режимы отказа.
• Extraction
• Filter
• Diff