如何將 PDF 和 Word 檔案轉成 AI 可用的文字：Microsoft 的 MarkItDown

更多操作說明請見 Ailoot 文件。

MarkItDown 是什麼？可以用來做什麼？#

你把合約、報告或會計資料匯出檔交給 AI，得到的回答卻和文件毫無關係。原因通常不在模型，而在於檔案本身有格式：Word 是包含標記的封存檔，Excel 是儲存格彼此連結的試算表，PDF 則是帶有頁面座標的一組字元。模型處理的是文字，因此必須有人先把文字取出來。

這就是 MarkItDown 的用途。儲存庫位於 github.com/microsoft/markitdown，採用 MIT 授權，因此可以不受限制地使用。截至 2026 年 8 月 18 日，它有 174,412 顆星和 12,756 個分支；最新版本 0.1.7 於 7 月 29 日發布。專案仍持續維護，但重心已從開發轉向維護：目前有 481 個尚未處理的提取要求，相較之下，整段歷史中合併的提取要求共 183 個。

開發者如此描述這個專案的用途：

說明中的下一句話，解釋了人們對這個工具抱怨的原因有一半：

輸出是提供給模型的原始材料，不會是一份漂亮的文件。專案在第一個章節就清楚說明了這一點。

說明也直接回答了為什麼使用 Markdown：主流模型早已「會說」這種標記語言，甚至會在沒有要求的情況下把它放進回答，因為它們在訓練時看過大量 Markdown。這種標記也很精簡：標題只需三個井字號，不必用十幾行中繼資料來描述。

MarkItDown 和一般轉換器有什麼不同？#

用一個例子就能看出差異。假設有個資料夾裝了 20 份 PDF，試著用 pandoc 處理看看。行不通：pandoc 可以輸出 PDF，卻無法讀取 PDF。最常見的情境正是「我有一堆文件，請交給模型處理」。

MarkItDown 作者拿自己和 textract 這個函式庫比較。textract 只會從各種來源擷取文字；MarkItDown 的不同之處，在於它會試著保留標題、清單、表格和連結等結構。

實際結論很簡單：如果要把文章轉成可供出版的版面，請用 pandoc；如果要讓 AI 理解 20 份合約，請用 MarkItDown。

如何安裝 MarkItDown，避免裝到最早期版本？#

先給出正確指令，再說明為什麼要這樣做。

1. 確認 Python 版本

   Python 3.12 最可靠：在所有經過測試的環境中，都能安裝最新版 MarkItDown。執行 python3 --version 即可查看目前版本。在 Intel Mac 或搭載舊版 macOS 的 Mac 上，Python 3.13 和 3.14 可能會悄悄降級；Python 3.15 尚未支援，原因如下文所述。

2. 列出需要的格式後安裝

   執行 pip install 'markitdown[pdf,docx,xlsx,pptx]'。引號不可省略，否則 shell 會解讀方括號。在 Intel Mac 上，請在 install 後加上 --prefer-binary 旗標。

3. 安裝後立即檢查

   執行 markitdown --version。回應應為 markitdown 0.1.8 或更新版本。若版本號更低，代表安裝時發生降級；本節會解釋原因。

pip install 'markitdown[pdf,docx,xlsx,pptx]'
markitdown --version

專案說明列出的主要指令是 pip install 'markitdown[all]'，可一次安裝所有內容。2026 年 9 月 28 日，也就是 0.1.8 發布一週後，我們在 Apple Silicon Mac 上使用 Python 3.14.6 和 3.12.12，於全新環境測試了 4 種指令：

8 次安裝都以「Successfully installed」結束，而且每次執行 markitdown --version 都回傳 0.1.8。8 月時，最新版仍是 0.1.7，在 Python 3.14 執行第三個指令卻安裝了 0.0.2。這個版本發布於 2025 年 3 月 8 日，是專案歷史上的第二個版本。目前共有 11 個穩定版本，從 0.0.1 到 0.1.8；若包含預先發布版本，則共有 26 個。

問題出在相依套件鏈。0.1.7 的 [all] 選項會安裝某個特定版本系列的 YouTube 字幕函式庫，而該系列的所有版本都聲明不支援 Python 3.14。安裝程式拒絕這些版本；由於 MarkItDown 沒有固定版本，它便一路往前回溯，直到找到可安裝的版本。最後找到並安裝 0.0.2，讓你電腦上裝的是一年半以前的版本。0.1.8 將字幕函式庫的需求提高到支援 3.14 的版本系列，因此降級問題在該處停止。

這套機制仍然存在。如果安裝程式找不到系統需要的某個元件，就會以相同方式悄悄退回 0.0.2。近期版本中，這個元件是用來偵測檔案類型的 onnxruntime 引擎。在 Mac 上，它的建置支援條件如下：Python 3.12 需要 macOS 11 或更新版本；3.13 需要 macOS 13；3.14 則只支援使用 macOS 14 或更新版本的 Apple Silicon。如果你的 Mac 不符合條件，即使只執行 pip install markitdown，也會安裝 0.0.2。在一台透過 Rosetta 執行 Python 3.14 的 Intel Mac 上測試時，結果完全如此：「Successfully installed」，沒有警告，實際安裝的是 0.0.2。

Intel Mac 還有另一個問題。自 2026 年 6 月起，用於讀取 PDF 的 cryptography 函式庫發布時不再提供這款處理器的預先建置版本，因此安裝程式會嘗試從原始碼建置。把 --prefer-binary 旗標加到指令中，便會改用有預先建置套件的舊版本。在 Intel 電腦的 Python 3.13 上測試時，這樣安裝的是 0.1.8，PDF 也能開啟。這個旗標會安裝 cryptography 48.0.1，它有 3 個已知漏洞，涉及 PKCS#7 解密和憑證鏈驗證。MarkItDown 只在解密加密 PDF 時使用它，讀取一般文件不會執行到這些部分。

Python 3.15 會因為兩個原因而降級。0.1.8 僅聲明支援 3.10 到 3.14，而且目前還沒有支援 3.15 的引擎。安裝程式在 3.15 上的解析結果也證實這點：基本指令和指定格式的指令都會安裝同一個 0.0.2。

發生降級時，指令中每個額外選項都會出現一行警告：

WARNING: markitdown 0.0.2 does not provide the extra 'all'

這行訊息會淹沒在幾十行下載資訊中，而且沒有說明被替換成哪個版本。若使用不含額外選項的基本指令，甚至連警告都沒有。最後只會愉快地顯示「Successfully installed」。

不加額外選項也不是解決方法。基本套件雖然會安裝，卻無法開啟 PDF：

PdfConverter recognized the input as a potential .pdf file, but the
dependencies needed to read .pdf files have not been installed. To resolve
this error, include the optional dependency [pdf] or [all] when installing
MarkItDown. For example:

* pip install 'markitdown[pdf]'
* pip install 'markitdown[all]'

工具本身建議使用 [all]，而在 0.1.8 中，這個建議於 Python 3.14 和 3.12 又能正常使用。不過，最好還是明確列出需要的格式：[all] 會多安裝約 15 個套件、約 55 MB，其中包括一個預先發布的 Azure 函式庫，以及曾讓安裝失敗的那條 YouTube 相依鏈。

安裝程式會自行處理 Azure 預先發布版本。pip 通常會略過預先發布版本，但這裡的需求明確指定了預先發布版本，因此 pip 會安裝它。我們在 Python 3.12 上測試了 4 個 pip 版本，從 23.2 到 26.2，全部都選擇了 0.1.8。

8 月時，我在另一個全新環境重新安裝，結果仍然相同：0.0.2，以及「Successfully」。

有幾個實用細節值得事先了解。

它相當龐大：基本安裝需要 143 MB；指定 4 種格式則需要 303 MB。最大元件是 81 MB 的檔案類型偵測器，連基本安裝也會包含它。對筆記型電腦來說不成問題，但對有大小限制的雲端函式就很重要。

不要把鏡像站當成備援。測試過的鏡像站有提供索引，也有 MarkItDown 檔案，但缺少一個必要相依套件，因此在 Python 3.14 和 3.12 上都安裝失敗。

安裝只是小問題，真正的問題大得多。AI 更常產生胡言亂語，是因為放進上下文視窗的是錯誤資訊，或資訊的表達方式不對。任務開始前決定要提供給模型哪些資訊，稱為上下文工程；文件整理也是其中一環。

如何把第一份文件轉成文字？#

最簡單的方式：

markitdown dogovor.docx

文字會印在終端機中。存成檔案有兩種方式：

markitdown dogovor.docx -o dogovor.md
markitdown dogovor.docx > dogovor.md

在 Mac 和 Linux 上差異不大，但在 Windows 上就很重要：如果輸出包含西里爾字母，使用 > 重新導向可能會讓程式崩潰。

也可以把檔案作為資料流傳入；此時指定副檔名提示會很有幫助：

cat dogovor.docx | markitdown -x docx

以下是 0.1.8 說明文件中的主要旗標：

相同的說明文件還列出 3 個經過測試的實用旗標：--list-plugins 顯示已安裝的外掛，-p 可在特定執行時啟用外掛，--keep-data-uris 則會在輸出中保留嵌入文件的圖片（預設會裁切）。其餘設定都與 Microsoft 的雲端服務有關。

Python 包裝程式只有 3 行：

from markitdown import MarkItDown

md = MarkItDown()
print(md.convert("ostatki.xlsx").text_content)

相同呼叫也接受網址。簡單的網頁回傳了 167 個字元的乾淨文字，包含標題和連結，不含選單和頁尾：

r = md.convert("https://example.com")

MarkItDown 能讀取哪些格式？實際上又代表什麼？#

以下整理宣稱支援的格式，以及實際狀況。

以下詳細說明 3 項。

圖片。專案說明中有 OCR 一詞，因此有人會以為程式可以讀取照片中的文字。它做不到。它會透過另一個程式 exiftool 讀取中繼資料；如果你用自己的金鑰連接視覺模型，它也可以把圖片傳給模型產生描述。

音訊。它支援語音轉錄，但不會傳入語言資訊，而且引擎預設以英文為主。它也會呼叫 Google 非官方的免費端點，每個金鑰每天約只能提出 50 次請求。

封存檔。程式會解開 ZIP 檔並逐一處理檔案，再把結果串接起來。如果無法解析某個檔案，錯誤會被捕捉並忽略。該檔案不會出現在結果中，你也不會知道它曾經被略過。

含有西里爾字母的文件會怎麼樣？#

以下檔案是專為測試而建立，資料都是虛構的。

Excel 庫存表也同樣乾淨地轉換完成，工作表名稱成為標題：

## Stock
| Item | In stock | Reserved | Available |
| --- | --- | --- | --- |
| Coffee beans, kg | 420 | 38 | 382 |
| Loose-leaf tea, kg | 180 | 52 | 128 |

簡報也轉成了文字，投影片編號以註記顯示，投影片標題則變成標題。這裡的西里爾文字也完整無缺。「MarkItDown 不懂西里爾字母」這種一概而論的說法是錯的。

接著來看 3 個確實會出問題的地方。

使用分號的 CSV。我們拿兩份內容相同的發票匯出檔進行比較。使用逗號的檔案產生了正確的 4 欄表格；使用分號的檔案則把整行內容放進同一個儲存格。

整行文字都進到同一個儲存格。編碼辨識正確，也沒有任何錯誤；-c 旗標也無法解決。模型收到這張表後，無法判斷哪個值是金額、哪個是狀態。保留原檔，以明確的逗號分隔與正確編碼重新匯出。不要全面替換分號：引號文字中的分隔字元與小數逗號可能是值的一部分。若不能重新匯出，請依實際分隔符解析原檔，再用理解 CSV 的寫入器產生新檔，保留引號與儲存格值。分析前核對來源與新檔的欄數、列數及核對總額。

Excel 貨幣格式。貨幣符號儲存在儲存格的顯示設定中，不會成為儲存格值的一部分。專案維護者已確認原因。對價目表或發票而言，這很重要：模型看到的是數字，卻不知道它們代表哪種貨幣。

Windows 主控台。含非拉丁字元的檔案可能會造成程式崩潰。

錯誤追蹤顯示 cp1251 編碼，表示問題出在 Windows 主控台。文件本身解析正確；失敗的是把結果印到終端機視窗的步驟。以下有兩種替代做法：

markitdown dogovor.docx -o dogovor.md
$env:PYTHONUTF8 = "1"; markitdown dogovor.docx > dogovor.md

第一種做法完全避開主控台；第二種則讓 Python 使用 UTF-8 寫入。至少有 6 次有人提交修正此工具問題的提案：有些提案在未合併的情況下關閉，其餘仍未處理，因此只能自行繞過問題。

PDF 還會出現第四種症狀：字母被 (cid:1090) 這類字串取代。這表示檔案使用非標準字型表，字元無法解碼。用 MarkItDown 處理這種文件沒有意義；你需要改用其他工具。

為什麼 PDF 會變得一團混亂？#

測試使用一篇大小為 2.16 MB 的雙欄科學論文。結束代碼是 0；0.9 秒後，輸出包含 88,000 個字元，幾乎全是亂碼。88,000 個字元看起來像是一切正常，直到你打開檔案：

|     | Hybrid |          | OCR-LLM     |     | Framework  |
| --- | ------ | -------- | ----------- | --- | ---------- |
...
Informationextractionfromcopy-heavydoc-
5202 tcO 11  ]LC.sc[  1v83101.0152:viXra

一次發生了 3 種問題。雙欄版面變成論文中不存在的表格；單字之間沒有空格，全都連在一起；最後一行則是頁面上的直立側欄，並且被倒著擷取。

接下來的情況更有趣。測試論文本身竟然就是那篇評測 MarkItDown 並與其他工具比較的研究。工具把報告自己測試結果的段落轉換成了這樣：

cues. This name-matching error could be miti-  OCRpreprocessingoverhead(0.056s),whileDo-
gatedthroughpromptengineeringtoprovidemore  clingandMinerUadoptmorecomputationallyin-
explicit matching instructions or fine-tuning the  tensive strategies with OCR latencies of approxi-

左右兩欄逐行交錯。模型讀到這種文字，就會把某個段落的半句和另一個段落的半句接在一起。

原因在技術上很簡單。Word 會明確儲存「這是標題」和「這是表格儲存格」。PDF 儲存的則是「這是一個字元」和「它在頁面上的這個座標」。從座標重建結構是另一項困難的工作，而 MarkItDown 幾乎沒有嘗試。PDF 解析原始碼中沒有標題偵測功能：如果頁面未被辨識為表單或表格，整份文件就會採用基本文字擷取方式處理。

使用者經常在專案的儲存庫中回報這個問題，包括科學論文和表格。

正如原始碼所示，這個工具在 PDF 中找不到任何標題。

「MarkItDown 的準確率達 82%」這個數字在網路上流傳，卻沒有任何方法說明。追查原始來源也找不到結果：連結鏈的最後一頁無法載入。因此不能把它當成測量數據。

掃描的合約會怎麼樣？#

這種行為比其他問題更危險，因為看起來不像失敗。

測試時，我們用含有文字的圖片製作 PDF，也就是拍照或掃描合約時會得到的檔案。為了排除偶然情況，重複執行了兩次：

連續兩次都是 0 個字元、0 個錯誤。結束代碼 0 代表「一切順利」，任何以結束代碼判斷成功的指令碼都會把這份文件算作已完成處理。接著，空白輸出會送進模型；模型什麼也看不到，就開始憑空編造回答。

有兩種替代方法，而且都需要付費。第一種是使用 -d 旗標，把文件傳送到 Microsoft 的雲端辨識服務；旗標說明明確指出必須提供有效的服務端點。第二種是使用另一個附加套件，以你的金鑰把頁面傳送給視覺模型，因此每頁都要向模型供應商付費。自 2026 年 4 月起，關於第二種方法的公開討論指出，多頁掃描文件只有第一頁會被處理。

你也可以在自己的電腦上執行文字辨識模型，但那是另一個專案。

只有一份文件時，直接開啟並手動複製文字比較簡單。若要連續處理大量掃描檔，就需要內建文字辨識功能的工具。

直接把檔案上傳到線上轉換器可以嗎？#

「MarkItDown online」是最常見的搜尋建議之一，確實也有網站提供這項服務。Microsoft 原版工具完全沒有網站，只能自行安裝為程式使用。任何在瀏覽器中開啟、名稱相似的工具，都是其他人製作的。

你可以在一分鐘內檢查這類服務：在開發人員工具中開啟網路要求分頁，上傳任何無害檔案，看看它是否傳到伺服器。如果有，無論 FAQ 多麼信誓旦旦地聲稱在瀏覽器中處理，這項說法都是假的。

這就是 MarkItDown 在不能把文件傳出組織的情況下受到重視的原因。有一則討論提到，有人的工作筆電禁止安裝任意程式，卻允許使用 Python 函式庫，因此本機工具成了唯一可用的選項。

MarkItDown 實際上能節省多少？#

Office 檔案是包含標記的封存檔。解開 3 個測試檔案，比較包含內容部分的大小和輸出大小，可得到以下結果：

這些檔案都很小；較大的檔案比例會不同，不存在一個通用的節省數字。看到比較文章列出整數時，請先問清楚測量方法。

開發者自己也提到節省空間：專案說明特別指出，Markdown 慣例在字元數方面非常精簡。這的確沒錯，但不應該是主要賣點。「模型收到 3,000 個字元，而不是 15,000 個」和「模型收到清楚的結構，而不是一團混亂」是不同層次的差異。前者節省費用；後者決定回答是否有道理。

如果你在意上下文用量，可另見Claude 的 token 用在哪裡和各方案包含多少 token。

如何透過 MCP 將 MarkItDown 連接至 Claude？#

MCP 是一種提供外部工具給 AI 自行使用的方式。關於這套機制和其他伺服器的概覽，請參閱 Claude Code 的 MCP 伺服器評測。

MarkItDown 伺服器只提供一種工具：將文件轉成文字。它接受本機檔案路徑、網頁 URL，或直接嵌入要求中的資料。

只要一個指令，就能讓 Claude Code 連上固定版本的伺服器。你需要 uv 套件管理器：

claude mcp add --scope user --env 'ORT_DISABLE_TELEMETRY=1' --env 'UV_PYTHON=3.12' --transport stdio markitdown -- uvx markitdown-mcp@0.0.1a7
claude mcp list

執行第二個指令後，markitdown 應顯示「Connected」。第一次啟動時會下載約 70 個套件，最多需要一分鐘；之後伺服器會在 1 到 1.5 秒內啟動。

以下注意事項均經人工逐一確認。

0.0.1a7 建置版本於 2026 年 9 月 14 日發布。在此之前，伺服器一年多來一直停留在 2025 年 5 月發布的 0.0.1a4。最新版仍是預先發布版本。

使用較新版 Python 的系統不一定都能安裝。它所依賴的 onnxruntime 引擎在 Python 3.14 上，只有搭載 macOS 14 或更新版本的 Apple Silicon Mac 才能使用，因此 Python 3.14 在 Intel Mac 和 macOS 13 或更舊版本上都會安裝失敗。我們在 Apple Silicon Mac 上使用 Python 3.14、3.13 和 3.12 執行伺服器，3 個版本都成功安裝。指令指定 UV_PYTHON=3.12，因為 Windows、Linux 和 Apple Silicon Mac 都有 3.12 的預先建置套件；若你沒有這個 Python 版本，uv 會自行下載。Intel Mac 也有另一個問題：自 2026 年 6 月起，Intel 已沒有 cryptography 的預先建置套件，uv 會從原始碼建置該函式庫。安裝時間較長，也可能失敗。

實際安裝的 MarkItDown 版本取決於 uv 的版本。從 MarkItDown 0.1.6 起，[all] 選項需要預先發布的 Azure 函式庫；uv 0.12 及更新版本會安裝該函式庫和最新版 MarkItDown 0.1.8，較舊的 uv 則會降級到 0.1.5。請執行 uv --version 查看 uv 版本。

有兩種資料會傳出電腦。第一種是遙測資料：在 Mac 和 Linux 上，伺服器內的 onnxruntime 引擎預設會將資料傳送給 Microsoft。指令中的 ORT_DISABLE_TELEMETRY=1 變數可將它停用。在測試中，未設定此變數時，伺服器會連線至 Microsoft 的遙測端點；設定後，處理磁碟中的檔案期間完全沒有任何連線。

第二種是音訊。伺服器會透過未加密的一般 HTTP，將 WAV、MP3、M4A 和 MP4 檔案傳送到 Google 的語音辨識服務進行轉錄。最好不要把與客戶交談的錄音傳給它。

大型文件無法透過它處理。一則尚未解決的討論指出，伺服器回應達到 51,000 個 token，超過 25,000 個 token 的上限；而工具不會把檔案拆成區塊。

還有安全性問題。套件自己的文件明確寫道：

換句話說，擁有此工具的代理程式可以讀取你能讀取的一切。在自己的電腦上工作時，這可以接受；你不可公開此伺服器，也不可交給不受信任的代理程式。

日常工作中，直接用指令執行程式，再把產生的文字放進專案會更簡單。如此一來，檔案會和其他資料放在一起，模型可以自行參考。

何時改用其他工具才比較恰當？#

依工作類型比較，和 GitHub 星數無關：

比較文章常略過一項關於 Marker 的細節。自 2026 年 7 月起，程式碼本身採寬鬆授權，但模型權重另採一份授權，並設有門檻：如果公司前一年的營收沒有超過 500 萬美元，而且籌得的資金也沒有超過同樣金額，就能免費使用。另一條款禁止任何正在開發競爭產品的人使用。這對大多數讀者沒有影響，但正在成長的企業採用前應先閱讀授權。

實際上可採用以下 4 個步驟：

1. 先全部交給 MarkItDown 處理，免費又迅速。
2. 開啟結果並檢查大小。
3. 如果文字看得懂，工作就完成了，不需要其他處理。
4. 如果輸出混亂或空白，再用較大型的工具處理那份特定檔案。

這樣只有真正需要的文件才會耗費更多時間和增加複雜度。

如何把 MarkItDown 整合進工作流程？#

Anthropic 在自家的 Office 檔案處理預設技能中使用 MarkItDown，並清楚說明了你也應完整採用的界線：

文字會失去儲存格和頁面參照，因此你不能用它修改來源檔案。以下是 3 種使用情境。

批次處理相似文件，例如驗收紀錄、發票、表單、申請書。把它們放進資料夾，再用一行指令處理：

for f in dokumenty/*.docx; do markitdown "$f" -o "text/$(basename "$f" .docx).md"; done

接著把文字檔資料夾交給模型，請它整理相關資訊並製成表格。這適用於數位檔案；掃描檔會失敗，而你會立刻從檔案大小為 0 發現問題。

常用專案資料，例如價目表、合約範本、政策、服務說明，可先轉成文字一次，放在專案旁邊。模型之後每次收到要求都能讀取，因此不必每次在對話中附上檔案。將檔案上傳至 Claude的文章解釋了這種方式和上傳檔案到聊天中的差異。

會計系統匯出檔。會計軟體或銀行帳戶匯出的 Excel 檔，可以在三分之一秒內轉成表格，模型也能直接計算，不必經過中間處理。請確認 CSV 以實際分隔符、引號規則與編碼匯出或解析，交給模型前核對列數、欄數與核對總額，不可用搜尋取代正規化分隔符。也要明確記錄幣別，只有 Excel 儲存格格式中的貨幣符號不會保留到擷取文字。

在終端機處理大型 PDF 不在此列。這是上下文用量相關的另一個問題，詳見在 Claude Code 中處理 PDF 而不浪費 token。如果你剛開始設定工作環境，請從安裝 Claude Code開始。

現在就開始的話，執行 pip install 'markitdown[pdf,docx,xlsx,pptx]'，處理第一份找到的 Word 合約，並檢查結果大小。只要半分鐘，你就會知道它是否適用於你的檔案。

準備好後，認識 Ailoot。