{"id":1287,"date":"2026-08-06T09:00:00","date_gmt":"2026-08-06T00:00:00","guid":{"rendered":"https:\/\/blog.hancom.com\/llamaindex-hwp-hwpx-parsing-hancom-data-loader-api\/"},"modified":"2026-08-20T11:10:40","modified_gmt":"2026-08-20T02:10:40","slug":"llamaindex-hwp-hwpx-parsing-hancom-data-loader-api","status":"publish","type":"post","link":"https:\/\/blog.hancom.com\/en\/llamaindex-hwp-hwpx-parsing-hancom-data-loader-api\/","title":{"rendered":"Limitations of LlamaIndex HWP\u00b7HWPX Parsing and Integration Guide for Hancom Data Loader API"},"content":{"rendered":"\n

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. <\/p>\n\n

<\/div>\n\n

Limitations of LlamaIndex HWP\u00b7HWPX Parsing and Impact on RAG Performance<\/strong><\/h2>\n\n
<\/div>\n\n

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.<\/p>\n\n

What HWPReader Extracts and What It Does Not<\/strong><\/h3>\n\n

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. <\/p>\n\n

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. <\/p>\n\n

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

Can’t I Convert HWP to PDF and Parse It?<\/strong><\/h3>\n\n

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>, a task that took 9.5 seconds to extract directly from HWPX took 150.3 seconds after converting to PDF and extracting\u2014a time difference of approximately 15.8 times.<\/p>\n\n

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. <\/p>\n\n

<\/div>\n\n
\"RAG<\/figure>\n\n
<\/div>\n\n

Why Low Parsing Quality Triggers RAG Hallucination<\/strong><\/h3>\n\n

If parsing quality is low, the subsequent chunking, embedding, and retrieval stages of RAG are sequentially compromised, leading to hallucinations.<\/p>\n\n

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. <\/p>\n\n

In fact, research summarizing document parsing technologies<\/a> presents layout analysis and table recognition as core pipeline components supporting downstream applications like RAG, and research on PDF structure recognition<\/a> 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.<\/p>\n\n

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\u00b7HWPX originals important.<\/p>\n\n

<\/div>\n\n

Criteria to Check Before Selecting an HWP Parsing API<\/strong><\/h2>\n\n
<\/div>\n\n

When selecting an HWP\u00b7HWPX 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.<\/p>\n\n

Why Direct Original Parsing Support Comes First<\/strong><\/h3>\n\n

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. <\/p>\n\n

This difference stems from the HWP file structure. According to the Hancom Tech blog article<\/a>, 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.<\/p>\n\n

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.<\/p>\n\n

Environments requiring on-premises or container-based REST API support<\/strong><\/h3>\n\n

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. <\/p>\n\n

Global overseas solutions fail on two counts here. They do not support HWP\u00b7HWPX 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. <\/p>\n\n

\ud83d\udccc On-Premises Adoption Self-Assessment<\/strong><\/h4>\n\n

\u2705 Air-gapped environment where documents cannot be sent externally<\/p>\n\n

\u2705 High proportion of HWP\u00b7HWPX documents<\/p>\n\n

\u2705 Handling documents with many tables and images<\/p>\n\n

\u2705 Must install directly on internal network servers<\/p>\n\n

If any of the above applies, you need a parsing solution that can be deployed internally without external transmission.<\/p>\n\n

<\/div>\n\n
\"Hancom<\/figure>\n\n
<\/div>\n\n

Parsing HWP\u00b7HWPX Directly with Hancom Data Loader<\/strong><\/h2>\n\n

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.<\/p>\n\n

Parsing Quality Comparison: HWPReader vs. Hancom Data Loader<\/strong><\/h3>\n\n

While HWPReader stops at text extraction, Hancom Data Loader performs structured parsing that restores table structures, paragraph hierarchy, and HWPX. <\/p>\n\n

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. <\/p>\n\n

HWPReader vs. Hancom Data Loader Parsing Comparison Table <\/strong><\/h4>\n\n
Item<\/td>LlamaIndex HWPReader<\/td>Hancom Data Loader<\/td><\/tr>
HWPX Support<\/td>Not supported (OLE only)<\/td>Supported (direct parsing)<\/td><\/tr>
Table Structure Recognition<\/td>Not Supported<\/td>Table Structure Recognition (TSR) applied<\/td><\/tr>
Paragraph Hierarchy Inference<\/td>None (treated equally)<\/td>Automatic Level inference<\/td><\/tr>
Output Format<\/td>Flat text<\/td>aijson Structured Output<\/td><\/tr>
On-Premise<\/td>Direct library operation<\/td>Container-based REST API for internal deployment<\/td><\/tr><\/tbody><\/table><\/figure>\n\n

Why Data Loader Is More Advantageous for Documents with Many Tables and Images<\/strong><\/h3>\n\n

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.<\/p>\n\n

Hancom Data Loader<\/a> 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.<\/p>\n\n

Core HWP\u00b7HWPX Parsing Features<\/strong><\/h3>\n\n

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.<\/p>\n\n

Converts HWP, HWPX, and PDF into data optimized for AI.<\/p>\n\n

HWP, HWPX, and PDF documents are output in JSON and TXT formats, while OOXML only supports output in TXT format.<\/p>\n\n

\ud83d\udca1 Curious how HWP\u00b7HWPX parsing results are actually structured?<\/p>\n\n

\ud83d\udc49 View Hancom Data Loader Live Demo<\/a> <\/p>\n\n

Integrating LlamaIndex with Hancom Data Loader API<\/strong><\/p>\n\n

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.<\/p>\n\n

API<\/a> keys can be issued from the My Page after signing up at sdk.hancom.com. <\/p>\n\n

Data Loader API Integration Flow<\/strong><\/h3>\n\n

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. <\/p>\n\n

1. Conversion Request<\/strong><\/p>\n\n

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. <\/p>\n\n

2. Completion Confirmation (choose one)<\/strong><\/p>\n\n

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}. <\/p>\n\n

3. Result Download<\/strong><\/p>\n\n

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

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. <\/p>\n\n

How to Connect aijson Response to LlamaIndex<\/strong><\/h3>\n\n

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. <\/p>\n\n

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. <\/p>\n\n

import json\nfrom llama_index.core import Document\n\n# Load .aijson returned by Data Loader\nwith open(\"result.aijson\", encoding=\"utf-8\") as f:\n  parsed = json.load(f)\n\n# Iterate through elements and convert to LlamaIndex Document\n# (Data Loader's scope is up to document preprocessing (parsing, structuring); subsequent chunking and retrieval are RAG steps)\ndocuments = []\nfor el in parsed[\"elements\"]:\n  documents.append(\n  Document(\n  text=el[\"content\"][\"text\"], # content holds html, markdown, text\n  metadata={\n  \"category\": el[\"category\"][\"label\"], # Title, table, body, etc.\n  \"level\": el[\"level\"], # Paragraph hierarchy, chunking metadata\n  \"page_index\": el[\"pageIndex\"],\n  },\n  )\n  )<\/pre>\n\n
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. <\/p>\n\n
HWP-Based RAG Pipeline Architecture<\/strong><\/h3>\n\n
The HWP-based RAG pipeline parses HWP\u00b7HWPX 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. <\/p>\n\n
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. <\/p>\n\n
\ud83d\udca1 Considering building HWP\u00b7HWPX-based RAG?<\/p>\n\n
\ud83d\udc49 Inquire about Hancom Data Loader adoption<\/a><\/p>\n\n
<\/div>\n\n
\"Process<\/figure>\n\n
<\/div>\n\n
Building HWP-Based RAG: Consider in These Environments<\/strong><\/h2>\n\n
<\/div>\n\n
If HWP\u00b7HWPX 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.<\/p>\n\n
When Building RAG Based on Public Institution, Financial, or Legal Documents<\/strong><\/h3>\n\n
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<\/a>, 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.<\/p>\n\n
The National Assembly collaborated with Samsung SDS to build parsed documents into a vector DB<\/a>, and Gyeonggi Provincial Office of Education collaborated with LG CNS to connect parsing results to a RAG assistant<\/a>. In these environments, the key criterion is whether it can be deployed internally as a container-based REST API even within closed networks. <\/p>\n\n
When Building In-House Knowledge Search and Business Chatbots<\/strong><\/h3>\n\n
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.’ <\/p>\n\n
Documents with mixed HWP\u00b7HWPX 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.<\/p>\n\n
\"Hancom<\/figure>\n\n
<\/div>\n\n
From HWP Parsing to RAG Construction: The Difference Parser Selection Makes<\/strong><\/h2>\n\n
<\/div>\n\n
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. <\/p>\n\n
Direct HWP\u00b7HWPX original parsing, built-in DLA and TSR, on-premises deployment, and aijson structured output are the prerequisites for public, financial, and legal RAG.<\/p>\n\n
\ud83d\udda5 Hancom Data Loader<\/strong><\/a><\/p>\n\n
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.  <\/p>\n\n
\ud83d\udc49 Explore Hancom Data Loader<\/a> <\/p>\n\n
\ud83d\udc49 Review Hancom Data Loader API Guide<\/a><\/p>\n\n
References <\/strong><\/h3>\n\n
    \n
  1. LlamaIndex<\/a>, “HWPReader API Reference”<\/li>\n\n\n\n
  2. Hancom Tech<\/a>, “Hangul Documents for the AX Era: Analysis of Open Source Ecosystem Status and Activation Strategy”<\/li>\n\n\n\n
  3. arXiv<\/a>, \u201cDocument Parsing Unveiled: Techniques, Challenges, and Prospects for Structured Information Extraction,\u201d 2024<\/li>\n\n\n\n
  4. arXiv<\/a>, \u201cRevolutionizing Retrieval-Augmented Generation with Enhanced PDF Structure Recognition,\u201d 2024<\/li>\n\n\n\n
  5. Hancom Tech<\/a>, “Hangul Document File Format: Parsing HWP Format with Python (1)”<\/li>\n\n\n\n
  6. THE ELEC<\/a>, “Public and Defense ‘HWPX’ Use Mandatory…AX Gains Momentum”<\/li>\n\n\n\n
  7. Hancom Data Loader API Guide<\/a><\/li>\n\n\n\n
  8. arXiv<\/a>, “A Systematic Analysis of Chunking Strategies for Reliable Question Answering”, 2026<\/li>\n\n\n\n
  9. ZDNet Korea<\/a>, “9 out of 10 Public Officials ‘Use HWP and PDF That AI Cannot Read’…Obstacle to AI Government Transition”<\/li>\n\n\n\n
  10. Yonhap News<\/a>, “Generative AI Introduced to Support National Assembly Proceedings… Samsung SDS Completes Phase 1 Construction”<\/li>\n\n\n\n
  11. IT Daily<\/a>, “Hancom Wins Gyeonggi Provincial Office of Education ‘Gyeonggi Education Digital Platform’ Project”<\/li>\n<\/ol>\n","protected":false},"excerpt":{"rendered":"
    LlamaIndex’s HWPReader supports HWP text extraction but does not support table structures or HWPX. This guide introduces how to integrate Hancom Data Loader API to parse HWP\u00b7HWPX directly without PDF conversion and build RAG, with code examples. <\/p>\n","protected":false},"author":2,"featured_media":1288,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[30,10],"tags":[],"class_list":["post-1287","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-hancom-product-user-guide","category-10"],"_links":{"self":[{"href":"https:\/\/blog.hancom.com\/en\/wp-json\/wp\/v2\/posts\/1287","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.hancom.com\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.hancom.com\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.hancom.com\/en\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.hancom.com\/en\/wp-json\/wp\/v2\/comments?post=1287"}],"version-history":[{"count":5,"href":"https:\/\/blog.hancom.com\/en\/wp-json\/wp\/v2\/posts\/1287\/revisions"}],"predecessor-version":[{"id":1739,"href":"https:\/\/blog.hancom.com\/en\/wp-json\/wp\/v2\/posts\/1287\/revisions\/1739"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blog.hancom.com\/en\/wp-json\/wp\/v2\/media\/1288"}],"wp:attachment":[{"href":"https:\/\/blog.hancom.com\/en\/wp-json\/wp\/v2\/media?parent=1287"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.hancom.com\/en\/wp-json\/wp\/v2\/categories?post=1287"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.hancom.com\/en\/wp-json\/wp\/v2\/tags?post=1287"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}