Classifier

De un vistazo

NextPDF\Pro\Classifier asigna un tipo de documento (factura, contrato, informe, etc.) y un idioma detectado mediante heurísticas deterministas sobre el texto y la estructura del documento. Está basado en reglas, no es un modelo de aprendizaje automático.

Disponibilidad y licencia

Esta función se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin ese derecho no carga las clases de la función. Compare las ediciones y obtenga 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.

Instalación

composer require nextpdf/pro:^3

Descripción conceptual

DocumentClassifier orquesta tres colaboradores:

• StructureAnalyzer inspecciona el PDF para obtener el número de páginas, el recuento de imágenes y fuentes, y los campos de formulario/firma, produciendo un StructureAnalysis.
• HeuristicClassifier (el ClassifierInterface predeterminado) puntúa el texto frente a diccionarios de palabras clave por tipo y aplica heurísticas estructurales (por ejemplo, los documentos cortos se inclinan en contra de «report»), generando un DocumentType y una confianza.
• LanguageDetector identifica el idioma a partir de perfiles de frecuencia de trigramas de caracteres para diez idiomas, recurriendo al inglés por debajo de un umbral de confianza.

classifyFromText() acepta texto ya extraído (con bytes de PDF en bruto opcionales para la estructura); classifyFromFile() acepta bytes de PDF en bruto y extrae el texto analizando directamente los operadores de presentación de texto de la §9.4.

Por qué funciona así

La decisión determinante es clasificar con heurísticas deterministas, no con un modelo de aprendizaje automático. Una canalización basada en reglas es una función pura de su entrada: unos bytes idénticos siempre producen un tipo, una confianza y un idioma idénticos, sin deriva del modelo y sin llamadas de red. Ese determinismo permite que el resultado exponga una confianza explícita, una compuerta isConfident() y un mapa scores por tipo, de modo que el módulo muestra cómo decidió en lugar de ocultar la elección tras un modelo. Por ello, los llamantes enrutan por contrato los documentos de baja confianza a revisión manual, y el texto demasiado corto para puntuar recurre a en bajo la misma regla fija. La contrapartida es deliberada: la precisión está acotada por perfiles fijos de palabras clave y trigramas, a cambio de reproducibilidad, inspeccionabilidad y un clasificador que se ejecuta enteramente en el mismo proceso.

Contexto de diseño: Una API que se niega a adivinar.

Contrato de comportamiento

• Entrada. Texto extraído (classifyFromText) o bytes de PDF en bruto (classifyFromFile). Una entrada vacía es válida y produce un resultado de baja confianza, normalmente DocumentType::Other.
• Salida. Un ClassificationResult con el DocumentType, una confianza en [0.0, 1.0], las características estructurales detectadas, un código de idioma ISO 639-1 y metadatos. isConfident(0.7) es el ayudante de umbral documentado.
• Determinismo. La clasificación y la detección de idioma son funciones puras de la entrada: misma entrada, mismo resultado, sin aleatoriedad, sin red.
• Alcance. Doce tipos de documento y diez perfiles de idioma, ambos fijos en esta versión. Se pueden suministrar estrategias personalizadas mediante ClassifierInterface.

Superficie pública de la API

Tipo	Clase	Miembros clave
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

Ejemplo de código — Inicio rápido

<?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,
);

Ejemplo de código — Producción

<?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',
    };
}

Casos límite y trampas

• La confianza es heurística. Trate los resultados por debajo del umbral como «inciertos» y enrútelos a revisión manual, como hace el ejemplo de producción.
• La detección de idioma necesita suficiente texto; las cadenas muy cortas recurren al inglés por diseño.
• classifyFromFile() utiliza una extracción de texto a nivel de bytes acotada; los PDF muy comprimidos o que solo contienen imágenes reducen el texto disponible para puntuar.
• Los conjuntos de tipos de documento y de idioma son fijos en esta versión; extienda la clasificación implementando ClassifierInterface, no mutando los diccionarios integrados.

Residencia de datos y mitigaciones de PII

La clasificación se ejecuta en el mismo proceso, sin llamadas de red ni almacenamiento de la entrada. El resultado incluye un DocumentType y un código de idioma, no el texto de origen. Si los llamantes conservan los metadata, revíselos en busca de PII incidental antes de almacenarlos.

Telemetría segura y depuración de registros

El módulo no emite telemetría y no registra la entrada. Los llamantes que añadan registro deben anotar únicamente el DocumentType y el código de idioma resultantes, nunca el texto clasificado.

Rendimiento

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 con un tope de descompresión acotado. Consulte performance_budget.

Notas de seguridad

classifyFromFile() analiza bytes de PDF no confiables con un escaneo acotado y un tope de tamaño de descompresión para resistir entradas de tipo bomba de descompresión. No se ejecuta ningún script incrustado.

Conformidad

Declaración	Cláusula del estándar	Estado
Texto recuperado mediante Tj para la clasificación de archivos	ISO 32000-2:2020 §9.4	Verificado (conjunto unitario)
Texto recuperado mediante TJ para la clasificación de archivos	ISO 32000-2:2020 §9.4	Verificado (conjunto unitario)
Clasificación basada en aprendizaje automático / modelos	—	No admitido (solo heurístico)

Alternativa / respaldo de Core

No existe ningún equivalente en Core para la clasificación de documentos ni la detección de idioma.

Nota sobre el límite de Enterprise

Este clasificador está basado en reglas y es determinista. No realiza ninguna incrustación, similitud vectorial, inferencia de modelos ni comprensión semántica. Esas capacidades no forman parte de este módulo ni están implícitas en él.

Límite de publicación

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

Véase también

• Classifier — Referencia detallada — la superficie pública completa de la API, el orden de la canalización y los modos de fallo.
• Extraction
• Filter
• Diff