Извлечение

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

NextPDF\Pro\Extraction обходит разобранный AST документа и формирует блоки текста и таблиц, каждый из которых несёт якорь цитирования (индекс страницы, ограничивающий прямоугольник, ссылку на узел). Это детерминированный структурный извлекатель для конвейеров атрибуции источников, а не движок поиска или понимания.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без этого права доступа не загружает классы возможности. Ни один флаг возможности времени выполнения не ограничивает этот модуль; классы Extraction доступны всегда, когда установлен nextpdf/pro. Сравнить редакции и получить лицензию.

Установка

composer require nextpdf/pro:^3

Концептуальный обзор

Оба извлекателя принимают NextPDF\Ast\AstDocument — дерево разобранного документа, формируемое подсистемой AST из Core. Они не разбирают исходные байты PDF самостоятельно; AST является границей ввода.

• CitedTextExtractor обходит дерево и выводит CitedTextBlock для каждого существенного текстового узла (абзац, заголовок, элемент списка, ячейка таблицы, код, аннотация), очищенный текст которого достигает минимальной длины. Необязательный бюджет токенов разбивает длинный текст на границах предложений. Каждый блок несёт CitationAnchor с идентификатором узла, индексом страницы, ограничивающим прямоугольником и уверенностью, считанной из узла (по умолчанию 1.0). Узлы без ограничивающего прямоугольника получают служебный прямоугольник нулевой площади, поэтому якорь всегда действителен.
• CitedTableExtractor находит узлы Table, читает их строки и ячейки и строит прямоугольную матрицу в построчном порядке, дополненную до самой широкой строки. Во вложенные таблицы рекурсия не выполняется. Уверенность ячейки по умолчанию равна 0.8, если узел не несёт явного значения.

Структурная иерархия, которую обходят эти извлекатели, соответствует модели логической структуры PDF (ISO 32000-2:2020 §14.7) и элементам структуры таблиц (§14.8), когда исходный документ размечен.

Почему это работает именно так

Извлекатель принимает разобранный AST как границу ввода, а не исходные байты PDF, поэтому риск разбора остаётся отделённым от логики извлечения. Уверенность считывается прямо из узла AST и передаётся без изменений; модуль никогда её не вычисляет, не ранжирует и не улучшает. Вывод остаётся в порядке документа, а не в порядке релевантности, потому что атрибуции источников нужно проверяемое происхождение, а не эвристическая догадка, которую извлекатель не может защитить. Каждый блок несёт якорь цитирования — идентификатор узла, индекс страницы, ограничивающий прямоугольник — поэтому нижестоящий конвейер может проследить каждую цитату до её источника. Это намеренно оставляет модуль детерминированным структурным извлекателем: он сообщает то, что утверждает AST, и отказывается выдумывать то, что документ не заявляет.

Предыстория проектирования: API, который отказывается угадывать.

Контракт поведения

• Вход. NextPDF\Ast\AstDocument. Модуль не принимает исходные байты PDF; сначала сформируйте AST с помощью подсистемы AST из Core.
• Выход. list<CitedTextBlock> или list<CitedTableBlock> в порядке документа.
• Уверенность передаётся как есть. Она считывается из атрибутов узла AST (или из фиксированного значения по умолчанию). Этот модуль не вычисляет и не улучшает уверенность.
• Без семантической обработки. Извлекатель не выполняет встраивание, поиск по векторной близости, ранжирование или понимание документов. Порядок вывода — это порядок документа, а не порядок релевантности.
• Детерминированность. Для одинакового AST формируемые блоки, якоря и индексы фрагментов стабильны.

Поверхность публичного API

Тип	Вид	Ключевые члены
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

Пример кода — быстрый старт

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

Пример кода — продакшн

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

Граничные случаи и подводные камни

• Неразмеченные или плохо размеченные документы дают меньше текстовых узлов; качество AST — это верхняя граница качества извлечения.
• Узлы без ограничивающего прямоугольника получают служебный прямоугольник нулевой площади BoundingBox(0,0,0,0) — выявляйте его через width === 0.0 && height === 0.0, если нужна реальная область.
• Во вложенные таблицы рекурсия не выполняется; выводится только самый внешний узел Table.
• Короткие строки дополняются синтетическими ячейками с нулевой уверенностью, чтобы у каждой строки было одинаковое число столбцов.

Размещение данных и меры по защите ПДн

Этот модуль обрабатывает любой текст, который содержит переданный AST, и возвращает его без изменений внутри блоков. Он не выполняет сетевых вызовов, внешнего хранения и журналирования извлечённого содержимого. Обработка ПДн, маскирование и меры по размещению данных — ответственность вызывающего кода для формируемых блоков. См. руководство по обработке ПДн из Core.

Безопасная телеметрия и очистка журналов

Извлекатель не отправляет телеметрию и не записывает в журнал извлечённый текст. Если вызывающий код оборачивает его журналированием, очищайте text, metadata и любое содержимое ячеек перед выводом журналов.

Производительность

Извлечение — это один обход дерева, линейный по числу узлов. Разбиение на фрагменты добавляет работу, пропорциональную длине текста. См. performance_budget.

Замечания по безопасности

Вход — это заранее разобранный AST, поэтому этот модуль не разбирает враждебные байты PDF самостоятельно. Относитесь к извлечённому тексту как к недоверенному и экранируйте его для его назначения.

Соответствие

Утверждение	Пункт стандарта	Статус
Обход узлов логической структуры	ISO 32000-2:2020 §14.7	Проверено (набор модульных тестов, размеченный AST)
Извлечение строк/ячеек таблицы	ISO 32000-2:2020 §14.8	Проверено (набор модульных тестов)
Семантический поиск / встраивания	—	Не поддерживается (вне области применения)

Резервный вариант Core / альтернатива

Подсистема AST из Core формирует AstDocument, потребляемый здесь; в Core нет аналога для самого извлечения блоков цитирования. См. /modules/core/ast/.

Примечание о границе Enterprise

Этот модуль — только структурный извлекатель. Он не выполняет семантический поиск, векторное встраивание, ранжирование по близости или интеллектуальный анализ документов. Эти возможности не входят в этот модуль и им не подразумеваются.

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

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

См. также

• Extraction reference
• Classifier
• Diff
• Core AST