모든 글

Docling: 한 가지 작업 따라 하기

PDF를 마크다운으로 바꾸고 변환 결과를 확인하는 Docling의 공식 문서 기반 안내예요.

마지막 업데이트

메뉴나 지원 기능이 달라졌다면 아래 자료 확인일과 현재 앱 버전을 함께 봐주세요.

앱 · APP
공식 자료를 읽고 정리했어요 · 직접 실행한 후기는 아직 없어요 자료 확인일:

PDF 문서를 다루다 보면 안에 있는 텍스트와 표를 깔끔하게 추출해서 마크다운 형식으로 바꾸고 싶을 때가 정말 많아요. 이번 글에서는 공식 문서를 바탕으로 Docling을 사용해 PDF 파일을 마크다운으로 변환하는 과정을 자세히 살펴볼게요. 이 문서는 직접 실행한 테스트 결과가 아니라 공식 가이드를 정리한 내용이에요.

이 글은 Docling v2.142.0 공식 릴리스를 다뤄요. 공식 릴리스 기록의 공개일은 2026-10-22(UTC)이고, 자료 확인일은 2026-10-22이에요.

Docling은 다양한 문서 포맷을 손쉽게 파싱하고 생성형 AI 생태계와 매끄럽게 연동할 수 있도록 도와주는 도구예요 F1. 공식 README는 PDF의 레이아웃, 읽기 순서와 표 구조 분석을 기능으로 안내해요. 이 기능 목록만으로 특정 PDF가 정확하게 변환된다고 판단할 수는 없으므로, 결과를 원본과 대조하는 과정까지 다뤄요. D2 본격적으로 작업을 시작하기 전에 필요한 준비물과 기본 설정부터 차근차근 확인해 볼게요.

한 가지 완성 목표

이번 가이드의 최종 목표는 공식 문서에서 제공하는 예시 소스를 바탕으로 특정 PDF 문서를 마크다운 문자열로 변환하고, 이를 로컬 파일로 저장한 뒤 다시 열어 주요 제목과 표 구조를 원본 PDF와 비교하는 것이에요. 이 과정은 파이썬 코드를 통해 이루어지며, 복잡한 문서 구조를 텍스트 환경에서 얼마나 잘 보존하는지 직접 확인해 볼 수 있어요. 공식 예시는 DocumentConverter로 입력 문서를 변환하고, export_to_markdown 메서드로 문자열을 얻는 흐름이에요. 표준 파이썬 파일 저장 코드를 덧붙여 살펴볼게요. F4

예시로 사용할 입력 소스는 아카이브에 등록된 Docling Technical Report PDF 주소이며, 변환 결과로 나온 문자열을 report.md 파일로 저장하는 방식을 기준으로 설명할게요. 작업이 모두 끝나면 저장된 파일을 열어보고 문서의 핵심 구조가 제대로 변환되었는지 검증하는 단계까지 진행해 볼 수 있어요. 저장·재확인 단계는 독자가 결과를 비교하도록 덧붙인 절차이며, 작성 과정에서 이 입력을 직접 실행한 것은 아니에요.

준비물과 버전 정보

Docling을 사용하기 위해서는 파이썬 환경이 필요해요. 파이썬 3.9 버전에 대한 지원은 docling 버전 2.70.0에서 중단되었으므로 반드시 파이썬 3.10 이상 버전을 준비해 주세요 F5. 설치는 파이썬 패키지 관리자인 pip를 통해 간단하게 진행할 수 있어요 F3.

설치를 진행하려면 터미널에 아래 명령어를 입력해 주세요. 운영체제는 macOS, Linux, Windows 모두 지원하며 x86_64 및 arm64 아키텍처 지원을 안내해요 F3.

python -m pip install "docling==2.142.0"

만약 패키지 관리 도구로 uv를 사용하고 있다면 아래 명령어를 대신 사용할 수도 있어요 F3.

uv add "docling==2.142.0"

README는 로컬 실행과 에어갭 환경 활용 가능성을 안내해요. D2 이번 예시는 외부 PDF URL을 입력하므로 네트워크 접근이 필요해요. 모델과 의존성 다운로드, 원격 서비스 사용 여부도 자기 설정에서 확인해 주세요. D3, D5 다만 사용하는 시스템 환경에 따라 적절한 파이썬 버전과 가상환경을 미리 구성해 두는 것이 의존성 충돌을 방지하는 좋은 방법이에요.

단계별 입력과 화면

개발 환경 준비가 끝났다면 이제 파이썬 스크립트를 작성해서 문서 변환 작업을 수행할 차례예요. 아래 코드를 convert_report.py로 저장한 뒤 해당 폴더의 터미널에서 python convert_report.py를 실행하는 절차예요. F4 report.md에 쓰는 예시이므로 보관할 동명 파일이 없는 작업 폴더를 준비해 주세요.

여기서 사용할 예시 입력은 양쪽 언어 가이드와 비교에서 모두 동일하게 적용되는 공통 소스예요. 아래의 예시 입력 코드를 파이썬 파일에 작성해 주세요.

예시 입력:

Source PDF: https://arxiv.org/pdf/2408.09869
Output file: report.md

입력을 처리하는 파이썬 예시는 아래와 같아요. F4

from docling.document_converter import DocumentConverter

source = "https://arxiv.org/pdf/2408.09869"
converter = DocumentConverter()
result = converter.convert(source)
markdown_content = result.document.export_to_markdown()

with open("report.md", "w", encoding="utf-8") as f:
    f.write(markdown_content)

코드를 실행하면 DocumentConverter가 지정된 URL에서 PDF를 다운로드하고 내부 파이프라인을 통해 문서를 분석해요 F4. 분석이 완료되면 결과 문서 객체에서 마크다운 문자열을 추출하고, 이를 현재 디렉토리에 report.md 파일로 저장하도록 구성한 예시예요. API는 문자열을 반환하고 파일 작성은 표준 파이썬 open/write 코드가 맡아요.

결과 확인 및 파일 비교

변환 작업이 정상적으로 끝났다면 파일이 제대로 생성되었는지 확인해야 해요. 생성된 report.md 파일을 텍스트 편집기나 마크다운 뷰어로 다시 열어서 원본 PDF의 주요 제목과 표 구조가 어떻게 매핑되었는지 비교해 보세요. 이 단계를 통해 변환 품질을 간접적으로 점검할 수 있어요.

예상 결과: report.md에 마크다운 텍스트가 기록되는 것이 예상 결과예요. 공식 문서는 Docling Technical Report[...]라는 일부 출력 예시를 보여주며, 실제 출력 전문이나 제목 기호의 일치를 보장하지는 않아요. F4

완료 조건은 다음과 같아요. 첫째, 지정한 URL의 PDF 파일이 오류 없이 파싱되어야 해요 F4. 둘째, 변환된 마크다운 문자열이 누락 없이 report.md 파일에 정상적으로 기록되어야 해요. 셋째, 저장된 파일을 다시 열었을 때 원본 핵심 제목과 대표 표의 행·열·수치·각주가 보존됐는지 확인해 주세요. 누락되거나 순서가 바뀐 부분이 있으면 위치를 기록하고 변환을 완료 처리하지 않는 것이 확인 기준이에요.

오류 해결 및 문서 품질 점검

문서 변환을 진행하다 보면 가끔 예기치 않은 오류나 품질 저하를 마주할 수 있어요. 이 글에서 다루는 v2.142.0 릴리스 노트에 따르면, 문서 변환에 실패할 경우 CLI가 종료 코드 1을 반환하도록 개선되어 파이프라인 자동화 과정에서 실패를 종료 코드로 구분할 수 있어요 F2.

또한 도구가 제공하는 변환 품질 참고 정보를 살펴보려면 Docling에서 제공하는 신뢰도 점수 기능을 활용할 수 있어요 D6. 변환 결과 객체에 포함된 confidence 필드를 통해 도구의 참고 등급을 살펴볼 수 있으며, 특히 문서 수준의 요약 등급인 mean_grade와 low_grade를 살펴보는 것이 검토 순서를 정할 때 참고할 수 있어요. 수치는 내부 계산값이며 계산법이 바뀔 수 있으므로 외부 정확도 시험 결과처럼 읽지 마세요. F8 참고로 표 추출 품질을 나타내는 table_score 항목은 공식 문서에 아직 구현되지 않았다고 표시돼 있어요 F9. 오류가 발생할 경우 사용 중인 파이썬 버전이 3.10 이상인지 확인하고 F5, 필요한 경우 공식 문서의 문제 해결 섹션을 참고해서 의존성을 재설정해 주세요.

다음 단계로 넘기기 전 확인

report.md는 사람이 읽고 구조를 확인할 마크다운 파일이에요. PDF 원본이나 Docling의 문서 객체와 같은 형식을 보관한 것은 아니에요. README는 마크다운 외에 손실 없는 JSON 등의 내보내기도 별도로 안내해요. D2 이 작업은 우선 마크다운 한 파일을 만들고 확인하는 데 범위를 두므로, 추가 형식은 필요할 때 선택하면 돼요.

개발자가 공개한 화면 예시는 문서 전체와 페이지별 ConfidenceReport 필드를 펼친 디버거 화면이에요. mean_grade·low_grade와 pages의 위치를 살펴볼 수 있지만 거기에 보이는 수치는 이 입력의 실행 결과가 아니에요. D6 CLI 창이나 변환 시작 버튼의 위치를 설명하는 이미지도 아니므로 실제 순서는 위 코드와 터미널 명령을 기준으로 따라가 주세요.

처리 속도와 품질은 이번 작성에서 측정하지 않았어요. 같은 PDF를 다시 실행해 비교할 때는 버전, 입력 URL 또는 파일, 선택한 모델과 출력 파일명을 함께 기록해 두면 차이를 확인하기 좋아요. 다른 도구와 비교할 때에도 동일한 PDF, 제목·표 확인 기준과 완료 조건을 유지해야 결과를 비교할 수 있어요.

Docling documentation reading guide

BumbleV가 만든 자료 안내 그림이며 실제 앱 화면이나 실행 결과가 아니에요. 그림의 근거가 된 공식 발표 · CC BY 4.0 · 2026-10-22

소개

한 가지 작업 따라 하기

공식 문서로 비교하기

Docling developer interface example
개발자 저장소에 공개된 실제 화면 예시예요. 본문의 작업을 직접 실행한 결과는 아니며 현재 버전과 화면이 다를 수 있어요. 원본·출처 및 재사용 조건 · 6aaf87ebd99b · MIT · 2026-10-22 · Copyright The Docling Contributors The above copyright notice and this permission notice shall be included in all AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

참고 자료