DocExtr

주요 기능

검색 색인이나 LLM 입력을 만들려면 HWP, PDF, Office 문서에서 본문과 표를 먼저 꺼내야 합니다. DocExtr는 HWP와 HWPX를 포함한 업무 문서를 하나의 CLI와 Python 라이브러리로 추출하고, 디렉터리와 압축 파일 단위로 일괄 처리합니다.

• 한글 문서 — HWP·HWPX에서 별도 변환 없이 텍스트·표·이미지 추출
• 목적별 네 가지 결과 — AI 에이전트용 Markdown·문서 구조, 원문 충실 평문·Markdown, 임베딩 청크, 검색 문서
• 문서 구조 보존 — PDF 페이지·PPTX 슬라이드·HWP 섹션 단위, 병합 셀, 이미지의 본문 위치
• 압축 파일 처리 — ZIP·TAR 안의 중첩 압축까지 한 번에 처리, 암호화 ZIP 지원, 깊이·용량 한도로 압축 폭탄 차단
• 대량 일괄 처리 — 디렉터리 단위 병렬 추출, 손상 문서는 오류 레코드로 남기고 나머지 계속 처리
• 결과 적재 — 문서별 디렉터리, JSONL 샤드 또는 SQLite·PostgreSQL·MySQL/MariaDB 문서·청크 테이블

내려받기

Linux x86_64·Windows x64 CLI와 Linux CPython 3.9~3.14 wheel을 제공합니다. 운영체제와 Python 버전에 맞는 파일을 선택합니다.

버전: 0.1.1 (2026-10-11) · 변경 이력

사용법

Python

아래 예제는 Linux x86_64 CPython 3.14 wheel을 설치합니다. 다른 버전은 위 목록의 해당 wheel을 사용합니다. wheel은 OCR 엔진을 포함하며 OCR 모델과 DB 출력은 포함하지 않습니다.

curl -fLO https://www.cubiware.co.kr/api/download/docextr/0.1.1/docextr-0.1.1-cp314-cp314-manylinux_2_28_x86_64.whl
python3.14 -m pip install ./docextr-0.1.1-cp314-cp314-manylinux_2_28_x86_64.whl

import docextr

result = docextr.extract_file("report.hwpx")
manifest = result["manifest"]
print(manifest["status"], manifest["diagnostics"])
print(result["text"]["text"])
for asset in result["agent"]["assets"]:
    print(asset["mime_type"], len(asset["data"]))

docextr.export_file("report.hwpx", "new-report-output")

CLI · Linux (bash)

extract는 문서 하나를 새 디렉터리에 manifest.json·document.txt·document.md·agent.md·embedding.jsonl·search.jsonl 등 목적별 파일로 저장합니다. batch는 파일·디렉터리·압축 파일을 목적별 JSONL 샤드나 DB 테이블에 기록합니다.

curl -fLO https://www.cubiware.co.kr/api/download/docextr/0.1.1/docextr-0.1.1-linux-x86_64
chmod +x ./docextr-0.1.1-linux-x86_64

./docextr-0.1.1-linux-x86_64 extract --input report.hwpx --output new-report-output

./docextr-0.1.1-linux-x86_64 batch --input documents --output batch-output

CLI · Windows (PowerShell)

Invoke-WebRequest -Uri https://www.cubiware.co.kr/api/download/docextr/0.1.1/docextr-0.1.1-windows-x86_64.exe -OutFile ./docextr-0.1.1-windows-x86_64.exe

.\docextr-0.1.1-windows-x86_64.exe extract --input report.hwpx --output new-report-output

.\docextr-0.1.1-windows-x86_64.exe batch --input documents --output batch-output

지원 포맷

형식별 추출 범위는 다릅니다. 스프레드시트는 셀 텍스트와 Markdown 표를 추출하며 내부 이미지는 추출하지 않습니다. 암호화 ZIP은 비밀번호 파일이 필요합니다. Python·CLI extract는 개별 파일을 처리하며 압축 파일 일괄 처리는 CLI batch에서 제공합니다.

OCR은 문서 속 이미지와 이미지 파일의 글자를 인식하는 선택 기능이며 기본값은 꺼짐입니다. CLI와 Python wheel에 엔진이 포함되고 모델은 별도로 설치합니다. 스캔 PDF는 쪽 렌더 옵션과 함께 읽습니다.

추출 결과

결과는 문서 상태와 경고를 담은 manifest와 요청한 목적별 산출물로 구성됩니다 — agent(정리한 Markdown·문서 구조·이미지), text(원문 충실 평문·Markdown), embedding(추정 토큰 기준 청크), search(문자 수 기준 검색 문서). PDF 페이지와 PPTX 슬라이드 순서는 유지하며 HWP/HWPX 섹션은 물리 페이지가 아닙니다. Python에서는 이미지 바이트를 반환하고 CLI에서는 별도 파일로 저장합니다.

manifest의 status와 diagnostics로 부분 추출과 오류를 확인합니다. DB 출력은 문서 테이블과 임베딩·검색 청크 테이블로 나누어 적재합니다.

사용 환경과 제한 사항

CLI · Linux

Linux x86_64 · glibc 2.34 이상 · OpenSSL 3, libstdc++, liblzma, libbz2, zlib

CLI · Windows

Windows x64 · MSVC CRT 정적 링크. Wine 명령 실행 검증, 실제 Windows 실행 미검증

Python

CPython 3.9~3.14 · Linux x86_64 · glibc 2.28 이상

라이선스

MIT, 의존성의 제3자 고지는 별도 적용

• HWP 4.x·비밀번호 암호화 문서와 7z·RAR은 미지원입니다.
• 복잡한 표·이미지 읽기 순서·객체 위치는 일부 누락될 수 있으므로 diagnostics를 확인합니다.
• 원본 외형의 PDF 변환·임베딩 벡터 생성·요약은 제공하지 않습니다.
• 프로세스 내부 추출은 네이티브 크래시·메모리 부족을 격리하지 못합니다. 기록 실패 시 일부 파일이 남을 수 있으므로 성공 완료 후 결과를 사용합니다.
• Windows 실행 파일은 Authenticode 미서명입니다. SmartScreen 경고가 발생할 수 있으며 서명된 코드만 허용하는 환경에서는 실행이 제한됩니다.