OpenDataLoader PDF: AI를 위한 안전하고 고성능의 PDF 처리 도구

읽을거리&정보공유
, , , , , , , , ,
1

OpenDataLoader PDF: AI를 위한 안전하고 고성능의 PDF 처리 도구
OpenDataLoader PDF: AI를 위한 안전하고 고성능의 PDF 처리 도구887×283 25.8 KB

OpenDataLoader PDF 소개

OpenDataLoader PDF는 PDF 문서를 JSON, Markdown, HTML로 변환하여 최신 AI 스택(LLM, 벡터 검색, RAG 등)에 바로 활용할 수 있도록 설계된 오픈소스 프로젝트입니다. 단순히 텍스트 추출에 그치지 않고, 문서의 레이아웃을 재구성하여 제목, 리스트, 표, 이미지, 읽기 순서까지 보존해줍니다. 이는 대규모 문서 처리와 검색, AI 모델 입력 최적화에 매우 중요한 역할을 합니다.

특히 이 프로젝트는 GPU 없이도 빠르고 가벼운 규칙 기반 추론(heuristic rule-based inference)으로 동작하며, 로컬 환경에서 실행되기 때문에 개인정보나 민감한 문서도 안전하게 처리할 수 있습니다. 또한, AI 안전성(AI-Safety) 기능이 기본 활성화되어 있어 PDF 내부에 숨겨진 잠재적 프롬프트 인젝션(prompt injection) 위험 요소를 자동으로 걸러냅니다. 이는 최근 LLM 기반 시스템에서 보안 위협으로 주목받는 부분을 실질적으로 대응할 수 있는 중요한 기능입니다.

image
image658×851 189 KB

OpenDataLoader PDF는 Python, Node.js, Java 환경을 모두 지원하고 있으며, Docker 이미지로도 제공되어 다양한 환경에서 쉽게 사용할 수 있습니다. 따라서 연구자, 기업, 개발자가 문서를 정제해 AI 학습이나 검색 시스템에 활용하려는 경우 매우 유용하게 적용할 수 있습니다.

일반적으로 PDF를 처리하기 위해서는 PyPDF2, pdfplumber, Apache PDFBox 같은 라이브러리가 널리 사용됩니다. 하지만 이러한 툴들은 텍스트 추출에 중점을 두어 문서 구조(표, 리스트, 이미지, 레이아웃 등)를 온전히 보존하지 못하는 경우가 많습니다. 반면 OpenDataLoader PDF는 문서의 레이아웃 복원을 핵심 기능으로 제공하며, JSON 형태의 구조화된 데이터를 출력해 이후 AI 모델 처리나 벡터 데이터베이스 인덱싱에 바로 사용할 수 있습니다.

또한 AI-Safety 필터링 기능은 기존 PDF 처리 라이브러리에는 없는 독창적인 기능으로, 특히 LLM 기반 RAG 시스템을 구축하는 사용자에게는 보안상 중요한 이점이 됩니다. 이 점에서 단순 텍스트 추출 라이브러리를 넘어, “AI 친화적 PDF 처리 엔진”이라고 할 수 있습니다.

OpenDataLoader PDF의 주요 기능

  • 문서 레이아웃 복원: OpenDataLoader PDF는 단순 텍스트가 아닌 문서의 구조를 재구성합니다. 제목, 본문, 리스트, 표, 이미지, 캡션, 헤더/푸터 등을 JSON에 명확히 구분하여 담습니다. 이는 검색 엔진이나 LLM이 문맥을 이해하는 데 큰 도움이 됩니다.

  • 다양한 출력 형식: PDF를 JSON, Markdown, HTML로 변환할 수 있습니다. 또한 원본 PDF 위에 추출된 레이아웃 정보를 시각화한 “Annotated PDF”를 생성할 수도 있어 결과를 직접 확인하기 쉽습니다.

  • AI-Safety: PDF에 숨겨진 악의적 콘텐츠(숨겨진 텍스트, 너무 작은 글자, off-page 요소, prompt injection 가능성이 있는 요소 등)를 자동으로 필터링합니다. 이 기능은 기본적으로 활성화되어 있으며 필요 시 특정 필터를 해제할 수도 있습니다. 더 자세한 내용은 GitHub 저장소의 AI Safety 문서를 참고해주세요.

  • 고속, 경량, 로컬 우선: GPU 없이도 규칙 기반 추론만으로 빠른 속도를 보장하며, 모든 처리가 로컬에서 실행됩니다. 따라서 민감한 데이터를 안전하게 다룰 수 있습니다.

OpenDataLoader PDF 설치 및 사용 예시

Python에서 OpenDataLoader PDF 설치 및 사용하기

OpenDataLoader PDF는 PyPI에 배포되어 있어 간단히 설치할 수 있습니다:

pip install -U opendataloader-pdf

이렇게 설치하면 최신 버전의 패키지가 환경에 추가됩니다. 설치 후에는 run() 함수를 사용해 PDF 파일을 손쉽게 처리할 수 있습니다. 입력으로는 개별 PDF 파일뿐 아니라 폴더 단위로도 지정할 수 있습니다. 또한, output_folder를 지정하지 않으면 입력 파일이 위치한 동일한 디렉토리에 결과가 저장됩니다.

다음은 Python에서 OpenDataLoader PDF 예시 코드입니다:

import opendataloader_pdf

opendataloader_pdf.run(
    input_path="path/to/document.pdf",
    output_folder="path/to/output",
    generate_markdown=True,
    generate_html=True,
    generate_annotated_pdf=True,
)

위 예시는 지정된 PDF 문서를 읽어 JSON 외에도 Markdown, HTML, Annotated PDF(레이아웃 분석이 시각적으로 표시된 PDF)를 함께 생성합니다. 아래 표는 run() 함수에서 사용할 수 있는 주요 파라미터를 정리한 것입니다:

파라미터 타입 필수 여부 기본값 설명
input_path str :white_check_mark: 필수 — 입력 PDF 파일 경로나 폴더 경로
output_folder str 선택 입력 폴더 출력 파일이 저장될 경로
password str 선택 None 암호화된 PDF의 비밀번호
replace_invalid_chars str 선택 " " 인식 불가능한 문자를 대체할 문자 (예: �, \u0000)
content_safety_off str 선택 None AI-Safety 필터를 비활성화 (예: all, hidden-text, off-page, tiny, hidden-ocg)
generate_markdown bool 선택 False Markdown 출력 파일 생성 여부
generate_html bool 선택 False HTML 출력 파일 생성 여부
generate_annotated_pdf bool 선택 False 분석된 레이아웃이 표시된 Annotated PDF 생성 여부
keep_line_breaks bool 선택 False 원본의 줄바꿈을 유지할지 여부
html_in_markdown bool 선택 False Markdown 내에서 HTML 태그를 허용할지 여부
add_image_to_markdown bool 선택 False Markdown 출력 시 이미지 포함 여부
no_json bool 선택 False JSON 출력 생성을 비활성화
debug bool 선택 False 실행 중 디버그 메시지를 출력할지 여부

이러한 기능들은 단순히 PDF를 텍스트로 변환하는 수준이 아니라, 문서의 구조를 인식하고 다양한 출력 형식으로 가공할 수 있도록 도와줍니다. 특히 RAG(Retrieval-Augmented Generation) 시스템을 구축하거나 사내 문서 검색 엔진을 만들 때 유용하게 활용할 수 있습니다.

Node.js / NPM에서 OpenDataLoader PDF 설치 및 사용하기

Node.js / NPM에서 사용하는 OpenDataLoader PDF 패키지는 Java CLI를 감싸는(Node.js wrapper) 형태로 제공되기 때문에, 사용 전 반드시 Java 11 이상이 시스템에 설치되어 있어야 하며, 해당 경로가 PATH 환경변수에 등록되어 있어야 합니다. 또한 이 라이브러리는 브라우저 환경에서는 동작하지 않으며, Node.js 기반의 백엔드 환경 전용임을 유의해야 합니다.

설치는 NPM을 통해 간단하게 할 수 있습니다:

npm install @opendataloader/pdf

설치 후에는 Python과 마찬가지로 run() 함수를 호출하여 PDF 문서를 처리할 수 있습니다. 입력(inputPath)으로는 PDF 파일 하나 또는 폴더 전체를 지정할 수 있습니다. 출력 폴더(outputFolder)를 지정하지 않으면, 결과 파일은 기본적으로 입력 PDF가 있는 디렉토리에 저장됩니다.

import { run } from '@opendataloader/pdf';

async function main() {
  try {
    const output = await run("path/to/document.pdf", {
      outputFolder: "path/to/output",
      generateMarkdown: true,
      generateHtml: true,
      generateAnnotatedPdf: true,
      debug: true,
    });
    console.log("PDF processing complete.", output);
  } catch (error) {
    console.error("Error processing PDF:", error);
  }
}

main();

위 Node.js 예제는 지정된 PDF를 JSON으로 파싱할 뿐만 아니라, Markdown, HTML, Annotated PDF까지 함께 생성하는 방식입니다.

Node.js에서 PDF를 처리하는 메인 함수는 run()으로, Promise를 반환하므로 await 또는 .then()을 활용할 수 있습니다:

run(inputPath: string, options?: RunOptions): Promise<string>

run() 함수에서 사용 가능한 파라매터들은 다음과 같습니다:

파라미터 타입 필수 여부 설명
inputPath string :white_check_mark: 필수 입력 PDF 파일 경로나 폴더 경로
options RunOptions 선택 실행을 위한 세부 옵션 설정 객체

이 때, 파라매터로 입력하는 RunOptions의 상세 옵션을 통해 세밀한 설정이 가능합니다:

속성 타입 기본값 설명
outputFolder string undefined 출력 파일이 저장될 경로. 지정하지 않으면 입력 파일 경로 옆에 저장
password string undefined 암호화된 PDF의 비밀번호
replaceInvalidChars string " " 인식 불가능한 문자를 대체할 문자
contentSafetyOff string undefined AI-Safety 필터 비활성화 옵션. 여러 값을 콤마로 구분하여 지정 (예: all, hidden-text, off-page, tiny, hidden-ocg)
generateMarkdown boolean false Markdown 출력 파일 생성 여부
generateHtml boolean false HTML 출력 파일 생성 여부
generateAnnotatedPdf boolean false 분석된 레이아웃이 표시된 Annotated PDF 생성 여부
keepLineBreaks boolean false 원본의 줄바꿈을 유지할지 여부
htmlInMarkdown boolean false Markdown 내에서 HTML 태그 사용 여부
addImageToMarkdown boolean false Markdown 출력 시 이미지 포함 여부
noJson boolean false JSON 출력 비활성화
debug boolean false 실행 중 디버깅 메시지 출력 여부

Node.js 환경에서는 특히 대량의 PDF를 자동 처리하는 서버 애플리케이션 이나, RAG(Retrieval-Augmented Generation) 기반의 백엔드 서비스 에서 이 패키지를 활용하면 좋습니다. 예를 들어 사내 문서를 일괄적으로 구조화해 JSON + Markdown으로 변환한 뒤, 이를 벡터 데이터베이스에 인덱싱하여 검색 가능한 AI 지식 베이스로 만드는 식의 활용이 가능합니다.

Java 및 Docker에서의 사용

그 외 Java 및 Docker 기반으로 OpenDataLoader PDF를 사용할 수 있습니다. 자세한 사용 방법은 OpenDataLoader PDF 프로젝트의 GItHub 저장소를 확인해주세요.

JSON 출력 구조

OpenDataLoader PDF는 PDF를 단순 텍스트가 아닌 구조화된 JSON 데이터로 변환합니다. 이 JSON은 문서 전체의 메타데이터와, 각 페이지의 요소들(제목, 본문, 표, 이미지 등)을 계층적으로 표현합니다. 즉, PDF 문서를 마치 DOM(Document Object Model) 처럼 트리 구조로 바꿔줍니다. 이 덕분에 AI 모델이나 검색 시스템에서 문서를 더욱 정교하게 활용할 수 있습니다.

OpenDataLoader PDF의 JSON 출력은 다음과 같이 문서의 구조를 상세하게 담습니다:

  • 문서 정보(제목, 저자, 생성일, 수정일 등)
  • 페이지별 요소(heading, paragraph, list, table, image 등)
  • 표의 행/열 구조 및 셀 내용
  • 리스트 항목 및 번호 스타일
  • 텍스트 속성(폰트, 색상, 크기 등)

이를 통해 단순히 텍스트가 아닌 “문서 구조”를 데이터베이스나 LLM 입력에 활용할 수 있습니다. 상세한 문서 및 스타일별 노드 정보 및 필드들은 다음과 같습니다:

루트 노드 (Root JSON Node)

루트에는 PDF 전체에 대한 기본 정보가 담깁니다.

필드 타입 필수 여부 설명
file name string 필수 처리된 PDF 파일 이름
number of pages integer 필수 PDF 페이지 수
author string 필수 문서 저자
title string 필수 문서 제목
creation date string 필수 생성일
modification date string 필수 수정일
kids array 필수 문서 내 요소 배열 (본문, 표, 이미지 등)

공통 필드 (모든 Content Node에 공통 적용)

문서의 각 요소(제목, 본문, 표 등)에는 공통적으로 다음 정보가 포함됩니다.

필드 타입 필수 여부 설명
id integer 선택 요소 고유 ID
level string 선택 계층 수준(heading 레벨 등)
type string 필수 요소 타입 (예: heading, paragraph, table, list, image 등)
page number integer 필수 해당 요소가 위치한 페이지 번호
bounding box array 필수 요소의 위치를 나타내는 좌표 정보

텍스트 요소 (Caption, Heading, Paragraph)

문자 정보가 있는 노드에는 다음 속성이 포함됩니다.

필드 타입 필수 여부 설명
font string 필수 폰트 이름
font size double 필수 폰트 크기
text color array 필수 텍스트 색상
content string 필수 텍스트 내용

표 (Table) 관련 노드

Table 노드

필드 타입 필수 여부 설명
number of rows integer 필수 행 개수
number of columns integer 필수 열 개수
rows array 필수 행 데이터 배열
previous table id integer 선택 연결된 이전 표 ID
next table id integer 선택 연결된 다음 표 ID

Table Row 노드

필드 타입 필수 여부 설명
row number integer 필수 행 번호
cells array 필수 셀 데이터 배열

Table Cell 노드

필드 타입 필수 여부 설명
row number integer 필수 셀의 행 번호
column number integer 필수 셀의 열 번호
row span integer 필수 병합된 행 수
column span integer 필수 병합된 열 수
kids array 필수 셀 안에 포함된 요소들

Heading 노드

필드 타입 필수 여부 설명
heading level integer 필수 제목 레벨(h1, h2 등)

리스트 (List & List Item)

List 노드

필드 타입 필수 여부 설명
number of list items integer 필수 리스트 항목 개수
numbering style string 필수 번호 스타일(숫자, 불릿 등)
previous list id integer 선택 연결된 이전 리스트 ID
next list id integer 선택 연결된 다음 리스트 ID
list items array 필수 리스트 항목 배열

List Item 노드

필드 타입 필수 여부 설명
kids array 필수 리스트 항목 내부 요소

Header & Footer 노드

필드 타입 필수 여부 설명
kids array 필수 헤더/푸터 내부 요소

Text Block 노드

필드 타입 필수 여부 설명
kids array 필수 텍스트 블록 내부 요소

활용 예시

이러한 JSON 구조를 이용하면 다음과 같은 활용이 가능합니다:

  • 문서의 목차(heading level 기반) 자동 생성
  • 표(table) 구조를 그대로 재현해 데이터베이스에 저장
  • 리스트를 항목 단위로 검색 가능하게 구성
  • 벡터 DB에 넣기 전에 문서 단락 단위로 chunking 최적화

즉, 단순히 PDF를 “텍스트로 뽑아내는” 것이 아니라, 문서의 논리적 구조를 유지한 채 AI/검색 시스템에서 활용할 수 있다는 점이 OpenDataLoader PDF의 큰 강점입니다.

라이선스

이 프로젝트는 Mozilla Public License 2.0로 공개 및 배포되고 있습니다. 상업적 활용이 가능하지만, 수정된 코드 배포 시 소스 공개 의무가 있을 수 있습니다. 상세한 조건은 LICENSE 문서 문서를 참고하시기 바랍니다. 추가로 서드파티 라이브러리 및 컴포넌트들에 대한 정보는 다음 링크들을 참고해주세요:

:github: OpenDataLoader PDF 프로젝트 GitHub 저장소

더 읽어보기



이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. :hugs:

:pytorch:파이토치 한국 사용자 모임:south_korea:이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일:love_letter:로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

:wrapped_gift: 아래:down_right_arrow:쪽에 좋아요:+1:를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ :star_struck: