RAG 파이프라인 문서 파싱, 한컴 데이터 로더 API 연동 가이드

RAG(Retrieval-Augmented Generation, 검색 증강 생성) 파이프라인을 구축했는데 답변이 자꾸 부정확하다면, 원인은 대형 언어모델이 아니라 그 앞단의 문서 파싱일 수 있습니다.

RAG는 외부 문서를 검색해 그 내용을 근거로 답변을 생성하는 방식인데, 표가 손상되고 문단 계층이 손실된 상태로 입력되면 성능이 좋은 모델을 사용해도 검색이 잘못된 청크를 참조하기 때문입니다.

실제로 문서의 구조 요소를 보존한 청킹이 구조를 무시한 청킹보다 RAG 결과를 크게 향상시킨다는 연구도 있습니다. 이번 글에서는 문서 파싱의 위치부터 API 연동, 구조화 데이터 활용, 폐쇄망 온프레미스 구축까지 짚어 보겠습니다.

RAG 파이프라인에서 문서 파싱이 중요한 이유는?

RAG 파이프라인은 문서추출 → 파싱 → 청킹 → 임베딩 → 벡터DB 저장 → 검색 → LLM 답변 순으로 흐르며, 가장 앞단인 문서 추출·파싱 품질이 낮으면 이후 청킹·임베딩·검색이 줄줄이 어긋나 답변 정확도가 떨어집니다.

RAG 파이프라인 전체 흐름과 문서 파싱의 위치

RAG 파이프라인은 문서를 미리 처리해 저장하는 인덱싱 구간(문서추출·파싱·청킹·임베딩·벡터DB 저장)과 질문에 답하는 질의 구간(검색·LLM 답변)으로 나뉘며, 문서 파싱은 인덱싱 구간의 가장 앞단에 위치합니다. 여기서 문서 파싱(Document Parsing)이란 비정형 문서의 제목·본문·표 같은 요소를 구분하고 복원해, 기계가 읽을 수 있는 구조화된 표현으로 바꾸는 전처리 단계입니다.

RAG 파이프라인 단계별 입력과 출력

단계	입력	출력
문서추출	원본 문서(HWP·HWPX·PDF 등)	텍스트·표·이미지 등 원시 요소
파싱	추출된 원시 요소	구조화 데이터(제목·본문·표 요소로 구분)
청킹	구조화 데이터	의미 단위로 나뉜 텍스트 청크
임베딩	텍스트 청크	벡터(숫자 배열)
벡터DB 저장	벡터	검색 가능한 인덱스
검색	사용자 질문	질문과 유사한 청크
LLM 답변	질문 + 검색된 청크	최종 답변

파싱까지는 문서를 구조화 데이터로 변환하는 과정이고, 청킹부터는 검색과 답변에 활용할 의미 단위를 만드는 과정입니다. 이 중 문서 추출과 파싱을 전담하는 솔루션이 한컴 데이터 로더입니다.

문서 파싱 품질이 검색 정확도를 좌우하는 이유는?

구조가 무너진 평면 텍스트는 의미 단위로 나누기 어려워 청킹 경계가 어긋나고, 검색이 엉뚱한 청크를 가져와 AI가 맥락을 잃은 답변을 내놓게 됩니다. 

청킹은 글자 수가 아니라 의미 단위로 이뤄져야 하는데, 구조 정보가 손실되면 그 기준이 불명확해지기 때문입니다.

예를 들어 표 하나가 여러 청크로 쪼개지면 ‘2024년 매출’이라는 헤더와 ‘120억 원’이라는 값이 다른 조각으로 흩어져, 검색이 둘의 관계를 복원하지 못합니다. 제목과 본문의 위계가 손상돼 어느 챕터에 속하는지 알 수 없는 청크가 생기는 것도 마찬가지입니다.

실제로 문서의 구조적 요소를 기준으로 한 청킹이, 구조 정보를 무시한 기존 청킹보다 금융 보고서 기반 RAG 결과를 크게 향상시킨다는 연구도 보고됐습니다. 결국 구조 보존형 추출이 RAG 파이프라인 구축의 출발점이 됩니다.

문서 파싱 API, 어떻게 연동하나요?

한컴 데이터 로더의 문서 파싱 API는 변환 요청 → 완료 확인 → 결과 다운로드의 3단계 비동기 흐름으로 동작합니다. 첫 응답에서 받은 식별자(api_history_id)로 처리 상태를 추적해요. 

비동기란 요청을 보낸 즉시 결과를 받는 것이 아니라, 작업이 백그라운드에서 처리되는 동안 완료 여부를 따로 확인하는 방식입니다. RAG 파이프라인 구축 과정에서 문서 파싱 API 연동 방법을 익혀두면, 이후 어떤 문서 포맷이 들어와도 같은 흐름으로 처리할 수 있습니다. 

변환 요청부터 결과 다운로드까지 3단계

문서 파싱 API 연동은 변환 요청 → 완료 확인(Webhook 또는 폴링) → 결과 다운로드 순서로 진행됩니다. 모든 호출은 https://api.sdk.hancom.com/api/api-services를 기준 주소로 쓰고, 인증은 발급받은 X-API-Key를 헤더에 담아 처리합니다.

1. 변환 요청

• POST /api/api-services/convert로 파일을 보냅니다.
• 헤더에 X-API-Key를 넣고, multipart/form-data로 변환할 file과 결과를 받을 webhook_url(HTTPS 필수)을 함께 전달하면, 응답에 이후 단계의 키인 api_history_id가 담겨 옵니다.

2. 완료 확인

• 작업이 끝났을 때 지정한 주소로 결과를 알려주는 Webhook을 받거나(권장), GET /api/api-services/status/{api_history_id}로 상태를 직접 조회(폴링)합니다.
• 상태는 PENDING → PROCESSING → DONE 순으로 바뀌고, 문제가 있으면 FAILED로 표시됩니다.

3. 결과 다운로드

• GET /api/api-services/download/{api_history_id}로 구조화 결과 파일 result.aijson을 내려받습니다.

첫 응답에서 받은 api_history_id로 이후 상태 조회와 결과 다운로드를 모두 진행하므로, 요청 직후 이 값을 반드시 저장해 두어야 합니다.

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

REST API 사용 시 확인해야 할 제약 사항은?

REST API 사용법을 제대로 익히려면 파일 크기·암호화, 입력·출력 포맷, 통신·크레딧, 호출 빈도 네 가지를 먼저 확인해야 합니다. 

REST API로 연동할 때는 파일당 최대 100MB·1,000페이지 이하를 권장하고, 암호화(DRM) 문서는 사전 해제가 필요하며, 입력은 HWP·HWPX·PDF·출력은 aijson으로 고정된다는 점도 알아두어야 합니다.

대용량·다중 페이지 문서를 비동기로 처리하는 패턴은 AWS Textract 등 클라우드 문서 AI에서도 공통으로 쓰이는 표준 방식이에요. 예를 들어 AWS Textract는 페이지 수가 많은 PDF일수록 비동기 처리로 다른 작업을 함께 진행할 수 있다고 안내하는데, 한컴 데이터 로더의 1,000페이지 권장 기준은 이와는 별개로 자체적으로 정한 처리 안정성 기준입니다.

연동 전 확인할 제약 3가지

✅ 파일 크기·암호화
파일은 최대 100MB·1,000페이지 이하를 권장하므로, 분량이 큰 문서는 미리 분할해 두는 것이 좋습니다. 암호화(DRM)·암호보호 문서는 변환되지 않아 사전에 보안 해제가 필요합니다. 

✅ 입력·출력 포맷
API 입력은 HWP·HWPX·PDF만 지원하고, 결과는 구조화 JSON인 aijson으로 나옵니다.

✅ 통신·크레딧
모든 호출과 Webhook은 HTTPS만 허용하고, 크레딧은 페이지당 10 Credit 기준이며 변환 실패 시 자동 환불됩니다.

✅ 호출 빈도

변환 요청 API는 초당 최대 20회까지 호출할 수 있어, 대량의 문서를 한꺼번에 처리할 때는 이 한도를 고려해 요청을 분산하는 편이 안전합니다. 

API 결과는 한컴 데이터 로더 라이브 데모에서 HWP·HWPX·PDF 파일을 직접 올려 바로 확인해 볼 수 있습니다.

구조화 데이터 결과를 RAG 전처리에 활용하는 방법

문단 계층·표 구조·좌표 같은 메타데이터가 함께 추출되면, 텍스트만 뽑아낸 결과보다 청킹 경계를 정확하게 잡을 수 있어 RAG 검색 정확도가 올라갑니다.

평면 텍스트와 구조화 데이터는 어떻게 다른가요?

평면 텍스트는 표·계층 정보가 사라진 단순 글자 나열이고, 구조화 데이터는 각 요소에 메타데이터가 붙어 문서 구조를 유지한 결과입니다. 한컴 데이터 로더의 결과 파일 aijson은 추출 요소를 elements 배열로 담고, 각 요소마다 category(제목·표·본문 등 요소 유형)·level(문단 계층)·bbox(좌표)를 함께 보존합니다.

한눈에 살펴보는 평면 텍스트와 구조화 데이터의 차이

항목	평면 텍스트	구조화 데이터
표 구조	행·열 관계 소실, 글자만 나열	셀 단위로 표 구조 유지
문단 위계	제목·본문 구분 사라짐	level로 계층 보존
좌표·위치	위치 정보 없음	bbox로 위치 정보 유지
청킹 활용도	의미 단위 분할 어려움	메타데이터 기준 경계 설정 가능

구조화 데이터의 핵심은 메타데이터입니다. 어떤 글자가 제목이고 어떤 칸이 표의 한 셀인지가 명시되어 있으면, 청킹 단계에서 그 경계를 기준으로 의미 단위를 나눌 수 있습니다. 이 메타데이터가 곧 다음 단계인 청킹의 기준선이 됩니다.

한컴 데이터 로더는 RAG의 어느 단계까지 담당하나요?

한컴 데이터 로더는 문서 추출과 파싱을 담당해 구조화 데이터(aijson)를 생성하고, 이후 청킹·임베딩·검색은 한컴의 RAG 솔루션인 한컴피디아가 수행합니다. 한컴 데이터 로더가 청킹을 직접 수행하는 것은 아니지만, 추출한 계층 정보(level, category)는 한컴피디아가 의미 단위로 청킹하는 기준으로 활용됩니다.

추출·파싱과 이후 단계를 나눠 보는 시각은 도구 조합에도 유용합니다. 글로벌 도구인 Unstructured도 문서를 Title·Table·ListItem 같은 요소 유형으로 분류하고 좌표·계층 메타데이터를 붙여 출력합니다. 구조화 추출이 RAG 전처리의 독립된 단계로 자리 잡았다는 뜻입니다. 어느 도구가 추출을, 어느 단계가 청킹·검색을 맡는지 경계를 명확히 해 두면 RAG 아키텍처 설계와 도구 선택이 한결 수월해집니다.

온프레미스·폐쇄망 환경에서도 RAG 파이프라인을 구축할 수 있나요?

한컴 데이터 로더는 SaaS API와 온프레미스 두 가지 배포 방식을 지원해, 문서가 외부로 나가면 안 되는 폐쇄망 RAG 구축이 필요한 환경에서도 내부망에 설치해 온프레미스 문서 AI로 RAG 파이프라인을 구축할 수 있습니다. 

SaaS API와 온프레미스, 어떤 차이가 있나요?

SaaS API는 별도 설치 없이 즉시 연동할 수 있고, 온프레미스는 고객사 내부 서버에 직접 설치해 문서 데이터가 외부로 나가지 않는 방식입니다.

SaaS API는 별도 서버 구축 없이 바로 연동할 수 있어 초기 투자 부담이 적고, 페이지 단위 과금이라 쓴 만큼만 비용이 듭니다. 빠른 테스트나 온프레미스 구축 전 파일럿에 적합합니다. 다만 SaaS API는 원본을 변환 직후 삭제하고 결과를 7일간 보관 후 자동 삭제하는데, 데이터가 처리되는 동안 외부 서버를 거친다는 점에서 온프레미스의 ‘외부 전송 자체가 없음’과는 다른 개념입니다.

온프레미스는 고객사 내부 서버에 직접 설치·운용하며 문서가 외부로 전송되지 않아, 인터넷이 차단된 폐쇄망에서도 작동합니다. 공공·금융처럼 보안 요건이 높은 환경에 적합하죠.

우리 환경에 맞는 배포 방식 선택 기준

빠른 도입과 비용 효율이 우선이면 SaaS API가, 망분리·보안 요건이 핵심이면 온프레미스가 적합하며, 온프레미스는 컨테이너 기반 REST API로 내부망에 배포할 수 있습니다.

상황별 배포 방식 선택

✅ SaaS API가 맞는 경우
빠른 파일럿으로 결과부터 확인하거나 서버 인프라 초기 투자 부담을 줄이고 싶다면 SaaS API가 맞습니다. 페이지 단위 과금이라 소규모 검증부터 부담 없이 시작할 수 있죠.

✅ 온프레미스가 맞는 경우
망분리·보안 가이드라인을 반드시 지켜야 하거나 공공·금융 폐쇄망에서 RAG 파이프라인을 구축해야 한다면 온프레미스가 적합합니다. 온프레미스는 컨테이너 기반 REST API로 내부망에 배포할 수 있어, 별도 SDK 설치 부담 없이 REST 표준 호출만으로 운용됩니다. 컨테이너는 애플리케이션을 격리된 환경으로 묶어 어디서나 동일하게 실행하는 기술입니다.

한컴 데이터 로더는 두 방식 모두 동일한 추출 엔진으로 제공되어, SaaS API와 온프레미스를 오가더라도 결과물 일관성이 유지됩니다.

RAG 파이프라인과 API 연동 자주 묻는 질문

RAG 파이프라인 문서 파싱, 지금 시작하는 방법

문서 파싱 품질이 검색 정확도를 좌우하고, 3단계 비동기 API로 연동하며, 구조화 데이터의 계층 정보가 청킹 기준이 되고, 폐쇄망에서는 온프레미스로 배포하는 흐름까지 짚었다면 RAG 문서 파싱 API를 갖춘 한컴 데이터 로더로 RAG 파이프라인 구축을 바로 시작할 수 있습니다. 실제로 경기도교육청 AI 디지털플랫폼 구축 사업에서는 한컴 데이터 로더가 2,800여 개 학교 홈페이지와 4만여 건의 안내자료, 7,000여 건의 지침·법령 데이터를 AI 학습 가능한 형태로 변환하는 데 활용된 바 있습니다. 

💻 한컴 데이터 로더

한컴 데이터 로더는 HWP·HWPX·PDF·OOXML(PPTX, DOCX, XLSX)을 구조화 데이터로 전환하는 문서 파싱 솔루션입니다. 추출된 데이터는 자사 RAG 솔루션 한컴피디아와 연계해 문서 수집부터 검색·답변까지 한컴 단일 스택으로 구축할 수 있습니다. 에이전트가 신뢰할 수 있는 문서 전처리, 한컴 데이터 로더로 시작해 보세요.

👉 한컴 데이터 로더 둘러보기
👉 한컴 데이터 로더 도입 문의하기

---

참고 자료

1. AWS, 「검색 증강 생성(RAG)이란 무엇인가요?」
2. Antonio Jimeno Yepes 외, 「Financial Report Chunking for Effective Retrieval Augmented Generation」, 2024
3. AWS, 「Processing Documents Asynchronously (Amazon Textract)」
4. Unstructured, 「Document elements and metadata」
5. Zhang Li 외, 「MDPBench: A Benchmark for Multilingual Document Parsing in Real-World Scenarios」, 2026
6. Pius Horn·Janis Keuper, 「Beyond String Matching: Semantic Evaluation of PDF Table Extraction」, 2026
7. 디일렉, 「한컴, 380억 경기교육청 AI 사업 참여…학습 데이터 변환도구 공급」, 2025