Inteligencia

De un vistazo

NextPDF Enterprise Intelligence convierte datos en bruto de pares clave-valor y de tablas en estructuras tipadas, opcionalmente validadas frente a un esquema, y orquesta la generación de PDF con búsqueda dirigiendo un backend de OCR sobre las páginas escaneadas. Describe las estructuras que produce; no afirma la precisión del OCR ni la exhaustividad de la extracción.

Disponibilidad y licencia

Esta capacidad se incluye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin ese derecho de uso no carga las clases de la capacidad. Un despliegue sin un derecho de uso de Enterprise activo no carga estas clases. Comparar ediciones y obtener una licencia.

Instalación

composer require nextpdf/enterprise:^3

Descripción conceptual

El extractor estructurado toma pares clave-valor en bruto —producidos aguas arriba por un acelerador o un analizador heurístico— y emite objetos de par tipados. Cuando se suministra un esquema, conserva únicamente los pares cuya clave coincide con un campo del esquema e informa de qué campos obligatorios faltan. Un par sin una confianza explícita recibe un valor predeterminado fijo. Es un paso de tipado y validación sobre datos que ya están extraídos; no es en sí mismo un motor de extracción o de reconocimiento y no asigna ninguna precisión calculada.

El extractor de tablas toma cuadrículas de filas en bruto y construye resultados de tabla estructurados con objetos por celda y rectángulos delimitadores sintetizados y uniformes, derivados subdividiendo un área de página normalizada. Las filas cortas se rellenan para que cada fila tenga el mayor número de columnas. Una tabla sin filas o sin columnas se omite. Los rectángulos delimitadores son una síntesis de cuadrícula uniforme, no una maquetación medida.

El orquestador de capas con búsqueda acepta un PDF escaneado o mixto, detecta qué páginas carecen de una capa de texto utilizable, dirige el backend de OCR configurado y produce un resultado que describe el recuento de palabras por página y una confianza media. El texto invisible es el mecanismo de una página escaneada con búsqueda: un operador de mostrado de texto puede colocar glifos mientras el modo de renderizado de texto está configurado para que el texto no se rellene ni se trace —ISO 32000-2:2020 §9.3.3— y los operadores de mostrado de texto colocan glifos en el flujo de contenido —ISO 32000-2:2020 §9.4—. Cuando el origen está etiquetado, la jerarquía de estructura lógica asigna el contenido a un orden de lectura —ISO 32000-2:2020 §14.7—, la estructura etiquetada admite la reutilización de contenido —ISO 32000-2:2020 §14.8— y los elementos de estructura de tabla describen filas y celdas —ISO 32000-2:2020 §14.8—.

La rasterización real y la inyección de texto invisible las realiza un proceso sidecar independiente; la superficie de PHP orquesta el flujo de trabajo y produce los metadatos del resultado. La salida de una ejecución de capa es un documento derivado: cualquier firma existente queda invalidada y el estado de cumplimiento requiere una nueva validación. Los valores de confianza son de paso o valores predeterminados fijos, no una cifra de precisión garantizada.

Por qué funciona así

La superficie traza una línea firme entre estructurado y reconocimiento. El tipado y la validación frente a un esquema se ejecutan en proceso, porque son deterministas y baratos. El reconocimiento —rasterización e inyección de texto invisible— se delega a un backend de OCR inyectado y a un sidecar independiente, porque es pesado, específico del backend y conviene mantenerlo fuera de la frontera de confianza de PHP. Esa separación permite que un despliegue elija dónde se calculan y almacenan las imágenes del documento y el texto reconocido, sin cambiar el código que lo invoca. El módulo también se niega a inventar una cifra de precisión: un par sin etiqueta recibe un valor predeterminado fijo, y la confianza informada se transmite en lugar de calcularse. Nunca se entrega al invocador un número de precisión fabricado.

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

Superficie de la API

Type	Kind	Role	Stability	Since
StructuredExtractor	clase	Tipa pares clave-valor en bruto; filtro de esquema y comprobación de campos obligatorios	stable	2.2.0
ExtractionSchema / SchemaField	clases	Definiciones de campo y conjunto de campos obligatorios	stable	2.2.0
KeyValuePair	clase	Un par clave-valor tipado con confianza	stable	2.2.0
TableExtractor	clase	Construye tablas estructuradas a partir de cuadrículas de filas en bruto	stable	2.2.0
TableResult / TableCell	clases	Forma de tabla con texto, confianza y rectángulo delimitador por celda	stable	2.2.0
SearchableOverlay	clase	Orquesta la generación de PDF con búsqueda respaldada por OCR	stable	2.2.0
OverlayConfig / OverlayQuality	clases	Sugerencia de idioma, DPI, preajuste de calidad, omisión de páginas nativas	stable	2.2.0
SearchableOverlayResult / PageOverlayInfo	clases	Recuento de palabras por página y confianza media	stable	2.2.0
ExtractionConfig / ExtractionStrategy	clases	Estrategia heurística frente a asistida por OCR y sugerencias de OCR	stable	2.2.0

El backend de OCR es un contrato inyectado. El orquestador no incorpora un modelo de OCR; un despliegue suministra el backend y es responsable de dónde se calcula el OCR.

Ejemplo de código — Inicio rápido

Type and schema-validate raw key-value pairs

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Intelligence\StructuredExtractor;
use NextPDF\Enterprise\Intelligence\ExtractionSchema;

/**
 * Type raw pairs against a schema and list any missing required fields.
 *
 * @param list<array{key: string, value: string, confidence?: float}> $rawPairs Upstream key-value data.
 *
 * @return list<string> Missing required field names (empty when compliant).
 */
function validate(array $rawPairs, ExtractionSchema $schema): array
{
    $extractor = new StructuredExtractor();
    $pairs = $extractor->extract($rawPairs, $schema);

    return $extractor->validateSchema($schema, $pairs);
}

El extractor tipa y filtra datos que un paso aguas arriba ya produjo. No realiza ningún reconocimiento por sí mismo.

Ejemplo de código — Producción

Searchable-overlay orchestration with safe logging

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Accelerator\OcrStrategyInterface;
use NextPDF\Enterprise\Intelligence\OverlayConfig;
use NextPDF\Enterprise\Intelligence\SearchableOverlay;
use Psr\Log\LoggerInterface;

final readonly class OverlayJob
{
    public function __construct(
        private OcrStrategyInterface $ocr,
        private LoggerInterface $logger,
    ) {}

    /**
     * Generate a searchable PDF from a scanned input.
     *
     * @param string $pdfData Scanned or mixed PDF bytes.
     *
     * @return string The derived searchable PDF bytes.
     */
    public function run(string $pdfData): string
    {
        try {
            $result = (new SearchableOverlay($this->ocr))
                ->generate($pdfData, new OverlayConfig(language: 'eng'));

            $this->logger->info('Overlay complete', [
                'pages' => $result->pageCount,
                'words' => $result->wordCount,
            ]);

            return $result->pdfData;
        } catch (\Throwable $e) {
            $this->logger->error('Overlay failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }
}

El registro lleva únicamente recuentos de páginas y de palabras. No lleva el texto reconocido ni los bytes del documento. El bloque catch vuelve a lanzar la excepción; no se traga el fallo.

Casos límite y aspectos a tener en cuenta

• Los extractores estructurado y de tablas consumen datos ya extraídos. No analizan un PDF, no ejecutan un modelo ni miden la precisión. La confianza es de paso o un valor predeterminado fijo.
• Los rectángulos delimitadores de tabla sintetizados son una subdivisión de cuadrícula uniforme, no una maquetación medida. Quien necesite geometría real debe obtenerla en otro lugar.
• La capa con búsqueda es un documento derivado. Cualquier firma digital existente queda invalidada; el estado de cumplimiento debe volver a validarse tras la capa.
• Cuando el backend de OCR no está disponible, las páginas afectadas aportan cero palabras en lugar de hacer fallar toda la ejecución de forma silenciosa: hay que comprobar el resultado por página.
• Una página que ya tiene una capa de texto nativa utilizable se omite de forma predeterminada. Desactive la omisión en la configuración si debe volver a aplicar OCR.
• La precisión del OCR depende por completo del backend suministrado, de la calidad de la entrada y de la sugerencia de idioma. NextPDF no afirma la precisión del reconocimiento ni la exhaustividad de la extracción.

Rendimiento

La extracción estructurada y de tablas es lineal respecto al tamaño de la entrada. El coste de la capa con búsqueda está dominado por el backend de OCR y por la rasterización del sidecar al DPI configurado; la sobrecarga de orquestación es pequeña. Las entradas de páginas y de tamaño están acotadas y fallan de forma cerrada en caso de desbordamiento. El perfil de reproducibilidad es structural: la extracción es determinista para una entrada fija, mientras que la salida de la capa depende del backend de OCR y puede variar entre backends o versiones.

Notas de seguridad

Los extractores son pasos de estructurado de solo lectura. La superficie de capa produce un documento derivado y acota el tamaño de la entrada y el número de páginas, fallando de forma cerrada en caso de desbordamiento. El backend de OCR es un punto de integración, no parte de la frontera de confianza; un despliegue lo elige y lo opera. En este módulo no ocurre ninguna operación criptográfica, por lo que no realiza ninguna afirmación FIPS.

Residencia de datos y mitigaciones de PII

La extracción estructurada y de tablas se ejecuta en proceso en el host. La orquestación de capas con búsqueda dirige un backend de OCR inyectado: dónde se ejecuta ese backend —en proceso, en un sidecar local o en un servicio remoto— y, por tanto, dónde se calculan y almacenan las imágenes del documento y el texto reconocido, es una responsabilidad del despliegue ajena a la frontera de la biblioteca. Si la entrada contiene datos personales, la capa de texto reconocido también los contendrá; trate el documento derivado en consecuencia.

Telemetría segura y depuración de registros

La biblioteca lanza excepciones tipadas con mensajes estructurales y no coloca bytes del documento ni texto reconocido en el texto de las excepciones. Un despliegue que registre alrededor de esta superficie debe registrar recuentos y configuración —como se muestra en el ejemplo de producción— y no debe registrar la carga útil del PDF en bruto ni el texto reconocido en los registros ni en un backend de APM.

Comportamiento en modo FIPS

En este módulo no ocurre ninguna operación criptográfica, por lo que no hay ningún comportamiento específico del modo FIPS.

Conformidad

Claim	Standard	Clause
El modo de renderizado de texto controla si los glifos se rellenan, se trazan o ninguno de los dos (la base del texto OCR invisible).	ISO 32000-2:2020	§9.3.3
Los operadores de mostrado de texto colocan glifos en el flujo de contenido.	ISO 32000-2:2020	§9.4
La jerarquía de estructura lógica asigna el contenido a un orden de lectura.	ISO 32000-2:2020	§14.7
La estructura etiquetada admite la reutilización de contenido.	ISO 32000-2:2020	§14.8
Los elementos de estructura de tabla describen filas y celdas.	ISO 32000-2:2020	§14.8
El árbol de estructura asigna el contenido a un orden de lectura.	ISO 32000-2:2020	§14.7

Todas las cláusulas están parafraseadas. NextPDF no reproduce texto normativo. Consulte el estándar publicado para conocer la redacción autorizada. NextPDF no realiza ninguna afirmación sobre la precisión del OCR ni sobre la exhaustividad de la extracción; esta página expone las estructuras producidas y la frontera de orquestación, no una garantía de calidad.

Contrato de comportamiento

• Los extractores estructurado y de tablas consumen datos ya extraídos; no analizan un PDF, no ejecutan un modelo ni miden la precisión. La confianza es de paso o un valor predeterminado fijo.
• Un filtro de esquema conserva únicamente los pares cuya clave coincide con un campo del esquema e informa de los campos obligatorios que faltan; los rectángulos delimitadores de tabla sintetizados son una subdivisión de cuadrícula uniforme, no una maquetación medida.
• La capa con búsqueda es un documento derivado: cualquier firma digital existente queda invalidada y el estado de cumplimiento debe volver a validarse.
• Cuando el backend de OCR no está disponible, las páginas afectadas aportan cero palabras en lugar de hacer fallar toda la ejecución de forma silenciosa; una página con una capa de texto nativa utilizable se omite de forma predeterminada.
• Las entradas de páginas y de tamaño están acotadas y fallan de forma cerrada en caso de desbordamiento. La extracción es determinista para una entrada fija; la salida de la capa depende del backend de OCR suministrado.

Límite de publicación

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

Alternativa de Core

NextPDF Core (Apache-2.0) no tiene orquestación de capas con búsqueda ni una superficie de estructurado validado frente a un esquema —ninguna; esta capacidad no tiene equivalente en el nivel Core—. El modelo AST de Core es la base del documento analizado, no una superficie de extracción ni de OCR.

Alternativa de Pro

NextPDF Pro incluye extracción estructural basada en AST sobre un documento ya analizado; no proporciona el estructurado de pares clave-valor validado frente a un esquema, la reconstrucción de tablas a partir de cuadrículas en bruto ni la orquestación de capas con búsqueda respaldadas por OCR. Estas se incluyen únicamente en el paquete nextpdf/enterprise.

Nota sobre la frontera de Enterprise

Los extractores estructurado/de tablas y el orquestador de capas se describen a nivel de comportamiento. La rasterización real y la inyección de texto invisible se ejecutan en un proceso sidecar independiente; los detalles internos del sidecar, el modelo de OCR y cualquier detalle de orquestación interno quedan fuera del alcance de la superficie pública. El backend de OCR es un contrato inyectado suministrado por el despliegue.

Frontera de despliegue

El despliegue suministra y opera el backend de OCR y elige dónde se calcula el OCR (en proceso, en un sidecar local o en un servicio remoto) y, por tanto, dónde se calculan y almacenan las imágenes del documento y el texto reconocido. NextPDF Enterprise orquesta el flujo de trabajo y produce los metadatos del resultado; no incorpora un modelo de OCR ni garantiza la precisión del reconocimiento ni la exhaustividad de la extracción.

Frontera de cumplimiento legal

No se aplica ninguna restricción de control de exportaciones a la superficie de Intelligence. La biblioteca no afirma ninguna garantía sobre la precisión del OCR ni sobre la exhaustividad de la extracción, ni ningún estado de cumplimiento normativo. Esta documentación no es una opinión legal; consulte a sus propios asesores de cumplimiento y legales.

Consulta también

• Referencia de Intelligence: la referencia profunda de la API de esta capacidad.
• Extracción de Pro: bloques de cita estructurales basados en AST.
• Privacidad: detección de PII sobre el texto extraído.
• NextPDF Enterprise: la superficie completa de funciones de Enterprise.
• Core AST: el modelo del documento analizado.
• Tagged PDF · OCR · Searchable PDF: términos del glosario.