DoclingConverter

DoclingConverter

DoclingConverter는 파일 경로, URL, 또는 ByteStream 객체 리스트를 받아 Docling으로 파싱해 레이아웃, 표, 제목, 기타 구조적 요소를 포착하는 풍부한 문서 표현으로 변환해요.

출처: 문서

본문

Overview

DoclingConverter는 파일 경로, URL, 또는 ByteStream 객체 리스트를 받아 Docling으로 파싱해 레이아웃, 표, 제목, 기타 구조적 요소를 포착하는 풍부한 문서 표현으로 변환합니다.

이 컴포넌트는 export_type 파라미터로 제어되는 세 가지 내보내기 모드를 지원합니다:

  • ExportType.MARKDOWN(기본값) — 각 입력 문서를 하나의 Document 안의 단일 Markdown 문자열로 내보냅니다. 전체 문서 콘텐츠를 형식화된 텍스트로 보존하고 싶을 때 이 모드를 사용하세요.
  • ExportType.DOC_CHUNKS — Docling의 HybridChunker로 각 문서를 청킹하고 청크마다 하나의 Document를 반환해요. 청크 메타데이터에 Docling의 구조적 컨텍스트가 포함됩니다. 다운스트림 검색이 의미적으로 일관된 청크의 이점을 얻는 인덱싱 파이프라인에 이 모드를 사용하세요.
  • ExportType.JSON — 전체 Docling 문서를 하나의 Document 안의 JSON 문자열로 직렬화합니다. 완전한 구조화 표현에 접근해야 할 때 이 모드를 사용하세요.

converter 파라미터로 사전 구성된 DocumentConverter 인스턴스를 전달하고, convert_kwargs로 Docling 변환 단계에 추가 키워드 인자를 전달해 파싱 동작을 커스터마이즈할 수 있어요. ExportType.MARKDOWN에는 md_export_kwargs로 Markdown 렌더링 옵션(예: 이미지 자리표시자 텍스트)을 제어하고, ExportType.DOC_CHUNKS에는 chunker 파라미터로 커스텀 BaseChunker 인스턴스를 제공합니다.

문서 메타데이터는 MetaExtractor 인스턴스로 채워집니다. 기본 MetaExtractor는 Docling 특정 메타데이터(청크 구조 또는 문서 출처)를 dl_meta 키 아래 추가해요. meta_extractor 파라미터로 커스텀 BaseMetaExtractor 구현체를 제공할 수 있습니다. meta run 파라미터에 딕셔너리를 전달해 모든 출력 문서에 추가 메타데이터를 붙이거나, 딕셔너리 리스트를 전달해 소스별로 붙일 수 있어요.

Usage

Docling 통합을 설치합니다:

pip install docling-haystack

On its own

from haystack_integrations.components.converters.docling import (
    DoclingConverter,
    ExportType,
)

# Default: full document as Markdown
converter = DoclingConverter()
result = converter.run(sources=["report.pdf", "notes.docx"])
documents = result["documents"]
print(documents[0].content)

# One document per chunk
converter = DoclingConverter(export_type=ExportType.DOC_CHUNKS)
result = converter.run(sources=["report.pdf"])
documents = result["documents"]

In a pipeline

from haystack import Pipeline
from haystack.components.writers import DocumentWriter
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack_integrations.components.converters.docling import DoclingConverter

document_store = InMemoryDocumentStore()

pipeline = Pipeline()
pipeline.add_component("converter", DoclingConverter())
pipeline.add_component("writer", DocumentWriter(document_store=document_store))
pipeline.connect("converter", "writer")

pipeline.run({"converter": {"sources": ["report.pdf", "manual.docx"]}})

export_type=ExportType.DOC_CHUNKS를 설정하면 DoclingConverter가 이미 문서를 청킹하므로, 보통 파이프라인에 별도의 DocumentSplitter가 필요하지 않아요.

Additional Features

Custom chunking

커스텀 Docling 청커를 제공해 문서가 어떻게 분할되는지 제어할 수 있어요. chunker 파라미터는 ExportType.DOC_CHUNKS에서만 효과가 있습니다:

from docling.chunking import HybridChunker
from haystack_integrations.components.converters.docling import (
    DoclingConverter,
    ExportType,
)

chunker = HybridChunker(tokenizer="BAAI/bge-small-en-v1.5", max_tokens=256)
converter = DoclingConverter(export_type=ExportType.DOC_CHUNKS, chunker=chunker)
result = converter.run(sources=["report.pdf"])

Attaching metadata

단일 딕셔너리를 전달하면 모든 출력 문서에 메타데이터를 적용하고, 리스트를 전달하면 소스별로 설정합니다:

from haystack_integrations.components.converters.docling import DoclingConverter

converter = DoclingConverter()

# Same metadata for all sources
result = converter.run(
    sources=["a.pdf", "b.pdf"],
    meta={"project": "research"},
)

# Per-source metadata
result = converter.run(
    sources=["a.pdf", "b.pdf"],
    meta=[{"title": "Report A"}, {"title": "Report B"}],
)

Processing in-memory files

메모리에 로드된 파일을 변환하려면 ByteStream 객체를 전달하세요. Docling이 파일 형식을 감지할 수 있도록 ByteStream 메타데이터에 file_path를 설정합니다:

from haystack.dataclasses import ByteStream
from haystack_integrations.components.converters.docling import DoclingConverter

with open("report.pdf", "rb") as f:
    data = f.read()

source = ByteStream(data=data, meta={"file_path": "report.pdf"})
converter = DoclingConverter()
result = converter.run(sources=[source])

더 알아보기 (Learn more)