MarkItDown은 여러 문서를 마크다운으로 통일하는 변환기이지, RAG 전처리 전체를 대신하는 파서나 청커는 아닙니다.
PDF, Word, Excel, PPT, HTML처럼 입력 형식이 제각각이면 변환 계층 하나만 통일해도 파이프라인은 단순해집니다. 다만 변환 결과가 생겼다는 사실과 검색에 쓸 만한 데이터가 만들어졌다는 판단은 구분해야 합니다. 표 구조, 읽기 순서, 이미지 설명, 메타데이터를 샘플 문서로 확인한 뒤 청킹과 품질 검사를 붙이는 편이 안전합니다.
MarkItDown은 여러 형식의 파일을 LLM이 다루기 쉬운 마크다운 텍스트로 바꿉니다. 제목과 목록, 표 같은 구조를 한 가지 표현으로 맞출 수 있어 포맷마다 서로 다른 출력 인터페이스를 유지하는 부담이 줄어듭니다. ZIP 내부 파일을 재귀적으로 처리할 수 있다는 점도 여러 문서가 묶인 입력에 유용합니다.
그러나 “마크다운으로 변환됨”이 “원문 의미가 보존됨”을 뜻하지는 않습니다. 도입 전에 최소한 다음 결과를 원문과 나란히 봐야 합니다.
가장 작은 사용 형태는 다음과 같습니다.
1
2
3
4
5
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("복잡한_회사_실적보고서.xlsx")
print(result.text_content)
이 코드는 “파일 하나를 변환해 텍스트를 얻는다”는 핵심 조각입니다. 설치할 선택 의존성, 지원 버전, 암호화되거나 손상된 파일의 처리, 예외 기록, 대용량 파일 제한은 포함하지 않습니다. 따라서 운영 절차로 복사하기보다, 배포 패키지 정보와 대상 형식의 요구 사항을 확인하는 출발점으로 봐야 합니다.
변환 뒤에는 원본 파일명, 페이지나 시트, 슬라이드 같은 출처 정보를 청크와 함께 남기는 로직도 필요합니다. MarkItDown이 내놓는 순수 텍스트만 저장하면 검색 답변에서 근거 위치를 되짚기 어려울 수 있습니다.
문서 안의 사진이나 다이어그램을 설명하려면 LLM 클라이언트와 모델을 넘길 수 있습니다.
1
2
3
4
5
6
from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("아키텍처_다이어그램_포함.pdf")
이 역시 최소 예시입니다. API 인증, 전송되는 데이터의 범위, 재시도, 비용 상한, 모델 응답 검증은 생략돼 있습니다. 이미지가 많은 문서는 호출량이 커질 수 있고, 생성된 설명에는 누락이나 잘못된 해석이 들어갈 수 있습니다. 민감 문서라면 외부 모델로 전송해도 되는지부터 확인해야 합니다.
호환 API를 제공하는 Ollama, LLaVA 계열 로컬 구성을 고려할 수 있지만, 이를 곧바로 “비용 0원”으로 표현하기는 어렵습니다. API 사용료 대신 하드웨어, 운영, 처리 시간과 모델 품질 검증 비용이 생깁니다.
MarkItDown의 가치가 가장 잘 드러나는 문서보다 실패 비용이 큰 문서를 먼저 넣어 보는 편이 낫습니다.
특히 표의 숫자와 열 이름이 어긋나면 검색은 성공해도 답이 틀릴 수 있습니다. 변환 성공률만 집계하지 말고 구조 보존률과 근거 추적 가능성도 품질 지표로 두는 이유입니다.
파일 형식을 하나의 마크다운 인터페이스로 통일하려는 팀에는 MarkItDown이 유용한 시작점입니다. 반면 정교한 레이아웃 복원, 청크별 메타데이터, 인용 위치 보존이 핵심이라면 별도 파싱과 후처리를 예상해야 합니다.
실행 순서는 간단합니다. 대표 문서보다 어려운 문서 묶음으로 변환 품질을 측정하고, 형식별 실패 규칙을 만든 뒤, 헤더 기반 청킹과 출처 메타데이터를 붙입니다. 마지막으로 VLM을 켠 경우와 끈 경우의 정확도, 지연, 비용을 비교해야 합니다. 이 검증을 통과할 때 MarkItDown은 RAG의 “구원자”가 아니라 관리 가능한 변환 계층이 됩니다.
PDF는 눈에 보이는 좌표와 읽기 순서가 다를 수 있으므로 다단 문서와 각주가 섞인 샘플을 우선 봅니다. Excel은 셀 값만 남는지보다 sheet 이름, 병합 header, 빈 셀의 의미와 수식 결과가 어느 열에 연결되는지가 중요합니다. PowerPoint는 slide 순서와 speaker note, 도형 안의 text가 섞이지 않는지 확인해야 합니다.
| 문서 유형 | 먼저 볼 실패 | RAG에 미치는 영향 |
|---|---|---|
| 다단 PDF | 열 사이 문장 혼합 | 존재하지 않는 문장과 논리 생성 |
| 병합 셀 Excel | header와 숫자 열 불일치 | 올바른 숫자를 잘못된 항목에 인용 |
| 도형 중심 PPT | text box 순서 붕괴 | 설명 단계와 결론의 순서 역전 |
| 이미지 문서 | OCR, VLM 누락 | 핵심 근거가 검색 대상에서 사라짐 |
한 변환 기준으로 모든 형식을 합격시키기보다 문서 유형별 필수 요소를 정의합니다. 숫자 보고서는 표 정확도에 높은 비중을 두고, 규정 문서는 section 번호와 각주, 발표 자료는 slide 경계와 제목을 우선할 수 있습니다. 변환이 어려운 형식은 전용 parser로 보내는 fallback도 파이프라인의 일부입니다.
최소 메타데이터는 원본 파일 ID, checksum, 변환 시각, 변환기 버전, 페이지, sheet, slide 위치입니다. 같은 파일명이 다시 업로드될 수 있으므로 이름만으로 문서를 식별하면 이전 청크와 새 청크가 섞일 수 있습니다. 원본 checksum과 변환 결과 version을 연결하면 답변이 어느 시점의 문서를 근거로 했는지 추적할 수 있습니다.
청크에는 상위 제목 경로와 표의 header를 함께 넣습니다. 숫자 한 행만 잘라 저장하면 검색 결과에서 열 의미를 잃을 수 있고, 페이지 번호만 남기면 Excel, PPT의 위치를 표현하기 어렵습니다. 사용자에게 보여 줄 citation label과 내부 재처리에 쓸 source key를 나누면 파일명이 바뀌어도 인덱스를 안정적으로 관리할 수 있습니다.
VLM이 만든 이미지 설명은 원문에서 직접 추출한 text와 다른 종류의 근거입니다. generated_description처럼 출처 유형을 표시하고 model, prompt version을 남겨야 나중에 설명 오류를 찾을 수 있습니다. 생성 설명을 원문 문장처럼 섞어 저장하면 답변이 추론을 사실 인용으로 보일 위험이 있습니다.
각 형식에서 실패하기 쉬운 문서 5~10개를 골라 사람이 핵심 문장, 표 셀, 제목 경계를 표시합니다. 변환 뒤 이 요소가 존재하는지와 순서가 맞는지 자동 검사하고, 읽기 순서처럼 단순 문자열 비교로 부족한 항목은 사람이 표본 검토합니다. 라이브러리나 선택 dependency를 업데이트할 때 같은 세트를 다시 실행합니다.
변환 성공률은 예외 없이 파일이 끝났다는 지표일 뿐입니다. 필수 요소 보존률, 잘못 추가된 text, 처리 시간과 peak memory를 함께 기록해야 합니다. 대용량 파일 하나가 worker를 점유하거나 VLM 재시도가 과도하게 발생하는 경우를 찾기 위해 크기 구간별 분포도 봅니다.
실패 문서는 빈 Markdown으로 저장하지 않고 상태와 원인을 별도 queue에 둡니다. 암호화 파일, 손상 파일, 지원하지 않는 형식, 일시적 VLM 오류는 서로 다른 재처리 정책이 필요합니다. 수동 보정한 결과가 있다면 다음 자동 변환에서 덮어쓰지 않도록 원본, 자동 결과, 검수 결과를 분리해야 합니다.
품질 검사가 통과한 문서만 다음 청킹 단계로 보내면 변환 실패가 검색 품질 문제로 숨어드는 것을 막을 수 있습니다.
먼저 제목 계층, 표의 행, 열, 페이지, 시트, 슬라이드 경계와 반복 머리글을 확인해야 합니다. 원본 위치 메타데이터를 붙인 뒤 문서 유형에 맞는 청킹 규칙을 적용하는 편이 안전합니다.
이미지 설명을 추가할 수 있지만 다이어그램의 관계나 작은 글자를 잘못 읽을 수 있습니다. 중요한 그림은 사람이 만든 정답 설명과 비교하고 외부 API 전송 범위, 비용도 함께 확인해야 합니다.
공통 인터페이스는 운영을 단순하게 하지만 특정 형식의 레이아웃과 표 정확도가 부족할 수 있습니다. 어려운 문서에서 전용 parser와 품질, 속도를 비교해 format별 fallback을 두는 방법도 있습니다.
←→ 키와 좌우 스와이프를 지원합니다. 읽던 페이지는 이 기기에 저장됩니다.