DocExtr

Architecture

프로젝트 성격

수천만~수억 건 단위의 문서 디지털화 파이프라인용 추출 엔진입니다. 소스는 비공개로 운영하되, 동일한 필요가 있는 곳에서 그대로 쓸 수 있도록 실행 패키지(바이너리·Python 휠) 다운로드 + 사용 가이드 동봉 형태로 배포합니다.

해결하려는 문제

대규모 문서 디지털화 환경에서, 압축 파일 내부 중첩(zip 안의 zip 등)·다양한 포맷·메타데이터 추출이 반복적으로 요구됩니다. AI·검색 시스템 입력으로 적합한 Plain Text·Markdown 형태의 일관 출력이 필요한데, 기존 도구는 단일 포맷이나 낮은 처리량에 머물러 대규모 파이프라인에 그대로 적용하기 어렵습니다.

사용법

단일 실행 파일 docextr로 디렉토리를 입력받아 JSONL을 출력하거나 RDBMS 테이블에 직접 적재합니다. Python에서는 import docextr로 파일 경로 또는 인메모리 바이트를 추출합니다.

# 디렉토리 → JSONL 샤드 (워커 8개)
docextr run \
  --input  /data/documents \
  --output /data/output \
  --workers 8

# RDBMS 직접 적재 (JSONL 생략)
docextr run \
  --input  /data/documents \
  --output-db "postgres://user:pass@host/db" \
  --db-table extraction \
  --db-mode  replace

import docextr

# (선택) HWP OLE 복구·OCR 폴백 사용 시 Python 파서 경로 지정
docextr.set_python_path("/path/to/docextr/python/parsers")

# 파일 경로로 추출
result = docextr.extract("/data/report.hwp")
print(result["plain_text"])   # 본문 텍스트
print(result["markdown"])     # 마크다운
print(result["blake3"])       # BLAKE3 해시

# 인메모리 바이트로 추출
with open("/data/report.pdf", "rb") as f:
    result = docextr.extract_bytes(f.read(), "report.pdf")

지원 포맷

• 문서·텍스트 txt · md · html · docx · pptx · xlsx · xls · doc · hwp · hwpx · pdf · 소스/설정 100+종 (c · cpp · java · py · json · xml · yaml · cmake 등)
• 스캔 PDF (OCR) PaddleOCR v5 폴백 (모델 설치 시. 미설치 시 텍스트 레이어 없음 오류)
• 압축 (재귀) zip · tar · tar.gz · tar.bz2 · 7z (MAX_DEPTH 16 · MAX_SIZE 4 GiB)
• 미지원 rar (라이선스) · 암호화 아카이브

출력

레코드 필드 (4종)

• plain_text 본문 텍스트
• markdown 마크다운
• structured_json 구조 JSON (제목·작성자·메타)
• blake3 BLAKE3 해시 64자 hex

샤드 출력은 JSONL · CSV. 14컬럼 JSONL 스키마 전체는 동봉 가이드 참조.

기능

• 핵심 엔진은 Rust 네이티브, HWP·OCR만 Python 폴백
• 압축 아카이브 16단계 재귀 탐색
• 14컬럼 JSONL — source_path · plain_text · markdown · structured_json · blake3 · file_type · file_size · error · title · author · created · word_count · quality_score · has_structure
• JSONL · CSV 샤드 또는 RDBMS 직접 적재
• 오류 무중단 처리 (실패 파일도 레코드 생성, 파이프라인 계속)
• 병렬 워커 (--workers N) 기반 처리량 확장

사양 · 측정 환경

버전

v0.1.0

배포 형태

Linux · Windows 단일 실행 파일 + Python 휠

소스

비공개 (실행 패키지 다운로드만)

런타임

Rust 코어 + Python 휠 (폴백 파서 사용 시)

Python 라이브러리

import docextr (네이티브 바인딩)

처리 성능

포맷·압축 상태에 따라 추출 경로를 분기하고, 다중 워커로 병렬 처리합니다.

안정성 제어

중첩 압축 폭탄(Zip bomb)을 방어하고, 손상된 파일을 만나도 해당 파일만 격리한 채 파이프라인을 계속 진행합니다.

보안 · 컴플라이언스

라이선스

비공개 · 다운로드만 제공 (소스 비공개)

신뢰 경계

VFS — MAX_DEPTH 16 · MAX_SIZE 4GiB · zip bomb 방어

장애 격리

Extractor 단위 panic 격리 + fallback 체인

출력 무결성

레코드별 BLAKE3 해시 동봉

RDBMS 어댑터

SQLite · PostgreSQL · MySQL · MariaDB · Oracle (feature gate)

기술 지원

도입 계약 시 정식 유지보수와 보안 취약점 패치 지원 채널을 제공합니다.

도입 · 시작하기

1. 공식 배포 패키지 수령 (바이너리 및 운영 가이드 포함)
2. 설치 — 단일 실행 파일 또는 Python 휠 환경 설정
3. 실행 — CLI: docextr <input> --output <jsonl|csv|db>
4. 적재 — JSONL/CSV 또는 RDBMS 5종에 직접 적재 (14컬럼 스키마 고정)