NextPDF Connect(Pro)에서 텍스트 콘텐츠 추출

한눈에 보기

기존 PDF에서 인덱싱, 분석 또는 후속 처리에 사용할 텍스트를 추출합니다. 해당 도구는 extract_text입니다. Pro 도구 공급자를 기준으로 다시 검증되며, 공급자는 프로토콜 이름 extract_text로 new ExtractTextTool()을 등록합니다. extract_text는 Pro 등급 도구입니다. 서버는 부팅 시 class_exists()로 이 도구를 탐지하고, Pro 패키지가 설치된 경우에만 등록합니다. 일반 출력, 페이지 범위, 페이지 단위로 분할된 구조화 출력을 지원합니다.

설치

composer require nextpdf/server
composer require nextpdf/pro

전송 계층을 바인딩합니다. 도구를 사용하기 전에 diagnostic.capabilities로 도구 사용 가능 여부를 확인합니다.

개념 개요

추출 과정에서는 콘텐츠 스트림의 텍스트 표시 연산자를 스트림 순서대로 읽습니다(ISO 32000-2 §9.4). 출력은 인코딩된 읽기 순서를 반영합니다(ISO 32000-2 §9.10). 텍스트 레이어가 없는 스캔된 PDF는 텍스트가 거의 나오지 않거나 전혀 나오지 않습니다. 이는 원본의 속성이며 도구 결함이 아닙니다. format: "plain"은 단일 문자열을 반환합니다. format: "structured"는 문자 수가 포함된 페이지별 객체를 반환합니다. page_range는 처리할 페이지를 제한합니다.

API 표면

도구	등급	역할	위험 등급
extract_text	Pro	텍스트 추출(일반 / 구조화 / 범위)	안전
parse_pdf	Core(환경 변수로 게이트됨)	하위 수준 구조(페이지 수, 메타데이터)	안전

도구 이름은 레지스트리에서 사용하는 프로토콜 이름입니다. 도구 카탈로그가 기준 카탈로그입니다. 사용할 수 있는 도구는 설치된 등급에 따라 달라집니다.

코드 예제 — 빠른 시작

1. extract_text를 source(서버가 읽을 수 있는 경로)와 format: "plain"으로 실행합니다.
2. 하위 집합을 추출하려면 extract_text를 page_range: "1-3"으로 실행합니다.
3. 페이지 단위로 분할된 출력을 얻으려면 extract_text를 format: "structured"로 실행합니다.

코드 예제 — 프로덕션

범위를 요청하기 전에 페이지 수를 파악하려면 parse_pdf(또는 앞서 실행한 범위 제한 없는 extract_text)를 사용합니다. RAG/인덱싱에서는 각 페이지를 독립적으로 청크할 수 있도록 format: "structured"를 권장합니다. 암호화된 원본에는 password 매개변수를 제공합니다. 문자 수는 바이트가 아니라 UTF-8 코드 포인트 수입니다.

경계 사례 및 주의 사항

• 원본 누락. 잘못된 경로를 전달하면 파일을 찾을 수 없음 오류가 반환됩니다. 서버가 읽을 수 있는 절대 경로를 사용합니다.
• 스캔된 PDF. 텍스트 레이어가 없으면 텍스트가 비어 있거나 거의 없습니다. 원본을 먼저 OCR 처리합니다.
• 범위를 벗어난 페이지. 문서의 실제 페이지 범위를 벗어난 요청은 실제 페이지 수와 함께 거부됩니다.
• 암호화된 원본. password 매개변수를 제공합니다.
• Pro 부재. Core만 설치된 경우 extract_text는 등록되지 않습니다. diagnostic.capabilities로 탐지합니다.

성능

추출 비용은 문서 크기에 따라 늘어나며, 예산은 대용량 입력을 허용하도록 설정되어 있습니다. 이 도구는 PDF가 아니라 텍스트를 반환하므로 생성되는 모든 산출물의 프로파일은 structural입니다.

보안 참고 사항

추출된 텍스트에는 민감한 콘텐츠가 포함될 수 있습니다. 결과는 기밀로 취급하고 신뢰할 수 있는 채널을 통해서만 반환합니다. 이 도구는 파일 시스템에 쓰지 않습니다. 서버 권한으로 원본 경로만 읽으므로 호출자가 전달할 수 있는 경로를 제한합니다.

적합성

진술	규격	조항	reference_id
텍스트는 텍스트 연산자를 통해 스트림 순서대로 표시됩니다.	ISO 32000-2	§9.4
추출은 인코딩된 읽기 순서를 반영합니다.	ISO 32000-2	§9.10

이 레시피는 태그가 없는 문서에서 추출된 텍스트가 논리적 읽기 순서를 충실히 따른다고 주장하지 않습니다. 해당 순서는 인코딩된 순서입니다.

상업적 맥락

extract_text는 Pro 등급 도구이며, 서버 부팅 시 Pro 패키지가 확인된 경우에만 등록됩니다.

전송 계층 가용성

전송 계층	사용 가능	참고
MCP(stdio)	예(Pro)	대용량 텍스트는 stdio 프레임 크기를 키웁니다.
REST	예(Pro)	지원되는 환경에서는 대용량 결과를 스트리밍합니다.
gRPC	예(Pro)	대용량 텍스트에는 메시지 크기 제한이 적용됩니다.

HITL 위험 등급

extract_text는 안전(읽기 전용, 부작용 없음)하며 게이트를 거치지 않습니다.

확인 게이트 JSON 봉투

읽기 전용 추출은 게이트를 거치지 않습니다:

{ "allowed": true }

함께 보기

• PDF 양식 채우기
• 디지털 서명
• 도구 카탈로그