Classifier — Referencia detallada

De un vistazo

Esta página es la referencia a nivel de contrato del clasificador de documentos de NextPDF Pro. La superficie se compone de un orquestador, NextPDF\Pro\Classifier\DocumentClassifier, y sus colaboradores: StructureAnalyzer, LanguageDetector y la estrategia ClassifierInterface con su HeuristicClassifier predeterminado. Los resultados llegan como un ClassificationResult inmutable que contiene un DocumentType, una confianza en [0.0, 1.0], los valores ClassificationFeature detectados y un código de idioma ISO 639-1. La clasificación se basa en reglas y es determinista: sin inferencia de modelos, sin aleatoriedad, sin llamadas de red ni acceso al sistema de archivos. Esta página expone la API pública, el contrato de comportamiento observable y los modos de fallo.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin esa titularidad no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Ningún indicador de capacidad en tiempo de ejecución restringe este módulo. Las clases del clasificador están disponibles siempre que nextpdf/pro esté instalado.

Superficie de API pública

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
DocumentClassifier	constructor: StructureAnalyzer, LanguageDetector, ClassifierInterface	Orquesta el análisis de estructura, la clasificación por estrategia y la detección de idioma	—	—	final; inyectar colaboradores solo para estrategias personalizadas
DocumentClassifier::create()	ninguno	Construye los colaboradores predeterminados con HeuristicClassifier como estrategia	self	—	Configuración predeterminada determinista
DocumentClassifier::classifyFromText()	$text, $pdfData = ''	Un $pdfData vacío usa una estructura vacía; los bytes en bruto no vacíos añaden señales estructurales	ClassificationResult	No lanza excepciones; una entrada escasa reduce la confianza	La detección de idioma siempre se ejecuta sobre $text
DocumentClassifier::classifyFromFile()	string $pdfData	Escanea los flujos de contenido, recupera el texto de §9.4, analiza la estructura y clasifica	ClassificationResult	No lanza excepciones; los flujos ilegibles reducen el texto recuperado	Escaneo de bytes acotado, no un análisis completo del PDF
ClassifierInterface::classify()	$text, StructureAnalysis $structure	Contrato de estrategia consumido por el orquestador	ClassificationResult	Definido por la implementación	Punto de extensión para estrategias de clasificación personalizadas
ClassifierInterface::supports()	string $contentType	Sondeo de tipo de contenido para clasificadores compuestos	bool	—	Recibe un tipo MIME o un descriptor de contenido
HeuristicClassifier	ninguno	Estrategia predeterminada: diccionarios de palabras clave más heurísticas estructurales	—	No lanza excepciones	final; supports() acepta application/pdf y text/plain
StructureAnalyzer::analyze()	string $pdfData	Escaneo por regex de los bytes en bruto; sin análisis completo del PDF	StructureAnalysis	No lanza excepciones	Cuenta páginas, imágenes y fuentes; detecta campos de formulario y de firma
LanguageDetector::detect()	string $text	Coincidencia por perfil de trigramas con comprobación previa de rango de escritura CJK	código ISO 639-1 non-empty-string	No lanza excepciones	Recurre a en por debajo del umbral de aceptación
LanguageDetector::detectWithConfidence()	string $text	Como detect(), pero exponiendo la confianza	array{language: non-empty-string, confidence: float}	No lanza excepciones	Un texto corto devuelve en con confianza 0.0
ClassificationResult	constructor: $type, $confidence, $features, $language, $metadata = []	Objeto de valor inmutable	—	—	final readonly; metadata contiene scores y method
ClassificationResult::isConfident()	float $threshold = 0.7	Compara la confianza con el umbral	bool	—	Compuerta documentada para el enrutamiento a revisión manual
StructureAnalysis	constructor: $pageCount, $imageCount, $fontCount, $hasFormFields, $hasSignatureFields, $imageDensity, $detectedFeatures	Objeto de valor inmutable producido por StructureAnalyzer	—	—	final readonly; imageDensity es imágenes por página
DocumentType	enum con respaldo de cadena, 12 casos	Casos: Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other	valores de respaldo invoice … other	—	label() devuelve un nombre legible
ClassificationFeature	enum con respaldo de cadena, 7 casos	Casos: HasTables, HasHeaders, HasSignatures, HasLogos, HasBarcodes, HasForms, IsScanned	valores de respaldo has_tables … is_scanned	—	Señales estructurales que alimentan la clasificación

Firmas de los puntos de entrada

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

Contrato de comportamiento

Orden del pipeline

DocumentClassifier ejecuta el análisis de estructura, luego la clasificación por estrategia y después la detección de idioma, y ensambla un ClassificationResult. La estrategia aporta el tipo, la confianza, las características y los metadatos; el detector aporta el idioma. classifyFromText() sin bytes de PDF sustituye por una estructura vacía: cero páginas, cero recuentos, sin características. classifyFromFile() deriva tanto la estructura como el texto de los mismos bytes en bruto.

Puntuación heurística

HeuristicClassifier puntúa el texto en minúsculas frente a diccionarios de palabras clave por tipo de documento, normalizados por la longitud del texto. Los diccionarios, pesos y umbrales concretos son detalles de implementación y no se publican. Después, las señales estructurales ajustan las puntuaciones: los valores ClassificationFeature coincidentes impulsan sus tipos asociados; los documentos por encima de un umbral de páginas se alejan de Letter y Receipt; los documentos de varias páginas con encabezados y tablas reciben un impulso a Report; una característica de formulario detectada añade una señal fuerte de Form. La puntuación más alta gana y se asigna a un DocumentType. Una normalización acotada asigna la puntuación en bruto a [0.0, 1.0]. Una puntuación por debajo del mínimo produce DocumentType::Other con un pequeño piso de confianza distinto de cero. El metadata del resultado contiene el mapa scores por tipo y method: heuristic. HeuristicClassifier por sí solo informa el idioma en; DocumentClassifier lo sobrescribe con la salida del detector.

Detección de idioma

Una comprobación de rango de escritura para texto CJK se ejecuta antes de la puntuación por trigramas. El predominio de hangul selecciona ko; cualquier kana selecciona ja; en caso contrario, una proporción suficiente de ideogramas selecciona zh. El resto del texto se puntúa por la frecuencia de trigramas de caracteres frente a diez perfiles integrados. Los posibles valores de retorno son los códigos ISO 639-1 en, zh, ja, ko, de, fr, es, pt, it y nl. Un texto por debajo de una longitud mínima devuelve en con confianza 0.0. Un resultado por debajo del umbral de aceptación con un margen estrecho también devuelve en. La confianza refleja el margen entre la mejor y la segunda mejor puntuación de perfil.

Recuperación de texto de archivos

classifyFromFile() escanea los bytes en bruto en busca de segmentos stream/endstream. Cada segmento se prueba como datos Flate bajo un límite de inflado acotado; si falla, se usan los bytes en bruto del segmento. Cuando el diccionario de flujo adyacente declara un predictor PNG en /DecodeParms, la reversión respeta los parámetros Predictor, Columns, Colors y BitsPerComponent según ISO 32000-2:2020 §7.4.4.4, usando las clases DecodeParms y PngPredictor del módulo Filter. Luego se recupera el texto de los operadores de mostrado de texto de §9.4: cadenas literales mostradas con Tj y cadenas literales dentro de arreglos TJ. El clasificador puntúa el texto recuperado; no depende de la disposición visual.

Análisis de estructura

StructureAnalyzer::analyze() cuenta los tokens de página, imagen y fuente en los bytes en bruto, detecta los campos /AcroForm y de firma, y deriva la densidad de imágenes. La detección de características es heurística: el dibujo repetido de rectángulos sugiere tablas, las declaraciones de tamaño de fuente grande sugieren encabezados, y una alta densidad de imágenes con pocas fuentes sugiere un documento escaneado. Los recuentos reflejan los tokens visibles en los bytes en bruto; las estructuras serializadas dentro de flujos de objetos comprimidos no se cuentan.

Determinismo

Todo el pipeline es una función pura de sus bytes de entrada. Una entrada idéntica produce un ClassificationResult idéntico. No hay inferencia de modelos, ni aleatoriedad, ni llamadas de red, ni acceso al sistema de archivos.

Casos límite y modos de fallo

• Un texto vacío o casi vacío produce un DocumentType::Other de baja confianza por diseño. Ramificar según isConfident() en lugar de según el tipo por sí solo.
• Ningún método público de este módulo lanza excepciones. Los flujos cuya descompresión falla se escanean en bruto; los parámetros de predictor malformados o no admitidos recurren a los bytes sin filtrar.
• La recuperación de texto solo coincide con las formas de cadena literal Tj y TJ. Las cadenas hexadecimales, el texto dentro de contenido cifrado y los operadores divididos entre flujos no se recuperan, lo que reduce el texto disponible para puntuar.
• El límite de descompresión acota la memoria durante el inflado de flujos y resiste las entradas de bomba de descompresión. El contenido más allá del límite no se infla.
• Los PDF solo de imágenes o muy comprimidos recuperan poco texto; esperar resultados de baja confianza y enrutarlos a revisión manual.
• La detección de idioma por debajo de la longitud mínima de texto devuelve en con confianza 0.0; las cadenas muy cortas nunca producen un resultado que no sea inglés.
• Los doce tipos de documento y los diez perfiles de idioma son fijos en esta versión. La extensión se realiza mediante una implementación personalizada de ClassifierInterface, no editando los datos integrados.
• En este módulo no ocurre ninguna operación criptográfica, por lo que no hay comportamiento específico del modo FIPS.

Conformidad

Afirmación	Estándar	Cláusula
La clasificación de archivos recupera el texto mostrado con el operador Tj.	ISO 32000-2:2020	§9.4
La clasificación de archivos recupera las cadenas literales dentro de los operadores de arreglo TJ.	ISO 32000-2:2020	§9.4
La reversión del predictor PNG respeta los parámetros de filtro Predictor, Columns, Colors y BitsPerComponent.	ISO 32000-2:2020	§7.4.4.4

Los códigos de idioma siguen ISO 639-1; esto es una declaración basada en el producto sobre el formato de salida, no una afirmación de conformidad citada. Todas las cláusulas están parafraseadas; NextPDF no reproduce texto normativo. Estas son declaraciones de capacidad, no certificaciones. NextPDF no posee ninguna certificación ni concede ninguna. La clasificación es heurística y de mejor esfuerzo: el módulo afirma determinismo, no exactitud, y quien la invoca es responsable del umbral de decisión.

Notas de desarrollo

• Disponible desde nextpdf/pro 2.2.0; vigente en nextpdf/pro 3.1.0.
• Usar DocumentClassifier::create() para el pipeline predeterminado. Inyectar colaboradores solo para suministrar una estrategia ClassifierInterface personalizada.
• Tratar los resultados por debajo del umbral como inciertos y enrutarlos a revisión manual; isConfident() con su valor predeterminado 0.7 es la compuerta documentada.
• El módulo no almacena nada, no emite telemetría y no registra ninguna entrada. Si quien lo invoca persiste metadata, conviene revisarlo primero frente a su propia política de tratamiento de datos.
• La puntuación por palabras clave y el recuento de trigramas son lineales respecto a la longitud del texto. El análisis de estructura es lineal respecto a la longitud en bytes del PDF bajo el límite de descompresión acotado. El presupuesto de la página es de 1000 ms de tiempo de reloj y 64 MB de memoria máxima.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de API pública admitida. Las rutas de espacios de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de tickets quedan fuera del alcance.

Véase también

• Classifier (capacidad) — instalación, inicio rápido y ejemplos de enrutamiento en producción.
• Extraction — referencia detallada — la superficie completa de extracción de texto para un texto de entrada más rico.
• Filter — referencia detallada — DecodeParms y PngPredictor, usados durante la clasificación de archivos.
• Diff — referencia detallada — la superficie hermana de comparación de documentos a nivel de bytes.