MarkItDown 教學｜微軟開源文件轉 Markdown 工具，LLM 與 RAG 必備
kyle

在 AI 應用開發中，不管是建立 RAG（Retrieval-Augmented Generation）知識庫、讓 LLM 分析文件內容、還是做資料前處理，第一步往往是把各種格式的文件轉成 LLM 看得懂的純文字。PDF、Word、Excel、PowerPoint 這些格式雖然人類讀起來方便，但對語言模型來說卻是一堵牆。微軟開源的 MarkItDown 就是為了解決這個問題而生，它能把超過 29 種檔案格式轉換成結構化的 Markdown，保留標題、表格、連結等重要資訊，讓 LLM 能直接理解文件的層次與脈絡。

MarkItDown 是什麼

MarkItDown 是微軟在 2024 年底開源的 Python 工具，專門把各種檔案格式轉換成 Markdown。它跟過去常用的 textract 類似，但最大的差異在於 MarkItDown 會盡量保留文件的結構——標題層級、表格、列表、超連結都會對應到 Markdown 語法，而不是把所有內容打成一整段純文字。

為什麼是 Markdown？因為像 GPT-4o、Claude、Gemini 這些主流 LLM 在訓練時就大量接觸 Markdown 格式，它們對 Markdown 的理解能力遠比其他標記語言好。把文件轉成 Markdown 再餵給模型，能得到更好的分析結果。

MarkItDown 在 GitHub 上已經累積超過 91,000 顆星，是微軟最受歡迎的 Python 開源專案之一。

支援的檔案格式

MarkItDown 支援的格式相當豐富，以下是主要的類別：

類別支援格式
Office 文件Word (.docx)、Excel (.xlsx, .xls)、PowerPoint (.pptx)
PDF.pdf（支援 Azure Document Intelligence 加強解析）
圖片EXIF 元資料擷取、搭配 LLM 做圖片描述、OCR 辨識
音訊EXIF 元資料擷取、語音轉文字
網頁與標記語言HTML、CSV、JSON、XML
壓縮檔ZIP（自動遞迴處理內部檔案）
其他YouTube 影片字幕、EPub 電子書、Outlook 郵件

值得一提的是，ZIP 檔案會自動展開並逐一轉換裡面的每個檔案，這在批次處理大量文件時非常方便。

安裝 MarkItDown

MarkItDown 需要 Python 3.10 或以上版本，目前支援到 3.13。實測 Python 3.14 因為部分依賴（如 magika）尚未支援，會退回安裝舊版 0.0.2，建議使用 3.12 或 3.13。最簡單的方式是透過 pip 安裝：

# 安裝所有格式支援（推薦）
pip install 'markitdown[all]'

# 或只安裝需要的格式支援，減少相依套件
pip install 'markitdown[pdf,docx,pptx]'

可以選擇安裝的模組包含：[all]、[pdf]、[docx]、[pptx]、[xlsx]、[xls]、[outlook]、[az-doc-intel]、[audio-transcription]、[youtube-transcription]。如果只是處理 PDF 和 Office 文件，不需要裝全部，可以減少安裝時間與磁碟空間。

建議使用虛擬環境來隔離套件：

# 建立虛擬環境
python -m venv .venv
source .venv/bin/activate  # macOS / Linux
# .venv\Scripts\activate   # Windows

# 在虛擬環境中安裝
pip install 'markitdown[all]'

CLI 命令列使用

安裝完成後，MarkItDown 會提供 markitdown 命令，可以直接在終端機使用。

基本轉換

# 轉換 PDF，結果輸出到終端機
markitdown report.pdf

# 轉換並儲存到檔案（使用 -o 參數）
markitdown report.pdf -o report.md

# 也可以用重導向儲存
markitdown presentation.pptx > presentation.md

透過 pipe 輸入

MarkItDown 也支援標準輸入，可以跟其他指令串接：

# 透過 pipe 輸入檔案（二進位格式需要用 -x 提示副檔名）
cat document.pdf | markitdown -x .pdf

# 搭配 curl 直接轉換網路上的檔案
curl -s https://example.com/report.xlsx | markitdown -x .xlsx > report.md

批次轉換

如果有一整個資料夾的文件需要轉換，可以用簡單的 shell 腳本：

# 把資料夾內所有 PDF 轉成 Markdown
for f in documents/*.pdf; do
  markitdown "$f" -o "${f%.pdf}.md"
done

# 轉換多種格式
for f in documents/*.{pdf,docx,pptx,xlsx}; do
  [ -f "$f" ] && markitdown "$f" -o "${f%.*}.md"
done

Python API 使用

除了 CLI，MarkItDown 也提供 Python API，方便整合到自己的程式或 pipeline 中。

基本用法

from markitdown import MarkItDown

# 建立轉換器實例
md = MarkItDown()

# 轉換檔案
result = md.convert("report.pdf")

# 取得 Markdown 文字
print(result.text_content)

就這麼簡單，三行程式碼就能完成轉換。result.text_content 會回傳轉換後的 Markdown 字串，可以直接拿來用。

批次處理多個檔案

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()

# 把資料夾內所有 PDF 轉成 Markdown
for pdf_file in Path("documents").glob("*.pdf"):
    result = md.convert(str(pdf_file))
    output_path = pdf_file.with_suffix(".md")
    output_path.write_text(result.text_content, encoding="utf-8")
    print(f"已轉換: {pdf_file.name} -> {output_path.name}")

搭配 Azure Document Intelligence

對於結構複雜的 PDF（例如多欄排版、含大量表格），可以搭配 Azure Document Intelligence 來提升解析品質：

from markitdown import MarkItDown

# 使用 Azure Document Intelligence 加強 PDF 解析
md = MarkItDown(docintel_endpoint="https://your-resource.cognitiveservices.azure.com/")
result = md.convert("complex-report.pdf")
print(result.text_content)

需要先在 Azure 建立 Document Intelligence 資源，並設定好認證。這個功能對於掃描文件或排版特殊的 PDF 特別有用。

實測轉換效果

光看 API 不夠直覺，我們實際跑幾個格式來看看轉換出來的效果。

Excel → Markdown 表格

準備一個有標題列的 Excel 檔案，MarkItDown 會自動把工作表名稱轉成標題，資料轉成 Markdown 表格：

## 銷售數據
| 產品 | 數量 | 單價 | 總額 |
| --- | --- | --- | --- |
| 筆記型電腦 | 15 | 32000 | 480000 |
| 滑鼠 | 120 | 350 | 42000 |
| 鍵盤 | 80 | 1200 | 96000 |
| 螢幕 | 25 | 8500 | 212500 |

工作表名稱「銷售數據」直接變成了 ## 標題，第一列自動被識別為表頭。如果 Excel 有多個工作表，每個都會轉成獨立的區塊。

HTML → Markdown

HTML 的轉換效果最好，標題、表格、段落、連結都能精準對應到 Markdown：

# 2026 年 AI 程式助手比較

以下是目前主流的 AI 程式開發助手的比較：

| 工具 | 開發者 | 特色 |
| --- | --- | --- |
| Claude Code | Anthropic | CLI 為主，深度理解程式碼 |
| GitHub Copilot | GitHub/Microsoft | IDE 整合最廣泛 |
| Cursor | Cursor Inc. | 專屬 IDE，AI-first 設計 |

## 結論

每個工具都有自己的優勢，選擇適合自己工作流程的最重要。

Word (.docx) → Markdown

Word 文件的標題層級、列表、表格都能正確轉換。實測一份包含標題、項目符號列表和表格的 Word 文件：

MarkItDown 測試報告

# 第一章：功能介紹

MarkItDown 支援多種檔案格式轉換，包含：

* PDF 文件
* Word 文件
* Excel 試算表

# 第二章：使用方式

可以透過 CLI 或 Python API 來使用。

|  |  |
| --- | --- |
| 方式 | 適用情境 |
| CLI | 快速轉換單個檔案 |
| Python API | 整合到程式中批次處理 |

可以注意到表格的表頭辨識不如 Excel 精準——Word 的表格沒有明確的「表頭」概念，所以第一列會被當成一般資料列，表頭顯示為空。整體來說結構保留得很完整。

PowerPoint (.pptx) → Markdown

每張投影片會標註頁碼，標題變成 # 一級標題：

<!-- Slide number: 1 -->
# MarkItDown 簡介
微軟開源的文件轉換工具

<!-- Slide number: 2 -->
# 支援格式
PDF
Word
Excel
PowerPoint
HTML
圖片
音訊

投影片的文字內容都有保留，但排版和視覺效果當然就沒了——畢竟 Markdown 本來就不是拿來做簡報的。這個輸出格式很適合讓 LLM 理解簡報在講什麼。

ZIP 自動展開

把多個檔案打包成 ZIP 丟給 MarkItDown，它會自動展開並逐一轉換，每個檔案用 ## File: 標記：

Content from the zip file `test-bundle.zip`:

## File: sales.xlsx

## 銷售數據
| 產品 | 數量 | 單價 | 總額 |
| --- | --- | --- | --- |
| 筆記型電腦 | 15 | 32000 | 480000 |
...

## File: ai-tools.html

# 2026 年 AI 程式助手比較
...

## File: data.csv

| 日期 | 溫度(°C) | 濕度(%) | 天氣 |
| --- | --- | --- | --- |
...

這個功能非常實用。把一整包文件丟進去，一次就能全部轉完。

幾個要注意的地方

實測下來有幾個值得注意的行為：

  • JSON 和 XML 基本上是原樣輸出，不會轉成 Markdown 結構。這合理，因為這些格式本身就是結構化的文字，LLM 可以直接讀。
  • 圖片不搭配 LLM 時，如果圖片沒有 EXIF 元資料，轉換結果會是空的。要讓圖片有輸出，需要傳入 llm_client 讓模型描述圖片內容。
  • YouTube 字幕擷取不太穩定，可能會因為 YouTube 的反爬機制而失敗，回傳的是網頁 HTML 而不是字幕內容。
  • pipe 輸入二進位格式（如 PDF、Excel）時，建議加上 -x .xlsx 參數提示副檔名，否則 MarkItDown 可能無法正確辨識格式。

進階功能：LLM 圖片描述與 OCR

MarkItDown 可以搭配 LLM 來處理圖片，讓轉換結果包含圖片的文字描述，這對建立完整的知識庫非常有幫助。

用 LLM 描述圖片內容

from markitdown import MarkItDown
from openai import OpenAI

# 建立 OpenAI client
client = OpenAI()

# 傳入 LLM client，MarkItDown 會自動用它來描述圖片
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o"
)

# 轉換圖片檔，會得到 LLM 產生的圖片描述
result = md.convert("architecture-diagram.png")
print(result.text_content)

這裡傳入的 llm_client 使用的是 OpenAI SDK 的介面，任何相容 OpenAI API 的服務都可以用，包括 Azure OpenAI。也可以透過 llm_prompt 參數自訂描述圖片時的提示詞。

OCR 辨識文件中的圖片文字

安裝 markitdown-ocr plugin 後，可以對 PDF、Word、PowerPoint、Excel 文件中嵌入的圖片進行 OCR，擷取圖片裡的文字：

from markitdown import MarkItDown
from openai import OpenAI

# 啟用 plugin 並搭配 LLM vision 能力做 OCR
md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)

# 轉換含有圖片的 PDF，圖片中的文字也會被辨識出來
result = md.convert("scanned-document.pdf")
print(result.text_content)

這個功能對於處理掃描文件、含有截圖的簡報特別實用。

Docker 使用

如果不想在本機安裝 Python 環境，也可以透過 Docker 來使用：

# 建立 Docker image
docker build -t markitdown:latest .

# 轉換檔案（透過標準輸入輸出）
docker run --rm -i markitdown:latest < report.pdf > report.md

Docker 方式適合在 CI/CD pipeline 中使用，或是團隊成員不想各自設定 Python 環境的情況。

實際應用場景

MarkItDown 在 AI 開發流程中有幾個常見的應用場景：

RAG 知識庫建立

建立 RAG 系統時，最費工的步驟之一就是把企業內部的文件轉成可被向量化的文字。MarkItDown 可以一次處理整個文件資料夾，轉出來的 Markdown 保留了原始結構，切 chunk 的時候可以根據標題層級來分段，效果比純文字好很多。

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()

# 把公司內部文件全部轉成 Markdown
knowledge_base = []
for doc in Path("company-docs").rglob("*.*"):
    if doc.suffix in [".pdf", ".docx", ".pptx", ".xlsx"]:
        result = md.convert(str(doc))
        knowledge_base.append({
            "source": doc.name,
            "content": result.text_content
        })

# 接下來就能把 knowledge_base 丟給 embedding model 做向量化

文件分析與摘要

想用 LLM 分析一份報告或合約？先用 MarkItDown 轉成 Markdown，再丟給模型處理：

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown()
client = OpenAI()

# 轉換文件
result = md.convert("quarterly-report.pdf")

# 用 LLM 做摘要
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "請用繁體中文摘要以下文件的重點。"},
        {"role": "user", "content": result.text_content}
    ]
)
print(response.choices[0].message.content)

MCP Server 整合

MarkItDown 也有社群開發的 MCP Server ，可以讓 Claude Desktop、Cursor 等支援 MCP 的 AI 工具直接呼叫 MarkItDown 來轉換文件，不需要自己寫程式碼。

Plugin 擴充系統

MarkItDown 提供了 plugin 系統，讓開發者可以擴充支援的格式或加入自訂的轉換邏輯。預設 plugin 是關閉的，需要手動啟用：

from markitdown import MarkItDown

# 啟用所有已安裝的 plugin
md = MarkItDown(enable_plugins=True)
result = md.convert("special-format.xyz")

CLI 也可以管理 plugin：

# 列出已安裝的 plugin
markitdown --list-plugins

# 啟用 plugin 進行轉換
markitdown --use-plugins document.pdf

目前官方提供的 plugin 包括 markitdown-ocr（前面提到的 OCR 功能），如果想開發自己的 plugin，可以參考 GitHub 上的 markitdown-sample-plugin 範例。

小結

MarkItDown 解決了 AI 開發流程中一個很基本但很重要的問題：把非結構化的文件變成 LLM 能理解的格式。安裝簡單、API 直覺、支援的格式涵蓋大部分常見的辦公文件，加上 OCR 和 LLM 圖片描述等進階功能，不管是快速做個文件轉換，還是建立完整的 RAG pipeline，MarkItDown 都是值得放進工具箱的選項。

GitHub 倉庫： microsoft/markitdown

Post Views: 130
Tags:

發佈留言