DoclingServeConverter

DoclingServeConverter

DoclingServeConverter는 파일 경로, URL, 또는 ByteStream 객체 리스트를 받아 실행 중인 DoclingServe 인스턴스로 보내 파싱합니다. 로컬 파일과 ByteStream 객체는 /v1/convert/file 엔드포인트로 업로드되고, URL 문자열은 /v1/convert/source로 보내집니다.

출처: 문서

본문

Overview

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

  • ExportType.MARKDOWN(기본값) — 문서 콘텐츠를 Markdown 문자열로 반환합니다. 형식이 보존된 잘 구조화된 텍스트 출력을 원할 때 이 모드를 사용하세요.
  • ExportType.TEXT — 문서에서 추출한 평문을 반환합니다. 깨끗하고 형식 없는 텍스트가 필요할 때 이 모드를 사용하세요.
  • ExportType.JSON — 전체 Docling 문서 표현을 JSON 문자열로 반환합니다. 완전한 구조화 표현에 접근해야 할 때 이 모드를 사용하세요.

각 소스는 출력에서 하나의 Document를 생성합니다. 변환에 실패한 소스는 경고 로그와 함께 건너뜁니다.

DoclingServe API에 convert_options 파라미터로 추가 변환 옵션을 전달할 수 있어요(예: {"do_ocr": True, "ocr_engine": "tesseract"}). DoclingServe 인스턴스가 인증을 요구하면 api_key 파라미터로 API 키를 전달하거나 DOCLING_SERVE_API_KEY 환경 변수를 설정하세요.

이 컴포넌트는 동기(run)와 비동기(run_async) 실행을 모두 지원합니다.

Usage

Docling Serve 통합을 설치합니다:

pip install docling-serve-haystack

로컬에서 DoclingServe 인스턴스를 시작합니다(Docker 필요):

docker run -p 5001:5001 ghcr.io/docling-project/docling-serve-cpu:latest

On its own

from haystack_integrations.components.converters.docling_serve import (
    DoclingServeConverter,
)

# Default: Markdown output
converter = DoclingServeConverter(base_url="http://localhost:5001")
result = converter.run(sources=["report.pdf", "notes.docx"])
documents = result["documents"]
print(documents[0].content[:200])

# Plain text output
from haystack_integrations.components.converters.docling_serve import ExportType

converter = DoclingServeConverter(
    base_url="http://localhost:5001",
    export_type=ExportType.TEXT,
)
result = converter.run(sources=["report.pdf"])
print(result["documents"][0].content)

In a pipeline

from haystack import Pipeline
from haystack.components.preprocessors import DocumentSplitter
from haystack.components.writers import DocumentWriter
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack_integrations.components.converters.docling_serve import (
    DoclingServeConverter,
)

document_store = InMemoryDocumentStore()

pipeline = Pipeline()
pipeline.add_component(
    "converter",
    DoclingServeConverter(base_url="http://localhost:5001"),
)
pipeline.add_component("splitter", DocumentSplitter())
pipeline.add_component("writer", DocumentWriter(document_store=document_store))
pipeline.connect("converter", "splitter")
pipeline.connect("splitter", "writer")

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

Additional Features

Converting URLs directly

먼저 다운로드하지 않고 원격 문서를 변환하려면 URL 문자열을 전달하세요:

from haystack_integrations.components.converters.docling_serve import (
    DoclingServeConverter,
)

converter = DoclingServeConverter(base_url="http://localhost:5001")
result = converter.run(sources=["https://arxiv.org/pdf/2602.17316"])
print(result["documents"][0].content[:200])

Attaching metadata

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

from haystack_integrations.components.converters.docling_serve import (
    DoclingServeConverter,
)

converter = DoclingServeConverter(base_url="http://localhost:5001")

# 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 객체를 전달하세요. DoclingServe가 파일 형식을 감지할 수 있도록 ByteStream 메타데이터에 file_path를 설정합니다:

from haystack.dataclasses import ByteStream
from haystack_integrations.components.converters.docling_serve import (
    DoclingServeConverter,
)

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

source = ByteStream(data=data, meta={"file_path": "report.pdf"})
converter = DoclingServeConverter(base_url="http://localhost:5001")
result = converter.run(sources=[source])

더 알아보기 (Learn more)