LLM 파이프라인에 문서를 넣기 전, 표와 목록 구조를 살려 마크다운으로 정리하는 방법
PDF나 워드 문서에 담긴 표와 목록, 제목 같은 구조를 그대로 살려 텍스트로 뽑아내는 과정이 이제 한 줄 명령으로 끝납니다. MarkItDown은 다양한 파일 형식을 마크다운으로 변환하는 Python 유틸리티로, 생성형 AI 모델이 문서를 이해하기 쉽게 정리해 줍니다. 복잡한 레이아웃을 단순 텍스트로 깨뜨리지 않고, 문서의 뼈대를 유지한 채 변환한다는 점이 가장 큰 특징입니다.
마크다운을 고른 이유
마크다운은 순수 텍스트에 가깝지만 문서의 구조를 표현할 수 있는 최소한의 마크업을 제공합니다. GPT-4o 같은 주류 LLM은 마크다운을 자연스럽게 이해하고 응답에 포함시키며, 이는 방대한 마크다운 텍스트로 학습되었음을 시사합니다. 또한 마크다운 형식은 토큰 효율이 높아 LLM 처리 비용과 시간을 줄이는 데 유리합니다. MarkItDown은 이러한 장점을 살려 LLM 파이프라인에 최적화된 변환을 수행합니다.
변환 가능한 파일 형식
MarkItDown은 PDF, PowerPoint, Word, Excel, 이미지, 오디오, HTML, 텍스트 기반 형식(CSV, JSON, XML), ZIP 파일, YouTube URL, EPub 등 다양한 형식을 지원합니다.
- 오피스 문서 PowerPoint, Word, Excel 파일을 마크다운으로 변환합니다.
- 멀티미디어 이미지의 OCR과 오디오의 음성 전사를 통해 텍스트를 추출합니다.
- 웹 및 기타 HTML, YouTube URL, EPub, ZIP 파일 등을 지원합니다.
설치와 실행 방법
Python 3.10부터 3.14까지를 요구하며, 가상 환경을 사용하는 것을 권장합니다. pip install 'markitdown[all]' 명령으로 모든 선택적 의존성을 포함해 설치할 수 있습니다. 특정 형식만 필요하면 pip install 'markitdown[pdf, docx]'처럼 옵션을 지정하여 설치 범위를 좁힐 수 있습니다. Python API를 통해 MarkItDown 클래스를 인스턴스화하고 convert 메서드를 호출하는 방식도 지원합니다.
플러그인과 Azure 연동
MarkItDown은 제3자 플러그인을 지원하여 새로운 형식이나 기능을 추가할 수 있습니다. 예를 들어 markitdown-ocr 플러그인은 LLM Vision을 활용해 PDF나 워드 문서 내 이미지에서 텍스트를 추출합니다. Azure Content Understanding와 연동하면 클라우드 기반의 고품질 변환과 구조화된 필드 추출(YAML front matter)이 가능합니다. 이 기능은 영상 파일 변환이나 도메인 특화 필드 추출이 필요할 때 유용하며, Azure API 호출 비용이 발생한다는 점을 유의해야 합니다. Azure Document Intelligence와의 연동도 지원하여 레이아웃 분석을 강화할 수 있습니다.
보안과 적용 범위 확인
MarkItDown은 현재 프로세스의 권한으로 I/O를 수행하므로, 신뢰할 수 없는 환경에서는 입력을 반드시 정제해야 합니다. convert() 메서드는 로컬 파일, 원격 URI, 바이트 스트림을 모두 처리하도록 설계되어 유연하지만, 보안이 중요한 서버 측 애플리케이션에서는 convert_local()이나 convert_stream()처럼 필요한 최소한의 API를 호출하는 것이 좋습니다. 이 도구는 LLM 파이프라인을 위한 텍스트 분석에 최적화되어 있으며, 사람이 직접 읽기 위한 고해상도 문서 변환에는 적합하지 않을 수 있습니다. Python 라이브러리로 다른 시스템에 통합하는 용도로 설계되었으므로, 웹 서버나 데스크톱 앱 같은 최종 사용자 애플리케이션을 직접 구축하는 용도로는 권장되지 않습니다.
