출력 이해하기
레이아웃 카테고리와 HTML 태그
업스테이지 Document Parse는 입력 문서에서 다양한 레이아웃 카테고리 를 식별하고 이를 HTML 태그 로 변환해요.
아래 표는 모든 레이아웃 카테고리와 해당 HTML 태그를 설명해요.
해당 레이아웃 카테고리에 적합한 HTML 태그가 없는 경우, 모델이 감지한 레이아웃 카테고리를 설명하기 위해 data-category 속성과 함께 <p> 태그를 사용해요. 단, list 는 예외예요. document-parse-260930 과 document-parse-nightly 의 enhanced 모드에서는(auto 모드가 enhanced 로 처리한 페이지 포함) 대신 실제 <ul> 또는 <ol> 요소에 <li> 항목을 담아 반환하고, 목록 종류는 요소의 sub_category 필드(ul 또는 ol)에서 확인할 수 있어요.
| 레이아웃 카테고리 | HTML 태그 |
|---|---|
| table | <table> .. </table> |
| figure | <figure><img> .. </img></figure> |
| chart | <figure><img data-category="chart"> .. </img></figure> |
| heading1 | <h1>... </h1>; enhanced 모드(document-parse-260930, document-parse-nightly)에서는 sub_category 에 따라 <h2>부터 <h6>까지 |
| header | <header> .. </header> |
| footer | <footer> .. </footer> |
| caption | <p data-category="caption">..</p>; <table> 안에 들어간 캡션은 <caption>, <figure> 안에 들어간 캡션은 <figcaption> |
| paragraph | <p data-category="paragraph">..</p> |
| equation | <p data-category="equation">..</p> |
| list | <p data-category="list">..</p>; enhanced 모드(document-parse-260930, document-parse-nightly)에서는 <ul>/<ol> + <li> |
| index | <p data-category="index">..</p> |
| footnote | <p data-category="footnote"> </p> |
| code | <pre><code> .. </code></pre> |
일부 요소는 sub_category 필드도 함께 제공해요. 카테고리 안에서 더 세분화된 분류값이고, 값 집합이 열려 있어요. 예를 들어 figure 는 signature, stamp, qr_code, bar_code 일 수 있고, chart 는 line, bar, pie 일 수 있으며, heading1 은 제목 단계(h2부터 h6까지, 1단계 제목이면 생략)를 담고, code 블록은 프로그래밍 언어(예: python)를 담아요. 값 집합은 열려 있고 시간이 지나면서 늘어나므로, sub_category 는 고정된 값 목록이 아니라 임의의 문자열로 다뤄 주세요. 모델이 세분류를 제공하지 않으면 이 필드는 생략돼요. 제목 단계, 목록 종류, code 카테고리는 document-parse-260930 과 document-parse-nightly 의 enhanced 모드 파서가 제공해요.
레이아웃 카테고리의 자세한 예시는 아래에서 확인할 수 있어요.


수식 인식
equation 카테고리 출력의 경우, 모델은 MathJax 같은 일반적인 수식 렌더링 엔진에서 적절히 표시될 수 있도록 인식된 텍스트를 LaTex 형식으로 <p data-category="equation"> 태그 안에 제공해요.
샘플 수식 이미지의 출력은 아래에서 확인할 수 있어요.
응답에서 content.html과 content.markdown 필드는 LaTex 형식으로 인식된 수식을 담고 있으며, content.text 필드는 OCR 결과 텍스트를 담고 있어요.
현재 OCR 모델은 수식 인식을 지원하지 않기 때문에, content.text 필드에는 정확한 수식 텍스트가 포함되지 않을 수 있어요. equation 카테고리의 경우, content.text 필드의 OCR 결과는 하위 호환성을 위해 제공돼요.
사용자는 자신의 HTML 파일에서 content.html 필드 값을 제대로 렌더링하는 데 어려움을 겪을 수 있어요.
이는 JSON 형식의 API 응답이 \\ 문자를 이스케이프하기 때문이에요. 이 문제를 해결하려면 JavaScript를 사용해 HTML을 언이스케이프하면 돼요.
아래 예시 코드는 MathJax 라이브러리를 임포트하고 API 응답을 언이스케이프하여 HTML 파일에서 수식을 제대로 렌더링하는 방법을 보여줘요.
이 sanitize 단계는 이 수식 예제가 쓰는 <p> 태그만이 아니라, 위 표에 나온 모든 레이아웃 카테고리에서 Document Parse 가 낼 수 있는 태그와 속성을 전부 허용해요 — 그래야 문서의 다른 요소가 조용히 사라지지 않아요.
사용자는 요청 본문의 base64_encoding 필드에 ["equation"]을 지정하여 원본 문서에서 수식의 base64 인코딩된 이미지를 얻을 수도 있어요.
소수점 4자리 형식의 좌표
document-parse-240910부터, 사용자는 입력 문서에서 바운딩 박스를 그리거나 요소를 잘라낼 때 상대 좌표를 사용할 수 있어요. 절대 위치는 각 항목의 coordinates 필드에 있는 x, y 값에 요청한 이미지의 너비와 높이를 곱하여 계산할 수 있어요.