LlamaIndex의 HWP·HWPX 파싱 한계와 한컴 데이터 로더 API 연동 가이드

HANCOM 2026.08.06

LlamaIndex의 HWPReader는 HWP 텍스트 추출은 지원하지만, 표 구조와 문단 계층, HWPX는 지원하지 않습니다. 이러한 한계는 RAG(Retrieval-Augmented Generation, 검색 증강 생성) 검색 정확도와 답변 품질에도 영향을 줄 수 있습니다. 이번 글에서는 HWPReader의 한계를 살펴보고, 한컴 데이터 로더 API를 연동해 HWP·HWPX를 구조화 데이터로 활용하는 방법을 소개합니다.

LlamaIndex HWP·HWPX 파싱의 한계와 RAG 성능 영향

LlamaIndex HWPReader는 텍스트 추출은 되지만 표 구조·문단 계층·HWPX는 지원하지 않고, 이 파싱 품질 한계가 RAG의 할루시네이션(Hallucination)과 검색 정확도 저하로 직결됩니다.

HWPReader로 추출되는 것과 추출되지 않는 것

HWPReader는 HWP의 텍스트와 머리말은 추출하지만, 표 구조·이미지·문단 계층·HWPX는 지원하지 않습니다. LlamaIndex 공식 레퍼런스와 GitHub 소스를 직접 확인해 보면, HWPReader는 HWP 내부의 텍스트 태그만 골라 압축을 해제한 뒤 텍스트로 디코딩하는 구조입니다.

그래서 표는 셀 관계가 사라지고, 이미지 같은 텍스트 이외의 요소는 처리 대상에서 제외되며, 제목·본문 위계도 위계 구분 없이 처리되어 계층 정보가 남지 않습니다. 로딩도 파일 하나씩만 가능합니다. 가장 큰 제약은 HWPX 지원인데, HWPReader는 OLE 기반 HWP만 지원하기 때문에 XML·ZIP 기반의 HWPX는 처리할 수 없습니다.

LlamaIndex HWPReader 지원 범위 표

항목	HWPReader 지원 여부	RAG 영향
텍스트 추출	지원(텍스트 태그 한정)	본문 검색은 가능
머리말	지원	메타 정보 일부 확보
표 구조	미지원	표 수치 질의 오답
이미지	미지원(비텍스트 무시)	도표 정보 누락
문단 계층	미지원(동등 처리)	청킹 맥락 손실
HWPX	미지원(OLE 전용)	HWPX 문서 처리 불가
로딩 방식	단일 파일만	대량 배치 처리 부담

HWP를 PDF로 변환해서 파싱하면 안 되나요?

HWP를 PDF로 변환한 뒤 파싱할 수는 있지만, 약 15.8배 더 느리고 구조 손실까지 떠안게 됩니다. 한컴테크 분석에 따르면, HWPX에서 직접 추출하면 9.5초가 걸린 작업이 PDF로 변환한 뒤 추출하면 150.3초가 걸려, 약 15.8배의 시간 차이가 났습니다.

속도보다 더 큰 문제는 데이터 품질입니다. PDF 변환 과정에서 표가 평면 텍스트로 붕괴되면 행과 열 관계가 사라져 ‘몇 년도 예산이 얼마인지’ 같은 수치 질의에 부정확한 답이 나오고, 제목 계층이나 각주 같은 레이아웃 요소도 손실되어 청킹 기준점이 모호해집니다.

파싱 품질이 낮으면 RAG 할루시네이션이 시작되는 이유

파싱 품질이 낮을 경우 RAG는 이어지는 청킹·임베딩·검색 단계가 순차적으로 손상되며 할루시네이션이 시작됩니다.

RAG는 문서를 추출·파싱한 뒤 의미 단위로 자르고(청킹) 벡터로 바꿔(임베딩) 벡터DB에 저장한 다음, 질문과 가까운 조각을 검색해 LLM이 답을 생성하는 흐름입니다. 파싱 단계에서 구조 정보가 손실되면 손상된 구조로 청킹이 일어나, LLM은 사실상 원본과 다른 문서를 참조하게 되므로 모델이 좋아도 정확한 답을 내기 어렵습니다.

실제로 문서 파싱 기술을 정리한 연구는 레이아웃 분석과 표 인식을 RAG 같은 후속 활용을 뒷받침하는 파이프라인 핵심 구성요소로 제시하고, PDF 구조 인식을 다룬 연구에서도 RAG 프레임워크와 LLM API가 성숙해도 파싱 정확도가 병목이면 전문 지식 질의응답 품질이 떨어진다고 설명합니다.

즉 RAG 할루시네이션의 상당수는 모델이 아니라 파서 단계의 정보 손실에서 시작되므로, HWP·HWPX 원본을 직접 파싱하는 솔루션이 중요해집니다.

HWP 파싱 API 선택 전 확인해야 할 기준

HWP·HWPX 파싱 API를 선택할 때는 원본 직접 파싱 지원, DLA(Document Layout Analysis, 문서 구조 분석)·TSR(Table Structure Recognition, 표 구조 인식) 내재화, aijson 구조화 출력, 온프레미스 배포 가능 여부를 순서대로 확인합니다.

원본 직접 파싱 지원 여부가 먼저인 이유

‘HWP 지원’이라고 표기되어 있어도 내부적으로 PDF 변환을 거치는 경우가 있으므로, 실제로 원본 HWP를 직접 파싱하는지 확인하는 것이 중요합니다. 지원 포맷 목록만으로는 내부 처리 방식을 알 수 없기 때문입니다.

이러한 차이는 HWP 파일 구조에서 비롯됩니다. 한컴테크 블로그 전문에 따르면 HWP는 저장소와 스트림으로 구성된 CFB(Compound File Binary File Format, 복합 파일 이진 형식)이며 용량을 줄이기 위해 압축까지 적용돼 있어, 오픈소스로 압축을 풀어 텍스트를 뽑는 일과 표·계층 구조를 원래대로 복원하는 일은 난이도가 전혀 다릅니다.

그래서 원본 바이너리를 직접 해석하는 HWP SDK 원천기술이 있어야 PDF 변환 없이 구조를 보존한 채 추출하고, HWP 3.0 구버전까지 처리해 공공 현장의 레거시 문서를 RAG에 올릴 수 있습니다.

온프레미스·컨테이너 기반 REST API 지원이 필요한 환경

문서를 외부로 보낼 수 없는 환경이라면 온프레미스·컨테이너 기반 REST API 지원이 사실상 필수 조건입니다. 클라우드 API는 문서를 외부 서버로 전송해야 해서, 망분리가 적용된 공공·금융·법무 환경에서는 규정상 쓸 수 없는 경우가 많습니다.

해외 글로벌 솔루션은 여기서 두 번 걸립니다. HWP·HWPX를 지원하지 않는 데다 클라우드 전용이라 국내 폐쇄망과는 출발선부터 맞지 않습니다. 반면 컨테이너 기반 REST API는 내부망에 직접 설치해 외부 전송 없이 운용할 수 있고, 언어에 상관없이 연동할 수 있으며 GPU 없이 CPU만으로도 구동됩니다.

📌 온프레미스 도입 자가진단

✅ 문서를 외부로 보낼 수 없는 망분리 환경이다

✅ HWP·HWPX 문서 비중이 높다

✅ 표·이미지가 많은 문서를 다룬다

✅ 내부망 서버에 직접 설치해야 한다

위 사항 중 하나라도 해당된다면 외부 전송 없이 내재화할 수 있는 파싱 솔루션이 필요합니다.

한컴 데이터 로더로 HWP·HWPX 직접 파싱하기

한컴 데이터 로더는 HWP·HWPX·PDF·OOXML을 구조화 데이터로 전환하는 문서 파싱 솔루션으로, HWP·HWPX를 PDF 변환 없이 직접 파싱하고 DLA·OCR(Optical Character Recognition, 광학 문자 인식)·TSR을 단일 파이프라인으로 묶어 구조화 결과를 aijson으로 반환합니다.

HWPReader와 한컴 데이터 로더 파싱 품질 비교

HWPReader가 텍스트 추출에 머문다면, 한컴 데이터 로더는 표 구조·문단 계층·HWPX까지 복원하는 구조화 파싱을 수행합니다.

두 방식 모두 HWP에서 텍스트를 가져오지만, HWPReader의 출력은 계층 정보를 포함하지 않는 구조화되지 않은 텍스트라 RAG에 쓰려면 추가 후처리가 필요한 경우가 있습니다. 반면 한컴 데이터 로더는 Level 추론으로 문단 계층을 자동 태깅하고 결과를 aijson 구조화 포맷으로 내보냅니다.

HWPReader vs 한컴 데이터 로더 파싱 비교 표

항목	LlamaIndex HWPReader	한컴 데이터 로더
HWPX 지원	미지원(OLE 전용)	지원(직접 파싱)
표 구조 인식	미지원	표 구조 인식(TSR) 적용
문단 계층 추론	없음(동등 처리)	Level 추론 자동
출력 포맷	평면 텍스트	aijson 구조화 출력
온프레미스	라이브러리 직접 운용	컨테이너 기반 REST API 내재화

표·이미지가 많은 문서일수록 데이터 로더가 유리한 이유

TSR(Table Structure Recognition, 표 구조 인식)과 DLA(Document Layout Analysis, 문서 구조 분석)의 적용 여부에 따라, 표·이미지가 많아질수록 파싱 품질 격차가 크게 벌어집니다.

한컴 데이터 로더는 표 안의 표나 병합 셀까지 구조화하는 복잡한 표 추출을 지원해, 예산표·통계 차트·다단 양식이 많은 공공·금융 문서에 적합합니다.

HWP·HWPX 파싱 핵심 기능

한컴 데이터 로더의 HWP·HWPX 파싱은 DLA, 표 추출, 문서 내 이미지, TSR을 하나의 파이프라인으로 묶어, 포맷마다 별도 파서를 붙이지 않아도 되는 점이 핵심입니다.

HWP·HWPX·PDF를 AI에 최적화된 데이터로 변환합니다.

HWP·HWPX·PDF 문서는 JSON 및 TXT 형태로 출력되는 반면, OOXML은 TXT 형태로만 출력을 지원합니다.

💡 HWP·HWPX 파싱 결과가 실제로 어떻게 구조화되는지 궁금하다면?

👉 한컴 데이터 로더 라이브 데모 보러가기

한컴 데이터 로더 API로 LlamaIndex 연동하기

한컴 데이터 로더 API는 REST API로, HWP·HWPX 파일을 업로드하면 aijson 형태로 구조화 결과를 돌려주고, 이를 LlamaIndex Document 객체로 변환해 RAG 파이프라인에 연결합니다.

API 키는 sdk.hancom.com 가입 후 마이페이지에서 발급받을 수 있습니다.

데이터 로더 API 연동 흐름

데이터 로더 API 연동은 변환 요청, 완료 확인, 결과 다운로드의 세 단계로 진행되는 비동기 흐름입니다. 요청 즉시 결과가 오지 않고 처리 후 따로 받아오는 구조이므로, 첫 응답의 api_history_id를 저장해 두는 것이 중요합니다.

1. 변환 요청

POST https://api.sdk.hancom.com/api/api-services/convert로 문서를 보냅니다. 헤더에 X-API-Key를 넣고 multipart로 file과 선택값 webhook_url을 전달하면, 응답에 api_history_id·job_id와 함께 status: PROCESSING이 돌아옵니다.

2. 완료 확인(택1)

Webhook을 등록해 두면 완료 시 서버가 status: DONE·download_url·expired_at을 보내줍니다. 권장 방식이며, 폴링을 쓴다면 GET https://api.sdk.hancom.com/api/api-services/status/{api_history_id}로 상태를 조회합니다.

3. 결과 다운로드

GET https://api.sdk.hancom.com/api/api-services/download/{api_history_id}를 호출하면 .aijson 파일을 받습니다.

연동 전 제한 사항도 확인하는 것을 권장합니다. 파일당 최대 100MB, 1,000페이지 이하 문서 사용이 권장되며, 암호화(DRM) 문서는 지원하지 않습니다. 입력 포맷은 HWP·HWPX·PDF, 출력은 aijson입니다.

aijson 응답을 LlamaIndex에 연결하는 방법

aijson 응답은 elements 배열에서 category·level·content.text를 꺼내 LlamaIndex Document 객체로 변환하면, 계층 메타데이터를 유지한 채 청킹·임베딩으로 이어집니다.

aijson은 루트에 runtime·version·metadata·elements·pageSizes를 두고, 각 elements 항목이 id·category·level·confidence·content·bbox·pageIndex를 담습니다. 여기서 level이 문단 계층 정보라, 청킹 시 메타데이터로 그대로 활용할 수 있습니다.

import json
from llama_index.core import Document

# 데이터 로더가 반환한 .aijson 로드
with open("result.aijson", encoding="utf-8") as f:
    parsed = json.load(f)

# elements를 순회해 LlamaIndex Document로 변환
# (데이터 로더 범위는 문서 전처리(파싱, 구조화)까지, 이후 청킹, 검색은 RAG 단계)
documents = []
for el in parsed["elements"]:
    documents.append(
        Document(
            text=el["content"]["text"],  # content는 html, markdown, text 보유
            metadata={
                "category": el["category"]["label"],  # 제목, 표, 본문 등
                "level": el["level"],  # 문단 계층, 청킹 메타데이터
                "page_index": el["pageIndex"],
            },
        )
    )

이렇게 만든 Document 리스트는 이후 청킹·임베딩·벡터DB·검색·LLM 답변으로 이어지며, 데이터 로더는 RAG 전체를 대신하는 것이 아니라 가장 앞단 전처리를 책임집니다.

HWP 기반 RAG 파이프라인 아키텍처

HWP 기반 RAG 파이프라인은 HWP·HWPX를 데이터 로더 API로 파싱해 aijson을 얻고, 이를 청킹·임베딩·벡터DB·검색·LLM 답변으로 잇는 구조입니다. 데이터 로더는 가장 앞단 추출·파싱을 담당하고, 검색·질의응답은 그 뒤에 별도로 붙습니다.

이때 aijson의 level·bbox·pageIndex 같은 메타데이터가 청킹 품질을 높입니다. 청킹 전략을 분석한 연구에서는 문서를 의미 단위로 적절하게 나누는 것이 검색 정확도와 처리 효율을 높이는 데 중요하며, 청크가 과도하게 겹치면 검색 성능 향상 없이 저장 공간과 처리 비용만 증가할 수 있다고 설명합니다.

💡 HWP·HWPX 기반 RAG 구축을 검토 중이라면?

👉 한컴 데이터 로더 도입 문의

HWP 기반 RAG 구축, 이런 환경에서 고려해 보세요

HWP·HWPX 문서 비중이 높거나, 폐쇄망 환경이거나, 표·이미지가 포함된 문서를 RAG에 활용해야 한다면 PDF 변환 없는 직접 파싱 API가 필요합니다.

공공기관·금융·법무 문서 기반 RAG 구축이 필요한 경우

공공·금융·법무는 HWP 비중이 높고 문서를 외부로 보낼 수 없어, 온프레미스 직접 파싱 API가 필요합니다. 행정기관 종사자 1만 4,208명을 대상으로 한 조사에 따르면, 보고서·계획서 등 행정 문서를 주로 HWP나 이미지·스캔 PDF처럼 AI가 인식하기 어려운 형식으로 작성한다는 응답이 91.1%였습니다.

국회는 삼성SDS와 협업해 파싱한 문서를 벡터DB로 구축했고, 경기도교육청은 LG CNS와 협업해 파싱 결과를 RAG 어시스턴트로 연결했습니다. 이런 환경에서는 폐쇄망 안에서도 컨테이너 기반 REST API로 내재화할 수 있는지가 핵심 판단 기준입니다.

사내 지식검색과 업무 챗봇 구축이 필요한 경우

사내 매뉴얼·보고서는 표와 계층 구조 비중이 높아, 구조 손실 없는 파싱이 챗봇 답변 정확도에 직접 영향을 줍니다. 보고서 속 표가 손상되거나 목차 위계가 사라지면 챗봇이 ‘어느 항목의 어떤 수치’인지 맥락을 잃기 때문입니다.

HWP·HWPX가 섞여 있는 문서도 단일 API로 함께 처리할 수 있어 포맷별로 파이프라인을 나눌 필요가 없고, 사내 문서의 표·계층 비중이 높을수록 표 구조 인식(TSR)과 Level 추론의 효과가 더 크게 나타납니다.

HWP 파싱부터 RAG 구축까지, 파서 선택이 만드는 차이

RAG 품질은 모델보다 파서 단계에서 차이가 발생합니다. HWPReader는 텍스트 추출에는 충분하지만 표 구조·문단 계층·HWPX 앞에서 멈추고, 그 손실이 청킹·검색 단계 이후 답변 품질까지 순차적으로 이어집니다.

HWP·HWPX 원본 직접 파싱, DLA·TSR 내재화, 온프레미스 배포, aijson 구조화 출력이 공공·금융·법무 RAG의 전제가 되는 이유입니다.

🖥 한컴 데이터 로더

한컴 데이터 로더는 HWP·HWPX·PDF·OOXML을 구조화 데이터로 전환하는 문서 파싱 솔루션입니다. PDF 변환 없이 원본을 직접 파싱해 aijson으로 구조화하고, 추출된 데이터는 자사 RAG 솔루션 한컴피디아와 연계해 문서 수집부터 검색·답변까지 한컴 단일 스택으로 구축할 수 있습니다. 자세히 알아보고 싶다면 아래 링크를 통해 한컴 데이터 로더 API 가이드를 확인할 수 있습니다.

👉 한컴 데이터 로더 구경하기

👉 한컴 데이터 로더 API 가이드 살펴보기

참고 자료

LlamaIndex, 「HWPReader API Reference」
한컴테크, 「AX 시대를 위한 한글 문서: 오픈소스 생태계 현황 분석과 활성화 전략」
arXiv, 「Document Parsing Unveiled: Techniques, Challenges, and Prospects for Structured Information Extraction」, 2024
arXiv, 「Revolutionizing Retrieval-Augmented Generation with Enhanced PDF Structure Recognition」, 2024
한컴테크, 「한/글 문서 파일 형식: Python을 통한 HWP 포맷 파싱하기 (1)」
디일렉(THE ELEC), 「공공·국방 ‘HWPX’ 사용 의무화…AX 급물살」
한컴 데이터 로더 API 가이드
arXiv, 「A Systematic Analysis of Chunking Strategies for Reliable Question Answering」, 2026
ZDNet Korea, 「공무원 10명 중 9명 “AI 못 읽는 HWP·PDF 쓴다”…AI 정부 전환 ‘걸림돌’」
연합뉴스, 「국회 의정 지원에도 생성형 AI 도입…삼성SDS, 1단계 구축 완료」
아이티데일리, 「한컴, 경기도교육청 ‘경기교육 디지털플랫폼’ 사업 수주」

게시물 조회수: 158