Extracción

De un vistazo

NextPDF\Pro\Extraction recorre un AST de documento analizado y produce bloques de texto y de tablas, cada uno con un anclaje de citación (índice de página, caja delimitadora, referencia de nodo). Es un extractor estructural determinista para pipelines de atribución de origen, no un motor de búsqueda ni de comprensión.

Disponibilidad y licencias

Esta función se incluye en NextPDF Pro (nextpdf/pro) y se activa con un envoltorio de licencia de nivel Pro. Un despliegue sin esa habilitación no carga las clases de la función. Ningún indicador de capacidad en tiempo de ejecución restringe este módulo; las clases de Extraction están disponibles siempre que nextpdf/pro esté instalado. Compare las ediciones y obtenga una licencia.

Instalación

composer require nextpdf/pro:^3

Descripción conceptual

Ambos extractores toman un NextPDF\Ast\AstDocument — un árbol de documento analizado producido por el subsistema AST de Core. No analizan ellos mismos los bytes de PDF en bruto; el AST es el límite de entrada.

• CitedTextExtractor recorre el árbol y emite un CitedTextBlock por cada nodo de texto sustancial (párrafo, encabezado, elemento de lista, celda de tabla, código, anotación) cuyo texto recortado alcanza una longitud mínima. Un presupuesto de tokens opcional divide el texto largo en los límites de las oraciones. Cada bloque lleva un CitationAnchor con el id de nodo, el índice de página, la caja delimitadora y una confianza leída del nodo (predeterminada 1.0). Los nodos sin caja delimitadora reciben una caja centinela de área cero para que el anclaje sea siempre válido.
• CitedTableExtractor encuentra los nodos Table, lee sus filas y celdas, y construye una matriz rectangular por filas rellenada hasta la fila más ancha. No se desciende recursivamente en las tablas anidadas. La confianza de la celda toma por defecto 0.8 a menos que el nodo lleve un valor explícito.

La jerarquía estructural que recorren estos extractores se corresponde con el modelo de estructura lógica de PDF (ISO 32000-2:2020 §14.7) y los elementos de estructura de tabla (§14.8) cuando el documento de origen está etiquetado.

Por qué funciona así

El extractor toma un AST analizado como su límite de entrada, no bytes de PDF en bruto, de modo que el riesgo de análisis se mantiene separado de la lógica de extracción. La confianza se lee directamente del nodo del AST y se transmite sin cambios; el módulo nunca la calcula, clasifica ni mejora. La salida permanece en orden de documento, no en orden de relevancia, porque la atribución de origen necesita una procedencia verificable en lugar de una conjetura heurística que el extractor no puede defender. Cada bloque lleva un anclaje de citación — id de nodo, índice de página, caja delimitadora — para que un pipeline posterior pueda rastrear cada cita hasta su origen. Esto mantiene deliberadamente el módulo como un extractor estructural determinista: informa lo que el AST afirma y se niega a inventar cualquier cosa que el documento no establezca.

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

Contrato de comportamiento

• Entrada. Un NextPDF\Ast\AstDocument. El módulo no acepta bytes de PDF en bruto; produzca primero el AST con el subsistema AST de Core.
• Salida. list<CitedTextBlock> o list<CitedTableBlock> en orden de documento.
• La confianza es de paso. Se lee de los atributos del nodo del AST (o de un valor predeterminado fijo). Este módulo no calcula ni mejora la confianza.
• Sin procesamiento semántico. El extractor no realiza ninguna incrustación, similitud vectorial, clasificación ni comprensión de documentos. El ordenamiento de la salida es el orden de documento, no el orden de relevancia.
• Determinismo. Para un AST idéntico, los bloques, anclajes e índices de fragmento producidos son estables.

Superficie pública de la API

Tipo	Clase	Miembros clave
NextPDF\Pro\Extraction\CitedTextExtractor	final class	__construct(?int $maxTokensPerChunk = null, int $minChunkLength = 10), extract(AstDocument $document): list<CitedTextBlock>
NextPDF\Pro\Extraction\CitedTableExtractor	final class	extract(AstDocument $document): list<CitedTableBlock>
NextPDF\Pro\Extraction\CitedTextBlock	final readonly class	string $text, CitationAnchor $anchor, float $confidence, int $chunkIndex, array $metadata, estimatedTokens(): int
NextPDF\Pro\Extraction\CitedTableBlock	final readonly class	string $nodeId, int $pageIndex, int $rowCount, int $colCount, array $matrix
NextPDF\Pro\Extraction\CitedTableCell	final readonly class	int $row, int $col, ?string $textContent, float $confidence

Ejemplo de código — Inicio rápido

<?php

declare(strict_types=1);

use NextPDF\Pro\Extraction\CitedTextExtractor;

/** @var \NextPDF\Ast\AstDocument $ast */
$blocks = (new CitedTextExtractor())->extract($ast);

foreach ($blocks as $block) {
    printf(
        "p%d chunk#%d (%d tokens): %s\n",
        $block->anchor->pageIndex,
        $block->chunkIndex,
        $block->estimatedTokens(),
        $block->text,
    );
}

Ejemplo de código — Producción

<?php

declare(strict_types=1);

use NextPDF\Pro\Extraction\CitedTextExtractor;

function chunkForCitation(\NextPDF\Ast\AstDocument $ast): array
{
    // Token-bounded chunks for downstream citation storage.
    $extractor = new CitedTextExtractor(
        maxTokensPerChunk: 400,
        minChunkLength: 16,
    );

    $rows = [];
    foreach ($extractor->extract($ast) as $block) {
        $rows[] = [
            'text'      => $block->text,
            'page'      => $block->anchor->pageIndex,
            'node_id'   => $block->anchor->nodeId,
            'chunk'     => $block->chunkIndex,
        ];
    }

    return $rows;
}

Casos límite y trampas

• Los documentos sin etiquetar o mal etiquetados producen menos nodos de texto; la calidad del AST es el límite superior de la calidad de la extracción.
• Los nodos sin caja delimitadora reciben una caja centinela de área cero BoundingBox(0,0,0,0) — detéctela mediante width === 0.0 && height === 0.0 si se requiere una región real.
• Las tablas anidadas no se recorren recursivamente; solo se emite el nodo Table más externo.
• Las filas cortas se rellenan con celdas sintéticas de confianza cero para que cada fila tenga el mismo número de columnas.

Residencia de datos y mitigaciones de PII

Este módulo procesa cualquier texto que contenga el AST suministrado y lo devuelve sin cambios dentro de los bloques. No realiza llamadas de red, ni almacenamiento externo, ni registro del contenido extraído. El tratamiento de PII, la redacción y los controles de residencia son responsabilidad del llamante sobre los bloques producidos. Consulte la guía de tratamiento de PII de Core.

Telemetría segura y depuración de registros

El extractor no emite telemetría y no registra el texto extraído. Si un llamante lo envuelve con registro, depure text, metadata y cualquier contenido de celda antes de emitir registros.

Rendimiento

La extracción es un único recorrido del árbol, lineal respecto al número de nodos. La división en fragmentos añade trabajo proporcional a la longitud del texto. Consulte performance_budget.

Notas de seguridad

La entrada es un AST ya analizado, de modo que este módulo no analiza por sí mismo bytes de PDF hostiles. Trate el texto extraído como no confiable y escápelo para su destino.

Conformidad

Declaración	Cláusula del estándar	Estado
Recorrido de nodos de estructura lógica	ISO 32000-2:2020 §14.7	Verificado (conjunto unitario, AST etiquetado)
Extracción de filas/celdas de tabla	ISO 32000-2:2020 §14.8	Verificado (conjunto unitario)
Búsqueda semántica / incrustaciones	—	No admitido (fuera del alcance)

Alternativa / opción de Core

El subsistema AST de Core produce el AstDocument que se consume aquí; no existe ningún equivalente en Core para la extracción de bloques de citación en sí. Consulte /modules/core/ast/.

Nota sobre el límite de Enterprise

Este módulo es únicamente un extractor estructural. No realiza búsqueda semántica, incrustación vectorial, clasificación por similitud ni inteligencia de documentos. 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 compatible. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivos de runbook y los prefijos de tickets quedan fuera del alcance.

Véase también

• Referencia de Extraction
• Classifier
• Diff
• Core AST