opendataloader-pdf 딥다이브
— PDF를 'AI가 바로 먹는 데이터'로 바꾸고 접근성까지 자동화

1프로젝트 한줄 요약

OpenDataLoader PDF는 두 가지 일을 합니다. 첫째, PDF에서 제목·문단·표·리스트·이미지를 올바른 읽는 순서(reading order)로 뽑아 Markdown·JSON·HTML로 내보냅니다. 이때 모든 요소에 경계상자(bounding box, 화면상 위치 좌표)가 붙어, RAG에서 "이 답의 근거가 원문 몇 페이지 어디"인지 짚어 줄 수 있습니다. 둘째, 구조 정보가 없는 PDF를 시각장애인용 스크린리더가 읽을 수 있는 Tagged PDF로 자동 변환합니다.

코어는 Java(JVM)로 작성됐고, 파이썬·Node.js·자바용 SDK를 제공합니다. 만든 곳은 한글과컴퓨터, 즉 한컴(Hancom Inc.)입니다(소스 저작권 헤더와 연락처 open.dataloader@hancom.com으로 확인). 라이선스는 Apache-2.0로, 상업적 사용에 매우 너그럽습니다.

2왜 주목받는가

이 프로젝트가 약 2.3만 개의 별을 모은 건 운이 아니라 타이밍과 실력입니다. 지금 두 가지 거대한 수요가 동시에 폭발하고 있습니다. ① 모든 회사가 사내 PDF로 RAG·챗봇을 만들려 하는데 PDF 전처리가 병목이고, ② 유럽 접근성법(EAA, 2025-06-28 발효)·미국 ADA/Section 508·한국 디지털포용법 등으로 PDF 접근성이 법적 의무가 됐습니다(수동 보정 비용은 문서당 $50~200). OpenDataLoader는 이 둘을 한 번에 풉니다.

자체 벤치마크(opendataloader-bench, 실문서 200개)에서 하이브리드 모드가 종합 1위(0.907)를 주장합니다. 경쟁 오픈소스 파서와 비교하면:

3기술 스택 전체 지도

이 프로젝트는 한 저장소 안에 여러 언어 패키지를 담은 모노레포입니다. 코드 바이트 비율은 Java가 압도적(약 168만 줄 분량)이고 Python·TypeScript·JavaScript·Shell이 보조합니다. 즉 진짜 엔진은 Java이고, 다른 언어는 그 Java를 호출하는 얇은 껍데기(wrapper)입니다.

① 코어 — Java (java/, Maven 멀티모듈)

② Python SDK — JVM을 부르는 얇은 래퍼

python/opendataloader-pdf/는 "Java CLI를 위한 파이썬 래퍼"입니다. 기본 의존성이 아예 없습니다(dependencies = []) — JAR 파일을 품고 있다가 JVM 프로세스를 띄워 일을 시키는 구조죠. 다만 선택 의존성 [hybrid]를 깔면 하이브리드 백엔드 서버가 따라옵니다.

③ Node.js SDK + 배포 채널

node/opendataloader-pdf/는 TypeScript로 작성된 npm 패키지(@opendataloader/pdf)로, 역시 번들된 JAR로 JVM을 띄웁니다. 배포는 네 갈래입니다.

4아키텍처 심화 분석

코어의 동작은 processors 패키지로 짜인 파이프라인입니다. PDF 한 장이 들어와 여러 단계를 거쳐 구조화 데이터로 나오는 길을, 위에서 아래로 따라가 봅시다.

핵심 설계 패턴 1 — 두 갈래 입력 처리(태그 vs 휴리스틱)

입력 PDF에 이미 구조 태그가 들어 있으면(작성자가 잘 만든 PDF), TaggedDocumentProcessor가 작성자의 의도를 그대로 추출합니다(--use-struct-tree). 태그가 없으면 휴리스틱(처리기들)이 글자 좌표·크기·간격을 보고 "이건 제목, 이건 표"를 추론합니다. 좋은 재료가 있으면 살리고, 없으면 손수 분석하는 영리한 분기입니다.

핵심 설계 패턴 2 — Triage 기반 하이브리드

모든 페이지를 AI에 보내면 느리고 비쌉니다. 그래서 TriageProcessor가 페이지별 복잡도를 판정해 "간단한 페이지=로컬 결정론(빠름·무료), 복잡한 페이지(무테두리 표·스캔·수식)=AI 백엔드"로 자동 분기합니다. 응급실에서 환자 중증도를 분류(triage)하듯, 자원을 꼭 필요한 곳에만 쓰는 전략입니다. AI 백엔드는 별도 로컬 서버(FastAPI+Docling)로 떠 있고 okhttp로 통신합니다.

핵심 설계 패턴 3 — 출력 생성기 분리 + 결정론

분석이 끝나면 시맨틱 요소(의미 단위)가 만들어지고, 그걸 JsonWriter·MarkdownGenerator·HtmlGenerator·AutoTagger 등 포맷별 생성기가 각자 변환합니다. 분석과 출력을 분리했기에 --format json,markdown처럼 여러 포맷을 한 번에 뽑을 수 있죠. 로컬 모드는 같은 입력이면 항상 같은 출력(결정론)이라, 테스트·재현이 쉽습니다.

JSON 출력은 이런 모양입니다. 각 요소가 타입·페이지·좌표·내용을 모두 담습니다.

// heading(제목) 요소 하나의 JSON (README 예시)
{ "type":"heading", "id":42, "level":"Title",
  "page number":1,
  "bounding box":[72.0, 700.0, 540.0, 730.0],  // [좌,하,우,상] PDF 포인트
  "font":"Helvetica-Bold", "font size":24.0,
  "content":"Introduction" }
// 72pt = 1인치. 이 좌표 덕에 원문 위치를 정확히 짚을 수 있다

5디렉토리 구조 해부

최상위는 언어별 폴더(java/·python/·node/)로 갈리고, 빌드를 묶는 루트 package.json이 모노레포 오케스트레이션을 합니다. 진짜 로직은 java/opendataloader-pdf-core/에 있습니다.

6학습 포인트 (기술별)

① 문서 레이아웃 분석 + 읽는 순서 복원

"PDF는 왜 그냥 긁으면 안 되는가"를 코드로 이해할 수 있습니다. 좌표·폰트 정보로 제목/표/문단을 분류하고, XY-Cut++로 다단 레이아웃을 바로잡는 과정은, 문서 AI(Document Intelligence) 분야의 핵심 기술입니다. RAG 파이프라인을 제대로 만들려는 사람에게 특히 값집니다.

② PDF 접근성과 Tagged PDF

평소 접하기 어려운 접근성(a11y) 도메인을 다뤄 봅니다. 태그 없는 PDF를 스크린리더가 읽을 수 있는 Tagged PDF로 바꾸는 autotagging/은, "보이는 것"과 "기계가 읽는 구조"가 어떻게 다른지를 가르쳐 줍니다. 법적 의무가 된 분야라 실무 가치도 높습니다.

③ AI 데이터 파이프라인의 안전 설계

숨은 텍스트·프롬프트 인젝션을 추출 단계에서 걸러내는 설계는, "AI가 먹을 데이터"를 만드는 모든 파이프라인이 고민해야 할 주제입니다. 데이터 위생(data hygiene)을 입구에서 처리하는 사고방식을 배울 수 있습니다.

④ 멀티언어 패키징 + 옵션 단일소스화

하나의 Java 엔진을 Python·Node·Java에서 똑같이 쓰게 하고, 옵션을 한 곳에서 정의해 자동 생성하는 패턴(--export-options → generate-options.mjs)은, 여러 언어로 라이브러리를 배포하는 팀에게 그대로 유용한 실전 노하우입니다.

⑤ Triage로 비용·정확도 절충하기

"쉬운 건 빠른 로컬, 어려운 것만 비싼 AI"라는 하이브리드 전략은, LLM을 실제 서비스에 넣을 때 비용을 통제하는 보편적 패턴입니다. TriageProcessor가 어떤 신호로 복잡도를 판정하는지 따라가 보면, AI 시스템의 비용 설계 감각이 생깁니다.

7시스템 요구사항

가장 큰 장점은 로컬 모드에 GPU가 필요 없다는 점입니다. JVM만 있으면 됩니다. 한 가지 주의할 성능 포인트는, convert() 호출마다 JVM 프로세스를 새로 띄우므로 파일을 하나씩이 아니라 배치로 한 번에 넘기는 게 빠릅니다.

# 로컬(빠름, 기본) — pip 한 줄
pip install -U opendataloader-pdf

# Python에서 — 여러 파일을 배치로 한 번에
import opendataloader_pdf
opendataloader_pdf.convert(
    input_path=["a.pdf", "b.pdf", "folder/"],
    output_dir="output/",
    format="markdown,json")   # 여러 포맷 동시 출력

# 하이브리드(복잡 표·OCR·수식) — 서버 + 처리 2단계
pip install -U "opendataloader-pdf[hybrid]"
opendataloader-pdf-hybrid --port 5002          # 터미널1: 백엔드 서버
opendataloader-pdf --hybrid docling-fast a.pdf  # 터미널2: 처리
# 접근성 태깅:  opendataloader-pdf --format tagged-pdf a.pdf

주요 CLI 옵션(실제 확인): --format(json/markdown/html/text/tagged-pdf), --sanitize(안전 필터), --use-struct-tree(원본 태그 사용), --reading-order(기본 xycut/off), --pages, --image-output, --include-header-footer, --hybrid, --threads, --to-stdout, --export-options.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

• GitHub: opendataloader-project/opendataloader-pdf · 공식 사이트: opendataloader.org
• 벤치마크: opendataloader-bench · LangChain 통합: langchain-opendataloader-pdf
• 배포: PyPI · npm · Maven Central
• 표준/배경: veraPDF · Well-Tagged PDF · PDF Association
• 경쟁/비교 도구: docling · markitdown