Classifier — глубокий справочник

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

Эта страница — справочник контрактного уровня для классификатора документов NextPDF Pro. Поверхность состоит из одного оркестратора, NextPDF\Pro\Classifier\DocumentClassifier, и его сотрудников: StructureAnalyzer, LanguageDetector и стратегии ClassifierInterface с реализацией по умолчанию HeuristicClassifier. Результаты приходят как неизменяемый 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 под ограниченным потолком инфляции; при неудаче используются сырые байты сегмента. Когда соседний словарь потока объявляет PNG-предиктор в /DecodeParms, обращение учитывает параметры Predictor, Columns, Colors и BitsPerComponent согласно ISO 32000-2:2020 §7.4.4.4, используя классы DecodeParms и PngPredictor модуля Filter. Затем текст восстанавливается из операторов показа текста §9.4: литеральные строки, показанные Tj, и литеральные строки внутри массивов TJ. Классификатор оценивает восстановленный текст; он не зависит от визуальной разметки.

Анализ структуры

StructureAnalyzer::analyze() считает токены страниц, изображений и шрифтов в сырых байтах, обнаруживает /AcroForm и поля подписей и выводит плотность изображений. Обнаружение признаков эвристично: повторяющееся рисование прямоугольников указывает на таблицы, объявления крупного размера шрифта указывают на заголовки, а высокая плотность изображений при малом числе шрифтов указывает на отсканированный документ. Счётчики отражают токены, видимые в сырых байтах; структуры, сериализованные внутри сжатых потоков объектов, не учитываются.

Детерминизм

Весь конвейер — чистая функция от входных байтов. Идентичный вход даёт идентичный ClassificationResult. Нет ни вывода модели, ни случайности, ни сетевого вызова, ни доступа к файловой системе.

Граничные случаи и режимы отказа

• Пустой или почти пустой текст по замыслу даёт DocumentType::Other с низкой уверенностью. Ветвитесь по isConfident(), а не по одному лишь типу.
• Ни один публичный метод этого модуля не бросает. Потоки, не поддающиеся распаковке, сканируются в сыром виде; некорректные или неподдерживаемые параметры предиктора откатываются к нефильтрованным байтам.
• Восстановление текста сопоставляет только формы литеральных строк Tj и TJ. Шестнадцатеричные строки, текст внутри зашифрованного содержимого и операторы, разбитые между потоками, не восстанавливаются, что уменьшает объём текста, доступного для оценивания.
• Потолок распаковки ограничивает память при инфляции потока и сопротивляется входу типа «декомпрессионная бомба». Содержимое сверх потолка не инфлируется.
• PDF, содержащие только изображения или сильно сжатые, восстанавливают мало текста; ожидайте результаты с низкой уверенностью и направляйте их на ручную проверку.
• Определение языка ниже минимальной длины текста возвращает en с уверенностью 0.0; очень короткие строки никогда не дают неанглийский результат.
• Двенадцать типов документов и десять языковых профилей фиксированы для этого выпуска. Расширение — через пользовательскую реализацию 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.
• Считайте результаты ниже порога неопределёнными и направляйте их на ручную проверку; isConfident() со значением по умолчанию 0.7 — документированный барьер.
• Модуль ничего не хранит, не отправляет телеметрию и не логирует ввод. Если вызывающие стороны сохраняют metadata, сначала проверьте их на соответствие собственной политике обработки данных.
• Оценивание ключевых слов и подсчёт триграмм линейны по длине текста. Анализ структуры линеен по длине PDF в байтах при ограниченном потолке распаковки. Бюджет страницы — 1000 мс времени и 64 МБ пиковой памяти.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов рунбуков и префиксы тикетов вне области охвата.

См. также

• Classifier (возможность) — установка, быстрый старт и примеры продакшн-маршрутизации.
• Extraction — глубокий справочник — полная поверхность извлечения текста для более богатого входного текста.
• Filter — глубокий справочник — DecodeParms и PngPredictor, используемые при классификации файла.
• Diff — глубокий справочник — родственная поверхность побайтового сравнения документов.