Extraction — 심층 참조

한눈에 보기

이 페이지는 NextPDF\Pro\Extraction의 계약 수준 참조입니다. 이 모듈에는 다섯 개의 공개 심볼이 있습니다. 두 개의 추출기(CitedTextExtractor, CitedTableExtractor)와 세 개의 불변 값 객체(CitedTextBlock, CitedTableBlock, CitedTableCell)입니다. 두 추출기 모두 파싱된 NextPDF\Ast\AstDocument를 소비하며, 어느 쪽도 원시 PDF 바이트를 읽지 않습니다. 추출은 결정론적이고 구조적입니다. 이 모듈 어디에도 의미, 임베딩, 랭킹 단계는 존재하지 않습니다. 작업 중심 관점은 기능 페이지에 있습니다.

가용성 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)로 제공되며 Pro 티어 라이선스 봉투로 활성화됩니다. 해당 자격 증명이 없는 배포에서는 이 기능의 클래스가 로드되지 않습니다. 에디션 비교 및 라이선스 받기.

이 모듈을 게이트하는 런타임 기능 플래그는 없습니다. nextpdf/pro가 설치되고 라이선스가 있으면 언제든 클래스를 사용할 수 있습니다.

공개 API 표면

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
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

동작 계약

• Node selection. CitedTextExtractor는 유형이 Paragraph, Heading, ListItem, TableCell, Code, Annotation 중 하나인 노드에 대해 블록을 방출합니다. 텍스트가 null인 노드는 건너뜁니다. 노드는 트리밍된 텍스트 길이가 최소 minChunkLength(기본값 10) 이상일 때만 방출됩니다. 모든 길이는 바이트 길이입니다.
• Traversal order. 순회는 문서 루트에서 깊이 우선으로 진행됩니다. 자격 있는 노드는 그 자식이 방문되기 전에 방출됩니다. chunkIndex는 문서 전체 순회에 걸쳐 증가하며 매 extract() 호출마다 0으로 재설정됩니다.
• Chunking. maxTokensPerChunk가 설정되지 않으면 각 노드는 한 블록을 산출합니다. 설정되면 maxTokensPerChunk * 4바이트보다 긴 텍스트가 분할됩니다. 분할기는 선호 절단점에서 최대 200바이트 역방향으로 스캔해 찾은 문장 경계(줄바꿈, 또는 마침표 뒤 공백)를 우선합니다. 그렇지 않으면 예산 지점에서 강제로 끊습니다. 절단 후의 공백은 건너뛰며, 빈 청크는 버립니다.
• Citation anchor. 각 블록의 CitationAnchor는 노드 id, 페이지 인덱스, 바운딩 박스, 신뢰도, 그리고 null 콘텐츠 해시를 담습니다. 바운딩 박스가 없는 노드는 공유된 넓이 0 센티넬 BoundingBox(0, 0, 0, 0)을 받으므로, 앵커는 항상 구조적으로 유효합니다.
• Text confidence. 신뢰도는 노드의 confidence 속성이 int나 float일 때 이를 읽으며, 기본값은 1.0입니다. 숫자가 아닌 속성 값은 기본값으로 되돌아갑니다.
• Block metadata. metadata는 항상 nodeType과 pageIndex를 담습니다. structType, lang, alt는 노드에 존재할 때 복사됩니다. 노드가 untagged 속성을 가지면 untagged가 true로 설정됩니다.
• Table selection. CitedTableExtractor는 가장 바깥쪽 Table 노드만을 문서 순서로 수집합니다. Table 노드가 한 번 처리되면 그 하위 트리는 다시 검사되지 않으며, 중첩 테이블은 지원되지 않습니다.
• Matrix shape. 행은 TableRow 자식에서, 셀은 그 TableCell 자식에서 옵니다. 다른 자식 유형은 무시됩니다. colCount는 모든 행에 걸친 최대 셀 개수입니다. 짧은 행은 합성 셀(빈 nodeId, null 텍스트, null bbox, 테이블의 페이지 인덱스, 신뢰도 0.0)로 colCount에 맞춰 오른쪽으로 채워집니다. 행이 없거나 열이 없는 테이블은 블록을 산출하지 않습니다.
• Cell confidence. 실제 셀의 신뢰도는 그 confidence 속성이 int나 float일 때 이를 읽으며, 기본값은 0.8입니다. 텍스트 블록은 기본값 1.0, 테이블 셀은 기본값 0.8입니다.
• Structure mapping. 순회되는 계층은 PDF 논리 구조 모델(ISO 32000-2:2020 §14.7)에 매핑됩니다. 소스가 태그된 경우 테이블 행은 TR 구조 요소(§14.8)에 매핑됩니다.

엣지 케이스 및 실패 모드

• 이 표면의 어떤 것도 예외를 던지지 않습니다. 두 extract() 메서드 모두 자격 있는 노드가 없는 문서에 대해 빈 리스트를 반환합니다.
• 넓이 0 바운딩 박스는 공유 싱글턴 센티넬입니다. 실제 영역이 필요한 호출자는 이를 명시적으로 탐지해야 합니다: 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 노드는 §14.8의 Table/TR 구조 요소에 대응합니다. 추출 품질은 태깅 품질에 의해 한정됩니다. 태그되지 않은 콘텐츠는 더 적거나 더 거친 노드를 산출합니다.

이것들은 구조적 정렬 진술이며, 적합성 테스트 결과가 아닙니다. NextPDF는 어떠한 인증도 보유하지 않으며 어떠한 인증도 부여하지 않습니다. 이 모듈은 자체적인 적합성 주장을 하지 않으며, Core AST 하위 시스템이 산출한 구조를 그대로 소비합니다.

개발 노트

• 하나의 CitedTextExtractor 인스턴스를 여러 문서에 걸쳐 순차적으로 재사용하는 것은 안전합니다. extract()는 각 순회 전에 chunkIndex를 재설정합니다.
• 노이즈 노드(페이지 번호, 흩어진 글리프 런)를 필터링하려면 청킹 후가 아니라 청킹 전에 minChunkLength를 조정하세요.
• CJK 및 기타 멀티바이트 스크립트에서는 바이트 기반 휴리스틱이 토큰을 과대 계산하므로, maxTokensPerChunk를 그에 맞춰 조정하세요.
• CitedTableBlock::toArray()와 CitedTableCell::toArray()는 JSON 파이프라인을 위해 snake_case 키를 방출합니다. CitedTextBlock에는 직렬화기가 없으니 필드를 직접 인코딩하세요.
• 이 표면에서 CitationAnchor의 contentHash 필드는 항상 null입니다. 파이프라인이 필요로 할 때 콘텐츠 해시를 다운스트림에서 계산하세요.

게시 경계

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

함께 보기

• Extraction — 기능 페이지
• Classifier — 심층 참조 (Pro)
• Core AST