개요
Docling은 PDF, DOCX, PPTX, HTML, 이미지 및 오디오 등 다양한 형식을 파싱하여 구조화된 문서 표현으로 통합합니다. 레이아웃 분석, 읽기 순서, 표, 코드 및 수식 인식 등 고급 PDF 이해 기능을 갖추고 있으며, Markdown, HTML 및 무손실 JSON으로 내보낼 수 있고, 스캔 문서 OCR을 지원하며, LangChain, LlamaIndex 등 AI 프레임워크와 원활하게 통합됩니다.
README 미리보기
\n \n \n \n\n\n# Docling\n\n\n \n\n\n[](https://arxiv.org/abs/2408.09869)\n[](https://docling-project.github.io/docling/)\n[](https://pypi.org/project/docling/)\n[](https://pypi.org/project/docling/)\n[](https://github.com/astral-sh/uv)\n[](https://github.com/astral-sh/ruff)\n[](https://pydantic.dev)\n[](https://pypi.org/project/prek/)\n[](https://opensource.org/licenses/MIT)\n[](https://pepy.tech/projects/docling)\n[](https://apify.com/vancura/docling)\n[](https://app.dosu.dev/097760a8-135e-4789-8234-90c8837d7f1c/ask?utm_source=github)\n[](https://docling.ai/discord)\n[](https://www.bestpractices.dev/projects/10101)\n[](https://lfaidata.foundation/projects/)\n\n## What is Docling ?\n\nDocling simplifies document processing by parsing diverse formats — including advanced PDF understanding — and providing seamless integrations with the generative AI ecosystem.\n\n## Features\n\n- 🗂️ Parsing of [multiple document formats][supported_formats] including PDF, DOCX, PPTX, XLSX, HTML, EPUB, Apple Pages, WAV, MP3, WebVTT, Box Notes, email formats (EML, MSG), images (PNG, TIFF, JPEG, ...), LaTeX, DocLang, plain text, and more\n- 📑 Advanced PDF understanding incl. page layout, reading order, table structure, code, formulas, image classification, and more\n- 🧬 A unified, expressive [DoclingDocument][docling_document] representation format\n- ↪️ Various [export formats][supported_formats] and options, including Markdown, HTML, WebVTT, DocLang, [DocTags](https://arxiv.org/abs/2503.11576) and lossless JSON\n- 📜 Support for several application-specific XML schemas including [DocLang](https://doclang.ai), [USPTO](https://www.uspto.gov/patents) patents, [JATS](https://jats.nlm.nih.gov/) articles, and [XBRL](https://www.xbrl.org/) financial reports.\n- 🔒 Local execution capabilities for sensitive data and air-gapped environments\n- 🤖 Plug-and-play [integrations][integrations] incl. LangChain, LlamaIndex, Crew AI & Haystack for agentic AI\n- 🔍 Extensive OCR support for sca
FAQ (5)
문제 해결왜 투명한 PNG 이미지가 Docling picture enrichment(classifier, description, chart extraction)에서 완전한 검정색으로 변하는가?
Docling의 enrichment 모델은 PIL의 convert("RGB")를 사용해 RGBA 이미지를 변환하는데, 이 방식은 알파 채널 아래에 저장된 색상(보통 검정색)을 그대로 유지하므로 투명한 영역이 흰색 대신 검정색으로 바뀝니다. 이 문제는 document_picture_classifier.py:167, picture_description_base_model.py:106, inference_engines/vlm/_utils.py:131에 영향을 미칩니다. 수정 방법: 이 세 곳의 convert("RGB")를 docling/backend/image_backend.py의 _to_rgb(#4511에서 추가됨)로 교체하세요. 이 함수는 이미지를 흰색 배경 위에 평탄화합니다. 자체 코드에서의 임시 해결 방법으로, 이미지를 모델에 전달하기 전에 RGBA를 흰색 위에 합성하세요. 예: bg = Image.new("RGB", img.size, (255,255,255)); bg.paste(img, mask=img.split()[3]). 참고로 페이지 이미지는 이미 _to_rgb를 거치며, prepare_element를 통해 DOCX/HTML/PPTX에 임베딩된 그림만 버그가 있는 경로를 통과합니다.
문제 해결왜 Docling이 수천 개의 작은 도형이 포함된 PDF를 변환할 때 document_timeout을 무시하고 영원히 멈추는가?
이것은 Docling 2.132–2.134 (commit 42de1e2)에서 발생한 회귀(regression)입니다: reading order 모델이 페이지 구분자 후보를 무제한으로 생성하고(예: 각 좌석이 사각형으로 표시된 콘서트홀 평면도의 경우 약 195K), 후보 병합의 복잡도가 quadratic(이차)이므로 변환이 사실상 완료되지 않습니다. 또한 이 단계 내부에서 document_timeout 예산이 확인되지 않아 파이프라인이 무기한 블로킹되었습니다.
수정 사항: PR #4633이 포함된 Docling 버전으로 업그레이드하세요. 이 수정은 (1) 페이지당 구분자 후보를 5,000개로 제한하며 — 제한을 초과하는 페이지는 경고와 함께 구분자 추출을 건너뛰고 기본 reading order로 폴백합니다 — (2) 남은 document_timeout 예산이 소진되면 후보 루프와 병합이 중단되고 TIMEOUT 오류가 기록되므로, 변환이 행(hang) 상태가 되는 대신 PARTIAL_SUCCESS 상태로 반환됩니다.
업그레이드할 수 없는 경우의 우회 방법: pip install docling==2.124로 영향을 받지 않는 마지막 버전으로 고정하세요.
문제 해결여러 PDF를 병렬로 처리하면서 tesserocr OCR을 실행할 때 발생하는 Docling segmentation fault(SIGSEGV)를 해결하는 방법
근본 원인: Docling의 TesseractOcrModel은 파이프라인당 하나의 tesserocr PyTessBaseAPI 리더를 캐시하며, tesserocr는 스레드 안전(thread-safe)하지 않습니다. 변환이 동시에 실행되면(settings.perf.doc_batch_concurrency > 1이거나 하나의 DocumentConverter가 여러 스레드에서 호출되는 경우), 동시에 수행되는 SetImage/SetRectangle/GetUTF8Text 호출이 서로의 상태를 손상시킵니다. 이후 프로세스는 SIGSEGV(종료 코드 139)로 종료되거나, cysignals.signals.SignalError: Segmentation fault 오류를 발생시키거나, OCR 텍스트가 누락된 채 상태 success를 조용히 반환합니다.
우회 방법:
1. 변환하기 전에 배치 변환을 순차적으로 실행하도록 강제합니다:
from docling.datamodel.settings import settings
settings.perf.doc_batch_concurrency = 12. 자체 스레드에서 Docling을 호출하는 경우, 하나의 DocumentConverter를 공유하지 마세요. 스레드별로 별도의 DocumentConverter를 생성하거나(각각 자체 파이프라인과 tesserocr 리더를 빌드합니다), threading.Lock으로 모든 convert()/convert_all() 호출을 직렬화하세요.
3. docling을 최신 릴리스로 업그레이드하고 업스트림 수정 상태는 이슈 #4940을 확인하세요.
참고: Python은 SIGSEGV를 catch할 수 없으므로, 크래시가 발생한 문서 하나가 프로세스 내 모든 변환을 중단시킵니다. 스레드 안전 수정이 릴리스될 때까지 동시성을 1로 유지하세요.
문제 해결pillow<13 의존성 충돌에도 불구하고 Pillow 13과 함께 Docling을 설치하는 방법은?
Docling(2.141.0까지)은 docling-slim, docling-core, docling-parse, docling-ibm-models 네 개 패키지에서 pillow>=10.0.0,<13.0.0으로 버전을 고정합니다. 이로 인해 pip-audit이 지적한 8개의 CVE(CVE-2026-112895, CVE-2026-112400, CVE-2026-112397, CVE-2026-112896, CVE-2026-112897, CVE-2026-112395, CVE-2026-112404, CVE-2026-112899)를 수정하는 Pillow 13.0.0의 설치가 차단됩니다.
해결 방법: 의존성 오버라이드를 사용하여 Pillow 13을 강제로 지정합니다. uv를 사용하는 경우 프로젝트에 오버라이드를 추가하거나 오버라이드 파일을 사용합니다:
uv pip install docling --overrides overrides.txt # overrides.txt 내용: pillow==13.0.0또는 pyproject.toml에서:
[tool.uv]
override-dependencies = ["pillow>=13.0.0"]Python 3.12 환경에서 docling 2.132.0으로 호환성이 검증되었습니다. PDF, 스캔된 PDF, PNG, JPEG가 모두 성공적으로 변환되었으며, Markdown 내보내기, 페이지/테이블 수, 페이지 이미지 크기가 Pillow 12.3.0과 동일했습니다. TableFormer도 정상적으로 작동했습니다. 소스 코드 감사를 통해 docling, docling-core, docling-parse, docling-ibm-models가 Pillow 13에서 제거된 API(
Image._show, get_child_images, ImageCmsProfile.product_name/product_info, ExifTags.IFD.Makernote, dtype을 변경하는 fromarray)를 사용하지 않음이 확인되었습니다. 상한을 <14.0.0으로 상향해 달라는 요청이 현재 대기 중이며, 공식 수정 사항은 2.141.0 이후의 릴리스를 확인하세요.문제 해결Docling이 세미콜론으로 구분된 CSV 파일을 쉼표 기준으로 분할하는 이유는 무엇이며, 이를 어떻게 해결할 수 있나요?
이는 Docling의 CSV 백엔드에 존재하는 버그입니다: docling/backend/csv_backend.py의 _sniff_dialect()가 첫 번째 줄(헤더)만을 사용해 구분 기호를 감지합니다. 헤더 열 이름에 쉼표가 포함된 경우(예: Weight (kg, net)), Python의 csv.Sniffer가 ; 대신 ,를 선택하여 모든 셀이 손상됩니다. 이 문제는 ;가 열 구분 기호이고 ,가 소수점 기호인 유럽 로캘에서 Excel이보낸 파일에 흔히 영향을 미칩니다. 해결 방법: (1) 변환하기 전에 헤더 열 이름에서 쉼표를 제거합니다(예: Weight (kg, net)를 Weight (kg net)로 변경) — 그러면 동일한 파일이 ;를 기준으로 올바르게 분할됩니다. (2) 파일을 전처리합니다: 전체 파일 내용을 사용해 dialect를 감지하고(csv.Sniffer().sniff(full_text, ',;\t|:')) 파일을 다시 쓰거나, CSV를 먼저 XLSX로 변환한 후 Docling으로 변환합니다. (3) 일관성을 위해 dialect 감지가 여러 행을 사용하도록 개선하는, issue #4895에 연결된 수정 PR이 병합되면 Docling을 업데이트합니다.