PDF를 마크다운으로 변환해 LLM 토큰 절약하기: MarkItDown 가이드

20페이지짜리 PDF를 Claude에 넣고 질문 하나를 던지면, 답은 무리 없이 돌아옵니다. 그런데 보이지 않는 게 하나 있습니다. 바로 청구서입니다. 여러분의 질문이 읽히기도 전에, 그 문서 한 장이 수만 토큰을 삼켜버릴 수 있습니다. 팀 단위로 하루에 몇 번씩 이렇게 하면, 깔끔한 텍스트만으로도 충분했을 모델에 PDF 원본을 퍼붓느라 실제 비용을 지불하게 됩니다.

무료 해결책이 있고, 사실 처음부터 눈앞에 있었습니다. 파일을 먼저 마크다운으로 변환하는 것입니다. 이 가이드는 PDF가 왜 그렇게 비싼지, 얼마나 아낄 수 있는지, 그리고 마이크로소프트의 오픈소스 변환 도구 MarkItDown으로 단 한 번의 명령에 변환하는 방법을 정확히 설명합니다.

PDF가 토큰을 그렇게 많이 잡아먹는 이유

아무도 말해주지 않는 부분이 여기 있습니다. PDF를 LLM에 건네면, 그것은 여러분이 읽는 방식대로 읽히지 않습니다. Anthropic의 PDF 공식 문서에 따르면, 시스템은 모든 페이지마다 두 가지 작업을 합니다.

1. 페이지에서 텍스트를 추출합니다.
2. 페이지 전체를 이미지로 변환한 뒤, 그 이미지를 텍스트와 함께 보냅니다.

두 번째 단계가 바로 조용히 토큰을 빨아들이는 구멍입니다. 모델은 단어만 읽는 게 아니라, 차트와 표와 레이아웃을 이해할 수 있도록 각 페이지의 사진까지 들여다봅니다. 여러분은 그 둘 모두에 대해 비용을 냅니다.

Anthropic이 제시한 수치를 보면 비용이 구체적으로 다가옵니다. 추출된 텍스트만 따져도 밀도에 따라 페이지당 1,500에서 3,000 토큰이 듭니다. 거기에 더해 페이지마다 이미지 비용이 얹힙니다. Amazon Bedrock 연동에서 나온 시사적인 데이터가 하나 있습니다. 전체 시각 PDF 모드는 3페이지 PDF에 약 7,000 토큰을 쓰는 반면, 같은 세 페이지를 단순 텍스트로 추출하면 약 1,000 토큰만 씁니다. 7배 차이이고, 그 차이는 전적으로 페이지마다 들어가는 이미지에서 옵니다.

이걸 실제 문서 규모로 키워봅시다. 빽빽한 20페이지 보고서는 모든 페이지가 이미지로 래스터화되고 나면 40,000에서 70,000 토큰 사이 어디든 떨어질 수 있습니다. 여러분은 아직 아무것도 묻지 않았습니다. 그저 파일을 열었을 뿐입니다.

주황빛 빨강 블록은 순수한 추가 비용입니다. 페이지에 볼 만한 시각 자료가 있든 없든, 모든 페이지마다 이미지 하나가 들어갑니다.

해결책: 대신 깔끔한 마크다운을 넣기

대부분의 문서는 굳이 눈으로 볼 필요가 없습니다. 계약서, 명세서, 연구 논문, 글머리 기호로 가득한 슬라이드 묶음. 이 모두는 레이아웃을 입은 텍스트일 뿐입니다. 레이아웃을 벗겨내고 구조만 남겨두면, 모델은 실제로 필요했던 것을 하나도 잃지 않습니다.

바로 그것이 마크다운이 주는 가치입니다. 마크다운은 한 포맷이 도달할 수 있는 한 가장 일반 텍스트에 가깝지만, 그러면서도 중요한 구조는 그대로 담아냅니다. 제목, 목록, 표, 링크, 코드 블록, 굵게와 강조까지요. 주류 LLM은 방대한 양의 마크다운으로 학습되었기 때문에, 그것을 자연스럽고 손쉽게 파싱합니다. MarkItDown을 만든 마이크로소프트는 이렇게 간단히 표현합니다. 마크다운은 "마크업이나 서식이 최소한이라 일반 텍스트에 극도로 가깝지만, 그래도 중요한 문서 구조를 표현하는 방법을 제공한다"고요.

PDF를 마크다운으로 변환하면 페이지마다 들어가던 이미지를 통째로 걷어냅니다. 래스터화된 페이지도, 시각 처리 추가 비용도 없고, 모델이 어차피 읽으려던 구조화된 텍스트만 남습니다. 절약은 바로 거기서 나옵니다.

마이크로소프트의 무료 변환 도구, MarkItDown 소개

MarkItDown은 마이크로소프트가 만든 가벼운 파이썬 유틸리티로, 관대한 MIT 라이선스로 공개되어 있으며 GitHub에서 가장 많은 별을 받은 개발자 도구 중 하나입니다. 별이 135,000개를 넘습니다. 이 도구의 유일한 임무는, 현실 세계의 지저분한 파일들을 LLM이 저렴하게 읽을 수 있는 깔끔한 마크다운으로 바꾸는 것입니다.

PDF 전용 도구만은 아닙니다. 긴 형식 목록을 변환합니다.

• PDF 문서
• Word (.docx)
• Excel (.xlsx, .xls)
• PowerPoint (.pptx)
• 이미지, EXIF 메타데이터와 그림 속 텍스트를 위한 OCR 포함
• 오디오, 메타데이터와 음성 전사 포함
• HTML 페이지
• CSV, JSON, XML 데이터
• ZIP 압축 파일 (내용물을 훑어 들어갑니다)
• YouTube URL (자막을 가져옵니다)
• EPub 전자책
• Outlook 메시지 (.msg)

하나의 도구, 하나의 출력 포맷으로, 평소라면 무거운 바이너리 형태로 모델에 던졌을 거의 모든 것을 처리합니다.

30초 만에 MarkItDown 설치하기

평범한 파이썬 패키지입니다. 모든 것을 한꺼번에 받으려면 all 엑스트라를 설치하세요.

pip install 'markitdown[all]'

몇 가지 포맷만 필요하고 더 가벼운 설치를 원한다면, 그 엑스트라만 지정하세요.

pip install 'markitdown[pdf, docx, pptx]'

사용 가능한 옵션에는 [all], [pdf], [docx], [pptx], [xlsx], [xls], [outlook], [audio-transcription], [youtube-transcription] 등이 있습니다.

명령줄에서 PDF를 마크다운으로 변환하기

가장 빠른 길은 CLI입니다. 파일을 지정하고 원하는 곳으로 출력을 보내세요.

markitdown report.pdf -o report.md

또는 단순 리다이렉션을 써도 같은 결과가 나옵니다.

markitdown report.pdf > report.md

파일을 곧장 파이프로 흘려보낼 수도 있습니다.

cat report.pdf | markitdown

이게 워크플로의 전부입니다. 이제 여러분에게는 어떤 모델에든 건네고, 저장소에 넣고, 채팅에 붙여넣을 수 있는 report.md가 생겼고, 비용은 원본의 극히 일부에 불과합니다.

무거운 파일이 들어가고, 에이전트가 바로 읽을 수 있는 마크다운이 나오며, 그 사이엔 명령 한 줄뿐입니다.

파이썬으로 변환하기 (그리고 폴더 전체를 일괄 처리하기)

이걸 파이프라인에 끼워 넣는다면, 파이썬 API도 그만큼 짧습니다.

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("report.pdf")
print(result.text_content)

result.text_content가 바로 디스크에 쓰거나 모델에 넘길 준비가 된 여러분의 마크다운 문자열입니다. 문서 폴더 하나를 한 번에 변환하려면, 그 위를 순회하세요.

from pathlib import Path
from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
for src in Path("docs").glob("*.pdf"):
    out = src.with_suffix(".md")
    out.write_text(md.convert(str(src)).text_content, encoding="utf-8")

이걸 한 번 돌리면, 비싼 PDF가 들어찬 디렉터리가 저렴하고 구조화된 마크다운 디렉터리로 바뀝니다. 어떤 에이전트든 매 턴마다 시각 처리 세금을 다시 내지 않고도 읽을 수 있게 됩니다.

실제로 얼마나 절약될까요?

솔직한 답은 이렇습니다. 문서에 따라 다르지만, 이득은 크고 일관됩니다. 텍스트 위주의 전형적인 파일을 기준으로 대략적인 모습은 다음과 같습니다.

가치가 글에 담겨 있는 문서라면, 마크다운으로 변환하는 것만으로 토큰 비용을 절반을 훌쩍 넘게, 종종 80% 이상 줄입니다. 이 절약은 마법이 아닙니다. 모델이 텍스트만 필요했는데도 페이지마다 사진을 보내느라 내던 비용을 더 이상 내지 않을 뿐입니다.

물론 마크다운이 말 그대로 공짜는 아닙니다. 추출된 텍스트는 여전히 토큰을 씁니다. 하지만 그 텍스트 비용은 어차피 내야 했던 바닥선입니다. 여러분이 걷어내는 것은 그 위에 얹혀 있던 페이지당 이미지 더미입니다.

PDF를 그대로 두어야 할 때 (과도하게 최적화하지 말 것)

변환은 옳은 기본값이지, 만능 규칙이 아닙니다. 시각적 레이아웃 자체가 핵심일 때는 원본 PDF를 유지하세요.

• 모델이 실제로 읽어야 하는 차트와 그래프. 의미가 막대 그래프 안에 살아 있다면, 그 이미지는 진짜 역할을 하고 있는 것입니다.
• 스캔된 문서, 즉 텍스트를 찍은 이미지. MarkItDown이 OCR을 할 수 있지만, 인식이 불안정하다면 모델 자체의 시각 능력이 페이지를 더 안정적으로 읽어낼 수 있습니다.
• 복잡한 시각적 표나 양식, 위치와 정렬이 의미를 담고 있어 마크다운에서는 그 의미가 납작해지는 경우.
• 인포그래픽과 디자인 비중이 높은 페이지, 레이아웃 자체가 내용인 경우.

그 외의 모든 것, 즉 대부분의 문서에서는 마크다운이 이깁니다.

질문은 결코 추상적인 "PDF냐 마크다운이냐"가 아닙니다. "모델이 이 페이지를 봐야 하는가, 아니면 그냥 읽으면 되는가"입니다.

PDF를 넘어서: Word, Excel, PowerPoint, 심지어 YouTube까지

같은 한 줄 명령이 나머지 문서 더미에도 그대로 통합니다. Word 문서, 스프레드시트, 슬라이드 묶음, 웹 페이지, 심지어 YouTube 영상의 자막까지 모두 똑같은 방식으로 깔끔한 마크다운으로 접혀 들어갑니다.

markitdown deck.pptx -o deck.md
markitdown budget.xlsx -o budget.md
markitdown https://www.youtube.com/watch?v=VIDEO_ID -o transcript.md

여러분의 워크플로가 Office 파일이나 웹에서 정기적으로 컨텍스트를 끌어와 모델에 넘기는 일이라면, 모든 것을 먼저 마크다운으로 표준화하는 것이야말로 가장 저렴하면서 가장 효과가 큰 습관 중 하나입니다.

MarkItDown MCP 서버로 코딩 에이전트에 연결하기

코딩 에이전트와 함께 작업한다면, 이건 한층 더 좋아집니다. MarkItDown은 공식 MCP(Model Context Protocol) 서버를 함께 제공합니다. 그래서 여러분이 손으로 무언가를 실행하지 않아도, 에이전트가 작업 도중에 직접 파일을 변환할 수 있습니다.

설치한 뒤 stdio로 실행하세요.

pip install markitdown-mcp
markitdown-mcp

이 서버는 단 하나의 도구, convert_to_markdown(uri)를 노출합니다. 여기서 uri는 어떤 http:, https:, file:, data: URI든 될 수 있습니다. 한 번 에이전트에 연결해두면, 에이전트가 PDF나 스프레드시트나 웹 페이지를 가져와 필요할 때마다 마크다운으로 바꿀 수 있고, 그동안 내내 시각 처리 가격이 아니라 텍스트 토큰 가격만 냅니다.

이건 에이전트를 하나 이상 돌릴 때 정확히 복리처럼 쌓이는 종류의 일입니다. 멀티 에이전트 콕핏인 AgentsRoom에서는 MCP 서버를 한 번만 설정하면 방 안의 모든 에이전트가 그것을 물려받습니다. 참조 문서를 .md로 변환해 저장소에 커밋해두면, 각 에이전트는 같은 PDF를 매번 다시 이미지로 변환하는 대신 매 턴마다 저렴하고 구조화된 텍스트를 읽습니다. 단일 세션을 가볍게 유지하는 그 규율이 함대 전체를 감당 가능한 비용으로 유지해줍니다. 이는 코딩 에이전트를 병렬로 돌리고 그 하나하나가 여러분의 공유 컨텍스트를 읽을 때 특히 중요합니다.

이것은 좋은 에이전트 구성이 이미 컨텍스트를 관리하는 방식과도 자연스럽게 잘 어울립니다. AGENTS.md 컨텍스트 파일을 유지한다면, 그것이 PDF 원본이 아니라 가벼운 .md 참조를 가리키게 하는 편이 컨텍스트 창을 빠듯하게 유지해줍니다. 그리고 컨텍스트 드리프트를 잡아내는 카나리아 기법에서 다뤘듯이, 그것이 긴 세션에서 승부의 절반입니다.

핵심 정리

PDF 원본을 LLM에 넣는 것은, 페이지마다 조용히 이미지로 변환되기 때문에 여러분이 알아채지 못한 채 내고 있던 세금입니다. MarkItDown은 그 세금을 무료로 없애줍니다. 명령 한 번이면 거의 모든 파일이 깔끔한 마크다운으로 바뀌고, 토큰 비용의 최대 80%를 덜어내며, 모델은 똑같이 잘, 종종 더 잘 답합니다. 페이지 사진을 보며 눈을 가늘게 뜨는 대신 구조를 읽기 때문입니다.

먼저 변환하고, 그다음에 물어보세요. 여러분의 토큰 청구서와 컨텍스트 창이 둘 다 고마워할 것입니다.

하나의 터미널이 아니라 에이전트 팀 전체에 이걸 적용할 준비가 되셨나요? AgentsRoom 다운로드에서 시작하고, 프로바이더 호환성 매트릭스에서 각 에이전트가 무엇을 지원하는지 확인하고, 멀티 프로바이더 지원에 대해 더 읽어보세요.