Docling — 멀티포맷 문서 변환

Docling은 IBM Research에서 개발한 문서 변환 라이브러리로, PDF, DOCX, PPTX, HTML, 이미지 등 다양한 형식을 구조화된 문서 모델(DoclingDocument)로 변환합니다. OCR, 레이아웃 분석, 표 인식, 이미지 추출을 포함하는 종합 파이프라인을 제공합니다.

pip install docling

기본 변환
이미지 추출 (Markdown 링크)
표 추출
OCR 활성화

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("document.pdf")

# Markdown으로 내보내기
markdown_text = result.document.export_to_markdown()
print(markdown_text)

Docling은 문서 내 이미지를 추출하여 별도 파일로 저장하고, Markdown에서 **이미지 링크(![]())**로 참조합니다.

from docling.document_converter import DocumentConverter
from docling.datamodel.base_models import InputFormat
from docling.document_converter import PdfFormatOption
from docling.datamodel.pipeline_options import PdfPipelineOptions
from pathlib import Path

# 이미지 추출 옵션 설정
pipeline_options = PdfPipelineOptions()
pipeline_options.images_scale = 2.0  # 이미지 해상도 배율
pipeline_options.generate_page_images = False
pipeline_options.generate_picture_images = True  # 그림/차트 이미지 추출

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_options=pipeline_options,
        )
    }
)

result = converter.convert("document.pdf")

# 이미지를 파일로 저장하면서 Markdown 내보내기
output_dir = Path("output")
output_dir.mkdir(exist_ok=True)
image_dir = output_dir / "images"
image_dir.mkdir(exist_ok=True)

# 문서 내 이미지(Picture) 요소 순회 및 저장
for idx, (element, _level) in enumerate(result.document.iterate_items()):
    if hasattr(element, "image") and element.image is not None:
        image_path = image_dir / f"figure_{idx}.png"
        element.image.pil_image.save(str(image_path))
        print(f"이미지 저장: {image_path}")

# Markdown 내보내기 (이미지 경로 포함)
markdown_text = result.document.export_to_markdown(
    image_mode="referenced",  # 이미지를 참조 형태로 내보내기
)

# 결과 Markdown에 이미지가 링크로 포함됨:
# ![figure_3](images/figure_3.png)
print(markdown_text)

내보낸 Markdown에서 이미지는 다음과 같은 형태로 표현됩니다:

## 2.1 Architecture

The Transformer architecture uses self-attention...

![figure_3](images/figure_3.png)

As shown in the figure above, the encoder-decoder...

Docling은 PDF 내 표를 자동으로 인식하고 Markdown 표로 변환합니다.

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("report.pdf")

# 표 요소만 추출
for element, _level in result.document.iterate_items():
    if hasattr(element, "label") and element.label == "table":
        # Markdown 표로 내보내기
        print(element.export_to_markdown())
        print("---")

복잡한 병합 셀, 다단 헤더도 처리하며 구조를 보존합니다.

스캔된 PDF나 이미지 기반 문서는 OCR을 활성화하여 텍스트를 추출합니다.

from docling.document_converter import DocumentConverter
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.datamodel.base_models import InputFormat
from docling.document_converter import PdfFormatOption

pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True  # OCR 활성화
pipeline_options.ocr_options.lang = ["ko", "en"]  # 한국어 + 영어

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_options=pipeline_options,
        )
    }
)

result = converter.convert("scanned_document.pdf")
markdown_text = result.document.export_to_markdown()

Docling + 청킹 파이프라인

Docling의 내장 HybridChunker는 문서 구조를 인식하면서 토큰 기반 크기 제어를 동시에 수행합니다.

from docling.document_converter import DocumentConverter
from docling.chunking import HybridChunker

# 1. 문서 변환
converter = DocumentConverter()
result = converter.convert("document.pdf")

# 2. 구조 인식 + 토큰 기반 청킹
chunker = HybridChunker(
    tokenizer="gpt-4o",      # 토크나이저
    max_tokens=512,            # 청크당 최대 토큰
    merge_peers=True,          # 같은 레벨의 짧은 섹션 병합
)
chunks = list(chunker.chunk(result.document))

for chunk in chunks:
    print(f"[{chunk.meta.headings}] ({len(chunk.text)} chars)")
    print(chunk.text[:200])
    print("---")

파라미터	설명	기본값
`tokenizer`	토크나이저 (모델명 또는 객체)	`"gpt2"`
`max_tokens`	청크당 최대 토큰 수	`512`
`merge_peers`	같은 레벨의 짧은 섹션을 병합	`True`

HybridChunker는 헤딩, 단락, 표, 리스트 등 문서 구조를 인식하여 의미 단위를 존중합니다. 단순히 토큰 수로 자르지 않으므로, Docling 변환 결과에 가장 적합한 청킹 도구입니다.

지원 형식

입력 형식	레이아웃 분석	표 인식	이미지 추출	OCR
PDF	O	O	O	O
DOCX	O	O	O	-
PPTX	O	-	O	-
HTML	O	O	O	-
이미지 (PNG, JPG)	-	-	-	O
Markdown	O	O	-	-

VLM 파이프라인 — Vision Language Model 기반 문서 이해

Docling v2부터 기존 OCR 파이프라인 외에 Vision Language Model(VLM) 파이프라인을 지원합니다. VLM은 문서 페이지 이미지를 직접 “읽고 이해”하여, 복잡한 레이아웃·차트·수식도 높은 정확도로 변환합니다.

VLM vs OCR 비교

항목	OCR 파이프라인 (`PdfPipeline`)	VLM 파이프라인 (`VlmPipeline`)
동작 방식	텍스트 추출 → 레이아웃 분석 → 구조화	페이지 이미지를 VLM이 직접 해석
복잡한 레이아웃	규칙 기반, 일부 오류 가능	시각적 이해로 높은 정확도
차트/수식	제한적 (텍스트만 추출)	시각적 맥락 포함 변환
속도	빠름	느림 (GPU 권장)
리소스	CPU로 충분	GPU 메모리 필요 (2B 모델 기준 ~4GB VRAM)
적합한 경우	텍스트 중심 문서, 대량 처리	복잡한 레이아웃, 시각 요소가 많은 문서

기본 사용법

VlmPipeline을 pipeline_cls로 지정하면 VLM 기반 변환이 활성화됩니다. 기본 모델은 GraniteDocling (IBM, 258M 파라미터)입니다.

from docling.datamodel.base_models import InputFormat
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.pipeline.vlm_pipeline import VlmPipeline

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_cls=VlmPipeline,
        ),
    }
)

result = converter.convert("document.pdf")
print(result.document.export_to_markdown())

모델 선택

VlmPipelineOptions의 vlm_options로 사용할 VLM 모델을 지정합니다. Docling은 여러 사전 정의 모델 스펙을 제공합니다.

SmolDocling (HuggingFace)
GraniteDocling (MLX, macOS)
커스텀 모델 (InlineVlmOptions)
API 서버 연동 (vLLM / Ollama)

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import VlmPipelineOptions
from docling.datamodel import vlm_model_specs
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.pipeline.vlm_pipeline import VlmPipeline

pipeline_options = VlmPipelineOptions(
    vlm_options=vlm_model_specs.SMOLDOCLING,
)

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_cls=VlmPipeline,
            pipeline_options=pipeline_options,
        ),
    }
)

result = converter.convert("document.pdf")
print(result.document.export_to_markdown())

Apple Silicon Mac에서는 MLX 프레임워크로 가속할 수 있습니다.

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import VlmPipelineOptions
from docling.datamodel import vlm_model_specs
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.pipeline.vlm_pipeline import VlmPipeline

pipeline_options = VlmPipelineOptions(
    vlm_options=vlm_model_specs.GRANITEDOCLING_MLX,
)

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_cls=VlmPipeline,
            pipeline_options=pipeline_options,
        ),
    }
)

result = converter.convert("document.pdf")
print(result.document.export_to_markdown())

HuggingFace의 임의 VLM 모델을 직접 지정할 수 있습니다.

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import VlmPipelineOptions
from docling.datamodel.pipeline_options_vlm_model import InlineVlmOptions
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.pipeline.vlm_pipeline import VlmPipeline

pipeline_options = VlmPipelineOptions(
    vlm_options=InlineVlmOptions(
        repo_id="ibm-granite/granite-vision-3.3-2b",
        prompt="Convert this page to docling.",
        scale=2.0,
        temperature=0.0,
    ),
)

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_cls=VlmPipeline,
            pipeline_options=pipeline_options,
        ),
    }
)

result = converter.convert("document.pdf")
print(result.document.export_to_markdown())

원격 VLM 서버(vLLM, Ollama, LM Studio 등)와 연동할 수 있습니다.

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import VlmPipelineOptions
from docling.datamodel.pipeline_options_vlm_model import (
    ResponseFormat,
    openai_compatible_vlm_options,
)
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.pipeline.vlm_pipeline import VlmPipeline

pipeline_options = VlmPipelineOptions(
    enable_remote_services=True,
    vlm_options=openai_compatible_vlm_options(
        model="ibm-granite/granite-docling-258M",
        hostname_and_port="localhost:8000",  # vLLM 서버
        prompt="Convert this page to docling.",
        format=ResponseFormat.DOCTAGS,
    ),
)

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_cls=VlmPipeline,
            pipeline_options=pipeline_options,
        ),
    }
)

result = converter.convert("document.pdf")
print(result.document.export_to_markdown())

VlmPipelineOptions 주요 설정

옵션	설명	기본값
`vlm_options`	VLM 모델 설정 (사전 정의 스펙 또는 `InlineVlmOptions`)	GraniteDocling
`accelerator_options.device`	추론 디바이스 (`"auto"`, `"cpu"`, `"cuda"`, `"mps"`)	`"auto"`
`accelerator_options.num_threads`	CPU 스레드 수	`4`
`accelerator_options.cuda_use_flash_attention2`	Flash Attention 2 활성화 (Ampere+ GPU)	`False`
`enable_remote_services`	원격 API 서비스 허용 여부	`False`
`document_timeout`	문서당 최대 처리 시간 (초)	`None`

VLM 파이프라인은 GPU가 있을 때 가장 효과적입니다. CUDA GPU가 없는 환경에서는 기존 OCR 파이프라인(PdfPipeline)이 더 빠르고 실용적입니다. macOS에서는 MLX 가속(GRANITEDOCLING_MLX, SMOLDOCLING_MLX)을 활용하세요.

RAG 개요

RAG 개발 단계

RAG 성능 향상 전략

RAG 아키텍처

Docling

Docling — 멀티포맷 문서 변환

Docling + 청킹 파이프라인

지원 형식

VLM 파이프라인 — Vision Language Model 기반 문서 이해

VLM vs OCR 비교

기본 사용법

모델 선택

VlmPipelineOptions 주요 설정

RAG 개요

RAG 개발 단계

RAG 성능 향상 전략

RAG 아키텍처

​Docling — 멀티포맷 문서 변환

​Docling + 청킹 파이프라인

​지원 형식

​VLM 파이프라인 — Vision Language Model 기반 문서 이해

​VLM vs OCR 비교

​기본 사용법

​모델 선택

​VlmPipelineOptions 주요 설정

Docling — 멀티포맷 문서 변환

Docling + 청킹 파이프라인

지원 형식

VLM 파이프라인 — Vision Language Model 기반 문서 이해

VLM vs OCR 비교

기본 사용법

모델 선택

VlmPipelineOptions 주요 설정