노드 사용법 익히기 - PDF 텍스트 리더(PDF Text Reader) 노드

이 튜토리얼에서는 에이전트리아(Agentria) 의 PDF 텍스트 리더(PDF Text Reader) 노드 사용법을 안내합니다. PDF 텍스트 리더 노드는 PDF 파일에서 텍스트 콘텐츠만 추출하여 문자열로 반환하고, 각 페이지가 그 문자열에서 차지하는 구간 정보를 함께 제공합니다.

이 튜토리얼에서는 PDF 파일을 업로드하면 텍스트를 추출해 반환하는 'PDF 텍스트 추출' 워크플로를 완성합니다.

사전 준비

에이전트리아 캔버스 진입 방법은 🔗3단계 핵심 가이드를 참고하시기 바랍니다.

PDF 파일 한 개를 미리 준비합니다. 페이지 구간 정보를 확인하기 위해 두 페이지 이상인 파일을 권장합니다.

준비한 파일에 텍스트 레이어(Text Layer)가 있는지 먼저 확인하시기 바랍니다. PDF 텍스트 리더 노드가 읽는 대상은 파일 안에 문자 정보로 저장된 텍스트 레이어입니다. PDF 뷰어에서 문서의 글자를 드래그해 선택 영역이 잡히거나 문서 내 검색으로 단어가 찾아지면 텍스트 레이어가 있는 파일입니다. 선택도 검색도 되지 않는다면 페이지가 이미지만으로 이루어진 파일이므로 텍스트가 추출되지 않습니다.

텍스트 레이어가 없는 파일을 사용하면 노드가 오류 없이 빈 문자열을 반환해 원인을 찾기 어렵습니다. 관련 내용은 아래 참고: 추출된 텍스트의 특징에서 자세히 설명합니다.

이 튜토리얼을 완료하면 다음을 수행할 수 있습니다.

1. PDF 텍스트 리더 노드의 pdf 항목에 파일 타입 변수를 연결할 수 있습니다.

2. 추출된 텍스트를 full_text로 받아 다른 노드에서 참조할 수 있습니다.

3. page_infos로 각 페이지가 full_text에서 차지하는 구간을 확인할 수 있습니다.

4. 노드 테스트로 추출 결과를 즉시 확인할 수 있습니다.

5. 어빌리티 테스트로 워크플로 전체 동작을 확인할 수 있습니다.

워크플로 개요

이 튜토리얼의 핵심은 PDF 텍스트 리더 노드입니다.

PDF 텍스트 리더 노드는 연결된 PDF 파일에서 텍스트 콘텐츠를 추출해 full_text 하나의 문자열로 반환합니다. 여기에 더해 page_infos로 각 페이지가 그 문자열의 어느 구간에 해당하는지 알려주므로, 특정 페이지의 텍스트만 골라 쓸 수도 있습니다.

PDF 텍스트 리더 노드는 '파일 처리 도구' 카테고리에 속합니다. 처리할 파일 형식에 따라 아래 노드를 함께 활용할 수 있습니다.

1단계: 인풋 변수 선언 (시작 노드)

시작 노드를 더블 클릭하여 노드 편집기(Node Editor)를 엽니다. 어빌리티 캔버스에서 시작 노드는 Ability Input으로 표시됩니다.

입력 변수 영역에서 아래 변수를 추가하고 저장을 클릭합니다.

pdf_file은 다음 단계에서 PDF 텍스트 리더 노드의 입력으로 연결할 변수입니다.

2단계: PDF 텍스트 리더 노드 추가

캔버스에서 노드 추가(Add Node)를 클릭하고, 파일 처리 도구 카테고리에서 PDF 텍스트 리더 노드를 드래그 앤 드롭으로 캔버스에 배치합니다.

3단계: PDF 텍스트 리더 노드 설정

New PDF 텍스트 리더 Node 1 노드를 더블 클릭하여 노드 편집기를 엽니다.

PDF 텍스트 리더 노드는 아래 항목을 제공합니다.

pdf 항목에 시작 노드의 pdf_file 변수를 드래그 앤 드롭으로 연결합니다.

노드가 정상 실행되면 아래 두 값을 출력합니다.

page_infos의 각 원소는 page, offset, length 세 값으로 구성됩니다.

• page : 페이지 번호입니다. 0부터 시작하므로 첫 번째 페이지는 0입니다.

• offset : 해당 페이지의 텍스트가 full_text에서 시작하는 문자 위치입니다.

• length : 해당 페이지의 텍스트 문자 수입니다.

full_text는 모든 페이지의 텍스트가 구분자 없이 이어진 하나의 문자열입니다. 따라서 offset부터 length만큼 잘라내면 특정 페이지의 텍스트만 얻을 수 있습니다.

full_text에는 페이지가 바뀌는 자리에 개행이나 구분자가 들어가지 않습니다. 앞 페이지의 마지막 글자와 다음 페이지의 첫 글자가 그대로 붙습니다. 즉 full_text만으로는 페이지 경계를 알 수 없으므로, 페이지 단위로 처리해야 한다면 page_infos를 사용합니다.

4단계: 엣지로 노드 연결

캔버스에서 아래 순서로 엣지(Edge)를 연결합니다.

1. 시작 노드의 아웃핀(Out-Pin) → New PDF 텍스트 리더 Node 1 노드의 인핀(In-Pin)

2. New PDF 텍스트 리더 Node 1 노드의 아웃핀 → 종료 노드의 인핀

5단계: 종료 노드 설정

종료 노드를 더블 클릭하여 노드 편집기를 엽니다. 어빌리티 캔버스에서 종료 노드는 Ability Output으로 표시됩니다.

출력 변수 영역에서 아래 변수를 추가하고 저장을 클릭합니다.

추가한 extracted_text 항목에 PDF 텍스트 리더 노드의 full_text를 드래그 앤 드롭으로 연결합니다.

6단계: 노드 테스트로 출력 확인

노드 편집기 상단의 테스트(TEST) 버튼을 클릭하면 왼쪽에 테스트 입력 패널이 열립니다. [Ability Input] pdf_file 항목에 준비한 PDF 파일을 드래그 앤 드롭으로 업로드한 뒤 테스트를 클릭합니다.

아웃풋 영역에서 아래 두 결과를 확인합니다.

• full_text에 PDF에 포함된 텍스트가 문자열로 담깁니다.

• page_infos에 페이지 수만큼의 원소가 생성됩니다. 두 페이지 문서라면 [0], [1] 두 개가 표시됩니다.

page_infos를 펼쳐 값이 이어지는지 확인합니다. 예를 들어 [0]의 length가 1092이면 [1]의 offset도 1092가 됩니다. 앞 페이지가 끝난 위치에서 다음 페이지가 시작하기 때문입니다.

노드 테스트는 해당 노드만 단독으로 실행합니다. 앞뒤 노드를 연결하지 않은 상태에서도 추출 결과를 먼저 확인할 수 있어, 워크플로를 완성하기 전에 파일이 정상적으로 읽히는지 점검할 때 유용합니다.

full_text가 비어 있다면 파일에 텍스트 레이어(Text Layer)가 없을 가능성이 높습니다. page_infos의 length가 모두 0으로 나오는지 확인하시기 바랍니다. 자세한 내용은 아래 참고: 추출된 텍스트의 특징에서 설명합니다.

7단계: 어빌리티 테스트로 워크플로 전체 실행

캔버스 우측 하단의 테스트 실행(RUN TEST) 버튼을 클릭하여 어빌리티 테스트(Ability Test)를 실행합니다.

pdf_file 항목에 PDF 파일을 업로드한 뒤 테스트를 실행하면, 종료 노드의 extracted_text에 추출된 텍스트가 반환되는 것을 확인할 수 있습니다.

참고: 추출된 텍스트의 특징

PDF 텍스트 리더 노드는 PDF에 담긴 텍스트를 있는 그대로 읽어 이어 붙입니다. 원본의 시각적인 구조는 유지되지 않으므로, 추출 결과를 다음 노드에서 활용할 때 아래 특징을 참고하시기 바랍니다.

텍스트 레이어가 있는 PDF에서만 추출됩니다. PDF 페이지에는 문자 정보를 담은 텍스트 레이어(Text Layer)와 그림으로 이루어진 이미지가 각각 들어갈 수 있습니다. PDF 텍스트 리더 노드가 읽는 대상은 이 중 텍스트 레이어입니다. 종이 문서를 스캔하거나 사진으로 촬영한 PDF는 페이지가 이미지만으로 이루어져 있어 읽어낼 텍스트 레이어가 없습니다.

단 스캔한 문서라도 광학 문자 인식(OCR, Optical Character Recognition) 처리를 거친 PDF에는 텍스트 레이어가 포함되어 있어 추출이 가능합니다. 스캐너 소프트웨어나 문서 편집 도구의 텍스트 인식 기능은 인식한 글자를 원본 이미지 위에 보이지 않는 텍스트로 겹쳐 저장하기 때문입니다. 겉으로 보이는 모습은 스캔 이미지와 같지만 파일 안에는 문자 정보가 함께 들어 있습니다. 이러한 PDF를 검색 가능한 PDF(Searchable PDF)라고 부릅니다.

텍스트 레이어가 없는 파일을 연결하면 노드는 오류를 내지 않고 정상 완료로 처리하며 full_text에 빈 문자열을 반환합니다. 워크플로가 성공한 것처럼 진행되면서 다음 노드로 빈 값이 전달되므로 원인을 찾기 어려울 수 있습니다. 이때 page_infos를 함께 확인하면 판별할 수 있습니다.

페이지 수만큼 원소는 정상적으로 생성되지만 모든 원소의 length가 0으로 반환됩니다. 페이지는 인식했으나 그 안에 문자 정보가 없다는 의미입니다.

텍스트 레이어가 없는 문서에서 텍스트를 얻으려면 Upstage AI OCR 노드처럼 광학 문자 인식을 수행하는 노드나 이미지를 함께 이해하는 AI 모델 노드를 사용합니다.

OCR 처리를 거친 PDF의 텍스트 레이어에는 인식 결과가 그대로 저장되어 있습니다. 따라서 추출은 되더라도 원문과 다른 글자가 섞여 있을 수 있습니다.

표는 셀 텍스트만 남습니다. 표는 왼쪽에서 오른쪽, 위에서 아래 순서로 셀 내용이 나열되며 행과 열을 구분하는 값은 포함되지 않습니다. 머리글 행도 본문과 같은 텍스트로 섞이고, 표가 끝나는 지점을 알려주는 표시도 없습니다. 표 데이터를 행 단위로 다뤄야 한다면 Excel Reader 노드나 CSV Reader 노드처럼 헤더와 행을 나누어 반환하는 노드를 사용합니다.

머리말과 꼬리말도 함께 추출됩니다. 페이지 번호나 문서 제목이 반복해서 들어가는 문서라면, 추출된 텍스트 중간중간에 같은 문구가 반복해서 나타납니다.

원본의 줄바꿈 위치에 공백이 들어갑니다. 한국어는 단어 중간에서도 줄이 바뀌기 때문에, 줄이 바뀐 자리에서 단어가 두 조각으로 나뉘어 보일 수 있습니다. AI 모델 노드에 넘겨 요약·분류하는 용도라면 대부분 문제가 되지 않지만, 특정 단어를 문자열로 정확히 찾아야 하는 워크플로에서는 이 점을 고려해야 합니다.

다음 단계

🎉 축하합니다! 에이전트리아를 사용해 'PDF 텍스트 추출' 워크플로를 완성했습니다.

추출된 텍스트를 AI 모델 노드에 연결하면 요약·분류·질의응답 등 다양한 문서 처리 워크플로로 확장할 수 있습니다. page_infos의 구간 정보를 활용해 특정 페이지의 텍스트만 골라 처리하는 구성도 만들어 보시기 바랍니다.

에이전트리아는 아이디어를 현실로 바꾸는 가능성의 공간입니다.

당신의 상상력으로 워크플로는 무한히 확장될 수 있습니다.

• 더 많은 어빌리티 예제가 궁금하다면 🔗어빌리티 가이드 페이지를 확인하세요.

• 에이전트 예제를 원한다면 🔗에이전트 가이드 페이지를 확인하세요.

자주 묻는 질문

PDF 텍스트 리더 노드란 무엇인가요?

PDF 텍스트 리더(PDF Text Reader) 노드는 에이전트리아에서 PDF 파일의 텍스트 콘텐츠만 추출해 반환하는 노드입니다. '파일 처리 도구' 카테고리에 속하며, pdf 항목에 PDF 파일 하나를 연결하면 전체 텍스트를 full_text 문자열로, 각 페이지가 그 문자열에서 차지하는 구간을 page_infos 배열로 출력합니다.

PDF 텍스트 리더 노드는 언제 사용해야 하나요?

PDF 문서의 내용을 워크플로에서 텍스트로 다뤄야 할 때 사용합니다. 계약서·보고서·매뉴얼 같은 PDF를 AI 모델 노드에 넘겨 요약하거나 분류하려면, 먼저 PDF 텍스트 리더 노드로 텍스트를 추출해야 합니다. 단 문자 정보를 담은 텍스트 레이어(Text Layer)가 있는 PDF여야 하며, 페이지가 이미지만으로 이루어진 파일에서는 텍스트가 추출되지 않습니다. 파일 형식이 PDF가 아니라면 Excel Reader 노드, Word Reader 노드 등 해당 형식의 리더 노드를 사용합니다.

full_text와 page_infos는 어떻게 다른가요?

full_text는 PDF의 모든 페이지 텍스트가 하나로 이어진 문자열이고, page_infos는 그 문자열을 페이지 단위로 나누는 기준이 되는 배열입니다. page_infos의 각 원소는 페이지 번호(page, 0부터 시작), 시작 위치(offset), 문자 수(length)를 담고 있습니다. 문서 전체를 다룰 때는 full_text를, 특정 페이지만 골라 처리할 때는 page_infos의 구간 정보를 사용합니다.

PDF 파일 여러 개를 한 번에 처리할 수 있나요?

PDF 텍스트 리더 노드는 노드 하나가 파일 하나를 처리합니다. pdf 항목에는 단일 파일만 연결할 수 있으므로, 여러 PDF를 다루려면 처리할 파일 수만큼 PDF 텍스트 리더 노드를 각각 캔버스에 배치하고 파일을 하나씩 연결합니다.

PDF 텍스트 리더 노드는 Upstage AI OCR 노드와 어떻게 다른가요?

두 노드는 대체 관계가 아니라 다루는 문서의 종류가 다릅니다. PDF 텍스트 리더 노드는 PDF에 이미 담겨 있는 텍스트 레이어(Text Layer)를 그대로 읽어 반환하므로, 페이지가 이미지만으로 이루어진 파일에서는 빈 문자열이 반환됩니다. Upstage AI OCR 노드는 이미지나 스캔된 문서에서 광학 문자 인식(OCR, Optical Character Recognition)으로 글자를 직접 인식해 텍스트를 만들어내는 노드로, 외부 API 키를 노드의 API Key 항목에 입력해 사용합니다. 스캔한 문서라도 OCR 처리를 거쳐 텍스트 레이어가 포함된 PDF라면 PDF 텍스트 리더 노드로 추출할 수 있으므로, 파일이 스캔본인지가 아니라 텍스트 레이어가 있는지를 기준으로 선택합니다.