Upstage Document Parse API 가이드

Upstage의 Document Parse API는 이 문제를 해결하는 문서 전처리 엔진이다.

 

Upstage console의 playground에서 API 키 없이도 문서를 업로드하면 레이아웃(제목, 본문, 표, 그림, 수식, 차트 등)을 인식한 뒤 HTML / Markdown / 텍스트 형태의 구조화된 결과를 확인해 볼 수 있고.

 

 

[Upstage Credit Redeem code]

UPWAVE-YOONK

 

업스테이지 콘솔에서

https://console.upstage.ai/docs/capabilities/extract

Dashboard > credit -> reddem 코드(UPWAVE-YOONK)를 입력하면 70달러의 크레딧을 제공하기 때문에

크레딧으로 테스트해볼 수 있다.

 

 

Document parsing은 “사람이 보는 문서”를 “기계가 이해할 수 있는 구조화된 텍스트”로 변환하는 API라고 보면 된다.

• 입력: PDF, 스캔 이미지, 오피스 문서(DOCX, PPTX, XLSX, HWP 등)
• 처리:
  • 레이아웃 요소 탐지
    • 문서 내 제목, 단락, 표, 리스트, 머리말/꼬리말, 그림, 차트, 수식 등)
  • 문서 구조 분석
    • 단락 간 부모–자식 구조, 리스트 계층, 캡션–그림 연결 등 문서의 계층적 구성을 파악)
  • 읽기 순서(reading order) 재정렬
    • 다단(multi-column) 문서 등 복잡한 레이아웃에서도 각 요소의 위치, 순서를 고려한 읽기 순서(reading order) 정렬
• 출력:
  • 전체 HTML / Markdown / Text
  • 요소별 category + 좌표 + 부분 HTML/Markdown/Text

 

문서를 전체 단위로 쓸 수도 있고, 요소 단위로 조각내어 벡터DB에 삽입할 수도 있다.

 

Document Parse는 기본 문자 인식(OCR)을 넘어, 문서 구조의 의미까지 반영한 표현을 제공한다.

주요 기능 요약

기능설명

레이아웃 감지	표·그림·제목·단락 등 다양한 요소를 자동 인식
구조 결정	요소 간 계층 관계 분석 (예: 그림 ↔ 캡션)
읽기 순서 직렬화	다단 문서도 자연스러운 순서로 정렬
구조화된 텍스트 변환	HTML, Markdown 등 의미 기반 구조 생성
좌표 정보 반환	페이지 내 상대 좌표로 후처리 용이
요소별 조각 추출	특정 요소만 선택, 삭제, 변환 가능

이처럼 문서의 형태와 의미까지 반영한 구조화 결과를 제공하기 때문에,
검색, QA, RAG, 하이라이팅, 인덱싱과 같은 후처리 단계에서 훨씬 정교하고 정확한 처리가 가능해진다.

 

 

Upstage는 Document Parse 모델을 alias 방식으로 제공한다.
alias를 사용하면 내부 버전이 바뀌어도 코드 수정 없이 최신 모델을 사용할 수 있다.

Alias실제 모델 버전RPS

document-parse	document-parse-250618	Sync 1 / Async 2
document-parse-nightly	최신 테스트 버전	Sync 1 / Async 2

일반적으로는 document-parse alias를 쓰면 된다.

또한 Upstage Playground에서 별도의 API 키 없이
샘플 문서를 바로 변환해볼 수 있다.

 

 

Document Parse의 응답은 크게 두 부분으로 나뉜다.

 

1. 문서 전체(HTML/Markdown/Text)

content.html 은 문서를 읽기 순서대로 재구성한 완성된 HTML이다.

이를 그대로 웹 뷰어에 렌더링해도 자연스럽게 읽을 수 있는 수준이다.

 

2. 요소(Element) 단위 정보

elements 배열 안에는 문서의 모든 요소가 담겨 있다.

각 element는:

• category (heading1, paragraph, table, figure, chart, equation …)
• content.html / markdown / text
• coordinates (0~1 사이의 상대 좌표)
• page 번호
• element id

{ "category": "paragraph", "content": { "html": "<p data-category='paragraph'>...</p>" }, "coordinates": [...], "page": 1, "id": 15 }

 

이 요소 기반 구조 덕분에 문서를 원하는 단위로 조각내서 벡터DB에 저장하거나, 특정 요소만 골라 쓸 수 있다.

이런 정보는 특히 다음과 같은  목적에 활용하기 좋다.

• 요소 단위 벡터DB 인덱싱
• 표만 추출
• 본문만 사용
• 그림+캡션을 하나의 유닛으로 처리
• 페이지 단위 하이라이팅