Pro 에디션

추출

한눈에 보기

NextPDF\Pro\Extraction은 파싱된 문서 AST를 순회하여 텍스트 및 표 블록을 생성하며, 각각은 인용 앵커(페이지 인덱스, 바운딩 박스, 노드 참조)를 담습니다. 이는 출처 귀속 파이프라인을 위한 결정적 구조 추출기이며, 검색이나 이해 엔진이 아닙니다.

가용성 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)로 제공되며 Pro 계층 라이선스 봉투로 활성화됩니다. 해당 엔타이틀먼트가 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 이 모듈을 게이트하는 런타임 기능 플래그는 없습니다. nextpdf/pro가 설치되어 있으면 언제나 Extraction 클래스를 사용할 수 있습니다. 에디션 비교 및 라이선스 받기.

설치

composer require nextpdf/pro:^3

개념 개요

두 추출기 모두 NextPDF\Ast\AstDocument — Core AST 하위 시스템이 생성한 파싱된 문서 트리 —를 받습니다. 이들은 원시 PDF 바이트를 직접 파싱하지 않습니다. AST가 입력 경계입니다.

**CitedTextExtractor**는 트리를 순회하여 트림된 텍스트가 최소 길이를 충족하는 각 실질적 텍스트 노드(문단, 헤딩, 목록 항목, 표 셀, 코드, 주석)에 대해 CitedTextBlock을 방출합니다. 선택적 토큰 예산은 긴 텍스트를 문장 경계에서 분할합니다. 각 블록은 노드 id, 페이지 인덱스, 바운딩 박스, 그리고 노드에서 읽은 신뢰도(기본 1.0)를 담은 CitationAnchor를 가집니다. 바운딩 박스가 없는 노드는 앵커가 항상 유효하도록 면적이 0인 센티넬 박스를 받습니다.
**CitedTableExtractor**는 Table 노드를 찾아 그 행과 셀을 읽고, 가장 넓은 행에 맞춰 패딩된 직사각형 행 우선 매트릭스를 빌드합니다. 중첩된 표는 재귀하지 않습니다. 노드가 명시적 값을 담지 않는 한 셀 신뢰도는 기본 0.8입니다.

이 추출기들이 순회하는 구조 계층은, 소스 문서가 태그된 경우 PDF 논리 구조 모델(ISO 32000-2:2020 §14.7)과 표 구조 요소(§14.8)에 대응합니다.

이렇게 동작하는 이유

추출기는 입력 경계로 원시 PDF 바이트가 아니라 파싱된 AST를 받으므로, 파싱 위험이 추출 로직과 분리된 채 유지됩니다. 신뢰도는 AST 노드에서 그대로 읽혀 변경 없이 전달됩니다. 모듈은 이를 계산하거나, 랭킹하거나, 개선하지 않습니다. 출력은 관련성 순서가 아니라 문서 순서를 유지합니다. 출처 귀속에는 추출기가 방어할 수 없는 휴리스틱 추측이 아니라 검증 가능한 출처가 필요하기 때문입니다. 모든 블록은 인용 앵커(노드 id, 페이지 인덱스, 바운딩 박스)를 담고 있어, 다운스트림 파이프라인이 각 인용을 그 기원까지 추적할 수 있습니다. 이는 모듈을 의도적으로 결정적 구조 추출기로 유지합니다. 모듈은 AST가 단언하는 것을 보고하고 문서가 명시하지 않은 것은 무엇도 지어내기를 거부합니다.

설계 배경: 추측을 거부하는 API.

동작 계약

입력. NextPDF\Ast\AstDocument입니다. 모듈은 원시 PDF 바이트를 받지 않습니다. 먼저 Core AST 하위 시스템으로 AST를 생성하십시오.
출력. 문서 순서의 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 품질이 추출 품질의 상한입니다.
바운딩 박스가 없는 노드는 면적이 0인 센티넬 BoundingBox(0,0,0,0)을 받습니다 — 실제 영역이 필요하면 width === 0.0 && height === 0.0으로 탐지하십시오.
중첩된 표는 재귀하지 않습니다. 가장 바깥쪽 Table 노드만 방출됩니다.
짧은 행은 합성된 신뢰도 0 셀로 패딩되어 모든 행이 동일한 열 수를 가집니다.

데이터 레지던시 및 PII 완화

이 모듈은 제공된 AST가 담은 텍스트를 그대로 처리하여 블록 안에 변경 없이 반환합니다. 네트워크 호출, 외부 저장, 추출된 콘텐츠의 로깅을 수행하지 않습니다. PII 처리, 마스킹, 레지던시 통제는 생성된 블록에 대해 호출자의 책임입니다. Core PII 처리 지침을 참조하십시오.

안전한 텔레메트리 및 로그 스크러빙

추출기는 텔레메트리를 방출하지 않으며 추출된 텍스트를 로그에 기록하지 않습니다. 호출자가 로깅으로 감싸는 경우, 로그를 방출하기 전에 text, metadata, 그리고 모든 셀 콘텐츠를 스크러빙하십시오.

성능

추출은 단일 트리 순회이며 노드 수에 선형적입니다. 청크 분할은 텍스트 길이에 비례하는 작업을 추가합니다. performance_budget를 참조하십시오.

보안 참고

입력은 미리 파싱된 AST이므로, 이 모듈은 적대적 PDF 바이트를 직접 파싱하지 않습니다. 추출된 텍스트는 신뢰할 수 없는 것으로 취급하고 목적지에 맞게 이스케이프하십시오.

적합성

주장	표준 조항	상태
논리 구조 노드 순회	ISO 32000-2:2020 §14.7	검증됨 (단위 스위트, 태그된 AST)
표 행/셀 추출	ISO 32000-2:2020 §14.8	검증됨 (단위 스위트)
시맨틱 검색 / 임베딩	—	미지원 (범위 밖)

Core 폴백 / 대안

Core AST 하위 시스템이 여기에서 소비되는 AstDocument를 생성합니다. 인용 블록 추출 자체에 대한 Core 등가물은 없습니다. /modules/core/ast/를 참조하십시오.

Enterprise 경계 참고

이 모듈은 구조 추출기일 뿐입니다. 시맨틱 검색, 벡터 임베딩, 유사도 랭킹, 문서 인텔리전스를 수행하지 않습니다. 그러한 기능은 이 모듈의 일부가 아니며 이 모듈이 함의하지도 않습니다.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위 밖입니다.