DocForge

AI 시대를 위한 스마트 문서 변환기

CPU 전용, 빠르고 가벼운 문서 변환기. 신뢰도 점수 기능 내장. PyTorch 불필요. GPU 불필요. 결과에만 집중합니다.

주요 기능

📄 다중 포맷 변환 -- PDF, DOCX, PPTX, HTML, EPUB를 Markdown, JSON, HTML, 또는 일반 텍스트로 변환
🎯 신뢰도 점수 -- 요소별, 페이지별, 문서별 신뢰도 점수 제공 (DocForge만의 고유 기능!)
⚡ 3단계 품질 모드 -- fast, balanced, best로 속도와 품질 간 균형 조절
🎨 아름다운 CLI -- Rich 기반 터미널 UI, 진행률 바, 패널, 컬러 출력 지원
🌊 스트리밍 변환 -- 대용량 문서를 메모리에 전부 올리지 않고 페이지 단위로 처리
📁 일괄 처리 + 감시 모드 -- 디렉토리 전체 변환, 파일 감시를 통한 자동화 지원
🚀 GPU 의존성 제로 -- 순수 CPU 동작, 수 초 내 설치, 어디서든 실행 가능
🧪 철저한 테스트 -- 433개 테스트, 0개 실패

빠른 시작

설치

pip install docforge

OCR 지원 포함 설치:

pip install docforge[ocr]

개발 환경 설치:

pip install docforge[dev]

기본 사용법

# PDF를 Markdown으로 변환
docforge convert document.pdf -o output.md

# 신뢰도 점수를 포함하여 변환
docforge convert document.pdf -o output.json --format json --confidence

# 최고 품질 모드 사용
docforge convert document.pdf -o output.md --quality best

CLI 명령어

`convert`

단일 문서를 원하는 출력 형식으로 변환합니다.

docforge convert INPUT_FILE -o OUTPUT [OPTIONS]

옵션	설명	기본값
`-o, --output`	출력 파일 경로 (필수)	--
`-f, --format`	출력 형식: `markdown`, `json`, `html`, `text`	확장자에서 자동 감지
`-q, --quality`	품질 모드: `fast`, `balanced`, `best`	`balanced`
`--confidence`	출력에 신뢰도 점수 포함	비활성
`--pages`	페이지 범위, 예: `1-10` 또는 `1-3,7-9`	전체 페이지
`--images / --no-images`	문서에서 이미지 추출	`--images`
`--image-dir`	추출된 이미지를 저장할 디렉토리	--

사용 예시:

docforge convert report.pdf -o report.md
docforge convert report.pdf -o report.json --format json --confidence
docforge convert report.pdf -o report.md --quality best --pages 1-10
docforge convert slides.pptx -o slides.md --no-images
docforge convert paper.pdf -o paper.md --images --image-dir ./figures/

`info`

문서의 상세 정보를 표시합니다 (메타데이터, 페이지 수, 예상 변환 시간).

docforge info document.pdf

`batch`

디렉토리 내 모든 지원 문서를 일괄 변환합니다.

docforge batch INPUT_DIR -o OUTPUT_DIR [OPTIONS]

옵션	설명	기본값
`-o, --output-dir`	출력 디렉토리 (필수)	--
`-f, --format`	모든 파일의 출력 형식	`markdown`
`-q, --quality`	품질 모드	`balanced`
`-r, --recursive`	하위 디렉토리 파일 포함	비활성
`--workers`	병렬 워커 수	CPU 코어 수

사용 예시:

docforge batch ./docs/ -o ./output/ --format markdown --quality fast
docforge batch ./papers/ -o ./converted/ --recursive --workers 4

`watch`

디렉토리를 감시하여 새로운 문서가 추가되면 자동으로 변환합니다.

docforge watch WATCH_DIR -o OUTPUT_DIR [OPTIONS]

옵션	설명	기본값
`-o, --output-dir`	출력 디렉토리 (필수)	--
`-f, --format`	출력 형식	`markdown`
`-q, --quality`	품질 모드	`balanced`
`--interval`	확인 간격 (초)	`2.0`

사용 예시:

docforge watch ./inbox/ -o ./converted/ --format markdown
docforge watch ./incoming/ -o ./processed/ --quality fast --interval 5

`benchmark`

동일 문서에 대해 세 가지 품질 모드의 변환 속도를 비교합니다.

docforge benchmark document.pdf

모드별 소요 시간, 발견된 요소 수, 평균 신뢰도를 비교 테이블로 출력합니다.

`confidence`

문서의 상세 신뢰도 보고서를 생성합니다. 페이지별 점수와 시각적 히트맵을 포함합니다.

docforge confidence document.pdf

`stream`

대용량 문서를 페이지 단위로 스트리밍 변환합니다. 결과를 점진적으로 기록합니다.

docforge stream INPUT_FILE -o OUTPUT [OPTIONS]

옵션	설명	기본값
`-o, --output`	출력 파일 경로 (필수)	--
`-f, --format`	출력 형식	자동 감지
`-q, --quality`	품질 모드	`balanced`
`--progress / --no-progress`	진행률 바 표시	`--progress`

사용 예시:

docforge stream large_document.pdf -o output.md --progress
docforge stream big_report.pdf -o output.json --format json --no-progress

지원 포맷

입력 / 출력 매트릭스

입력 포맷	Markdown	JSON	HTML	일반 텍스트
PDF	Yes	Yes	Yes	Yes
DOCX	Yes	Yes	Yes	Yes
PPTX	Yes	Yes	Yes	Yes
HTML	Yes	Yes	Yes	Yes
EPUB	Yes	Yes	Yes	Yes

품질 모드

모드	속도	레이아웃 분석	신뢰도 점수	제목 감지	표 분석
`fast`	최고 속도	건너뜀	건너뜀	기본	기본
`balanced`	보통	수행	수행	수행	기본
`best`	가장 느림	수행	수행	고급	고급

fast -- 파싱과 렌더링만 수행합니다. 빠른 미리보기나 처리량이 중요한 경우에 적합합니다.
balanced -- 레이아웃 분석과 신뢰도 점수가 추가됩니다. 대부분의 사용 사례에 권장됩니다.
best -- 고급 제목 감지, 표 분석을 포함한 전체 분석 파이프라인을 실행합니다. 품질이 중요한 경우에 사용하세요.

신뢰도 점수

DocForge는 변환 결과의 신뢰성을 알려주는 고유한 신뢰도 점수 시스템을 제공합니다. 신뢰도 점수는 세 가지 수준에서 계산됩니다:

요소 수준 -- 각 단락, 제목, 표, 이미지에 0.0에서 1.0 사이의 점수가 부여됩니다.
페이지 수준 -- 페이지 내 모든 요소의 평균 신뢰도입니다.
문서 수준 -- 전체 문서에 대한 종합 신뢰도입니다.

점수 해석

점수 범위	등급	의미
0.8 -- 1.0	HIGH	변환이 신뢰할 수 있음
0.5 -- 0.79	MEDIUM	일부 요소의 검토가 필요할 수 있음
0.0 -- 0.49	LOW	수동 검토 권장

낮은 신뢰도는 대개 스캔된 이미지의 OCR 품질 저하, 복잡한 레이아웃, 비표준 폰트, 또는 특수한 인코딩을 의미합니다.

신뢰도 점수 활용

# JSON 출력에 신뢰도 포함
docforge convert document.pdf -o output.json --format json --confidence

# 시각적 히트맵이 포함된 신뢰도 보고서 생성
docforge confidence document.pdf

Python API

DocForge는 Python 코드에서 라이브러리로 사용할 수 있습니다:

from pathlib import Path
from docforge.core import convert, convert_string, get_document_info
from docforge.models import ConversionConfig

# 기본 변환
result = convert(Path("document.pdf"))
print(result.output)                  # Markdown 문자열
print(result.elapsed_seconds)         # 변환 소요 시간
print(result.avg_confidence)          # 전체 신뢰도 점수

# 사용자 정의 설정
config = ConversionConfig(
    quality="best",
    output_format="json",
    include_images=True,
    include_confidence=True,
    page_range=(1, 10),               # 1페이지부터 10페이지까지
)
result = convert(Path("document.pdf"), config)

# HTML 문자열 직접 변환
result = convert_string("<h1>Hello</h1><p>World</p>", input_format="html")

# 전체 변환 없이 문서 정보 가져오기
info = get_document_info(Path("document.pdf"))
print(info["page_count"])
print(info["metadata"]["title"])

# 대용량 문서 스트리밍 변환
from docforge.streaming import stream_convert_generator

for page_num, page_output in stream_convert_generator(Path("large.pdf")):
    print(f"페이지 {page_num}: {len(page_output)}자")

# 일괄 변환
from docforge.batch import batch_convert

results = batch_convert(
    input_dir=Path("./docs"),
    output_dir=Path("./output"),
    config=ConversionConfig(quality="fast"),
    recursive=True,
    max_workers=4,
)

다른 도구와의 비교

기능	DocForge	MarkItDown	Docling	Marker	MinerU	PyMuPDF4LLM
라이선스	MIT	MIT	MIT	GPL	AGPL	AGPL
GPU 필요	아니오	아니오	선택적	예	예	아니오
PDF 지원	Yes	Yes	Yes	Yes	Yes	Yes
DOCX 지원	Yes	Yes	Yes	No	No	No
PPTX 지원	Yes	Yes	Yes	No	No	No
EPUB 지원	Yes	No	No	No	No	No
HTML 지원	Yes	Yes	Yes	No	No	No
출력 형식 수	4	1	3	1	2	1
신뢰도 점수	Yes	No	No	No	No	No
스트리밍	Yes	No	No	No	No	No
일괄 처리 + 감시	Yes	No	No	No	No	No
품질 모드	3	1	1	1	1	1
설치 크기	가벼움	가벼움	무거움	무거움	무거움	보통

프로젝트 구조

docforge/
├── pyproject.toml              # 프로젝트 설정 및 의존성
├── README.md                   # 영문 문서
├── README_KO.md                # 한국어 문서
├── src/
│   └── docforge/
│       ├── __init__.py         # 패키지 초기화, 버전
│       ├── cli.py              # Click CLI 명령어 (convert, info, batch, watch, benchmark, confidence, stream)
│       ├── core.py             # 핵심 변환 엔진 (파싱 -> 분석 -> 렌더링 파이프라인)
│       ├── models.py           # 데이터 모델 (Document, Page, Element, Confidence, ConversionConfig 등)
│       ├── streaming.py        # 페이지 단위 스트리밍 변환
│       ├── batch.py            # 일괄 처리 및 디렉토리 감시
│       ├── benchmark.py        # 벤치마크 및 출력 비교 유틸리티
│       ├── display.py          # Rich 디스플레이 헬퍼
│       ├── parsers/
│       │   ├── __init__.py
│       │   ├── pdf_parser.py   # PDF 파싱 (PyMuPDF + pdfplumber)
│       │   ├── docx_parser.py  # DOCX 파싱 (python-docx)
│       │   ├── pptx_parser.py  # PPTX 파싱 (python-pptx)
│       │   ├── html_parser.py  # HTML 파싱 (BeautifulSoup4)
│       │   └── epub_parser.py  # EPUB 파싱 (ebooklib)
│       ├── analyzers/
│       │   ├── __init__.py
│       │   ├── confidence.py   # 신뢰도 점수 엔진
│       │   ├── layout.py       # 레이아웃 분석
│       │   ├── heading.py      # 제목 감지 및 레벨링
│       │   └── table.py        # 표 구조 분석
│       └── renderers/
│           ├── __init__.py
│           ├── markdown.py     # Markdown 렌더러
│           ├── json_out.py     # JSON 렌더러
│           ├── html_out.py     # HTML 렌더러
│           └── text_out.py     # 일반 텍스트 렌더러
└── tests/
    ├── __init__.py
    ├── test_models.py
    ├── test_parsers.py
    ├── test_pdf_parser.py
    ├── test_renderers.py
    ├── test_analyzers.py
    ├── test_core.py
    └── test_cli.py

테스트

DocForge는 pytest 기반으로 433개의 테스트를 보유하며, 모두 통과합니다.

# 개발 의존성 설치
pip install docforge[dev]

# 전체 테스트 실행
pytest

# 커버리지 포함 실행
pytest --cov=docforge

# 특정 테스트 모듈 실행
pytest tests/test_core.py
pytest tests/test_cli.py

의존성

핵심 패키지

패키지	용도
PyMuPDF (>=1.24)	PDF 파싱 및 추출
pdfplumber (>=0.11)	PDF 표 추출
python-docx (>=1.0)	DOCX 파싱
python-pptx (>=0.6)	PPTX 파싱
BeautifulSoup4 (>=4.12)	HTML 파싱
ebooklib (>=0.18)	EPUB 파싱
lxml (>=4.9)	XML/HTML 처리
Click (>=8.0)	CLI 프레임워크
Rich (>=13.0)	터미널 포매팅 및 진행률 바

선택 패키지

패키지	용도	설치 방법
pytesseract (>=0.3)	OCR 지원	`pip install docforge[ocr]`
Pillow (>=10.0)	OCR용 이미지 처리	`pip install docforge[ocr]`

기여하기

기여를 환영합니다! 시작하려면:

저장소를 포크합니다
기능 브랜치를 생성합니다: git checkout -b feature/your-feature
개발 의존성을 설치합니다: pip install -e ".[dev]"
변경 사항을 적용하고 테스트를 추가합니다
테스트 스위트를 실행합니다: pytest
Pull Request를 제출합니다

라이선스

DocForge는 MIT 라이선스로 배포됩니다.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DocForge

주요 기능

빠른 시작

설치

기본 사용법

CLI 명령어

`convert`

`info`

`batch`

`watch`

`benchmark`

`confidence`

`stream`

지원 포맷

입력 / 출력 매트릭스

품질 모드

신뢰도 점수

점수 해석

신뢰도 점수 활용

Python API

다른 도구와의 비교

프로젝트 구조

테스트

의존성

핵심 패키지

선택 패키지

기여하기

라이선스

FilesExpand file tree

README_KO.md

Latest commit

History

README_KO.md

File metadata and controls

DocForge

주요 기능

빠른 시작

설치

기본 사용법

CLI 명령어

convert

info

batch

watch

benchmark

confidence

stream

지원 포맷

입력 / 출력 매트릭스

품질 모드

신뢰도 점수

점수 해석

신뢰도 점수 활용

Python API

다른 도구와의 비교

프로젝트 구조

테스트

의존성

핵심 패키지

선택 패키지

기여하기

라이선스

`convert`

`info`

`batch`

`watch`

`benchmark`

`confidence`

`stream`