# 如何將 PDF 和 Word 檔案轉成 AI 可用的文字：Microsoft 的 MarkItDown > 深入評測：如何將 PDF 和 Word 檔案轉成 AI 可用的文字：Microsoft 的 MarkItDown。 Source: https://ailoot.ai/blog/zh-hant-tw/markitdown-pdf-word-to-text/ Canonical: https://ailoot.ai/blog/zh-hant-tw/markitdown-pdf-word-to-text/ Language: zh-Hant-TW Publisher: Ailoot (https://ailoot.ai/) Translation: guide-171 Revision: sha256-b1f4c6744f1a574e61ad8dfe6a3f2d83e43410748dcd61893c1d75e8a315c606
重點摘要 MarkItDown 是 Microsoft 推出的免費工具，可將 Word、Excel、簡報和 PDF 轉成 AI 可用的結構化文字。它能在不到一秒的時間內妥善解析 Office 檔案。遇到版面複雜的 PDF，輸出會一團混亂；遇到掃描檔，則會回傳空檔案，結束代碼卻是 0。下文提供可用的安裝指令、以含西里爾字母的文件進行測試的結果，以及何時應改用其他工具的判斷原則。
更多操作說明請見 [Ailoot 文件](https://ailoot.ai/docs/)。 ## MarkItDown 是什麼？可以用來做什麼？
重點摘要 MarkItDown 是 Microsoft 推出的 Python 工具，可讀取檔案並以結構化文字回傳內容。標題會成為標題，表格也會保留為表格。它以 MIT 授權發布於公開的 GitHub 儲存庫，只要一個指令就能安裝，而且所有處理都在你的電腦上完成。它只有一項工作：整理文件，讓 AI 不只能看到文字，也能辨認文件結構。
你把合約、報告或會計資料匯出檔交給 AI，得到的回答卻和文件毫無關係。原因通常不在模型，而在於檔案本身有格式：Word 是包含標記的封存檔，Excel 是儲存格彼此連結的試算表，PDF 則是帶有頁面座標的一組字元。模型處理的是文字，因此必須有人先把文字取出來。 這就是 MarkItDown 的用途。儲存庫位於 [github.com/microsoft/markitdown](https://github.com/microsoft/markitdown)，採用 MIT 授權，因此可以不受限制地使用。截至 2026 年 8 月 18 日，它有 174,412 顆星和 12,756 個分支；最新版本 0.1.7 於 7 月 29 日發布。專案仍持續維護，但重心已從開發轉向維護：目前有 481 個尚未處理的提取要求，相較之下，整段歷史中合併的提取要求共 183 個。 開發者如此描述這個專案的用途：

MarkItDown 是一款輕量級 Python 工具，可將各種格式的檔案轉換為 Markdown，供大型語言模型及相關文字分析流程使用。

— Microsoft，專案說明（譯文），https://github.com/microsoft/markitdown
說明中的下一句話，解釋了人們對這個工具抱怨的原因有一半：

雖然輸出通常相當整潔，也方便人閱讀，但它的設計目的是供文字分析工具使用，未必適合忠實轉換以供人閱讀的文件。

— Microsoft，專案說明（譯文），https://github.com/microsoft/markitdown
輸出是提供給模型的原始材料，不會是一份漂亮的文件。專案在第一個章節就清楚說明了這一點。 說明也直接回答了為什麼使用 Markdown：主流模型早已「會說」這種標記語言，甚至會在沒有要求的情況下把它放進回答，因為它們在訓練時看過大量 Markdown。這種標記也很精簡：標題只需三個井字號，不必用十幾行中繼資料來描述。 ## MarkItDown 和一般轉換器有什麼不同？
重點摘要 pandoc 等轉換器會把一種標記語言轉成另一種，並保留適合人閱讀的版面。pandoc 完全不接受 PDF 作為輸入。MarkItDown 解決的是相反的問題：從 Office 檔案擷取內容，整理成模型能立即理解的形式，不浪費 token。保留視覺版面不是它的目標，這就是兩者的根本差異。
用一個例子就能看出差異。假設有個資料夾裝了 20 份 PDF，試著用 pandoc 處理看看。行不通：[pandoc](https://pandoc.org/) 可以輸出 PDF，卻無法讀取 PDF。最常見的情境正是「我有一堆文件，請交給模型處理」。 MarkItDown 作者拿自己和 textract 這個函式庫比較。textract 只會從各種來源擷取文字；MarkItDown 的不同之處，在於它會試著保留標題、清單、表格和連結等結構。 | 功能 | pandoc | MarkItDown | |----|----|----| | 讀取 PDF | 否 | 是，但有注意事項 | | 讀取 Word、Excel、簡報 | 部分支援 | 是 | | 輸出對象 | 人 | 模型 | | 主要價值 | 版面忠實度 | 結構與較少字元 | | 安裝方式 | 獨立程式 | 一個 Python 指令 | 實際結論很簡單：如果要把文章轉成可供出版的版面，請用 pandoc；如果要讓 AI 理解 20 份合約，請用 MarkItDown。 ## 如何安裝 MarkItDown，避免裝到最早期版本？
重點摘要 在 0.1.8 版中，專案說明裡的指令可在 Python 3.14 和 3.12 安裝最新版，這已在 8 個全新環境中重新確認。不過，在 Python 3.15、使用 3.14 的 Intel Mac，以及搭載較舊 macOS 並使用 3.13 或 3.14 的 Mac 上，仍可能悄悄降級到專案歷史上的第二個版本 0.0.2。這些情況下，安裝程式仍會回報成功。建議使用 Python 3.12、明確列出需要的格式，並立即確認版本號。
先給出正確指令，再說明為什麼要這樣做。 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` 或更新版本。若版本號更低，代表安裝時發生降級；本節會解釋原因。 ```bash 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 種指令： | 指令 | Python 3.14 安裝結果 | Python 3.12 安裝結果 | |----|----|----| | `pip install markitdown` | 0.1.8 | 0.1.8 | | `pip install 'markitdown[pdf,docx,xlsx,pptx]'` | 0.1.8 | 0.1.8 | | `pip install 'markitdown[all]'` | 0.1.8 | 0.1.8 | | `pip install 'markitdown[all]==0.1.8'` | 0.1.8 | 0.1.8 | 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。
注意 安裝後請立即執行 `markitdown --version`。只要 5 秒，卻是確認你確實安裝了所需版本的唯一方法。在這裡，安裝成功的訊息並不代表任何事。
8 月時，我在另一個全新環境重新安裝，結果仍然相同：0.0.2，以及「Successfully」。 有幾個實用細節值得事先了解。 它相當龐大：基本安裝需要 143 MB；指定 4 種格式則需要 303 MB。最大元件是 81 MB 的檔案類型偵測器，連基本安裝也會包含它。對筆記型電腦來說不成問題，但對有大小限制的雲端函式就很重要。 不要把鏡像站當成備援。測試過的鏡像站有提供索引，也有 MarkItDown 檔案，但缺少一個必要相依套件，因此在 Python 3.14 和 3.12 上都安裝失敗。 安裝只是小問題，真正的問題大得多。AI 更常產生胡言亂語，是因為放進上下文視窗的是錯誤資訊，或資訊的表達方式不對。任務開始前決定要提供給模型哪些資訊，稱為上下文工程；文件整理也是其中一環。 ## 如何把第一份文件轉成文字？
重點摘要 在終端機輸入一個指令：程式名稱加上檔案路徑。預設會直接在視窗中印出結果，因此可以立即存成檔案。有 3 種方式：輸出至主控台、使用旗標寫入檔案，或將檔案作為資料流傳入。若要整合到自己的指令碼中，可以使用 3 行的 Python 包裝程式，也支援網址。
最簡單的方式： ```bash markitdown dogovor.docx ``` 文字會印在終端機中。存成檔案有兩種方式： ```bash markitdown dogovor.docx -o dogovor.md markitdown dogovor.docx > dogovor.md ``` 在 Mac 和 Linux 上差異不大，但在 Windows 上就很重要：如果輸出包含西里爾字母，使用 `>` 重新導向可能會讓程式崩潰。 也可以把檔案作為資料流傳入；此時指定副檔名提示會很有幫助： ```bash cat dogovor.docx | markitdown -x docx ``` 以下是 0.1.8 說明文件中的主要旗標： | 旗標 | 功能 | |----|----| | `-o`、`--output` | 將結果寫入檔案，而非印在視窗中 | | `-x`、`--extension` | 以資料流方式傳入檔案時，用來提示副檔名 | | `-m`、`--mime-type` | 內容類型提示 | | `-c`、`--charset` | 字元編碼提示 | | `-d`、`--use-docintel` | 透過 Microsoft 的付費雲端服務處理 | | `-v`、`--version` | 顯示版本 | 相同的說明文件還列出 3 個經過測試的實用旗標：`--list-plugins` 顯示已安裝的外掛，`-p` 可在特定執行時啟用外掛，`--keep-data-uris` 則會在輸出中保留嵌入文件的圖片（預設會裁切）。其餘設定都與 Microsoft 的雲端服務有關。 Python 包裝程式只有 3 行： ```python from markitdown import MarkItDown md = MarkItDown() print(md.convert("ostatki.xlsx").text_content) ``` 相同呼叫也接受網址。簡單的網頁回傳了 167 個字元的乾淨文字，包含標題和連結，不含選單和頁尾： ```python r = md.convert("https://example.com") ``` ## MarkItDown 能讀取哪些格式？實際上又代表什麼？
重點摘要 專案說明列出多種格式：Office 檔案、PDF、圖片、音訊、封存檔、YouTube 連結和電子書。有 3 項的實際運作方式和字面上聽起來不同。免費版本完全沒有圖片文字辨識功能。語音會送到英文語音引擎。無法解析的檔案會從封存檔中消失，而且不會有警告。
以下整理宣稱支援的格式，以及實際狀況。 | 格式 | 宣稱支援 | 實際運作方式 | |----|----|----| | Word、Excel、簡報 | 是 | 運作良好，這是它的強項 | | CSV、JSON、XML、HTML | 是 | 可以運作，但 CSV 有分隔符號陷阱 | | PDF | 是 | 取決於版面：單欄可組合，雙欄會散掉 | | 圖片 | 「中繼資料與辨識」 | 無法辨識，只能讀取中繼資料或使用付費視覺模型 | | 音訊 | 「語音轉錄」 | 會送至 Google 的英文語音引擎 | | ZIP 封存檔 | 「逐一處理內容」 | 無法解析的檔案會悄悄消失 | | YouTube 連結 | 是 | 只接受 `''?...` 形式的完整連結 | | EPUB 電子書 | 是 | 可正常運作 | 以下詳細說明 3 項。 圖片。專案說明中有 OCR 一詞，因此有人會以為程式可以讀取照片中的文字。它做不到。它會透過另一個程式 exiftool 讀取中繼資料；如果你用自己的金鑰連接視覺模型，它也可以把圖片傳給模型產生描述。 音訊。它支援語音轉錄，但不會傳入語言資訊，而且引擎預設以英文為主。它也會呼叫 Google 非官方的免費端點，每個金鑰每天約只能提出 50 次請求。 封存檔。程式會解開 ZIP 檔並逐一處理檔案，再把結果串接起來。如果無法解析某個檔案，錯誤會被捕捉並忽略。該檔案不會出現在結果中，你也不會知道它曾經被略過。 ## 含有西里爾字母的文件會怎麼樣？
重點摘要 我們使用最新版處理了 3 份含西里爾字母的檔案：Word 合約、Excel 庫存表和簡報。3 份檔案中的西里爾文字和數字都完整保留。問題會出現在 3 個地方：使用分號的 CSV、Excel 儲存格的貨幣格式，以及 Windows 主控台輸出。這 3 項都有替代做法。
以下檔案是專為測試而建立，資料都是虛構的。 Excel 庫存表也同樣乾淨地轉換完成，工作表名稱成為標題： ```markdown ## 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 主控台。文件本身解析正確；失敗的是把結果印到終端機視窗的步驟。以下有兩種替代做法： ```powershell markitdown dogovor.docx -o dogovor.md $env:PYTHONUTF8 = "1"; markitdown dogovor.docx > dogovor.md ``` 第一種做法完全避開主控台；第二種則讓 Python 使用 UTF-8 寫入。至少有 6 次有人提交修正此工具問題的提案：有些提案在未合併的情況下關閉，其餘仍未處理，因此只能自行繞過問題。 PDF 還會出現第四種症狀：字母被 `(cid:1090)` 這類字串取代。這表示檔案使用非標準字型表，字元無法解碼。用 MarkItDown 處理這種文件沒有意義；你需要改用其他工具。 ## 為什麼 PDF 會變得一團混亂？
重點摘要 PDF 沒有結構，只有帶著頁面座標的字元。單欄文字通常能組合得還算合理；雙欄排版則會亂成一團：跨欄的行被接在一起，單字連成一串，版面甚至會變成原文件裡從未存在的表格。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%」這個數字在網路上流傳，卻沒有任何方法說明。追查原始來源也找不到結果：連結鏈的最後一頁無法載入。因此不能把它當成測量數據。 ## 掃描的合約會怎麼樣？
重點摘要 什麼也不會發生。檔案經過處理，程式回報成功，但輸出包含 0 個字元。沒有錯誤，也沒有警告。我們用圖片製成的 PDF 測試了兩次，也另外直接測試圖片本身，結果都相同。這個工具擷取的是檔案中原本就以文字儲存的內容；免費版本沒有文字辨識能力。
這種行為比其他問題更危險，因為看起來不像失敗。 測試時，我們用含有文字的圖片製作 PDF，也就是拍照或掃描合約時會得到的檔案。為了排除偶然情況，重複執行了兩次： | 輸入 | 結束代碼 | 輸出字元數 | 錯誤訊息 | |----|----|----|----| | 圖片製成的 PDF，第 1 次 | 0 | 0 | 無 | | 圖片製成的 PDF，第 2 次 | 0 | 0 | 無 | | 直接輸入 PNG 圖片 | 0 | 1（換行） | 無 | 連續兩次都是 0 個字元、0 個錯誤。結束代碼 0 代表「一切順利」，任何以結束代碼判斷成功的指令碼都會把這份文件算作已完成處理。接著，空白輸出會送進模型；模型什麼也看不到，就開始憑空編造回答。
注意 如果你要批次處理文件，請檢查輸出長度。結束代碼無法提供任何資訊：掃描檔的特徵就是輸出空白檔案，結束代碼卻是 0。
有兩種替代方法，而且都需要付費。第一種是使用 `-d` 旗標，把文件傳送到 Microsoft 的雲端辨識服務；旗標說明明確指出必須提供有效的服務端點。第二種是使用另一個附加套件，以你的金鑰把頁面傳送給視覺模型，因此每頁都要向模型供應商付費。自 2026 年 4 月起，關於第二種方法的公開討論指出，多頁掃描文件只有第一頁會被處理。 你也可以在自己的電腦上執行文字辨識模型，但那是另一個專案。 只有一份文件時，直接開啟並手動複製文字比較簡單。若要連續處理大量掃描檔，就需要內建文字辨識功能的工具。 ## 直接把檔案上傳到線上轉換器可以嗎？
重點摘要 技術上可以；有許多網域使用這個名稱。但它們都和 Microsoft 無關。「檔案不會離開瀏覽器」這種說法，按一下就能查證，而且不一定是真的。上傳合約或含有姓名的匯出檔之前，請親自確認檔案會傳到哪裡。
「MarkItDown online」是最常見的搜尋建議之一，確實也有網站提供這項服務。Microsoft 原版工具完全沒有網站，只能自行安裝為程式使用。任何在瀏覽器中開啟、名稱相似的工具，都是其他人製作的。 你可以在一分鐘內檢查這類服務：在開發人員工具中開啟網路要求分頁，上傳任何無害檔案，看看它是否傳到伺服器。如果有，無論 FAQ 多麼信誓旦旦地聲稱在瀏覽器中處理，這項說法都是假的。
注意 合約、發票或含有員工姓名的匯出檔都包含個人資料。如果你把這種檔案傳給第三方網站，傳送者就是你。使用本機工具可避免這個問題：檔案不會離開你的電腦。
這就是 MarkItDown 在不能把文件傳出組織的情況下受到重視的原因。有一則討論提到，有人的工作筆電禁止安裝任意程式，卻允許使用 Python 函式庫，因此本機工具成了唯一可用的選項。 ## MarkItDown 實際上能節省多少？
重點摘要 主要好處是模型終於能理解文件。大小也有差別：比較 Office 檔案內標記內容的大小與擷取後文字的大小，可看到縮小了 5 到 7 倍。它也會移除模型不需要閱讀的內容，例如字型、邊界和儲存格顏色的描述。
Office 檔案是包含標記的封存檔。解開 3 個測試檔案，比較包含內容部分的大小和輸出大小，可得到以下結果： | 檔案 | 內部標記 | 擷取文字 | 縮小倍數 | |-----------------|-----------------|---------------|-----------------------| | Word 合約 | 3,701 位元組 | 711 位元組 | 5.2 | | Excel 試算表 | 1,561 位元組 | 262 位元組 | 6.0 | | 簡報 | 2,203 位元組 | 296 位元組 | 7.4 | 這些檔案都很小；較大的檔案比例會不同，不存在一個通用的節省數字。看到比較文章列出整數時，請先問清楚測量方法。 開發者自己也提到節省空間：專案說明特別指出，Markdown 慣例在字元數方面非常精簡。這的確沒錯，但不應該是主要賣點。「模型收到 3,000 個字元，而不是 15,000 個」和「模型收到清楚的結構，而不是一團混亂」是不同層次的差異。前者節省費用；後者決定回答是否有道理。 如果你在意上下文用量，可另見[Claude 的 token 用在哪裡](https://ailoot.ai/blog/zh-hant-tw/where-claude-code-tokens-go/)和[各方案包含多少 token](https://ailoot.ai/blog/zh-hant-tw/claude-pro-max-usage-limits/)。 ## 如何透過 MCP 將 MarkItDown 連接至 Claude？
重點摘要 專案提供一個獨立套件，可用一個指令執行 MCP 伺服器：提供檔案路徑，就能取回文字。2026 年 9 月，這個套件終於更新到 0.0.1a7，但建置版本仍是預先發布版，而且預設會向 Microsoft 傳送遙測資料。以下指令透過 uv 連線、固定版本、使用 Python 3.12 並停用遙測。它沒有驗證機制，而且依據自己的文件，伺服器可以讀取啟動它的使用者能存取的任何檔案。
MCP 是一種提供外部工具給 AI 自行使用的方式。關於這套機制和其他伺服器的概覽，請參閱 [Claude Code 的 MCP 伺服器評測](https://ailoot.ai/blog/zh-hant-tw/mcp-servers-claude-code/)。 MarkItDown 伺服器只提供一種工具：將文件轉成文字。它接受本機檔案路徑、網頁 URL，或直接嵌入要求中的資料。 只要一個指令，就能讓 Claude Code 連上固定版本的伺服器。你需要 uv 套件管理器： ```bash 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 的上限；而工具不會把檔案拆成區塊。 還有安全性問題。套件自己的文件明確寫道：

伺服器不支援驗證，並以啟動它的使用者權限執行。轉換工具可以讀取伺服器使用者有權存取的任何檔案，或網路上的任何資料。

— Microsoft，markitdown-mcp 套件說明（譯文），https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp
換句話說，擁有此工具的代理程式可以讀取你能讀取的一切。在自己的電腦上工作時，這可以接受；你不可公開此伺服器，也不可交給不受信任的代理程式。
注意 專案文件沒有提供專供 Claude Code 使用的設定，只說明 Claude Desktop 和透過容器啟動的方式。如果你在網路上找到被稱為「來自官方文件」的 Claude Code 現成設定，請注意儲存庫裡並沒有這種設定。
日常工作中，直接用指令執行程式，再把產生的文字放進專案會更簡單。如此一來，檔案會和其他資料放在一起，模型可以自行參考。 ## 何時改用其他工具才比較恰當？
重點摘要 原則很簡單：如果結構已經記錄在檔案中，就用速度最快且免費的 MarkItDown。如果必須從頁面圖片重建結構，就用具備版面模型的工具。Docling 能處理表格和複雜版面，MinerU 能處理公式和多欄內容；若沒有時間折騰，有付費雲端服務可用。
依工作類型比較，和 GitHub 星數無關： | 工具 | 優勢 | 代價或限制 | |----|----|----| | MarkItDown | Office 檔案、速度、免費 | 無法處理複雜 PDF 或掃描檔 | | Docling | 透過專用模型處理表格和版面 | 每份文件需要數十秒 | | MinerU | 多欄、公式、密集表格 | 安裝較困難 | | Marker | 高準確度、公式、插圖 | 需要顯示卡，而且授權限制營收 | | unstructured | 將文件結構切成區塊並附上描述 | 輸出較難使用 | | 雲端解析器 | 不必設定 | 需要付費，且文件會離開你的電腦 | 比較文章常略過一項關於 Marker 的細節。自 2026 年 7 月起，程式碼本身採寬鬆授權，但模型權重另採一份授權，並設有門檻：如果公司前一年的營收沒有超過 500 萬美元，而且籌得的資金也沒有超過同樣金額，就能免費使用。另一條款禁止任何正在開發競爭產品的人使用。這對大多數讀者沒有影響，但正在成長的企業採用前應先閱讀授權。 實際上可採用以下 4 個步驟： 1. 先全部交給 MarkItDown 處理，免費又迅速。 2. 開啟結果並檢查大小。 3. 如果文字看得懂，工作就完成了，不需要其他處理。 4. 如果輸出混亂或空白，再用較大型的工具處理那份特定檔案。 這樣只有真正需要的文件才會耗費更多時間和增加複雜度。 ## 如何把 MarkItDown 整合進工作流程？
重點摘要 Anthropic 在自己的技能說明中直接列出原則：使用這個工具閱讀文件，不要根據它規劃編輯。以下 3 種情境一開始就能派上用場：批次解析相似文件、一次將常用參考資料加入 AI 專案，以及準備會計系統匯出檔供分析。
Anthropic 在自家的 Office 檔案處理預設技能中使用 MarkItDown，並清楚說明了你也應完整採用的界線：

快速檢查工作表：markitdown file.xlsx。無法取得儲存格座標，因此不要據此規劃編輯。

— Anthropic，表格處理技能說明（譯文），https://github.com/anthropics/skills/blob/main/skills/xlsx/SKILL.md
文字會失去儲存格和頁面參照，因此你不能用它修改來源檔案。以下是 3 種使用情境。 批次處理相似文件，例如驗收紀錄、發票、表單、申請書。把它們放進資料夾，再用一行指令處理： ```bash for f in dokumenty/*.docx; do markitdown "$f" -o "text/$(basename "$f" .docx).md"; done ``` 接著把文字檔資料夾交給模型，請它整理相關資訊並製成表格。這適用於數位檔案；掃描檔會失敗，而你會立刻從檔案大小為 0 發現問題。 常用專案資料，例如價目表、合約範本、政策、服務說明，可先轉成文字一次，放在專案旁邊。模型之後每次收到要求都能讀取，因此不必每次在對話中附上檔案。[將檔案上傳至 Claude](https://ailoot.ai/blog/zh-hant-tw/claude-file-upload/)的文章解釋了這種方式和上傳檔案到聊天中的差異。 會計系統匯出檔。會計軟體或銀行帳戶匯出的 Excel 檔，可以在三分之一秒內轉成表格，模型也能直接計算，不必經過中間處理。請確認 CSV 以實際分隔符、引號規則與編碼匯出或解析，交給模型前核對列數、欄數與核對總額，不可用搜尋取代正規化分隔符。也要明確記錄幣別，只有 Excel 儲存格格式中的貨幣符號不會保留到擷取文字。 在終端機處理大型 PDF 不在此列。這是上下文用量相關的另一個問題，詳見[在 Claude Code 中處理 PDF 而不浪費 token](https://ailoot.ai/blog/zh-hant-tw/pdf-claude-code-markdown/)。如果你剛開始設定工作環境，請從[安裝 Claude Code](https://ailoot.ai/blog/zh-hant-tw/install-claude-code/)開始。 現在就開始的話，執行 `pip install 'markitdown[pdf,docx,xlsx,pptx]'`，處理第一份找到的 Word 合約，並檢查結果大小。只要半分鐘，你就會知道它是否適用於你的檔案。
### 常見問題 MarkItDown 免費嗎？ 是。它採用 MIT 授權，商業使用不受限制。只有兩種選用方式需要付費：透過 `-d` 旗標使用 Microsoft 雲端辨識，以及用自己的金鑰透過視覺模型描述圖片。其他功能都在你的電腦上免費執行。 資料會傳送到伺服器嗎？ 一般轉換 Office 檔案和 PDF 時不會，所有處理都在本機完成。例外有 3 種：音訊轉錄會使用 Google 的服務，`-d` 旗標會將文件傳送至 Microsoft 雲端，圖片描述則會傳送給你用自己的金鑰連接的模型。這些方式都不會自動啟用。 為什麼安裝後找不到 markitdown 指令？ 最常見的情況是程式安裝在不包含於搜尋路徑的環境中。請檢查該環境內檔案的完整路徑。另一個常見原因是，你為某個 Python 版本安裝，卻用另一個版本呼叫。還有一個陷阱：Python 版本低於 3.10 時，會安裝一個空套件，卻不會回報安裝錯誤。 如果看到 `(cid:1090)` 之類的字串，而不是字母，該怎麼辦？ 這是 PDF 中未解碼的字型表。調整設定無法修復；你需要改用 Docling 或 MinerU 等其他工具處理。如果只有一份文件，直接從檢視器手動複製文字比較快。 可以一次處理整個資料夾中的檔案嗎？ 沒有專用的資料夾模式，但可以用一行終端機迴圈處理：for f in papka/\*.docx; do markitdown "\$f" -o "\$f.md"; done。另一種方式是把所有檔案放入 ZIP，再提供封存檔：程式會處理裡面的內容，但無法解析的檔案會悄悄消失。 輸出和手動複製文字有什麼不同？ 它會保留結構。手動複製只會得到平面文字，標題和段落無法區分，表格也會散掉。MarkItDown 會保留標題、清單和表格，因此模型能辨別各項內容。只有一份簡短文件時差異不大，但有 20 份文件時就很關鍵。 MarkItDown 能開啟有密碼保護的文件嗎？ 不能。有密碼保護的檔案無法開啟，而且不能把密碼傳給程式。你必須先在設定該保護的應用程式中移除保護。
### 來源 - [MarkItDown - GitHub 專案儲存庫](https://github.com/microsoft/markitdown) - [PyPI 上的 MarkItDown - 版本與發布日期](https://pypi.org/project/markitdown/) - [markitdown-mcp - MCP 伺服器說明](https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp) - [Anthropic Skills - MarkItDown 用於表格的方式](https://github.com/anthropics/skills/blob/main/skills/xlsx/SKILL.md) - [Docling - 使用版面模型進行文件解析](https://docling-project.github.io/docling/) - [MinerU - 複雜 PDF 版面解析](https://github.com/opendatalab/MinerU) - [Marker - 模型權重授權](https://github.com/datalab-to/marker/blob/master/MODEL_LICENSE) - [pandoc - 標記轉換器](https://pandoc.org/)
準備好後，認識 [Ailoot](https://ailoot.ai/)。 ## 常見問題：如何將 PDF 和 Word 檔案轉成 AI 可用的文字：Microsoft 的 MarkItDown ### 把 CSV 中所有分號換成逗號，就能修好分號分隔檔嗎？ 不能。引號內文字與小數格式都可能包含這些字元。應以預期分隔符重新匯出，或使用明確設定分隔符、編碼與引號規則的 CSV 解析器及寫入器，再與原檔核對欄數、列數與核對總額。 ### 結束碼為零，就代表 PDF 已成功轉成有用文字嗎？ 不能。本文掃描檔範例沒有報錯卻輸出空白，複雜 PDF 則可能輸出亂碼。請開啟結果，檢查長度與結構；空白或無法閱讀時，改用版面或辨識工具。 ## Ailoot · 公司及其專案組合 Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。 公司及其專案組合：數百萬客戶，每月銷售額達數十億。 Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。