hwp-parser

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HWP Parser 개발 도우미

HWP Parser 开发助手

한글(HWP/HWPX) 문서를 읽고 변환하는 모든 작업을 도와줍니다. Python API와 CLI 도구를 제공하며, LLM 활용을 위한 워크플로우를 지원합니다.

帮助您完成韩语文档（HWP/HWPX）的读取与转换全部操作。提供Python API和CLI工具，支持基于LLM的工作流。

환경 확인

环境检查

가상환경 활성화 확인

bash

source venv/bin/activate  # 또는 .venv/bin/activate

패키지 설치 확인

bash

pip install -e .  # 개발 모드
# 또는
pip install hwpparser[all]  # 전체 기능

시스템 의존성 확인

bash

# PDF 변환 (Chrome headless 사용)
# macOS - Chrome이 이미 설치되어 있으면 별도 설치 불필요
brew install --cask google-chrome

# Ubuntu/Debian
sudo apt install google-chrome-stable
# 또는 Chromium
sudo apt install chromium-browser

# HWPX 생성 (선택사항)
brew install pandoc  # macOS
sudo apt install pandoc  # Ubuntu

确认虚拟环境已激活

bash

source venv/bin/activate  # 或 .venv/bin/activate

确认包已安装

bash

pip install -e .  # 开发模式
# 或
pip install hwpparser[all]  # 完整功能

确认系统依赖

bash

# PDF 转换（使用Chrome headless）
# macOS - 若已安装Chrome则无需额外安装
brew install --cask google-chrome

# Ubuntu/Debian
sudo apt install google-chrome-stable
# 或Chromium
sudo apt install chromium-browser

# HWPX 生成（可选）
brew install pandoc  # macOS
sudo apt install pandoc  # Ubuntu

요청 분류

请求分类

사용자 요청을 분석하여 해당하는 기능 파악:

키워드	기능	참조
텍스트 추출, 읽기, 파싱	HWP → Text	`hwp_to_text()`
HTML 변환, 웹페이지	HWP → HTML	`hwp_to_html()`
ODT, OpenDocument	HWP → ODT	`hwp_to_odt()`
PDF 변환	HWP → PDF	`hwp_to_pdf()`
마크다운, 한글 생성	Markdown → HWPX	`markdown_to_hwpx()`
청킹, RAG, 벡터 DB	문서 청킹	`hwp_to_chunks()`
LangChain, 문서 로더	LangChain 연동	`HWPLoader`
일괄 변환, 폴더 처리	배치 변환	`batch_convert()`
검색 인덱싱, JSONL	인덱스 생성	`export_to_jsonl()`
메타데이터, 정보 추출	문서 메타데이터	`extract_metadata()`

分析用户请求以确定对应功能：

关键词	功能	参考
文本提取、读取、解析	HWP → Text	`hwp_to_text()`
HTML转换、网页	HWP → HTML	`hwp_to_html()`
ODT、OpenDocument	HWP → ODT	`hwp_to_odt()`
PDF转换	HWP → PDF	`hwp_to_pdf()`
Markdown、韩语文档生成	Markdown → HWPX	`markdown_to_hwpx()`
分块、RAG、向量数据库	文档分块	`hwp_to_chunks()`
LangChain、文档加载器	LangChain集成	`HWPLoader`
批量转换、文件夹处理	批量转换	`batch_convert()`
搜索索引、JSONL	索引生成	`export_to_jsonl()`
元数据、信息提取	文档元数据	`extract_metadata()`

작업 흐름

工作流程

1. 단일 파일 변환

1. 单个文件转换

python

import hwpparser

python

import hwpparser

HWP 읽기

读取HWP

doc = hwpparser.read_hwp("document.hwp") print(doc.text) # 텍스트 print(doc.html) # HTML

doc = hwpparser.read_hwp("document.hwp") print(doc.text) # 文本 print(doc.html) # HTML

파일로 저장

保存为文件

doc.to_odt("output.odt") doc.to_pdf("output.pdf")

빠른 변환

快速转换

text = hwpparser.hwp_to_text("document.hwp")

undefined

text = hwpparser.hwp_to_text("document.hwp")

undefined

2. CLI 사용

2. 使用CLI

bash

undefined

bash

undefined

텍스트 추출

文本提取

hwpparser text document.hwp

포맷 변환

格式转换

hwpparser convert document.hwp output.txt hwpparser convert document.hwp output.pdf

일괄 변환

批量转换

hwpparser batch ./hwp_files/ -f text -o ./text_files/

지원 포맷 확인

查看支持的格式

hwpparser formats

undefined

hwpparser formats

undefined

3. LLM/RAG 워크플로우

3. LLM/RAG工作流

python

undefined

python

undefined

청킹 (벡터 DB용)

分块（用于向量数据库）

chunks = hwpparser.hwp_to_chunks("document.hwp", chunk_size=1000) for chunk in chunks: embedding = embed(chunk.text) vector_db.insert(embedding, chunk.metadata)

LangChain 연동

LangChain集成

from hwpparser import HWPLoader, DirectoryHWPLoader

loader = HWPLoader("document.hwp") docs = loader.load()

from hwpparser import HWPLoader, DirectoryHWPLoader

loader = HWPLoader("document.hwp") docs = loader.load()

폴더 전체

加载整个文件夹

loader = DirectoryHWPLoader("./documents", recursive=True) docs = loader.load()

검색 인덱싱 (Elasticsearch/Algolia)

搜索索引生成（Elasticsearch/Algolia）

hwpparser.export_to_jsonl("./documents", "./index.jsonl", chunk_size=1000)

undefined

hwpparser.export_to_jsonl("./documents", "./index.jsonl", chunk_size=1000)

undefined

4. 배치 처리

4. 批量处理

python

undefined

python

undefined

폴더 내 모든 HWP → TXT

将文件夹中所有HWP转换为TXT

result = hwpparser.batch_convert("./hwp_files", "./text_files", "txt") print(f"변환 완료: {result.success}/{result.total}")

result = hwpparser.batch_convert("./hwp_files", "./text_files", "txt") print(f"转换完成：{result.success}/{result.total}")

모든 텍스트 합치기

合并所有文本

all_text = hwpparser.batch_extract_text("./documents")

undefined

all_text = hwpparser.batch_extract_text("./documents")

undefined

5. HWPX 생성

5. 生成HWPX

python

undefined

python

undefined

Markdown → HWPX

hwpparser.markdown_to_hwpx("# 제목\n내용", "output.hwpx")

hwpparser.markdown_to_hwpx("# 标题
内容", "output.hwpx")

HTML → HWPX

hwpparser.html_to_hwpx("<h1>제목</h1><p>내용</p>", "output.hwpx")

hwpparser.html_to_hwpx("<h1>标题</h1><p>内容</p>", "output.hwpx")

통합 변환 인터페이스

统一转换接口

hwpparser.convert("input.md", "output.hwpx") hwpparser.convert("input.docx", "output.hwpx")

undefined

hwpparser.convert("input.md", "output.hwpx") hwpparser.convert("input.docx", "output.hwpx")

undefined

지원 변환

支持的转换

입력 → 출력	함수/CLI
HWP → Text	`hwp_to_text()` , `convert ... -f text`
HWP → HTML	`hwp_to_html()` , `convert ... -f html`
HWP → ODT	`hwp_to_odt()` , `convert ... -f odt`
HWP → PDF	`hwp_to_pdf()` , `convert ... -f pdf`
Markdown → HWPX	`markdown_to_hwpx()` , `convert file.md file.hwpx`
HTML → HWPX	`html_to_hwpx()`
DOCX → HWPX	`convert file.docx file.hwpx`

输入 → 输出	函数/CLI
HWP → Text	`hwp_to_text()` , `convert ... -f text`
HWP → HTML	`hwp_to_html()` , `convert ... -f html`
HWP → ODT	`hwp_to_odt()` , `convert ... -f odt`
HWP → PDF	`hwp_to_pdf()` , `convert ... -f pdf`
Markdown → HWPX	`markdown_to_hwpx()` , `convert file.md file.hwpx`
HTML → HWPX	`html_to_hwpx()`
DOCX → HWPX	`convert file.docx file.hwpx`

주요 작업 예시

主要操作示例

단일 파일 텍스트 추출

单个文件文本提取

요청: "이 HWP 파일 내용 읽어줘"

python

text = hwpparser.hwp_to_text("document.hwp")
print(text)

请求："帮我读取这个HWP文件的内容"

python

text = hwpparser.hwp_to_text("document.hwp")
print(text)

폴더 전체 일괄 변환

整个文件夹批量转换

요청: "documents 폴더의 모든 HWP를 PDF로 변환해줘"

python

result = hwpparser.batch_convert("./documents", "./pdf_output", "pdf")
print(f"성공: {result.success}, 실패: {result.failed}")

请求："把documents文件夹里的所有HWP转换为PDF"

python

result = hwpparser.batch_convert("./documents", "./pdf_output", "pdf")
print(f"成功：{result.success}, 失败：{result.failed}")

RAG 파이프라인 구축

构建RAG流水线

요청: "HWP 문서들을 청킹해서 벡터 DB에 넣을 수 있게 해줘"

python

undefined

请求："帮我把HWP文档分块，以便存入向量数据库"

python

undefined

청킹

分块

chunks = hwpparser.hwp_to_chunks("document.hwp", chunk_size=1000)

벡터화 및 저장

向量化并存储

for chunk in chunks: embedding = your_embed_function(chunk.text) vector_db.insert({ 'embedding': embedding, 'text': chunk.text, 'metadata': chunk.metadata # file, page, offset 등 })

undefined

for chunk in chunks: embedding = your_embed_function(chunk.text) vector_db.insert({ 'embedding': embedding, 'text': chunk.text, 'metadata': chunk.metadata # 文件、页面、偏移量等 })

undefined

LangChain 문서 로더

LangChain文档加载器

요청: "LangChain에서 HWP 문서들 사용하고 싶어"

python

from hwpparser import DirectoryHWPLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter

请求："我想在LangChain中使用HWP文档"

python

from hwpparser import DirectoryHWPLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter

문서 로드

加载文档

loader = DirectoryHWPLoader("./documents", recursive=True) docs = loader.load()

청킹

分块

splitter = RecursiveCharacterTextSplitter(chunk_size=1000) chunks = splitter.split_documents(docs)

undefined

splitter = RecursiveCharacterTextSplitter(chunk_size=1000) chunks = splitter.split_documents(docs)

undefined

검색 인덱스 생성

生成搜索索引

요청: "Elasticsearch에 넣을 JSONL 파일 만들어줘"

python

hwpparser.export_to_jsonl(
    "./documents",
    "./search_index.jsonl",
    chunk_size=1000  # 청킹 포함
)

请求："帮我生成可导入Elasticsearch的JSONL文件"

python

hwpparser.export_to_jsonl(
    "./documents",
    "./search_index.jsonl",
    chunk_size=1000  # 包含分块
)

마크다운을 한글 문서로 변환

将Markdown转换为韩语文档

요청: "README를 HWPX로 만들어줘"

python

hwpparser.convert("README.md", "README.hwpx")

请求："把README转换为HWPX"

python

hwpparser.convert("README.md", "README.hwpx")

메타데이터 추출

提取元数据

요청: "이 HWP 파일 정보 알려줘"

python

meta = hwpparser.extract_metadata("document.hwp")
print(f"글자 수: {meta['char_count']}")
print(f"단어 수: {meta['word_count']}")

请求："告诉我这个HWP文件的信息"

python

meta = hwpparser.extract_metadata("document.hwp")
print(f"字符数：{meta['char_count']}")
print(f"单词数：{meta['word_count']}")

예외 처리

异常处理

python

from hwpparser.exceptions import (
    HWPFileNotFoundError,
    ConversionError,
    DependencyError,
    UnsupportedFormatError
)

try:
    result = hwpparser.convert("document.hwp", "output.pdf")
except HWPFileNotFoundError:
    print("파일을 찾을 수 없습니다")
except DependencyError as e:
    print(f"의존성 누락: {e}")
except ConversionError as e:
    print(f"변환 실패: {e}")

python

from hwpparser.exceptions import (
    HWPFileNotFoundError,
    ConversionError,
    DependencyError,
    UnsupportedFormatError
)

try:
    result = hwpparser.convert("document.hwp", "output.pdf")
except HWPFileNotFoundError:
    print("找不到文件")
except DependencyError as e:
    print(f"缺少依赖：{e}")
except ConversionError as e:
    print(f"转换失败：{e}")

테스트

测试

bash

undefined

bash

undefined

전체 테스트

完整测试

pytest tests/ -v

특정 모듈 테스트

测试特定模块

pytest tests/test_reader.py -v

커버리지

覆盖率测试

pytest tests/ --cov=hwpparser

undefined

pytest tests/ --cov=hwpparser

undefined

참고 문서

参考文档

API Reference
CLI Guide
Workflows
Troubleshooting

API 参考
CLI 指南
工作流
故障排除

의존성 라이선스

依赖许可证

중요: 이 프로젝트는 AGPL v3 라이선스의

pyhwp

라이브러리에 의존합니다.

라이선스: GNU Affero General Public License v3
저장소: https://github.com/mete0r/pyhwp

重要提示：本项目依赖于AGPL v3许可证的

pyhwp

库。

许可证：GNU Affero General Public License v3
仓库：https://github.com/mete0r/pyhwp ",