Limitations of LlamaIndex HWP·HWPX Parsing and Integration Guide for Hancom Data Loader API

LlamaIndex’s HWPReader supports HWP text extraction, but it does not support table structures, paragraph hierarchies, or HWPX. These limitations can impact RAG (Retrieval-Augmented Generation) search accuracy and answer quality. In this article, we examine the limitations of HWPReader and introduce how to utilize HWP and HWPX as structured data by integrating the Hancom Data Loader API.

Limitations of LlamaIndex HWP·HWPX Parsing and Impact on RAG Performance

LlamaIndex HWPReader extracts text but does not support table structures, paragraph hierarchy, or HWPX. These parsing quality limitations directly lead to RAG hallucination and reduced retrieval accuracy.

What HWPReader Extracts and What It Does Not

HWPReader extracts text and headers from HWP but does not support table structures, images, paragraph hierarchy, or HWPX. Reviewing the official LlamaIndex reference and GitHub source reveals that HWPReader is structured to select only text tags inside HWP, decompress them, and decode them as text.

Consequently, cell relationships in tables disappear, non-text elements like images are excluded from processing, and the hierarchy between titles and body text is processed without distinction, leaving no hierarchical information. Loading is also limited to one file at a time. The biggest constraint is HWPX support; since HWPReader only supports OLE-based HWP, it cannot process XML/ZIP-based HWPX.

LlamaIndex HWPReader Support Scope Table

Item	HWPReader Support	RAG Impact
Text Extraction	Supported (text tags only)	Body text retrieval possible
Headers	Supported	Partial metadata captured
Table Structure	Not Supported	Incorrect answers to table numeric queries
Image	Not supported (non-text ignored)	Chart information missing
Paragraph Hierarchy	Not supported (treated equally)	Chunking context loss
HWPX	Not supported (OLE only)	HWPX documents cannot be processed
Loading Method	Single file only	Burden of large-scale batch processing

Can’t I Convert HWP to PDF and Parse It?

You can convert HWP to PDF and then parse it, but it is approximately 15.8 times slower and incurs structural loss. According to Hancom Tech analysis, a task that took 9.5 seconds to extract directly from HWPX took 150.3 seconds after converting to PDF and extracting—a time difference of approximately 15.8 times.

A bigger problem than speed is data quality. When tables collapse into flat text during PDF conversion, row and column relationships are lost, leading to inaccurate answers to numeric queries like “what is the budget for which year,” and layout elements like title hierarchy and footnotes are also lost, making chunking reference points ambiguous.

Why Low Parsing Quality Triggers RAG Hallucination

If parsing quality is low, the subsequent chunking, embedding, and retrieval stages of RAG are sequentially compromised, leading to hallucinations.

RAG extracts and parses documents, then cuts them into semantic units (chunking), converts them into vectors (embedding), stores them in a vector DB, retrieves fragments close to the question, and generates answers with an LLM. When structural information is lost at the parsing stage, chunking occurs with damaged structure, so the LLM effectively references a document different from the original, making it difficult to produce accurate answers even with a good model.

In fact, research summarizing document parsing technologies presents layout analysis and table recognition as core pipeline components supporting downstream applications like RAG, and research on PDF structure recognition also explains that even when RAG frameworks and LLM APIs mature, if parsing accuracy is a bottleneck, the quality of specialized knowledge Q&A deteriorates.

In other words, much of RAG hallucination starts not from the model but from information loss at the parser stage, making solutions that directly parse HWP·HWPX originals important.

Criteria to Check Before Selecting an HWP Parsing API

When selecting an HWP·HWPX parsing API, check in order: support for direct original parsing, built-in DLA (Document Layout Analysis) and TSR (Table Structure Recognition), aijson structured output, and on-premises deployment capability.

Why Direct Original Parsing Support Comes First

Even if labeled as “HWP support,” some solutions internally go through PDF conversion, so it is important to confirm whether the original HWP is actually parsed directly. Support format lists alone do not reveal internal processing methods.

This difference stems from the HWP file structure. According to the Hancom Tech blog article, HWP is a CFB (Compound File Binary File Format) composed of storages and streams, with compression applied to reduce size. Extracting text by decompressing with open source and restoring table and hierarchical structures to their original state are completely different levels of difficulty.

Therefore, having the original HWP SDK core technology that directly interprets the original binary is necessary to extract while preserving structure without PDF conversion and to process legacy HWP 3.0 documents, enabling legacy documents from public sector sites to be uploaded to RAG.

Environments requiring on-premises or container-based REST API support

In environments where documents cannot be sent externally, on-premises and container-based REST API support is virtually a mandatory requirement. Cloud APIs require sending documents to external servers, which often cannot be used in air-gapped public, financial, and legal environments due to regulations.

Global overseas solutions fail on two counts here. They do not support HWP·HWPX and are cloud-only, so they do not align with domestic closed networks from the start. In contrast, container-based REST APIs can be installed directly on internal networks and operated without external transmission, can be integrated regardless of language, and run on CPU only without GPU.

📌 On-Premises Adoption Self-Assessment

✅ Air-gapped environment where documents cannot be sent externally

✅ High proportion of HWP·HWPX documents

✅ Handling documents with many tables and images

✅ Must install directly on internal network servers

If any of the above applies, you need a parsing solution that can be deployed internally without external transmission.

Parsing HWP·HWPX Directly with Hancom Data Loader

Hancom Data Loader is a document parsing solution that converts HWP, HWPX, PDF, and OOXML into structured data. It parses HWP and HWPX directly without PDF conversion and combines DLA, OCR (Optical Character Recognition), and TSR into a single pipeline to return structured results as aijson.

Parsing Quality Comparison: HWPReader vs. Hancom Data Loader

While HWPReader stops at text extraction, Hancom Data Loader performs structured parsing that restores table structures, paragraph hierarchy, and HWPX.

Both methods retrieve text from HWP, but HWPReader’s output is unstructured text that does not include hierarchical information, which may require additional post-processing for RAG use. In contrast, Hancom Data Loader automatically tags paragraph hierarchies through Level inference and exports the results in the aijson structured format.

HWPReader vs. Hancom Data Loader Parsing Comparison Table

Item	LlamaIndex HWPReader	Hancom Data Loader
HWPX Support	Not supported (OLE only)	Supported (direct parsing)
Table Structure Recognition	Not Supported	Table Structure Recognition (TSR) applied
Paragraph Hierarchy Inference	None (treated equally)	Automatic Level inference
Output Format	Flat text	aijson Structured Output
On-Premise	Direct library operation	Container-based REST API for internal deployment

Why Data Loader Is More Advantageous for Documents with Many Tables and Images

Depending on the application of TSR (Table Structure Recognition) and DLA (Document Layout Analysis), the gap in parsing quality widens significantly as the number of tables and images increases.

Hancom Data Loader supports complex table extraction that structures tables within tables and merged cells, making it suitable for public and financial documents with many budget tables, statistical charts, and multi-column forms.

Core HWP·HWPX Parsing Features

The core strength of Hancom Data Loader’s HWP and HWPX parsing is that it combines DLA, table extraction, in-document images, and TSR into a single pipeline, eliminating the need for separate parsers for each format.

Converts HWP, HWPX, and PDF into data optimized for AI.

HWP, HWPX, and PDF documents are output in JSON and TXT formats, while OOXML only supports output in TXT format.

💡 Curious how HWP·HWPX parsing results are actually structured?

👉 View Hancom Data Loader Live Demo

Integrating LlamaIndex with Hancom Data Loader API

The Hancom Data Loader API is a REST API. When you upload HWP or HWPX files, it returns structured results in aijson format, which can then be converted into LlamaIndex Document objects and connected to a RAG pipeline.

API keys can be issued from the My Page after signing up at sdk.hancom.com.

Data Loader API Integration Flow

Integrating the Data Loader API is an asynchronous flow consisting of three stages: conversion request, completion confirmation, and result download. Since the structure does not return results immediately but retrieves them separately after processing, it is important to save the api_history_id from the initial response.

1. Conversion Request

Send the document to POST https://api.sdk.hancom.com/api/api-services/convert. Include X-API-Key in the header and pass file and optional webhook_url as multipart, and the response returns api_history_id, job_id, and status: PROCESSING.

2. Completion Confirmation (choose one)

If you register a webhook, the server sends status: DONE, download_url, and expired_at upon completion. This is the recommended method. If using polling, query status with GET https://api.sdk.hancom.com/api/api-services/status/{api_history_id}.

3. Result Download

Call GET https://api.sdk.hancom.com/api/api-services/download/{api_history_id} to receive the .aijson file.

It is also recommended to check limitations before integration. We recommend using documents under 1,000 pages and a maximum of 100MB per file; encrypted (DRM) documents are not supported. The input formats are HWP, HWPX, and PDF, and the output is aijson.

How to Connect aijson Response to LlamaIndex

The aijson response extracts category, level, and content.text from the elements array and converts them into LlamaIndex Document objects, maintaining hierarchical metadata and continuing to chunking and embedding.

aijson places runtime, version, metadata, elements, and pageSizes at the root, and each elements item contains id, category, level, confidence, content, bbox, and pageIndex. Here, level is paragraph hierarchy information, so it can be used directly as metadata during chunking.

import json
from llama_index.core import Document

# Load .aijson returned by Data Loader
with open("result.aijson", encoding="utf-8") as f:
  parsed = json.load(f)

# Iterate through elements and convert to LlamaIndex Document
# (Data Loader's scope is up to document preprocessing (parsing, structuring); subsequent chunking and retrieval are RAG steps)
documents = []
for el in parsed["elements"]:
  documents.append(
  Document(
  text=el["content"]["text"], # content holds html, markdown, text
  metadata={
  "category": el["category"]["label"], # Title, table, body, etc.
  "level": el["level"], # Paragraph hierarchy, chunking metadata
  "page_index": el["pageIndex"],
  },
  )
  )

The Document list created this way continues to chunking, embedding, vector DB, retrieval, and LLM answer generation. Data Loader does not replace the entire RAG but is responsible for the very first preprocessing stage.

HWP-Based RAG Pipeline Architecture

The HWP-based RAG pipeline parses HWP·HWPX with Data Loader API to obtain aijson, then connects it to chunking, embedding, vector DB, retrieval, and LLM answer generation. Data Loader handles the very first extraction and parsing, and retrieval and Q are attached separately afterward.

In this process, metadata such as level, bbox, and pageIndex in aijson improves chunking quality. Research analyzing chunking strategies explains that appropriately dividing documents into semantic units is crucial for increasing search accuracy and processing efficiency, and that excessive chunk overlap can increase storage space and processing costs without improving retrieval performance.

💡 Considering building HWP·HWPX-based RAG?

👉 Inquire about Hancom Data Loader adoption

Building HWP-Based RAG: Consider in These Environments

If HWP·HWPX document proportion is high, or in closed network environments, or if documents containing tables and images must be utilized in RAG, a direct parsing API without PDF conversion is necessary.

When Building RAG Based on Public Institution, Financial, or Legal Documents

The public, financial, and legal sectors have a high proportion of HWP files and cannot send documents externally, necessitating an on-premises direct parsing API. According to a survey of 14,208 administrative agency workers, 91.1% of respondents stated that they primarily create administrative documents, such as reports and plans, in formats that are difficult for AI to recognize, such as HWP or image/scanned PDFs.

The National Assembly collaborated with Samsung SDS to build parsed documents into a vector DB, and Gyeonggi Provincial Office of Education collaborated with LG CNS to connect parsing results to a RAG assistant. In these environments, the key criterion is whether it can be deployed internally as a container-based REST API even within closed networks.

When Building In-House Knowledge Search and Business Chatbots

In-house manuals and reports have a high proportion of tables and hierarchical structures, so parsing without structural loss directly impacts chatbot answer accuracy. This is because if tables in a report are corrupted or the table-of-contents hierarchy disappears, the chatbot loses context regarding ‘which figure belongs to which item.’

Documents with mixed HWP·HWPX can be processed together with a single API, eliminating the need to divide pipelines by format. The higher the proportion of tables and hierarchy in in-house documents, the greater the effect of Table Structure Recognition (TSR) and Level inference.

From HWP Parsing to RAG Construction: The Difference Parser Selection Makes

RAG quality differences arise at the parser stage rather than the model stage. While HWPReader is sufficient for simple text extraction, it falls short with table structures, paragraph hierarchies, and HWPX, and that loss cascades through the chunking and retrieval stages down to the final answer quality.

Direct HWP·HWPX original parsing, built-in DLA and TSR, on-premises deployment, and aijson structured output are the prerequisites for public, financial, and legal RAG.

🖥 Hancom Data Loader

Hancom Data Loader is a document parsing solution that converts HWP, HWPX, PDF, and OOXML into structured data. It parses originals directly without PDF conversion to structure them as aijson. The extracted data can be linked with Hancompedia, our proprietary RAG solution, to build a complete Hancom stack from document collection to retrieval and answers. If you would like to learn more, you can check the Hancom Data Loader API guide via the link below.

👉 Explore Hancom Data Loader

👉 Review Hancom Data Loader API Guide

References

1. LlamaIndex, “HWPReader API Reference”
2. Hancom Tech, “Hangul Documents for the AX Era: Analysis of Open Source Ecosystem Status and Activation Strategy”
3. arXiv, “Document Parsing Unveiled: Techniques, Challenges, and Prospects for Structured Information Extraction,” 2024
4. arXiv, “Revolutionizing Retrieval-Augmented Generation with Enhanced PDF Structure Recognition,” 2024
5. Hancom Tech, “Hangul Document File Format: Parsing HWP Format with Python (1)”
6. THE ELEC, “Public and Defense ‘HWPX’ Use Mandatory…AX Gains Momentum”
7. Hancom Data Loader API Guide
8. arXiv, “A Systematic Analysis of Chunking Strategies for Reliable Question Answering”, 2026
9. ZDNet Korea, “9 out of 10 Public Officials ‘Use HWP and PDF That AI Cannot Read’…Obstacle to AI Government Transition”
10. Yonhap News, “Generative AI Introduced to Support National Assembly Proceedings… Samsung SDS Completes Phase 1 Construction”
11. IT Daily, “Hancom Wins Gyeonggi Provincial Office of Education ‘Gyeonggi Education Digital Platform’ Project”