포스팅 개요
RAG(Retrieval Augmented Generation) 시스템이나 AI Agent를 개발하다 보면 결국 데이터에 대한 고민을 하게 됩니다.
어떤 LLM을 사용할지, 어떤 Vector Database를 사용할지와 같은 부분도 중요하지만 그 전에 먼저 해결해야 하는 것이 있습니다. 바로 우리가 가지고 있는 문서를 LLM이 활용할 수 있는 데이터로 만드는 것입니다.
특히 회사에서 RAG나 AI Agent 시스템을 만들다 보면 PDF뿐만 아니라 HWP, HWPX, Word 등 여러 형태의 문서를 사용하게 됩니다.
보고서, 매뉴얼, 공고문, 연구 자료처럼 이미 회사에 쌓여 있는 문서가 굉장히 많기 때문인데요. 문제는 이러한 문서를 단순히 텍스트로만 추출해서 사용할 수 없다는 점입니다.
예를 들어 문서 안에는 제목과 본문이 있고, 표와 이미지가 있고, 때로는 차트나 여러 단계로 병합된 표도 있습니다.
텍스트만 가져오는 과정에서 이러한 구조가 모두 사라진다면 데이터는 추출했지만 정작 RAG에서 사용하기에는 애매한 결과가 만들어질 수 있죠.
저 또한 실무적으로 이러한 문제를 풀기 위해 여러 OCR과 Document Analysis 관련 서비스를 사용해보고 있습니다.
특히 국내에서는 HWP 문서를 처리해야 할 일이 많다 보니 HWP 파싱은 계속해서 고민하게 되는 부분 중 하나입니다.
이번 포스팅에서는 이러한 문서 처리를 위해 한컴에서 제공하는 한컴 데이터 로더(Hancom Data Loader)와 한컴 OCR API를 직접 사용해보고 사용하는 방법과 후기를 정리합니다.
한컴으로부터 제품 이용 및 원고료를 지원받아 작성했습니다.
데이터 로더 - AI 학습 및 RAG용 문서 데이터 추출 도구
HWP 및 PDF 문서를 구조화된 데이터로 변환할 수 있습니다. AI 학습 및 RAG 활용을 위한 데이터 전처리를 자동화합니다.
sdk.hancom.com
포스팅 본문
[1]. 한컴 데이터 로더와 OCR API
먼저 제가 사용해본 두 API에 대해서 간단하게 살펴보겠습니다.
[1-1]. 한컴 데이터 로더
한컴 데이터 로더는 문서를 분석해서 AI에서 활용할 수 있는 구조화된 데이터로 변환하는 문서 파싱 API입니다. HWP와 HWPX를 비롯해 PDF 문서도 지원합니다.
단순히 문서 안에 있는 글자만 추출하는 것이 아니라 제목, 부제목, 본문, 목록과 같은 텍스트 요소부터 표, 글상자, 이미지, 차트, 캡션 등의 문서 요소를 분석합니다. 그리고 머리말, 꼬리말, 각주, 페이지 번호, 수식뿐 아니라 글꼴이나 크기, 볼드, 정렬과 같은 정보도 추출할 수 있도록 구성되어 있습니다.
특히 표의 경우 병합된 셀이나 표 안의 표와 같은 구조를 분석할 수 있고, 이미지와 차트와 같은 시각적 정보 역시 AI 기술을 활용해 처리하도록 되어 있습니다. 이렇게 추출된 데이터는 이후 AI 학습 데이터, 검색 인덱싱이나 RAG 문서 전처리 등에 활용할 수 있습니다.
[1-2]. 한컴 OCR API
한컴 SDK에서는 OCR API도 제공하고 있습니다. OCR(Optical Character Recognition)은 이미지나 스캔 문서 안에 있는 글자를 인식해서 텍스트 데이터로 변환하는 기술입니다.
한컴 OCR API는 PNG, JPEG, BMP 등의 이미지에서 한국어와 영어 텍스트를 인식할 수 있는데요. 결과에는 단순히 전체 텍스트만 들어가는 것이 아니라 단어와 라인 단위의 텍스트, 좌표 그리고 인식 신뢰도도 함께 포함됩니다.
[2]. API Key 발급받기
먼저 API를 사용하기 위해서는 API Key가 필요합니다. API Key는 한컴 SDK에 회원가입한 뒤 마이페이지에서 발급받을 수 있습니다.
1. sdk.hancom.com에 회원가입 후 로그인합니다.
2. 우측 상단 프로필을 눌러 마이페이지로 이동합니다.
3. 좌측의 API 관리 메뉴로 이동합니다.
4. 사용할 서비스의 API Key 관리 버튼을 누릅니다.
5. API Key 생성 버튼을 누르고 이름과 메모를 입력합니다.
데이터 로더와 OCR은 각각 별도의 API Key를 발급받아야 합니다. 두 개의 서비스는 독립된 서비스여서 Key가 구분되어져 있습니다.
저도 처음에는 하나의 키로 같이 사용하는 줄 알았는데 API 관리 화면에 들어가면 두 서비스가 각각 구분되어 있습니다.
그래서 코드에서도 두 API Key를 따로 관리했습니다.
# .env
HANCOM_DATALOADER_API_KEY=발급받은_데이터로더_API_KEY
HANCOM_OCR_API_KEY=발급받은_OCR_API_KEY
회원가입 후에는 무료 체험용 크레딧도 받을 수 있습니다.
제가 가입했을 때는 10,000 크레딧을 받았습니다. 여러 문서를 넣어보고 API를 테스트하기에는 꽤 충분한 양이었습니다.
제가 테스트한 시점의 크레딧 차감 기준은 아래와 같았습니다.
| 서비스 | 기준 | 차감 |
| 데이터 로더 | PDF, HWP(X) 문서 | 1페이지당 10 Credit |
| OCR API | 이미지 | 이미지 1장당 2 Credit |
이제 API Key도 준비했으니 실제로 하나씩 사용해보겠습니다.
[3]. 한컴 데이터 로더 API 사용 방법
한컴 데이터 로더 사용 방법은 Document에 자세히 설명되어져 있습니다.
기본적으로 데이터 로더 API는 비동기로 동작합니다. 문서를 업로드하면 바로 최종 결과가 반환되는 것이 아니라 변환 작업을 요청한 뒤, 작업 상태를 확인하고 처리가 끝나면 결과를 다운로드하는 방식입니다.
전체적인 과정은 아래와 같습니다.
1. 변환 요청
POST /convert
↓
2. 변환 상태 조회
GET /status/{api_history_id}
↓=
3. 변환 결과 다운로드
GET /download/{api_history_id}
Base URL과 API Key는 공통으로 아래처럼 사용했습니다. 파이썬 코드 기준으로 설명하겠습니다.
import os
import time
import json
import requests
BASE_URL = "https://api.sdk.hancom.com/api/api-services"
HEADERS = {
"X-API-Key": os.environ["HANCOM_DATALOADER_API_KEY"]
}
[3-1]. 변환 요청
첫 번째 단계는 변환할 파일을 API에 전달하는 것입니다. 요청에는 변환할 file과 webhook_url을 함께 전달합니다.
def request_convert(file_path):
with open(file_path, "rb") as f:
response = requests.post(
f"{BASE_URL}/convert",
headers=HEADERS,
files={
"file": (
os.path.basename(file_path),
f,
"application/octet-stream"
)
},
data={
"webhook_url": "http://127.0.0.1:8000/webhook"
},
timeout=300
)
response.raise_for_status()
result = response.json()
print(result)
return result["data"]["api_history_id"]
변환 요청이 정상적으로 접수되면 api_history_id를 받을 수 있습니다.
이 값이 하나의 변환 작업을 구분하는 ID이고, 이후 상태 조회와 결과 다운로드에서도 계속 사용합니다.
{
"success": true,
"data": {
"api_history_id": 12345,
"job_id": "a1b2c3d4-...",
"status": "PROCESSING"
}
}
[3-2]. 변환 상태 조회
두 번째 단계는 방금 요청한 문서의 변환이 끝났는지 확인하는 것입니다.
앞에서 받은 api_history_id를 이용합니다.
저는 아래와 같이 활용했습니다.
def get_status(history_id):
response = requests.get(
f"{BASE_URL}/status/{history_id}",
headers=HEADERS,
timeout=30
)
response.raise_for_status()
return response.json()["data"]
상태는 처리 중인 PROCESSING, 완료된 DONE, 실패한 FAILED와 같은 형태로 확인할 수 있습니다.
저는 Python에서 몇 초 간격으로 상태를 확인하도록 만들었습니다. 제 예제 코드는 다음과 같습니다.
def wait_until_done(history_id):
while True:
result = get_status(history_id)
status = result["status"]
print("현재 상태:", status)
if status == "DONE":
return result
if status == "FAILED":
raise RuntimeError("문서 변환에 실패했습니다.")
time.sleep(5)
처리가 완료되면 상태가 DONE으로 변경됩니다.
[3-3]. 변환 결과 다운로드
마지막으로 변환 결과를 다운로드합니다. 역시 앞에서 받은 api_history_id를 사용하면 됩니다.
제가 작성한 코드는 아래와 같습니다. 공식 문서를 참고해서 만들었습니다.
def download_result(history_id, output_path):
response = requests.get(
f"{BASE_URL}/download/{history_id}",
headers=HEADERS,
timeout=300
)
response.raise_for_status()
with open(output_path, "wb") as f:
f.write(response.content)
return json.loads(response.content)
여기까지 연결하면 하나의 문서를 올리고 결과를 받는 전체 과정은 아래처럼 간단하게 만들 수 있습니다.
file_path = "sample.hwp"
history_id = request_convert(file_path)
wait_until_done(history_id)
result = download_result(
history_id,
"result.aijson"
)
print(result.keys())
결국 변환 요청, 상태 조회, 결과 다운로드의 세 단계로 이루어지며, API Document가 잘 나와있어서 API 자체의 사용 방법은 어렵지 않습니다.
[4]. 데이터 로더 결과 확인
그럼 실제 데이터를 활용해서 한컴 데이터 로더 결과를 확인해보겠습니다. 결과 확인을 위해서 개인적으로 웹 페이지를 하나 만들었습니다.
파일을 업로드하면 한컴 API를 호출하고, 처리가 끝나면 왼쪽에는 원본 문서를, 오른쪽에는 파싱된 결과를 보여주도록 만들었습니다.
HTML, Markdown, Text와 원본 aijson도 확인할 수 있도록 했습니다.
제가 가지고 있던 2페이지짜리 논문 PDF를 사용해봤는데요. 결과를 보면 본문, 제목, 표, 그림뿐만 아니라 머리말과 페이지 번호도 각각의 요소로 구분되어 있었습니다.
{
'PageHeader': 2,
'OtherText': 2,
'Figure': 2,
'ParaText': 10,
'ParaTitle': 1,
'PageNumber': 2,
'Table': 1
}
각 요소에는 HTML, Markdown, Text 형태의 내용과 함께 원본에서의 위치 정보도 들어 있었습니다. 그래서 왼쪽 원본 PDF에 해당 영역을 표시하고, 오른쪽 파싱 결과와 연결할 수 있었습니다. 위 사진과 같이 말이죠!
그리고 표도 잘 파싱이 되는 것을 확인할 수 있습니다.
API 응답의 HTML을 확인해보면 아래처럼 rowspan 정보가 그대로 들어 있었습니다.
<table>
<tr>
<td>Dimension</td>
<td>Pearson r</td>
<td>p-value</td>
<td>Direction</td>
</tr>
<tr>
<td>Contribution</td>
<td>0.743</td>
<td>1.14 x 10-50</td>
<td rowspan="3">
Strong positive
Strong positive
Moderate positive
</td>
</tr>
</table>
즉 단순히 표 안의 글자만 추출된 것이 아니라 셀 구조도 같이 유지되고 있었습니다.
다음으로 HWP와 HWPX도 넣어봤습니다.
HWP 결과에서는 문단의 텍스트뿐 아니라 정렬, 글자 굵기, 글꼴 크기, 글꼴 이름 그리고 페이지 번호 같은 정보도 같이 확인할 수 있었습니다.
그리고 표 안에 들어 있는 문단에는 행과 열의 위치, rowSpan, colSpan과 같은 정보가 들어 있었습니다.
위와 같은 표도 잘 파싱이 되는 것을 확인할 수 있습니다. 랜더링이 잘 되었죠. 실제 결과까지 확인해보면
위 사진과 같이 HTML이 정상적으로 추출되었음을 확인할 수 있습니다.
HWPX 양식 파일과 HWP 둘 다 잘 나오는 것을 확인했습니다.
빈 셀이 많고 여러 표가 섞여 있는 문서였는데 각 셀의 내용을 확인할 수 있었고, 웹 페이지에서도 문서 형태로 다시 구성할 수 있었습니다.
[5]. 한컴 OCR API 사용 방법
이번에는 한컴 OCR API를 사용해보겠습니다. OCR API는 이미지 안에 있는 글자를 인식해서 텍스트로 변환합니다.
PNG, JPEG, BMP 형식을 사용할 수 있고 파일당 최대 100MB 입니다.
그리고 앞에서 데이터 로더를 사용해보셨다면 OCR API 사용 방법도 어렵지 않습니다. 호출하는 과정 자체가 거의 동일하기 때문입니다.
1. OCR 요청
POST /convert
↓
2. OCR 상태 조회
GET /status/{api_history_id}
↓
3. OCR 결과 다운로드
GET /download/{api_history_id}
다만 이번에는 앞에서 별도로 발급받은 OCR API Key를 사용합니다. 앞에서도 언급하였지만, 데이터 로더와 다른 API입니다.
BASE_URL = "https://api.sdk.hancom.com/api/api-services"
OCR_HEADERS = {
"X-API-Key": os.environ["HANCOM_OCR_API_KEY"]
}[5-1]. OCR 요청
먼저 OCR을 수행할 이미지 파일을 업로드합니다. 즉, 이미지 파일 자체를 requests로 API를 통해 보냅니다.
저는 아래와 같이 코드를 구성했습니다.
def request_ocr(file_path):
with open(file_path, "rb") as f:
response = requests.post(
f"{BASE_URL}/convert",
headers=OCR_HEADERS,
files={
"file": (
os.path.basename(file_path),
f,
"application/octet-stream"
)
},
data={
"webhook_url": "http://127.0.0.1:8000/webhook"
},
timeout=300
)
response.raise_for_status()
result = response.json()
return result["data"]["api_history_id"]
이 과정 역시 요청이 접수되면 api_history_id를 받습니다.
[5-2]. OCR 상태 조회
OCR 처리가 끝났는지도 상태 조회 API로 확인할 수 있습니다. 데이터 로더와 굉장히 유사하죠?
저는 아래와 같이 코드를 만들었습니다.
def wait_ocr(history_id):
while True:
response = requests.get(
f"{BASE_URL}/status/{history_id}",
headers=OCR_HEADERS,
timeout=30
)
response.raise_for_status()
result = response.json()["data"]
print("현재 상태:", result["status"])
if result["status"] == "DONE":
return result
if result["status"] == "FAILED":
raise RuntimeError("OCR 처리에 실패했습니다.")
time.sleep(3)
OCR 처리가 끝나면 DONE 상태를 확인할 수 있습니다.
[5-3]. OCR 결과 다운로드
마지막으로 OCR 결과를 다운로드합니다.
def download_ocr(history_id, output_path):
response = requests.get(
f"{BASE_URL}/download/{history_id}",
headers=OCR_HEADERS,
timeout=300
)
response.raise_for_status()
with open(output_path, "wb") as f:
f.write(response.content)
return json.loads(response.content)
전체적으로 사용한다면 아래와 같습니다.
history_id = request_ocr("document.jpeg")
wait_ocr(history_id)
result = download_ocr(
history_id,
"ocr_result.aijson"
)
page = result["RESULT"][0][0]
print("이미지 크기:", page["image_width"], page["image_height"])
print("인식된 단어 수:", len(page["words"]))
print("인식된 라인 수:", len(page["lines"]))
OCR 결과에는 전체 텍스트와 함께 words와 lines가 들어 있습니다.
실제 단어 하나를 보면 아래와 같은 형태입니다.
{
"word_id": 0,
"bbox": [
886, 205,
1456, 219,
1454, 271,
884, 257
],
"text": "인공지능(AI)/LLM&RAG",
"score": "0.869420"
}
텍스트뿐 아니라 해당 글자가 이미지에서 어디에 있었는지를 알 수 있는 좌표와 OCR 인식 신뢰도도 같이 받을 수 있습니다.
[6]. OCR 결과 확인
앞에서 만든 웹 페이지에 OCR API도 같이 연동해서 확인해보겠습니다.
제가 만든 테스트 페이지에서는 편의를 위해 이미지 파일을 업로드하면 OCR API를 호출하도록 설정했습니다.
먼저 테스트를 위해 제가 작성한 블로그 화면을 휴대폰으로 직접 찍어봤습니다. 개인적으로 OCR 성능 테스트 할 때 이런 데이터로 확인해봅니다. 그래야 정확한 성능의 감을 잡을 수 있어서요.
모니터를 휴대폰으로 그냥 찍은 사진이라 약간의 빛 반사도 있는 상태였습니다.
이 이미지를 OCR API에 넣어보니 175개의 단어와 27개의 라인이 추출됐습니다.
line 0: 인공지능(AI)/LLM&RAG
line 1: 왜 LLM은 일본 문화에 집착할까?
LLM에 숨어 있는 문화
line 2: 적 지역적 편향
line 3: 이수진의블로그
line 4: 2026.7.26. 15:33
line 8: 이논문은제목부터가 좀 놀랍다.
"왜 모든 LLM은 일본 문화에 집착하는가"라는...
꽤 잘 데이터가 추출되었습니다. 사진 상태를 생각하면 개인적으로 한국어 텍스트는 잘 인식된 편이라고 느꼈습니다. 다른 데이터도 유사한 성능을 보여줬습니다.
표가 있는 화면을 찍은 이미지도 같이 테스트했습니다. 이 경우에는 작은 영어 글자가 많아서 일부 오인식도 확인됐는데요. 그럼에도 화질도 안좋고 사진 상태도 안 좋은 상태에서, 옛날 핸드폰으로 찍은 사진인데도 나름 결과가 좋게 나왔습니다.
그리고 한컴 OCR은 OCR 결과에 단어별 신뢰도가 같이 들어오기 때문에 어느 부분의 인식 결과를 조금 더 확인해봐야 하는지 판단하기가 편했습니다.
라인 p0o13 신뢰도 0.60
Mythology A Falklern Norratives ...
라인 p0o14 신뢰도 0.66
Gender Roles Culteral expectarions ...
라인 p0o15 신뢰도 0.69
Family & Social Roles ...
라인 p0o17 신뢰도 0.83
Social Structure and Duily Life
[7]. 데이터 로더와 OCR 결과 차이
앞에서 데이터 로더와 OCR API를 각각 사용해봤습니다. 두 API는 문서나 이미지에서 데이터를 가져온다는 점에서는 비슷해 보이지만, 실제 결과를 확인해보면 차이가 있는데요.
OCR은 이미지 안에 있는 글자를 인식해서 텍스트로 변환하는 것이 중심이라면, 데이터 로더 방식은 문서 안의 텍스트 뿐만 아니라 제목, 본문, 표와 같은 문서의 구조를 함께 분석합니다.
위 첫 번째 사진(데이터 로더)와 두 번째 사진(OCR) 결과를 보면 그 차이를 알 수 있는데요. OCR에서는 이미지의 글자를 인식해서 단어와 라인 단위로 추출할 수 있으며 위치를 확인할 수 있습니다. 즉, 이미지 안에 어떤 글자가 있고 그 글자가 어디에 있는지 초점이 맞추어져 있죠.
데이터 로더의 결과는 좀 더 다릅니다. 단순히 페이지에 있는 텍스트를 가져오는 것이 아니라 각각의 요소가 본문인지, 제목인지, 표인지와 같은 문서의 요소가 구분되어 있습니다. 즉, 표와 문서 구조까지 유지되는 점이 특징입니다.
RAG 등에서 활용할 때는 단순히 텍스트가 추출됐다는 것으로 끝나면 안됩니다. 예를 들어 표에 있는 여러 셀의 텍스트가 하나의 일반 텍스트처럼 섞여버린다면 어느 값이 어떤 행과 열에 해당하는지 알 수 어려워지겠죠? 제목과 본문의 관계나 문서 내부의 구분 역시 이후 청킹(chunking) 과정에서 활용할 수 있는 정보일 것입니다.
둘 중 뭐가 더 낫느냐는 상황에 따라 다를 것입니다. 한컴에서 제공하는 데이터 로더와 OCR은 이러한 차이점이 있다는 점을 알아두시고 활용하시면 될 것 같습니다!
[8]. 데이터 로더 결과를 RAG에 활용하기
마지막으로 데이터 로더에서 파싱한 결과를 가지고 간단하게 RAG까지 연결해봤습니다.
문서를 파싱하는 목적이 결국 데이터를 추출하는 것에서 끝나는 것이 아니라 이후 검색이나 RAG, AI Agent 등에서 활용하기 위한 경우가 많기 때문이죠.
저는 데이터 로더의 파싱 결과에서 본문이나 표와 같은 데이터를 가져와 청킹한 뒤 임베딩하고, 질문을 입력하면 관련 문서를 검색해서 답변할 수 있도록 간단하게 구성했습니다.
공고문 HWP를 색인한 다음 "AI 소재 R&D 플랫폼 구축 전략 후속조치"라고 질의해봤습니다.
검색 결과 중 가장 높은 결과가 5페이지에 있던 표에서 나왔습니다. HWP에는 본문처럼 보이는 내용이 실제로 표 안에 들어가 있는 경우가 많기 때문에 표의 구조와 내용을 같이 가져올 수 있다는 것이 RAG나 AI Agent에서 사용할 때 유용할 것 같다는 생각입니다.
마무리
이번 포스팅에서는 한컴에서 제공하는 데이터 로더와 OCR API를 직접 사용해봤습니다.
요즘 RAG나 AI Agent를 개발하면서 어떤 LLM을 사용할 것인지에 대한 이야기를 많이 합니다.
하지만 개인적으로 실제 시스템을 개발해보면 그 전에 가지고 있는 문서를 어떻게 잘 파싱하고, AI가 사용할 수 있는 형태의 데이터로 만드는지가 상당히 중요하다고 생각합니다.
특히 국내 업무 환경에서는 HWP와 HWPX 형태의 자료가 여전히 많습니다.
보고서나 공고문처럼 표가 많이 포함된 HWP 파일을 처리해야 하는 경우에는 단순한 텍스트 추출뿐 아니라 표와 문서 구조를 어떻게 가져올 것인지도 함께 고민해야 합니다.
제가 이번에 여러 HWP, HWPX, PDF 파일을 데이터 로더에 직접 넣어본 결과에서는 본문과 표, 이미지 등의 문서 요소를 구조화된 형태로 확인할 수 있었고, 특히 표의 병합 정보도 활용할 수 있었습니다.
OCR API 역시 직접 촬영한 이미지에서 텍스트와 위치, 신뢰도를 확인할 수 있었습니다.
문서 기반의 RAG나 AI Agent를 개발하면서 문서 파싱 방법을 고민하고 계시거나, 특히 처리해야 하는 HWP 파일이 많은 환경이라면 한 번 직접 가지고 있는 문서로 테스트해보셔도 좋을 것 같습니다.
비록 부족한 글이지만, 문서 파싱과 RAG 데이터 전처리를 고민하고 계신 분들께 조금이라도 도움이 되었으면 좋겠습니다.
긴 글 읽어주셔서 감사합니다.
혹시라도 저에게 연락을 주시고 싶으시다면,
- Linkedin: https://www.linkedin.com/in/lsjsj92/
- 블로그 댓글 또는 방명록
으로 연락 남겨주시면 됩니다!
'인공지능(AI) > LLM&RAG' 카테고리의 다른 글
| 왜 LLM은 일본 문화에 집착할까? LLM에 숨어 있는 문화적·지역적 편향 (197) | 2026.07.26 |
|---|---|
| RAG 검색 품질의 핵심 '일관성(Coherence)' 높이기: Amazon AGI 연구 논문 리뷰 (12) | 2025.11.30 |
| CRAG: RAG의 검색 실패와 환각(Hallucination)을 해결하는 Corrective RAG 논문 리뷰 (1) | 2025.11.23 |
| 윈도우(windows)에서 PostgreSQL pgvector 설치 및 사용하기 (1) | 2025.11.19 |
| 업스테이지 문서 파싱(Document parsing) playground 서비스 개발기( 코드 공유 ) (1) | 2025.10.15 |
