Getting Started with Document Digitization

PreviousGetting Started with Solar Chat Next[KOR] Edu Full Package - Use Case Zone

Last updated 9 days ago

Getting Started with Document Digitization

Documentation Digitization API를 사용하려면, 먼저 본인의 API Key를 발급받아야 합니다. API Key 발급 절차가 궁금하다면 01. Introduction to Upstage API()를 보고 오세요!

📌 목차

Document Digitization이란?
Document Digitization API는 언제 활용할까?
Document Parse란?
- Demo : Document Parse 를 활용한 재무제표 분석 챗봇
- Document Parse Input & Output 구조
- Getting Started with Document Parse API
Document OCR이란?
- Demo : Document OCR을 활용한 영어 손글씨 편지 번역기
- Document OCR Input & Output 구조
- Getting Started with Document OCR API

1. Document Digitization이란?

Document digitization이란 문서를 기계가 읽을 수 있는 형태(텍스트, HTML, Markdown 등)로 변환하는 과정을 말합니다. 변환된 문서는 이후 정보 검색, 요약, 추출 등의 AI 기반 처리에 활용될 수 있습니다.

문서 내의 텍스트와 레이아웃(단락, 표, 이미지 등) 을 인식하여 구조화된 HTML 또는 Markdown 형식으로 변환합니다.
LLM이 이해할 수 있는 형태로 문서를 가공하여 다양한 다운스트림 작업에 적합합니다.
내부적으로 OCR 기술을 포함하고 있어, OCR보다 더 높은 수준의 정보를 제공합니다.

문서 내의 텍스트와 위치 정보만 추출하는 방식으로, 기본적인 텍스트 인식 작업에 사용됩니다.

👉 (참고) Document Parsing은 내부적으로 OCR을 활용하지만, 레이아웃 인식, 표/차트 이해 등의 추가 기능이 포함된 더 고도화된 기술입니다. 빠르게 텍스트만 추출하는 기능이 필요하시다면 Document OCR을, 구조화된 데이터 추출이 필요하시다면 Document Parse를 활용하시는 것을 권장 드립니다.

2. Document Digitization API는 언제 활용할까?

문서 자동화 기술은 단순한 텍스트 추출을 넘어서 문서를 AI가 이해하고 처리할 수 있는 형태로 구조화하는 데 목적이 있습니다.

콘솔 데모는 기능을 체험하고 이해하는 데 매우 유용하지만, 실제 업무 자동화, 서비스 애플리케이션 구축, 데이터 파이프라인 통합에는 반드시 API 사용이 필요합니다.

✅ 콘솔 데모는 "사람이 직접 업로드하고 바로 확인"하는 테스트 용도

✅ API는 "시스템에서 자동으로 문서를 불러와 분석하고 가공"하는 실제 운영 환경 용도

👁️‍🗨️ LLM 입력을 위한 전처리

Document Digitization은 LLM 입력을 위한 전처리입니다.

LLM 기반의 챗봇, 검색 시스템, 문서 요약 등에 문서를 활용하기 위해선 반드시 먼저 문서를 문단/표/수식/이미지 등으로 나누고 이의 구조를 인식해야 합니다. Document Parse는 LLM이 문서를 정확히 분석할 수 있도록 도와주는 핵심 전처리 도구입니다.

LLM 파이프라인은 대부분 자동화된 백엔드 환경에서 작동합니다. 서비스에서 실시간으로 문서를 받아 처리하려면 반드시 API 연동이 필요합니다.

활용 예시
- 특허 문서를 문단 단위로 분할 후 유사도 기반 검색 시스템에 연동 후, 쿼리로 관련 문서 검색하여 LLM에게 제공하는 RAG 시스템 구축
- 논문 PDF를 파싱하여 요약/하이라이트 기능 탑재된 애플리케이션 개발

그렇다면 이렇게 구조화된 문서를 바탕으로 워크플로우를 자동화하고, 애플레케이션을 만드는데 핵심 역할을 하는 Document Parse를 알아보러 가볼까요~?

3. 📊 Document Parse란?

Upstage Document Parse는 다양한 문서를 자동으로 HTML 구조로 변환해주는 모델입니다. 문서 내의 단락, 표, 이미지, 수식, 차트와 같은 레이아웃 요소를 감지하고, 읽기 순서에 따라 직렬화하여 LLM이 쉽게 이해할 수 있는 형태로 바꿔줍니다.

3-1. Demo : Document Parse 를 활용한 재무제표 분석 챗봇

본격적으로 Document Parse를 알아보기 이전에 어떤식으로 활용할 수 있을 지 데모를 먼저 확인해보겠습니다. 이 데모에서는 재무제표 문서를 HTML로 변환하고, 해당 문서를 기반으로 자유롭게 질문을 주고받을 수 있는 챗봇을 제작했습니다.

📄 재무제표 분석 챗봇

✨ 주요 기능

✅ Upstage Document Pasre API를 활용하여 재무제표 문서를 HTML 형태로 변환
✅ Solar LLM을 활용하여 재무제표 기반 Q&A를 진행합니다.

🖥️ 예제 코드

자세한 코드와 설명은 다음 링크에서 확인하실 수 있습니다.
👉 데모를 입맛에 맞게 바꾸고 싶다면, huggingface에 gradio 용 space를 개설하여 수정해보세요!

⚡️ 이렇게 DP는 LLM의 “눈”이 되어주며, 이를 통해 LLM이 외부 정보를 활용하여 보다 더 정확한 답변을 생성 할 수 있습니다.

3-2. Document Parse Input & Output 구조

Input 문서 주의사항

지원 파일 형식: JPEG, PNG, BMP, PDF, TIFF, HEIC, DOCX, PPTX, XLSX
최대 파일 크기: 50MB
최대 페이지 수
- Synchronous API: 최대 100 페이지
- Asynchronous API: 최대 1,000 페이지
페이지당 최대 픽셀 수: 100,000,000 pixels (150 DPI 기준 이미지 변환 후 측정)
지원 문자셋 (OCR 사용 시):
- 영어, 한글, 한자, 숫자 지원
- 중국 한자(Hanzi), 일본 한자(Kanji)는 베타 버전입니다.

Output 구조 이해하기

Document에는 단순한 텍스트 뿐만 아니라 제목, 표, 차트, 문단 등 다양한 정보를 포함합니다.

예를 들어, 위에 있는 테이블, 이미지를 단순 Document OCR로 읽는다면 표의 형식, 이미지 내용을 가지고 올 수없지만 HTML 태그와 함께 가지고 온다면 테이블 형식은 테이블 그대로, 이미지는 이미지로 인식하여 가지고 올 수 있습니다.

이렇게 구조화되어 읽을 수 있게 하기 위해서는 HTML 태그를 이해해야 합니다.

▶️ Layout categories & HTML tags

Document Parse는 문서의 다양한 구성 요소를 HTML 태그로 변환합니다.

아래 태그를 통해서 LLM은 table은 table, figure는 이미지 등 각 문서의 구조들을 이해할 수 있습니다.

Layout category

HTML 태그 예시

table

<table>...</table>

figure

<figure><img>...</img></figure>

chart

<figure><img data-category="chart">...</img></figure>

heading1

<h1>...</h1>

paragraph

<p data-category="paragraph">...</p>

equation

<p data-category="equation">$$...$$</p>

list

<p data-category="list">...</p>

그 외 header, footer, caption, index, footnote 등의 항목도 인식하며 적절한 태그 또는 data-category 속성을 부여합니다.

▶️ Chart Recognition

차트는 일반적으로 이미지로 처리되어 활용이 어려웠지만, Upstage는 이를 분석해 표 형식으로 변환합니다.

지원 차트 종류: 막대그래프, 선그래프, 원그래프
HTML로 변환 시 <figure data-category="chart"> 내에 <table> 형태로 삽입됩니다.

▶️ Equation Recognition

수식은 LaTeX 포맷으로 변환되어 <p data-category="equation">$$...$$</p> 형태로 출력됩니다.

웹에서는 MathJax 등의 수식 렌더링 엔진을 사용하여 렌더링할 수 있습니다.

▶️ Coordinates (상대 좌표)

coordinates 필드에는 각 요소의 위치가 상대 좌표(0~1) 로 포함됩니다.

이를 통해 문서 내 특정 영역만 크롭하거나, 시각화에 활용할 수 있습니다.

"coordinates": [
  { "x": 0.0276, "y": 0.0178 },
  { "x": 0.1755, "y": 0.0178 },
  { "x": 0.1755, "y": 0.0641 },
  { "x": 0.0276, "y": 0.0641 }
]

3-3. Getting Started with Document Parse API

Document Parse API 호출 방식은 총 2가지 방법으로 구분될 수 있습니다.

문서를 처리할 때 API 요청 방식은 동기 방식과 비동기 방식으로 나뉘며, 각각의 방식은 작업이 실행되고 응답을 받는 시점에 따라 다릅니다.

🔁 동기(Synchronous) API

동기(Synchronous) 란, 데이터의 요청과 결과가 한 자리에서 동시에 일어나는 것을 말합니다. 즉, API 호출 요청을 하면 시간이 얼마나 걸리든지 요청한 자리에서 응답 결과를 받을 수 있습니다.

쉽게 비유하자면, 동기 방식은 식당에서 주문하고, 음식 나올 때까지 자리에 앉아서 기다리는 것과 같습니다.

Upstage Document Parse Synchronous API 의 특징은 아래와 같습니다.

최대 100페이지 지원
요청 후 바로 결과 반환
실시간 처리나 테스트에 적합

Python 예시

import requests

api_key = "UPSTAGE_API_KEY" # ex: up_xxxYYYzzzAAAbbbCCC
filename = "your_file.pdf" # ex: ./image.png

response = requests.post(
    "https://api.upstage.ai/v1/document-digitization",
    headers={"Authorization": f"Bearer {api_key}"},
    files={"document": open(filename, "rb")},
    data={
      "ocr": "force", # OCR을 강제로 수행하도록 설정 ("auto"로 설정 시 이미지 문서에서만 OCR 수행)
      "coordinates": True, # 각 레이아웃 요소의 위치 정보 반환 여부
      "chart_recognition": True, # 차트 인식 여부 
      "output_formats": '["html"]', # 결과를 HTML 형식으로 반환 (text, markdown도 가능)
      "base64_encoding": '["table"]', # 표에 대한 base64 인코딩 요청
      "model": "document-parse" # 사용할 모델 지정 
    )
print(response.json())

예상 응답 결과

{"api": "2.0",
  "content": {
    "html": "<h1 id='0' style='font-size:22px'>INVOICE</h1>\\n<h1 id='1' style='font-size:20px'>Company<br>Upstage</h1>\\n<br><h1 id='2' style='font-size:18px'>Invoice ID</h1>\\n<br><h1 id='3' style='font-size:14px'>휴 INV-AJ355548</h1>\\n<h1 id='4' style='font-size:18px'>Invoice Date</h1>\\n<br><h1 id='5' style='font-size:18px'>9/7/1992</h1>\\n<h1 id='6' style='font-size:16px'>Mamo<br>Lucy Park</h1>\\n<h1 id='7' style='font-size:18px'>Address</h1>\\n<br><h1 id='8' style='font-size:16px'>7 Pepper Wood Street, 130 Stone Comer<br>Terrace<br>Wilkes Barre, Pennsylvania, 18768<br>United States</h1>\\n<h1 id='9' style='font-size:16px'>Email</h1>\\n<br><h1 id='10' style='font-size:16px'>Ikitchenman0@arizona.edu</h1>\\n<br><h1 id='11' style='font-size:20px'>Service Details Form</h1>\\n<h1 id='12' style='font-size:16px'>Name<br>Sung Kim</h1>\\n<h1 id='13' style='font-size:16px'>260 'ess<br>Gwangovolungang:co 338, Gyeongg do.<br>Sanghyeon-dong, Sui-gu<br>Yongin-si, South Korea</h1>\\n<h1 id='14' style='font-size:18px'>Additional Request</h1>\\n<br><p id='15' data-category='paragraph' style='font-size:14px'>Vivamus vestibulum sagittis sapien. Cum sociis natoque<br>penatibus 항목 magnis dfs parturient montes, nascetur ridiculus<br>mus.</p>\\n<h1 id='16' style='font-size:14px'>TERMS AND CONDITIONS</h1>\\n<p id='17' data-category='list' style='font-size:14px'>L TM Seir that not be lable 1층 the Buyer drectly indirectly for any loun or damage sufflered by 전액 Buyer<br>2. The 별 www. the product for ore 과 관한 from the date 설 shipment.<br>3. Any ourchase order received by ~ sele - be interpreted 추가 accepting the offer Ma the 18% offer writing The buyer may<br>purchase 15 The offer My the Terms and Conditions the Seller included The offer</p>",
    "markdown": "",
    "text": ""
  },
  "elements": [
    {
      "category": "heading1",
      "content": {
        "html": "<h1 id='0' style='font-size:22px'>INVOICE</h1>",
        "markdown": "",
        "text": ""
      },
      "coordinates": [
        {
          "x": 0.0648,
          "y": 0.0517
        }, ...
        }
      ],
      "id": 0,
      "page": 1
    },
    ...

⏳ 비동기(Asynchronous) API

비동기(Asynchronous)란, 말 그대로 동시에 일어나지 않는다는 의미입니다. 즉, API 호출 요청을 하면 즉각적으로 응답 결과를 받는 것이 아닌, 작업 ID(request_id)를 먼저 받고, 이 ID를 바탕으로 나중에 결과를 따로 조회할 수 있습니다.

비동기 방식도 쉽게 비유하자면, 음식 포장 주문 후, “15분 뒤에 오세요~” 하고 문자로 알려주는 것과 같습니다. 많은 양의 작업을 처리해야 할 때는, 비동기로 요청한 후 다른 작업을 하면서 기다릴 수 있다는 뜻입니다.

Upstage Document Parse Asynchronous API 의 특징은 아래와 같습니다.

최대 1,000페이지 지원
요청 즉시 request_id 반환
처리 완료 여부를 주기적으로 확인하거나, 결과 다운로드

동작 흐름

API로 요청 → request_id 받기
상태 확인 API로 진행 상황 조회
결과 다운로드 URL 확보 후 사용

Python 예시

비동기 요청 보내기

# 1. 비동기 요청 보내기 
import requests

api_key = "UPSTAGE_API_KEY" # ex: up_xxxYYYzzzAAAbbbCCC
filename = "your_file.pdf" # ex: ./image.png

url = "https://api.upstage.ai/v1/document-digitization/async"
headers = {"Authorization": f"Bearer {api_key}"}
files={"document": open(filename, "rb")},
data = {"model": "document-parse"}

response = requests.post(url, headers=headers, files=files, data = data)
print(response.json())  

# {"request_id": "e7b1..."}

request_id로 요청 결과 확인

import requests

api_key = "UPSTAGE_API_KEY"
request_id = "여기에_받은_request_id_입력"  # ex: e7b1..

url = f"https://api.upstage.ai/v1/document-digitization/requests/{request_id}"
headers = {"Authorization": f"Bearer {api_key}"}

response = requests.get(url, headers=headers)
result = response.json()

응답 결과

{
    "id": "e7b1b3b0-1b3b-4b3b-8b3b-1b3b3b3b3b3b",
    "status": "completed",
    "model": "document-parse",
    "failure_message": "",
    "total_pages": 28,
    "completed_pages": 28,
    "batches": [
        {
            "id": 0,
            "model": "document-parse-240910",
            "status": "completed",
            "failure_message": "",
            "download_url": "<https://download-url>",
            "start_page": 1,
            "end_page": 10,
            "requested_at": "2024-07-01T14:47:01.863880448Z",
            "updated_at": "2024-07-01T14:47:15.901662097Z"
        },
        ...

4. 🖼️ Document OCR이란?

Document OCR (Optical Character Recognition) 은 문서 이미지에서 텍스트를 감지하고 인식하는 기술입니다.

Upstage Document OCR은 다양한 문서 포맷에서 높은 정확도와 속도를 기반으로 텍스트를 추출합니다.

언제 사용하나요?

문서의 레이아웃 구조는 필요 없고, 텍스트만 빠르게 뽑고 싶을 때
스캔 이미지나 사진에서 텍스트만 인식하고 싶을 때
문서 자동화의 전처리 단계에서 간단한 OCR 추출만 필요한 경우

활용 예시

스캔한 신분증에서 이름/생년월일/주민번호 텍스트 인식
회의실 칠판 사진에서 핵심 키워드 OCR 추출

4-1. Demo : Document OCR을 활용한 영어 손글씨 편지 번역기

이 데모는 사용자가 영어 손글씨 편지 이미지를 업로드하면, Upstage Document OCR API를 통해 이미지 내 텍스트를 추출하고, Upstage Solar LLM을 통해 한국어로 자연스럽게 번역해 주는 간단한 웹 애플리케이션입니다.

📩 영어 손글씨 편지 번역기

✨ 주요 기능

Upstage Document OCR을 활용하여 이미지 내 텍스트를 추출
Upstage Solar LLM을 활용하여 영어를 한국어로 번역

🖥️ 예제 코드

코드에 대한 자세한 설명은 huggingface Files 에서 확인해보실 수 있습니다!
👉 데모를 입맛에 맞게 바꾸고 싶다면, huggingface에 gradio 용 space를 개설하여 수정해보세요!

⚡️ 가볍게 문서 내에서 텍스트만 빠르게 추출하고 싶을 때는 Document OCR을 활용해보세요!

4-2 Document OCR Input, Output 구조

문서 Input 주의 사항

지원 파일 형식: JPEG, PNG, BMP, PDF, TIFF, HEIC, DOCX, PPTX, XLSX
최대 파일 크기: 50MB
최대 페이지 수: 30 페이지
페이지당 최대 픽셀 수: 100,000,000 pixels (150 DPI 변환 기준)
지원 문자셋: 영어, 한글, 한자 지원
텍스트 크기 조건:
- 페이지 대비 약 30% 이하 크기의 텍스트에 최적화
- 이 조건을 충족하지 않는 경우, 오류 가능성 있음

Output 구조

{
  "apiVersion": "1.1",
  "modelVersion": "ocr-2.2.1",
  "pages": [
    { "page": 1,
      "text": "Print the words \\nhello, world",
      "confidence": 0.99, 
      "words": [
        {
          "text": "hello",
          "boundingBox": {
            "vertices": [
              { "x": 65, "y": 52 },
              { "x": 221, "y": 55 },
              { "x": 221, "y": 104 },
              { "x": 65, "y": 104 } ]}}]}]}

Document OCR 모델은 문서 내의 텍스트를 인식하고, 각 단어에 대해 다음 정보를 제공합니다:

텍스트 내용 (text)
신뢰도 점수 (confidence)
단어의 위치 좌표 (boundingBox)

▶️ 다양한 문서 환경에서의 강인성 (Robustness)

Upstage OCR은 다음과 같은 상황에서도 안정적인 성능을 보입니다:

이미지 회전, 기울임
배경 워터마크 또는 체크박스 존재
문서 노이즈 또는 저화질 스캔본

모델은 상단 좌측 기준의 단어 박스 좌표를 정밀하게 감지하며, 의미 없는 텍스트 (워터마크 등)는 자동으로 필터링합니다.

▶️ 신뢰도 점수 활용 (Confidence Score)

문자 단위 인식 정확도를 바탕으로, 단어 단위 confidence score를 생성합니다.
이 점수는 OCR 결과의 신뢰도를 나타내며,
낮은 점수의 영역은 후처리 필터링이나 사용자 확인이 필요한 부분으로 활용 가능합니다.

4-3. Getting Started with Document OCR API

# pip install requests

import requests

api_key = "UPSTAGE_API_KEY" # ex: up_xxxYYYzzzAAAbbbCCC
filename = "your_file.pdf" # ex: ./image.png

url = "https://api.upstage.ai/v1/document-digitization"
headers = {"Authorization": f"Bearer {api_key}"}
files = {"document": open(filename, "rb")}
data = {"model": "ocr"} 

response = requests.post(url, headers=headers, files=files, data = data)

print(response.json())

응답 결과 (예시)

{
  "apiVersion": "1.1",
  "modelVersion": "ocr-2.2.1",
  "pages": [
    {
      "page": 1,
      "text": "Print the words \\nhello, world",
      "confidence": 0.99, 
      "words": [
        {
          "text": "hello",
          "boundingBox": {
            "vertices": [
              { "x": 65, "y": 52 },
              { "x": 221, "y": 55 },
              { "x": 221, "y": 104 },
              { "x": 65, "y": 104 } ]}}]}]}

WrapUp

🔹 Document Digitization이란?: 문서 내 텍스트와 구조 정보를 디지털화하여 기계가 이해할 수 있는 형태(HTML, markdwon등)로 변환하는 기술입니다. 검색, 분석, 요약, 질의응답 등 문서 기반 작업의 첫 단계가 됩니다.

🔹 Document Digitization이 중요한 이유 : 문서는 여전히 많은 정보의 중심이지만, 대부분 제목, 표, 차트, 이미지 등 시각적 정보로 구성되어 있습니다. 구조화되지 않은 문서를 그대로 사용하면 LLM이 이를 이해하기 어렵기 때문에 문서를 구조화된 형태로 변환하여 활용한다면 다양한 파이프라인, 시스템과 연동 가능합니다.

🔹 Document OCR vs Document Parse API

항목

Document OCR

Document Parse

목적

텍스트 감지 및 추출

텍스트 + 레이아웃 구조 인식

출력 형식

텍스트 + 위치 좌표 + 신뢰도

HTML + 카테고리 태그 + 차트/수식 포함

강점

빠르고 가벼운 전처리