HWP·HWPX 데이터 추출 – 포맷 구조부터 오픈소스 라이브러리까지

공공기관에서도 AI 활용이 본격화되면서, 기존 행정문서를 AI가 활용할 수 있는 데이터로 바꾸는 일이 중요한 과제가 되고 있습니다. 

행정안전부는 AI가 읽기 쉬운 개방형 문서 체계로 전환하기 위해 2026년 5월부터 온나라 문서시스템에서 HWP 첨부를 제한하고 HWPX 사용을 의무화했습니다. 기획재정부도 공공기관 경영평가에 AI 활용 가점을 신설하며 AX 전환 흐름을 평가 기준에 반영했습니다.

이제 HWP·HWPX 데이터 추출은 단순한 파일 변환이나 텍스트 추출을 넘어, 공공문서를 비정형 데이터 처리와 RAG 전처리에 활용하기 위한 핵심 작업이 되고 있습니다.

이번 글에서는 HWP·HWPX 전처리가 어려운 이유부터 포맷 구조, 주요 오픈소스 라이브러리, 그리고 실제 RAG 환경에서 고려해야 할 파싱 기준까지 정리해보겠습니다.

RAG 성능의 핵심, HWP·HWPX 데이터 전처리는 왜 어려울까?

공공기관에서 RAG 파이프라인 구축을 위해 HWP·HWPX 문서를 전처리할 때 가장 먼저 시도하는 일은 주로 텍스트 추출입니다. 실제로 ‘파이썬 hwp 텍스트 추출’ 라이브러리를 찾아 설치하고, 샘플 문서를 넣어보면 본문이 어느 정도 추출되는 것처럼 보입니다.

하지만 실제 공공기관 문서에 적용해 보면 결과가 달라집니다. 다단 편집이 적용된 문서는 읽기 순서가 뒤섞이고, 표가 많은 문서는 항목명과 수치가 분리되거나 일부 내용이 빠질 수 있습니다. 샘플 문서에서는 보이지 않던 한계가 실제 행정문서에서 드러납니다.

텍스트 추출 단계에서 문장 순서가 어긋나거나 표의 맥락이 사라지면, 이후 RAG 전처리 과정에서도 같은 문제가 이어집니다. 잘못 추출된 텍스트는 의미 단위가 아닌 위치에서 청킹되고, 그렇게 만들어진 조각은 임베딩과 검색 단계에서도 정확한 근거로 활용되기 어렵습니다.

HWP·HWPX 데이터 전처리는 단순히 글자를 뽑아내는 작업이 아닙니다. 공공문서를 RAG 파이프라인에 연결하려면 텍스트뿐 아니라 문단 순서, 표 구조, 항목과 값의 관계까지 함께 유지하는 방식으로 접근해야 합니다.

HWP·HWPX 파싱이 어려운 이유, 포맷 구조부터 이해하기

HWP는 바이너리, HWPX는 XML 기반 포맷으로 구조가 다릅니다.

HWP – CFB 기반 바이너리 포맷 구조

HWP 포맷은 내부에 폴더와 비슷한 계층 구조를 가진 CFB(Compound File Binary Format, 복합 파일 이진 형식)로 설계되어 있기 때문에 HWP 특화 파서가 필요합니다.

파일 내부가 저장소(Storage)와 스트림(Stream) 구조로 나뉘어 있고, 문서 정보는 DocInfo에, 본문 내용은 BodyText 스트림에 분산 저장됩니다.

그렇기 때문에 본문 데이터에 접근하려면 먼저 zlib으로 압축된 내용을 해제한 뒤, 각 데이터를 레코드 단위로 읽어야 합니다. 이때 레코드 헤더에 담긴 Tag ID, Level, Size 정보를 정확히 해석해야 다음 데이터의 위치를 찾을 수 있습니다.

만약 레코드 크기나 위치 계산이 어긋나면 이후 본문, 표, 서식 정보가 연쇄적으로 잘못 읽힐 수 있습니다. HWP 포맷 구조가 공개되어 있어도 직접 구현 난도가 높은 이유는 이처럼 내부 바이너리 구조와 레코드 흐름을 정밀하게 해석해야 하기 때문입니다.

출처: 한컴테크, 「한/글 문서 파일 형식: Python을 통한 HWP 포맷 파싱하기 (1)」

HWPX – 웹 표준과 연동되는 개방형 XML 포맷 구조

HWPX는 OWPML 오픈 XML 구조를 기반으로 한 개방형 문서 포맷입니다. ZIP 컨테이너 안에 여러 XML 파일과 리소스가 함께 묶여 있는 구조라, 기존 HWP처럼 바이너리 레코드를 직접 해석하는 방식보다 텍스트 데이터에 접근하기 쉬운 편입니다.

HWP가 압축 플래그 여부에 따라 zlib 압축 해제와 레코드 단위 파싱 과정을 거쳐야 하는 반면, HWPX는 XML 구조를 기반으로 본문과 문서 정보를 확인할 수 있습니다. 이 때문에 표준 XML 파서나 범용 개발 도구를 활용해 텍스트를 추출하거나, 마크다운(Markdown) 변환과 AI 학습용 비정형 데이터 정제 작업에 연결하기가 상대적으로 수월합니다.

다만 XML 기반 포맷이라고 해서 문서의 레이아웃과 구조가 자동으로 복원되는 것은 아닙니다. 본문 데이터와 서식 정보가 여러 XML 파일에 나뉘어 저장되고, 글자 모양이나 문단 모양 같은 정보는 header.xml 등을 참조해 해석해야 합니다.

따라서 단순 텍스트 추출을 넘어 다단 배열, 표 내부의 셀 병합 구조, 스타일 속성, 문단 계층까지 함께 살리려면 HWPX 포맷 구조를 이해하는 별도 파싱 과정이 필요합니다. AI 학습이나 RAG 전처리에 활용하려면 텍스트뿐 아니라 문서 내부 구조까지 함께 해석할 수 있어야 합니다.

출처: 한컴테크, 「한/글 문서 파일 형식: HWPX 포맷 구조 살펴보기」

HWP 포맷과 HWPX 포맷 구조 비교표

비교 항목	HWP 포맷	HWPX 포맷
포맷 유형	전용형 이진 구조 (CFB)	개방형 웹 표준 구조 (오픈 XML)
텍스트 접근 난이도	높음 (레코드 파싱 필요)	보통 (XML 기반 데이터 접근 가능)
서식 처리 방식	Storage 및 Stream 분산 저장	header.xml 참조 구조
암호화 방식	전체 스트림 암호화	파일별 개별 암호화

HWPX 전환 경향과 공공문서 의무화

HWP에서 HWPX로 전환하는 이유는 공공문서를 더 쉽게 열고, 분석하고, AI가 활용할 수 있는 데이터로 바꾸기 위해서입니다.

HWPX는 XML 기반의 개방형 포맷이라 기존 HWP보다 외부 시스템이나 AI 파이프라인과 연계하기가 수월합니다. 행정안전부가 온나라 문서시스템에서 HWP 첨부를 제한하고 HWPX 사용을 의무화한 것도 공공문서를 AI 친화적인 구조로 전환하려는 흐름으로 볼 수 있습니다.

기존 HWP 문서도 HWPX로 변환해 활용할 수 있습니다. 한컴은 HWP 파일을 HWPX로 변환할 수 있는 무상 변환기를 제공하고 있으며, 한 번에 최대 30개 파일까지 일괄 변환할 수 있습니다.

주요 HWP·HWPX 데이터 추출 오픈소스 라이브러리

HWP·HWPX 추출에 실제로 쓰이는 오픈소스 라이브러리는 세 가지이며, 모두 한컴이 공개한 HWP 파일 형식 공식 문서를 기반으로 개발되었습니다.

라이브러리	언어	지원 포맷	주요 기능	한계점
pyhwp	Python	HWP	ODT·HTML·TXT 변환(실험적), hwp5txt CLI	0.1b15 베타, 2020년 5월 이후 릴리스 정체, HWPX 미지원, 변환 기능 실험적 단계
hwplib · hwpxlib	Java	HWP · HWPX	내부 구조 확인, 텍스트 추출, 읽고 쓰기, 표·이미지·하이퍼링크 등 컨트롤 조작	HWP 포맷 암호화·PDF/HTML/이미지 변환 미지원, 표 구조 복원·OCR 별도 처리
hwp.js	JavaScript	HWP	텍스트 추출, 웹 브라우저 기반 파일 뷰잉	배포용 HWP 미지원, HWPX 미지원 암호화·PDF 변환 미지원

pyhwp

pyhwp는 HWP 텍스트 추출에 자주 언급되는 파이썬 라이브러리입니다. hwp5txt 커맨드라인 도구로 단일 파일 변환이 가능해, 개인 PC 작업이나 단발성 스크립트에서 활용됩니다. 

다만 변환 기능이 실험적(Experimental) 단계로 표기되어 있고, PyPI 마지막 릴리스가 0.1b15로 2020년 5월 이후 업데이트가 없어 운영 환경 적용에는 검토가 필요합니다.

hwplib과 hwpxlib

hwplib과 hwpxlib은 neolord0 개발자가 Apache 2.0 라이선스로 공개한 자바 라이브러리입니다.

텍스트 추출은 물론 표·이미지·하이퍼링크 같은 문서 객체의 읽기·쓰기와 제어 기능까지 지원해 활용 범위가 넓습니다.

다만 HWP와 HWPX가 별도 프로젝트로 분리되어 있으며, 암호화 파일은 hwpxlib이 확장 모듈로 HWPX만 지원하고, hwplib은 HWP 암호화 파일을 지원하지 않습니다. 또한 HWP 포맷의 PDF·HTML·이미지 변환을 지원하지 않습니다.

hwp.js

hwp.js는 이한(hahnlee) 개발자가 자바스크립트로 만든 HWP 뷰어 겸 파서로, 브라우저에서 다운로드 없이 HWP를 띄울 수 있어 프런트엔드 미리보기에 쓰입니다. 

다만 hwp.js는 개발자가 GitHub Issue #7에서 알파 단계의 라이브러리라고 언급한 바 있으며, 당시 기준으로 HWP 포맷 처리 커버리지를 약 20% 수준으로 설명했습니다. 따라서 브라우저 기반 HWP 미리보기나 일부 텍스트 확인 용도로는 참고할 수 있지만, 복잡한 서식과 표 구조가 포함된 공공문서를 운영용 RAG 파이프라인에 적용하려면 별도 검증이 필요합니다.

(*이 글은 2026년 6월 기준으로 확인되었으며 추후 기능이 추가되거나 수정될 수 있습니다.)

정리하면 오픈소스 라이브러리는 HWP·HWPX 문서의 내부 구조를 확인하거나 텍스트를 추출하는 데 유용하게 활용할 수 있습니다.

다만 RAG 파이프라인에 바로 연결하려면 단순 텍스트 추출을 넘어 표의 행·열 관계, 이미지 안의 텍스트, 문단 계층, 읽기 순서까지 함께 유지되어야 합니다. 이 부분은 라이브러리별 지원 범위가 다르기 때문에 실제 업무 문서에 적용하기 전 별도 검증이 필요합니다.

특히 HWP와 HWPX는 포맷 구조가 달라 하나의 오픈소스 라이브러리만으로 두 포맷을 모두 안정적으로 처리하기 어려울 수 있습니다. 

대량의 공공문서를 RAG 전처리에 활용하려면 포맷별 파서뿐 아니라 TSR(Table Structure Recognition, 표 구조 인식), OCR(Optical Character Recognition, 광학 문자 인식) 기능까지 함께 고려해야 합니다.

HWP·HWPX 오픈소스 파서의 한계점

오픈소스 라이브러리는 HWP·HWPX 문서의 구조 확인이나 텍스트 추출에는 유용하지만, 표와 이미지가 많은 공공기관 문서를 대량으로 처리하는 환경에서는 추가 검토가 필요합니다. 

특히 온프레미스 LLM 구축이나 사내 LLM 구축처럼 내부 문서를 RAG 파이프라인에 지속적으로 연결해야 한다면, 파싱 단계의 품질이 검색과 답변 품질에 직접 영향을 줄 수 있기 때문입니다. 

표 구조 손실 – 셀 데이터와 본문 맥락의 분리

HWP·HWPX 문서의 표에는 항목명, 값, 조건, 기준이 행과 열의 관계 안에 함께 담겨 있습니다. 예산서, 현황보고서, 지원사업 공고처럼 위치 정보가 중요한 문서에서는 어떤 값이 어떤 항목에 연결되는지도 함께 유지되어야 합니다.

텍스트 중심으로만 추출하면 표 안의 글자는 남더라도 병합 셀, 헤더, 행·열 관계가 충분히 보존되지 않을 수 있습니다. 예를 들어 예산서에서 ‘시스템 구축’, ‘2026년’, ‘3억 원’이라는 내용이 모두 추출되더라도, 3억 원이 어떤 사업명과 연도에 배정된 금액인지 연결되지 않으면 검색 단계에서 의미가 흐려질 수 있습니다.

따라서 표가 많은 공공문서를 다룰 때는 텍스트 추출 결과만 보지 말고, TSR과 셀 단위 구조화 출력 가능 여부까지 함께 확인하는 것이 좋습니다.

이미지 및 수식 누락

공공기관 문서에는 본문 텍스트 외에도 도표, 스캔 이미지, 직인, 수식, 차트가 함께 들어가는 경우가 많습니다. 이런 요소는 파일 안에 존재하더라도 일반 텍스트처럼 바로 추출되지 않기 때문에, 파서의 처리 범위에 따라 본문 데이터와 분리되거나 누락될 수 있습니다.

예를 들어 사업 안내 이미지에 포함된 문구, 표를 캡처한 이미지 속 수치, 수식 형태로 작성된 산정 기준은 별도 OCR이나 수식 처리 과정이 없으면 RAG 전처리 데이터에 제대로 반영되기 어렵습니다. 따라서 이미지와 수식이 많은 HWP·HWPX 문서를 다룰 때는 텍스트 추출 여부만 보지 말고, 이미지 속 텍스트 인식, 수식 처리, 본문과의 위치 관계까지 함께 확인하는 것이 좋습니다.

HWP·HWPX 파싱, 전문 솔루션이 필요한 이유 – 한컴 데이터 로더

🖥️한컴 데이터 로더

한컴 데이터 로더는 HWP·HWPX 원본 문서를 PDF 변환 없이 직접 파싱하고, 텍스트·표·이미지·문단 구조를 구조화 데이터로 전환하는 문서 파싱(Document Parsing) 솔루션입니다.

HWP·HWPX 원본 직접 파싱

한컴 데이터 로더는 HWP SDK 원천 기술을 바탕으로 HWP·HWPX 원본에서 직접 데이터를 추출합니다. PDF로 변환하는 과정에서 손실될 수 있는 각주, 병합 셀, 계층 구조에 대한 데이터를 원본을 유지해 파싱할 수 있고, 다양한 레이아웃 요소를 보존합니다. 

TSR – 표 구조를 데이터로 복원

TSR은 표의 행과 열 관계를 복원해 구조화된 데이터로 만드는 기술입니다. 

테두리 없는 표, 병합 셀, 중첩 표까지 인식해 표 제목과 셀 데이터의 연결을 유지합니다. 같은 숫자라도 어느 항목을 설명하는 값인지 구분할 수 있어, 예산표나 통계표가 많은 공공 보고서에서 수치 오독 가능성을 낮출 수 있습니다. 

DLA 및 OCR – 이미지와 문서 계층 구조까지 추출

DLA(Document Layout Analysis, 문서 구조 분석)는 문서를 제목, 본문, 표, 그림 같은 영역으로 나누고 사람이 읽는 순서를 추론하는 기술이며, OCR은 이미지 안의 글자를 텍스트로 변환하는 기술입니다. 한컴 데이터 로더의 DLA는 2단 레이아웃처럼 구조가 복잡한 문서에서도 본문 흐름을 사람이 읽는 순서대로 정렬합니다.

OCR을 함께 적용하면 이미지에 포함된 텍스트까지 추출할 수 있어, 오픈소스 라이브러리에서 처리하기 어려운 이미지 데이터도 RAG 파이프라인에 활용할 수 있습니다. 

*이미지 캡셔닝(Image Captioning) 기능은 현재 PoC 단계로, 상용 출시 일정은 추후 안내될 예정입니다.

RAG 파이프라인이 제대로 작동하려면 AI에게 넘어가는 데이터부터 정확해야 합니다. 그 출발점이 파싱 단계이며, 파싱 품질이 전체 파이프라인 성능을 좌우합니다. 한컴 데이터 로더는 HWP·HWPX 외에 PDF, OOXML까지 다양한 포맷을 아우릅니다. 라이브 데모에서 설치 없이 바로 확인할 수 있습니다.

👉 데이터 손실 없는 문서 파서, 라이브 데모 사용해 보기

👉 우리 기업에 딱 맞는 문서 파싱 솔루션, 한컴 데이터 로더 문의하기

HWP·HWPX 데이터 추출 관련 자주 묻는 질문 FAQ

---

참고 자료

1. ZDNet Korea, 「18일부터 공공문서 ‘HWPX’ 의무화…AI 친화형 행정 체계 전환」, 2026.5.12
2. 파이낸셜뉴스, 「공공기관 AI 조직·인력·예산 실적 공시 의무화…경영평가 반영」, 2025.10.28
3. Lin, 「Revolutionizing Retrieval-Augmented Generation with Enhanced PDF Structure Recognition」, arXiv:2401.12599, 2024 https://arxiv.org/abs/2401.12599
4. 한컴테크, 「한/글 문서 파일 형식: Python을 통한 HWP 포맷 파싱하기 (1)」, 정우진
5. 한컴테크, 「한/글 문서 파일 형식: HWPX 포맷 구조 살펴보기」
6. neolord0, 「hwplib: hwp library for java」 GitHub
7. neolord0, 「hwpxlib: hwpx library for java」 GitHub
8. hahnlee, 「hwp.js: Open source hwp viewer and parser library」 GitHub
9. pyhwp PyPI 페이지