KreuzbergConverter

KreuzbergConverter

파일을 Haystack 문서로 변환해주는 컴포넌트예요. Kreuzberg라는 문서 지능 프레임워크를 사용하는데, Rust 코어를 갖고 있어 91개 이상의 파일 형식에서 텍스트를 완전히 로컬에서 추출해요. 외부 API 호출이 전혀 없어요.

출처: KreuzbergConverter

본문

개요

KreuzbergConverter는 파일 경로, 디렉토리 경로, 또는 ByteStream 객체 목록을 받아서 Kreuzberg로 텍스트와 메타데이터를 추출해요. 모든 처리는 로컬에서 이뤄지고 외부 API 호출이 없어요.

지원하는 형식 범주:

  • 문서: PDF, DOCX, DOC, PPTX, PPT, XLSX, XLS, ODT, ODS, ODP, RTF, Pages, Keynote, Numbers 등
  • 이미지(OCR 경유): PNG, JPEG, TIFF, GIF, BMP, WebP, JPEG 2000, SVG
  • 텍스트/마크업: Markdown, HTML, XML, LaTeX, Typst, JSON, YAML, reStructuredText, Jupyter 노트북
  • 이메일: EML, MSG(첨부 파일 추출 포함)
  • 아카이브: ZIP, TAR, GZIP, 7Z(내부 내용을 재귀적으로 추출·처리)
  • 전자책/학술: EPUB, BibTeX, DocBook, JATS

컴포넌트는 기본적으로 원본 하나당 Haystack Document 하나를 반환해요. 페이지별 추출이나 청킹을 켜면 페이지/청크 하나당 문서 하나를 반환해요. 문서에는 품질 점수, 감지된 언어, 추출된 키워드, 테이블 데이터, PDF 주석 같은 풍부한 메타데이터가 담겨요.

기본적으로 배치 처리가 켜져 있고, Rust의 rayon 스레드 풀을 이용해 병렬 추출을 수행해요. 순차 처리가 필요하면 batch=False로 설정하면 돼요.

추출 동작은 Kreuzberg의 ExtractionConfig로 커스터마이즈할 수 있어요. 직접 전달하거나 config_path로 TOML/YAML/JSON 설정 파일에서 불러올 수 있어요. 전체 설정 참조는 Kreuzberg 문서에서 확인하세요.

사용법

Kreuzberg 통합을 설치해요.

pip install kreuzberg-haystack

단독 사용:

from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter

converter = KreuzbergConverter()
result = converter.run(sources=["report.pdf", "notes.docx"])
documents = result["documents"]

파이프라인 안에서:

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.kreuzberg import KreuzbergConverter

document_store = InMemoryDocumentStore()

pipeline = Pipeline()
pipeline.add_component("converter", KreuzbergConverter())
pipeline.add_component(
    "splitter",
    DocumentSplitter(split_by="sentence", split_length=5),
)
pipeline.add_component("writer", DocumentWriter(document_store=document_store))

pipeline.connect("converter", "splitter")
pipeline.connect("splitter", "writer")

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

추가 기능

OCR과 함께 Markdown 출력

ExtractionConfig로 출력 형식과 OCR 설정을 바꿀 수 있어요.

from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter
from kreuzberg import ExtractionConfig, OcrConfig

converter = KreuzbergConverter(
    config=ExtractionConfig(
        output_format="markdown",
        ocr=OcrConfig(backend="tesseract", language="eng"),
    ),
)
result = converter.run(sources=["scanned_document.pdf"])
documents = result["documents"]

페이지별 추출

PageConfig로 페이지당 문서 하나를 만들 수 있어요.

from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter
from kreuzberg import ExtractionConfig, PageConfig

converter = KreuzbergConverter(
    config=ExtractionConfig(
        page=PageConfig(extract_pages=True),
    ),
)
result = converter.run(sources=["multipage.pdf"])
# One Document per page, each with page_number in metadata

토큰 줄이기

TokenReductionConfig로 LLM에 넣을 출력 크기를 줄일 수 있어요. 토큰 축소는 TF-IDF 기반 추출 요약을 사용해 가장 중요한 용어와 구를 찾아 보존하면서, 덜 중요한 내용(여분 공백, 잡음 단어, 중복 구 등)을 점진적으로 제거해요. 다섯 단계가 있어요: "off"(축소 없음), "light"(약 15%), "moderate"(약 30%), "aggressive"(약 50%), "maximum"(50% 초과 축소).

from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter
from kreuzberg import ExtractionConfig, TokenReductionConfig

converter = KreuzbergConverter(
    config=ExtractionConfig(
        token_reduction=TokenReductionConfig(mode="moderate"),
    ),
)

파일에서 설정 불러오기

TOML/YAML/JSON 파일에서 추출 설정을 불러올 수 있어요.

from haystack_integrations.components.converters.kreuzberg import KreuzbergConverter

converter = KreuzbergConverter(config_path="extraction_config.toml")

전체 설정 참조와 지원 형식 매트릭스는 Kreuzberg 문서에서 확인하세요.

더 알아보기 (Learn more)