LLM 데이터 주입을 위해 100개 이상의 문서를 Markdown으로 일괄 변환하는 방법 — 3가지 실용적인 스크립트

디렉토리에 300개의 PDF, 50개의 DOCX 파일, 그리고 한 무더기의 PPTX 슬라이드가 쌓여 있었습니다. 모두 3년 동안 진행한 클라이언트 프로젝트의 내부 문서들이었습니다. 저는 저의 LLM 파이프라인(pipeline)을 위해 깨끗한 Markdown 형식이 필요했고, "하나씩 열어서 복사해서 붙여넣기" 방식으로는 해결할 수 없었습니다.

MarkItDown과 세 가지 스크립트를 사용하여 오후 한나절 만에 이 작업을 어떻게 완료했는지 소개합니다.

LLM에게 Markdown이 중요한 이유

코드를 보여드리기 전에, 이것이 왜 중요한지 이야기해 보겠습니다. LLM은 토큰(token) 단위로 비용을 청구합니다. 실제 사례는 다음과 같습니다:

# HTML — 보일러플레이트(boilerplate)만으로도 23개의 토큰 소모
'<h1 class="title" id="intro">Introduction</h1>'

...

이는 모든 제목, 모든 단락 래퍼(wrapper), 모든 테이블 셀(table cell)에서 7.6배의 효율성 격차가 발생함을 의미합니다. 수백 개의 문서를 LLM 컨텍스트 윈도우(context window)로 처리할 때, 가공되지 않은 HTML과 깨끗한 Markdown 사이의 차이는 토큰 사용량을 3~8배 줄여줄 수 있습니다. 이는 API 비용 절감, 더 빠른 추론(inference), 그리고 단일 컨텍스트 윈도우에 더 많은 문서를 담을 수 있음을 직접적으로 의미합니다.

MarkItDown은 Microsoft의 오픈 소스 문서-to-Markdown 변환기입니다. GitHub 스타 14만 개 이상을 기록 중이며, MIT 라이선스를 따르고, 하루에 약 200개의 스타를 얻고 있습니다. PDF, DOCX, PPTX, Excel 및 10개 이상의 다른 형식을 처리하며, 모두 깨끗하고 일관된 Markdown으로 변환합니다.

스크립트 1: batch_convert.py — 재귀적 디렉토리 변환기

이것이 핵심 도구입니다. 디렉토리를 지정하면 지원되는 모든 파일을 재귀적으로 찾아 변환한 뒤, 원본 파일 옆에 .md 파일을 생성합니다.

#!/usr/bin/env python3
"""MarkItDown을 사용하여 문서를 Markdown으로 일괄 변환합니다."""
import argparse
...

사용법은 매우 간단합니다:

pip install markitdown
python batch_convert.py ./client-docs --output-dir ./markdown-output

디렉토리를 지정하면 모든 PDF, DOCX, PPTX, Excel, HTML, CSV, JSON, XML, 이메일, RTF, ODF, EPUB 파일을 재귀적으로 찾아 각각 변환하며, 출력 폴더에 디렉토리 구조를 그대로 반영합니다.

스크립트 2: server.py — CLI 대신 API가 필요한 경우

때로는 파이프라인을 구축하면서 n8n 워크플로우, Zapier 웹훅(webhook), 또는 자체 프론트엔드(frontend)를 통해 HTTP 방식으로 변환을 트리거해야 할 때가 있습니다. 다음은 MarkItDown을 REST API로 노출하는 FastAPI 래퍼(wrapper)입니다:

#!/usr/bin/env python3
"""API 기반 변환을 위해 MarkItDown을 래핑하는 FastAPI 서버."""
import tempfile
...

이제 스택 내의 어떤 서비스든 파일을 POST하여 Markdown을 돌려받을 수 있습니다:

curl -X POST http://localhost:8000/convert \
  -F "file=@report.docx"

스크립트 3: pdf_cleanup.py — 지저분한 PDF를 위한 후처리 (Post-Processing)

PDF 변환은 상황이 매우 까다로워지는 지점입니다. 스캔된 문서는 빈 문자열로 출력되고, 다단 레이아웃(multi-column layouts)은 텍스트가 뒤섞이며, 워터마크가 출력물 곳곳에 흩어지기도 합니다. 이 스크립트는 가장 흔한 아티팩트(artifacts)들을 정리합니다:

#!/usr/bin/env python3
"""더 깨끗하고 LLM에 적합한 텍스트를 위해 MarkItDown 출력을 후처리합니다."""
import re
...

모든 출력물을 정리하려면 batch_convert 실행 후 이 스크립트를 실행하세요:

python pdf_cleanup.py ./markdown-output/*.md --in-place

Docker 옵션: 단 한 번의 명령으로 설정 없이 사용하기

Python 환경(특히 PDF 관련 종속성 문제)을 다루고 싶지 않다면, 모든 것이 컨테이너화되어 있습니다:

git clone https://github.com/Jakeshadow/markitdown-batch-examples.git
cd markitdown-batch-examples

...

Docker 이미지에는 모든 무거운 종속성(pdfminer, python-docx, openpyxl)이 포함되어 있어 시스템 라이브러리와 씨름할 필요가 없습니다.

MarkItDown vs Unstructured.io: 무엇을 언제 사용할 것인가

MarkItDown을 사용하기로 결정하기 전에 두 가지를 모두 평가했습니다. 간단한 비교는 다음과 같습니다:

• MarkItDown: MIT 라이선스, Python 네이티브(Python-native), 매우 단순한 API (md.convert("file.pdf")), 깨끗한 의미론적 Markdown (semantic Markdown) 생성. 설정 없이 LLM에 즉시 사용 가능한 출력을 원하는 배치 변환 (batch conversion) 파이프라인에 최적입니다.
• Unstructured.io: Apache 2.0, 더 난해한 형식(JPG OCR, 메타데이터를 포함한 EML 파싱)을 지원하지만, 의존성(dependencies)이 더 무겁고 설정이 더 복잡합니다. 텍스트와 함께 구조화된 청킹 (chunking) 메타데이터가 필요한 경우에 더 적합합니다.

LLM 파이프라인을 위해 내부 문서를 일괄 변환하는 저의 사용 사례에서는, 단순함과 출력 품질 측면에서 MarkItDown이 승리했습니다. 설정 파일도 필요 없고, 구성해야 할 파티셔닝 전략 (partitioning strategies)도 없습니다. 그저 파일을 지정하기만 하면 Markdown을 얻을 수 있습니다.

양측의 코드 예제를 포함한 전체 비교는 다음을 참조하세요: MarkItDown vs Unstructured.io.

요약 (The Takeaway)

세 개의 스크립트와 한 오후의 작업으로, 300개 이상의 문서가 난잡한 전용 형식 (proprietary formats)에서 깨끗하고 토큰 효율적인 (token-efficient) Markdown으로 변환되었습니다. 전체 파이프라인은 다음과 같습니다:

1. batch_convert.py — 디렉토리 내의 모든 파일을 대량 변환
2. pdf_cleanup.py — PDF 아티팩트 (artifacts)를 수정하기 위한 후처리
3. server.py — 프로그래밍 방식의 접근이 필요할 때 사용하는 REST API

설치 단계, Docker 설정 및 성능 벤치마크 (benchmarks)를 포함한 전체 가이드는 markitdown-pro.com에서 확인할 수 있습니다. 세 가지 스크립트와 Docker Compose 파일은 GitHub companion repo에 있습니다.

파일을 하나씩 열지 마세요. 스크립트에게 맡기세요.