做 RAG 或 Agent,第一步常被說成 embedding。但實際跑起來,embedding 之前還有一關:把 PDF、Word、PPT 裡的內容整理成模型能穩定吃的文字。
PDF 會有多欄、表格、註腳;PPT 裡有標題層級與條列;Word 還會夾雜樣式資訊。直接把原始檔案丟給模型,解析結果很難預測。
微軟開源的 MarkItDown 正好卡在這個位置。它不是給人做排版轉換,也不追求像素級還原,而是把常見檔案壓成適合 LLM 消耗的 Markdown。
專案在 GitHub 上有 174k+ Star(數字隨時變動,請以倉庫首頁為準)。支援的格式包括:
- Word
- Excel
- PowerPoint
- 圖片,支援 EXIF 與 OCR
- 音檔,支援 EXIF 與語音轉寫
- HTML、CSV、JSON、XML
- ZIP、EPub
- YouTube 連結
設計目標很明確:輸出不是給人類排版用的文件,而是給 LLM 用的結構化文字。
它解決什麼問題
Embedding 之前通常要做三件事:
- 抽出正文。
- 保留標題、列表、表格等結構。
- 把結果切成模型能處理的區塊。
MarkItDown 主要負責前兩步。
同類工具裡,textract 太老,輸出常常是純文字,結構資訊掉得多;pandoc 偏向文件轉換與還原,適合需要接近原版型的場景;unstructured 功能齊全,但系統較重,抽象層也換了一套。
MarkItDown 走中間路線:
- 夠輕量。
- 能保留一部分文件結構。
- 輸出 Markdown,對 LLM 友善。
- 有 CLI,也有 Python API。
Markdown 對 LLM 來說通常比複雜 HTML 或帶大量格式標記的文字省 token。GPT-4o 這類模型也能原生理解 Markdown 的標題、列表、表格與程式碼區塊。
不過 Markdown 不是永遠最短的表示法。複雜 Word 樣式、PDF 的頁首頁尾與座標版面,轉換後仍可能產生雜訊。但它提供了一個夠穩定的中間格式,後續切塊、檢索與生成都可以圍繞同一份文字進行。
怎麼用
Python 3.10+。全功能安裝:
pip install 'markitdown[all]'
只處理 PDF:
pip install 'markitdown[pdf]'
還有 [docx]、[pptx]、[xlsx]、[audio] 等分組。沒必要把 OCR、音檔轉寫和所有格式全部裝上。
CLI:
markitdown file.pdf > out.md
Python API:
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("report.pdf")
print(result.text_content[:500])
# 限制輸入來源:只讀本地檔案
from markitdown import MarkItDown, convert_local
result = convert_local("report.pdf")
print(result.text_content[:500])
MarkItDown().convert() 是高層介面,會依輸入選轉換方式。convert_local() 介面較窄,只處理本地檔案。
安全上要留意。README 頂端明確警告:MarkItDown 涉及 I/O 操作,權限風險與 Python 的 open()、網路請求中的 requests.get() 同等級。別因為它只是個文件轉換函式庫,就把它放進不可信輸入、任意網址或高權限的 Agent 環境。
它怎麼運作
核心結構不複雜:
- 一個
MarkItDownclass。 - 多個
Converter子類別。 - 依副檔名或 MIME 型別分派 Converter。
- 每個 Converter 自己負責一種格式。
PDF → PdfConverter,Word → DocxConverter,PPT → PptxConverter,YouTube 連結 → YoutubeConverter。
這種設計比一個大函式裡堆滿 if/else 容易擴充。要加一種新格式,通常是新增一個 Converter,再接上派發邏輯。
三層 API:
- 高層:
MarkItDown().convert() - 中層:
convert_local() - 底層:
convert_stream()
呼叫層級越低,權限範圍越窄,程式碼可以更明確地區分本地檔案、外部網路與串流輸入。對 Agent 來說這個差別不是裝飾。Agent 一旦能代替使用者讀檔、連網或處理不可信連結,權限設計就是核心功能。
圖片與音檔的路徑不太一樣。圖片可抽 EXIF,依設定走 OCR;音檔可抽 metadata 並做語音轉寫。這部分通常依賴外部服務,部署前要確認服務、費用與資料流向。
它哪裡好/哪裡不好
做得好的地方
覆蓋面廣。一個工具處理 PDF、Office、圖片、音檔、網頁、壓縮檔與 YouTube 連結。
API 是漸進式設計。最簡單時一行 CLI;要整合時用 MarkItDown().convert();要限制輸入來源時,下沉到 convert_local() 或 convert_stream()。
安全聲明寫得很工程化。README 沒有迴避本地檔案、網路請求與第三方服務的風險。
安裝考慮了依賴體積。全量裝簡單,按格式裝更省環境。
不足
第一,複雜排版還原度不如 pandoc。
PDF 的跨頁表格、註腳、浮動圖片、複雜頁眉、多欄版面,轉換後可能出現順序錯亂;OCR 效果也吃圖片文字品質。
第二,圖片 OCR 與音檔轉寫可能依賴 Azure、OpenAI 等外部服務。需要純本地、純 CPU、不能上傳資料的場景,要自己補模型與依賴。
第三,Excel 不適合無腦塞進單一長檔。大型活頁簿、合併儲存格、公式、隱藏分頁都可能讓結果變慢,還夾帶一堆不相關內容。正式環境應先篩選分頁、限制行列、清掉公式,或按表格切片。
所以 MarkItDown 不是 pandoc 的替代品,也不是「所有文件都能正確還原」的解析器。它比較像是 RAG 鏈路裡的第一道清洗器。
我試了一下
本地裝了 markitdown[pdf,docx,pptx],挑了三份材料:
- 20 頁、含表格的財報 PDF。
- 20 頁 PPT。
- 5 頁 Word。
結果:
- PDF 表格大致保住,標題層級正確。
- PPT 保留了條列結構。
- Word 輸出乾淨,段落與標題穩定。
- PDF 約 2 秒。
- PPT 約 1 秒。
- Word 不到 1 秒。
速度受檔案複雜度影響大。我這台機器上,PDF 解析主要吃在 PyMuPDF 處理頁面上;真正拖慢整條鏈的,通常是大型 Excel。
要把結果送進 RAG,我會在 result.text_content 之後再做兩件事:先按標題與段落切塊,再依表格、頁碼或檔名補上 metadata。別直接把一份 500 頁 PDF 塞進一次 convert(),然後期待檢索品質穩定。
誰該用
適合:
- RAG 的文件預處理。
- Agent 工具鏈的資料入口。
- 批次文件清洗。
- 需要把 PDF、Word、PPT 統一轉成 Markdown 的腳本。
- 在程式裡依副檔名或 MIME 型別分派不同轉換器的專案。
不太適合:
- 要求像素級或出版級版型還原。
- 必須完全離線的圖片 OCR 或音檔轉寫。
- 複雜 Excel 報表的整檔轉換。
- 需要座標級 PDF 定位、閱讀順序還原、嚴格表格語意的專案。
我的選擇很直接:要塞文字給 LLM 時,先試 MarkItDown;要盡量保留版型時,用 pandoc;要更細的版面分區與較重的資料處理時,再看 unstructured。
MarkItDown 的價值不在「支援格式數量」本身。它把 Agent 接收世界的方式簡化成一步:檔案進來,Markdown 出去。