Pro редакция

Extraction — глубокий справочник

Кратко

Эта страница — справочник контрактного уровня для NextPDF\Pro\Extraction. Модуль содержит пять публичных символов: два извлекателя (CitedTextExtractor, CitedTableExtractor) и три неизменяемых объекта-значения (CitedTextBlock, CitedTableBlock, CitedTableCell). Оба извлекателя потребляют разобранный NextPDF\Ast\AstDocument; ни один не читает сырые байты PDF. Извлечение детерминированно и структурно. Ни семантического, ни векторного (embedding), ни ранжирующего шага в этом модуле нет. Задачно-ориентированное описание находится на странице возможности.

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

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

Никакой runtime-флаг возможности не управляет этим модулем. Классы доступны всегда, когда nextpdf/pro установлен и лицензирован.

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

Символ	Параметры	Поведение по умолчанию	Возвращает	Бросает или завершается ошибкой	Примечания
`CitedTextExtractor::__construct()`	`?int $maxTokensPerChunk = null`, `int $minChunkLength = 10`	Нет бюджета токенов; обрезанный текст короче 10 байт отбрасывается	`CitedTextExtractor`	Не бросает	Бюджет `null` означает один блок на узел.
`CitedTextExtractor::extract()`	`AstDocument $document`	Обход в глубину; один блок на подходящий текстовый узел, деление по бюджету токенов	`list<CitedTextBlock>`	Не бросает	Детерминированно; `chunkIndex` сбрасывается в 0 при каждом вызове.
`CitedTextBlock`	пять readonly-полей	Неизменяемый объект-значение; метода-сериализатора нет	—	Не бросает	Ключи `metadata`: `nodeType`, `pageIndex`, плюс опциональные `structType`, `lang`, `alt`, `untagged`.
`CitedTextBlock::estimatedTokens()`	нет	`ceil(byte length / 4)`	`int`	Не бросает	Эвристика бюджета; не токенизатор.
`CitedTableExtractor::extract()`	`AstDocument $document`	Собирает внешние узлы `Table` в порядке документа	`list<CitedTableBlock>`	Не бросает	Никогда не спускается в поддерево таблицы.
`CitedTableBlock`	пять readonly-полей	Неизменяемая прямоугольная построчная матрица ячеек	—	Не бросает	Короткие строки дополняются справа во время извлечения.
`CitedTableBlock::toArray()`	нет	Сериализует в плоский массив с ключами snake_case	`array<string, mixed>`	Не бросает	Вложенные ячейки сериализуются через `CitedTableCell::toArray()`.
`CitedTableCell`	семь readonly-полей	Неизменяемая запись ячейки с координатами цитирования	—	Не бросает	Ячейки-заполнители несут пустой `nodeId` и уверенность 0.0.
`CitedTableCell::toArray()`	нет	Сериализует в плоский массив с ключами snake_case; `bbox` вкладывается или равен `null`	`array<string, mixed>`	Не бросает	—

final class CitedTextExtractor

public function __construct(
    private readonly ?int $maxTokensPerChunk = null,
    private readonly int $minChunkLength = 10,
)

public function extract(AstDocument $document): array

final class CitedTableExtractor

public function extract(AstDocument $document): array

final readonly class CitedTextBlock

public function __construct(
    public string $text,
    public CitationAnchor $anchor,
    public float $confidence,
    public int $chunkIndex,
    public array $metadata,
)

public function estimatedTokens(): int

final readonly class CitedTableBlock

public function __construct(
    public readonly string $nodeId,
    public readonly int    $pageIndex,
    public readonly int    $rowCount,
    public readonly int    $colCount,
    public readonly array  $matrix,
)

public function toArray(): array

final readonly class CitedTableCell

public function __construct(
    public readonly string       $nodeId,
    public readonly int          $row,
    public readonly int          $col,
    public readonly ?string      $textContent,
    public readonly ?BoundingBox $bbox,
    public readonly int          $pageIndex,
    public readonly float        $confidence,
)

public function toArray(): array

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

Выбор узлов. CitedTextExtractor выпускает блоки для узлов, тип которых Paragraph, Heading, ListItem, TableCell, Code или Annotation. Узел с null-текстом пропускается. Узел выпускается только тогда, когда длина его обрезанного текста не меньше minChunkLength (по умолчанию 10). Все длины — в байтах.
Порядок обхода. Обход выполняется в глубину от корня документа. Подходящий узел выпускается до посещения его дочерних узлов. chunkIndex увеличивается на протяжении всего обхода документа и сбрасывается в 0 при каждом вызове extract().
Разбиение на фрагменты. Если maxTokensPerChunk не задан, каждый узел даёт один блок. Если задан, текст длиннее maxTokensPerChunk * 4 байт делится. Разделитель предпочитает границу предложения — перевод строки или точку, за которой следует пробел, — находимую сканированием назад не более чем на 200 байт от предпочтительной точки среза. Иначе выполняется жёсткий разрыв по бюджету. Пробелы после среза пропускаются; пустые фрагменты отбрасываются.
Якорь цитирования. CitationAnchor каждого блока несёт id узла, индекс страницы, ограничивающий прямоугольник, уверенность и null-хеш содержимого. Узлы без ограничивающего прямоугольника получают общий часовой (sentinel) нулевой площади, BoundingBox(0, 0, 0, 0), поэтому якорь всегда структурно корректен.
Уверенность текста. Уверенность читает атрибут confidence узла, когда он int или float; по умолчанию 1.0. Нечисловые значения атрибута откатываются к значению по умолчанию.
Метаданные блока. metadata всегда несёт nodeType и pageIndex. structType, lang и alt копируются, когда присутствуют на узле. untagged устанавливается в true, когда узел несёт атрибут untagged.
Выбор таблиц. CitedTableExtractor собирает только внешние узлы Table, в порядке документа. Как только узел Table обработан, его поддерево повторно не исследуется; вложенные таблицы не поддерживаются.
Форма матрицы. Строки берутся из дочерних узлов TableRow; ячейки — из их дочерних узлов TableCell. Другие типы дочерних узлов игнорируются. colCount — максимальное число ячеек по всем строкам. Короткие строки дополняются справа до colCount синтетическими ячейками: пустой nodeId, null-текст, null-bbox, индекс страницы таблицы, уверенность 0.0. Таблица без строк или без столбцов не даёт блока.
Уверенность ячейки. Уверенность реальной ячейки читает её атрибут confidence, когда он int или float; по умолчанию 0.8. Текстовые блоки по умолчанию 1.0; ячейки таблиц по умолчанию 0.8.
Отображение структуры. Обойдённая иерархия отображается на модель логической структуры PDF (ISO 32000-2:2020 §14.7). Строки таблиц отображаются на структурный элемент TR (§14.8), когда источник тегирован.

Граничные случаи и режимы отказа

Ничто на этой поверхности не бросает. Оба метода extract() возвращают пустой список для документа без подходящих узлов.
Ограничивающий прямоугольник нулевой площади — общий одиночный часовой (singleton sentinel). Вызывающему коду, которому нужна реальная область, нужно обнаруживать его явно: width === 0.0 && height === 0.0.
Все проверки длины и деления основаны на байтах. Когда границы предложения нет в 200-байтовом окне, жёсткий разрыв может попасть внутрь многобайтовой последовательности UTF-8.
Цифра 4 байта на токен — лишь эвристика бюджетирования. Это не токенизатор и не соответствует токенизации какой-либо конкретной модели. estimatedTokens() использует ту же эвристику.
Числовая строка в атрибуте confidence не приводится к числу; применяется значение по умолчанию. Учитываются только значения int и float.
Пропуск пробелов после среза удаляет только обычные пробелы. Табуляции и переводы строк в начале фрагмента сохраняются.
Текст TableCell извлекается дважды по замыслу: как текстовые блоки через CitedTextExtractor и внутри матриц через CitedTableExtractor. Дедуплицируйте ниже по потоку, когда запускаете оба извлекателя над одним документом.
Ячейки-заполнители опознаются по пустому nodeId и уверенности 0.0. Реальная, но пустая ячейка сохраняет свой непустой nodeId.
В этом модуле не происходит криптографических операций, поэтому специфического поведения в режиме FIPS нет.

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

Когда исходный документ тегирован, AST зеркалирует иерархию логической структуры ISO 32000-2:2020 §14.7, а узлы Table/TableRow соответствуют структурным элементам Table/TR из §14.8. Качество извлечения ограничено качеством тегирования; нетегированное содержимое даёт меньше или более грубые узлы.

Это заявления о структурном соответствии, а не результаты тестов на соответствие. NextPDF не имеет сертификации и не выдаёт её. Этот модуль не делает собственных заявлений о соответствии; он потребляет любую структуру, которую произвела подсистема Core AST.

Заметки по разработке

Повторное использование одного экземпляра CitedTextExtractor для разных документов безопасно последовательно; extract() сбрасывает chunkIndex перед каждым обходом.
Настраивайте minChunkLength, чтобы отфильтровать шумовые узлы (номера страниц, случайные наборы глифов) до разбиения, а не после.
Для CJK и других многобайтовых письменностей байтовая эвристика переоценивает число токенов; выбирайте maxTokensPerChunk соответственно.
CitedTableBlock::toArray() и CitedTableCell::toArray() выдают ключи snake_case для JSON-конвейеров. У CitedTextBlock нет сериализатора; кодируйте его поля самостоятельно.
Поле contentHash объекта CitationAnchor всегда null на этой поверхности. Вычисляйте хеши содержимого ниже по потоку, когда они нужны конвейеру.

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

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