PaddleOCRVLDocumentConverter

PaddleOCRVLDocumentConverter

PaddleOCRVLDocumentConverter는 PaddleOCR의 대규모 언어 모델 기반 문서 파싱 API를 사용해 문서에서 텍스트를 추출하는 컴포넌트예요. 내부적으로 PaddleOCR-VL을 사용하죠. 자세한 내용은 PaddleOCR-VL 문서를 참고하시면 돼요.

출처: 문서

본문

개요

PaddleOCRVLDocumentConverter는 문서 소스 목록을 받아 PaddleOCR의 대규모 모델 문서 파싱 API를 이용해 이미지와 PDF에서 텍스트를 추출해요. 이미지와 PDF 파일을 모두 지원해요.

이 컴포넌트는 소스 하나마다 Haystack Document 하나를 반환하는데, 모든 페이지가 폼 피드 문자(\f)로 구분되어 이어져 있어요. 이 형식 덕분에 Haystack의 DocumentSplitter와 함께 사용했을 때 페이지 단위로 정확하게 나누고 오버랩을 처리할 수 있죠. 콘텐츠는 마크다운 형식으로 반환되며, 이미지는 ![img-id](img-id) 태그로 표현돼요.

이 컴포넌트는 필수 파라미터로 api_url을 받아요. API URL을 얻으려면 PaddleOCR 공식 사이트를 방문해 API 버튼을 클릭하고, PaddleOCR-VL용 예제 코드를 선택한 뒤 API_URL을 복사하면 돼요.

기본적으로 컴포넌트는 인증에 AISTUDIO_ACCESS_TOKEN 환경 변수를 사용해요. 초기화 시 access_token을 직접 전달할 수도 있고요. AI Studio 액세스 토큰은 이 페이지에서 얻을 수 있어요.

raw_paddleocr_responses는 레이아웃 임계값, 프롬프트 설정, 마크다운 후처리 옵션을 튜닝할 때 유용해요. 변환된 Haystack 문서와 함께 원본 API 출력을 볼 수 있으니까, 원하는 추출 결과를 만드는 데 큰 도움이 되죠.

참고: 이 컴포넌트는 마크다운 콘텐츠를 반환해요. 기본 설정의 DocumentCleaner()에 그대로 연결하는 것은 피하세요. remove_extra_whitespaces=True와 remove_empty_lines=True가 줄바꿈을 압축하고 제목·테이블·이미지 태그를 평평하게 만들 수 있거든요. 페이지 단위 청킹이 필요하면 컨버터를 DocumentSplitter에 바로 연결하고, 커스텀 정리가 필요하다면 그 옵션들을 꺼 주세요.

언제 사용하면 좋을까요

PaddleOCRVLDocumentConverter는 단순 OCR 텍스트 이상이 필요할 때 특히 잘 맞아요.

• 스캔 PDF와 카메라로 촬영한 문서 — 페이지 방향이 틀어지거나 텍스트가 휘어져 추출 품질이 떨어질 수 있는 경우에요.
• 레이아웃에 민감한 문서 — 인보이스, 리포트, 폼, 다단 PDF처럼 구조를 보존해야 다운스트림 청킹과 검색이 잘 되는 경우예요.
• 테이블·수식·차트·도장 — 일반 텍스트 OCR보다 더 목표 지향적인 추출이 필요할 때요.
• RAG 수집(ingestion) 파이프라인 — 마크다운 출력이 제목·목록·테이블·페이지 나눔을 보존해 나중에 분할하기 좋은 경우예요.

유용한 설정 영역

전체 파라미터 목록은 API reference에서 확인할 수 있어요. 실무에서 유용한 옵션들은 대략 이런 그룹으로 나뉘죠.

• 입력 처리와 이미지 정리: file_type, use_doc_orientation_classify, use_doc_unwarping — PDF와 이미지를 섞어 쓰거나, 삐뚤어진 스캔·모바일 사진을 다룰 때 도움이 돼요.
• 레이아웃 인지 추출: use_layout_detection, layout_threshold, layout_nms, layout_unclip_ratio, layout_merge_bboxes_mode, layout_shape_mode, merge_layout_blocks — 마크다운 생성 전에 영역을 어떻게 감지·병합할지 튜닝해요.
• 콘텐츠 집중: prompt_label, use_ocr_for_image_block, use_chart_recognition, use_seal_recognition — 일반 OCR, 수식, 테이블, 차트, 도장처럼 특정 콘텐츠 유형으로 추출을 편향시켜요.
• 마크다운 출력成形: format_block_content, markdown_ignore_labels, prettify_markdown, show_formula_number, restructure_pages, merge_tables, relevel_titles — 최종 리절트가 Haystack 문서가 되기 전에 얼마나 정리·재구성할지 제어해요.
• VLM 생성 제어: repetition_penalty, temperature, top_p, min_pixels, max_pixels, max_new_tokens, vlm_extra_args, additional_params — 출력 품질·결정성·비용 사이 트레이드오프가 필요할 때 유용해요.
• 디버깅과 검사: visualize=True와 반환되는 raw_paddleocr_responses — 새 문서 유형에 대한 추출 품질을 튜닝할 때 도움이 돼요.

전형적인 시나리오

몇 가지 흔한 워크플로에서 특히 유용한 설정들이 있어요.

• 폰으로 찍은 스캔 계약서·영수증: use_doc_orientation_classify=True와 use_doc_unwarping=True로 시작하세요.
• 테이블이 많은 금융·운영 PDF: use_layout_detection=True, merge_tables=True, restructure_pages=True를 고려해요.
• 수식이 많은 문서: prompt_label="formula"와 함께 show_formula_number=True를 사용하세요. 최종 마크다운에서 수식 번호가 중요하다면요.
• 그림이나 도장이 있는 복합 업무 문서: 보존하고 싶은 콘텐츠에 따라 use_chart_recognition=True, use_seal_recognition=True, 또는 use_ocr_for_image_block=True를 켜요.

사용법

PaddleOCRVLDocumentConverter를 사용하려면 paddleocr-haystack 통합 패키지를 설치해야 해요:

pip install paddleocr-haystack

단독으로 사용하기

로컬 파일을 처리하는 기본 사용법이에요:

from pathlib import Path
from haystack.utils import Secret
from haystack_integrations.components.converters.paddleocr import (
    PaddleOCRVLDocumentConverter,
)

converter = PaddleOCRVLDocumentConverter(
    api_url="<your-api-url>",
    access_token=Secret.from_env_var("AISTUDIO_ACCESS_TOKEN"),
)

result = converter.run(sources=[Path("my_document.pdf")])
documents = result["documents"]

구조가 복잡한 PDF를 위한 고급 설정이에요:

from pathlib import Path
from haystack.utils import Secret
from haystack_integrations.components.converters.paddleocr import (
    PaddleOCRVLDocumentConverter,
)

converter = PaddleOCRVLDocumentConverter(
    api_url="<your-api-url>",
    access_token=Secret.from_env_var("AISTUDIO_ACCESS_TOKEN"),
    use_doc_orientation_classify=True,
    use_doc_unwarping=True,
    use_layout_detection=True,
    use_ocr_for_image_block=True,
    merge_tables=True,
    restructure_pages=True,
    prettify_markdown=True,
)

result = converter.run(sources=[Path("quarterly_report.pdf")])
documents = result["documents"]
raw_responses = result["raw_paddleocr_responses"]

파이프라인에서 사용하기

OCR로 PDF를 처리해 Document Store에 쓰는 인덱싱 파이프라인 예시예요:

from haystack import Pipeline
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.components.preprocessors import DocumentSplitter
from haystack.components.writers import DocumentWriter
from haystack.utils import Secret
from haystack_integrations.components.converters.paddleocr import (
    PaddleOCRVLDocumentConverter,
)

document_store = InMemoryDocumentStore()
pipeline = Pipeline()
pipeline.add_component(
    "converter",
    PaddleOCRVLDocumentConverter(
        api_url="<your-api-url>",
        access_token=Secret.from_env_var("AISTUDIO_ACCESS_TOKEN"),
    ),
)
pipeline.add_component("splitter", DocumentSplitter(split_by="page", split_length=1))
pipeline.add_component("writer", DocumentWriter(document_store=document_store))
pipeline.connect("converter", "splitter")
pipeline.connect("splitter", "writer")

file_paths = ["invoice.pdf", "receipt.jpg", "contract.pdf"]
pipeline.run({"converter": {"sources": file_paths}})

더 알아보기 (Learn more)

• PaddleOCR-VL 문서
• PaddleOCR 공식 사이트
• API reference: PaddleOCR
• GitHub: paddleocr-haystack 통합