Claude Code 中的 PDF：轉換、Token 與結構保留

Claude 如何處理 PDF？為什麼每頁會消耗 1,500–3,000 個 token？#

Anthropic 的官方文件以簡單明瞭的三個步驟說明這項流程：

聽起來很合理，但處理成本會隨頁數線性增加。以下這個數字可以解釋，為什麼只處理一份 PDF 就會用完你的訂閱額度：

為了了解這個數字有多大，Anthropic 在 Bedrock 上以兩種模式測量同一份 3 頁 PDF。文字模式（Converse Document Chat）使用約 1,000 個 token。視覺分析（Claude PDF Chat）則使用約 7,000 個 token。納入影像會讓處理成本增加 7 倍。

頁面截圖的成本更高。一張 1000×1000 像素的螢幕截圖約消耗 1,300 個 token。

原理很簡單：PDF 成本高，是因為 Claude 不完全信任 OCR。它同時使用文字和影像進行比對，而兩個層面的費用都得一起支付。處理大型文件時，可以改用不同方式：將檔案存成 Markdown，放在專案資料夾中，再告訴 Claude：「這裡有一份包含資訊的文件，請把內容整理開來。」它會將內容分散到自己的檔案中，並使用整理好的文字繼續工作，而不是一次消耗所有內容。

一般任務中的 PDF 會消耗多少 token？#

具體數字（Sonnet 4.x 模型，輸入費用為每百萬個 token $3）：

這只是執行一輪 4 次請求的結果。之後就會用到提示快取（預設 TTL 為 5 分鐘，延長方案最多可達 1 小時，在有效期間內重複呼叫最多可享 90% 折扣），節省幅度會進一步增加。

每次在新的對話中上傳相同 PDF 時，Claude 都會重新讀取；快取不會在不同對話間延續。

若先將同一份 15 頁 PDF 轉成 Markdown，再於四個新聊天以 .md 載入，本例為 15 × 300 × 4 = 18,000 個輸入 token，而非 135,000。每轉換頁 300、每 PDF 頁 2,250 都是本次計算假設，不是所有 PDF 的實測常數。估算前先計實際文件 token 並確認轉換品質。

對 Claude Pro 訂閱方案來說，這個差異更顯著。一份 100 頁的報告就可能耗盡整個 5 小時額度。轉成 Markdown 後，同一額度足以處理 10 份以上這類文件。

2026 年 Anthropic API 對 PDF 有哪些限制？#

Anthropic 的文件在最上方列出了限制（截至 2026 年 5 月 31 日）：

Claude.ai（消費者版網頁應用程式）的限制不同：每個檔案最多 500 MB，每個對話最多 20 個檔案。但視覺分析僅適用於 100 頁以下的 PDF；超過這個頁數時，Claude 只能看到文字，看不到圖表和示意圖。

透過 API 傳送 PDF 的 3 種方式：

1. 透過 URL - "source": {"type": "url", "url": "..."} - 文件已上線時最簡單。
2. 使用 Base64 - "source": {"type": "base64", "media_type": "application/pdf", "data": "..."} - 適用於本機檔案。
3. 透過 Files API - "source": {"type": "file", "file_id": "file_abc123"} - 適用於重複請求；需要 beta 標頭 anthropic-beta: files-api-2025-04-14。

使用同一份 PDF 處理不同對話時，Files API 是主要的節省方式。上傳一次並取得 file_id，之後所有互動都使用它。搭配 cache_control: ephemeral，重複呼叫只需支付一般價格的 10%。

Anthropic 也提供了降低使用量的官方建議：

方法 1：如何在 5 分鐘內設定 MarkItDown？#

MarkItDown 是 Microsoft 的官方專案，由 AutoGen 團隊維護。截至 2026 年 5 月底，它在 GitHub 上有 134 千顆星和 9.2 千個分支。README 直接說明其用途：

支援的格式：

• 文件： PDF、DOCX、PPTX、XLSX
• 網頁： HTML、JSON、XML、CSV
• 媒體： 含轉錄功能的音訊、含 EXIF 和 OCR 的影像、YouTube 影片（透過字幕）
• 封存檔： ZIP、EPub
• 其他： Outlook MSG 檔案中的所有附件

安裝

需求：Python 3.10+（macOS 通常已預先安裝；Windows 則需要另外安裝）。

pip install 'markitdown[all]'

如果不需要所有格式，可以只安裝所需項目：

pip install 'markitdown[pdf, docx, pptx]'

轉換單一檔案

最簡單的情況：

markitdown document.pdf > document.md

完成後，document.md 會出現在目前資料夾中。使用 @document.md 將它載入 Claude Code，或直接放在專案旁邊。

Python API

如果想整合進自己的指令碼：

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("research-paper.pdf")
print(result.text_content)

# You can save it straight away:
with open("research-paper.md", "w") as f:
    f.write(result.text_content)

MarkItDown 無法處理的項目

• 掃描 PDF 的 OCR - 不會傳回任何內容。掃描檔需要 PyMuPDF4LLM 或 Docling。
• 多欄複雜版面 - 可能會打亂閱讀順序。
• PDF 中的內嵌 URL - 不會保留。

對於簡單的 PDF（報告、文章、文件），MarkItDown 是最佳選擇：這款用途廣泛的工具只需一分鐘即可安裝，也不需要 Python 知識。它處理西里爾字母文字和掃描文件的表現，請參閱將 PDF 轉換成供 AI 使用的文字分析中的測量結果。

方法 2：PyMuPDF4LLM 有哪些功能？什麼時候更適合使用？#

MarkItDown 提供廣泛的檔案格式支援；PyMuPDF4LLM 則提供深入的 PDF 處理能力。

截至 2026 年 5 月 31 日的版本為 1.27.2.3（於 2026 年 4 月 24 日發布）。

功能內容

• 以正確閱讀順序處理多欄頁面
• 將表格轉換成 GitHub Flavored Markdown
• 自動移除頁首和頁尾
• 擷取影像並以相對連結存入另一個資料夾
• 智慧 OCR：僅套用在無法讀取的區域，可節省約 50% 的處理時間
• 原生 C 引擎，不需要 GPU

安裝

pip install pymupdf4llm

使用方式

import pymupdf4llm

# Basic use - straight to Markdown:
md_text = pymupdf4llm.to_markdown("document.pdf")

# Save it:
with open("document.md", "w") as f:
    f.write(md_text)

如前所述，也可以用一行指令完成：

python3 -c "import pymupdf4llm; \
  open('document.md','w').write(pymupdf4llm.to_markdown('document.pdf'))"

什麼時候該選 PyMuPDF4LLM，而不是 MarkItDown？

• PDF 含有許多需要保留的連結時（MarkItDown 會遺失這些連結）。
• 文件是掃描檔，而且需要 OCR 時。
• 需要在本機快速處理數千個檔案時——原生 C 引擎比 Python 封裝函式更快。
• 需要將 PDF 中的影像擷取到另一個資料夾，以便進一步處理時。

授權細節（商業用途的重要資訊）

PyMuPDF4LLM 採雙重授權：AGPL v3 或 Artifex 商業授權。

AGPL 的意思：如果你在公開 SaaS 中使用這個程式庫，就必須依相同的 AGPL 授權公開服務的全部原始碼。若是內部使用（例如在筆電上執行自己的指令碼），則沒有相關限制。

若要在不公開程式碼的情況下進行商業開發，請向 Artifex（artifex.com）購買授權。價格未公開，請向業務部門詢價。

如果你正在為客戶開發產品，請在一開始就確認授權。MarkItDown（MIT）和 Docling（MIT）對 SaaS 來說更安全。

方法 3：如何將 MarkItDown MCP 伺服器連接到 Claude Code？#

使用 CLI 模式的 MarkItDown，意思是「我事先手動轉換檔案」；使用 MCP 伺服器，意思則是「由 Claude Code 決定何時轉換」。

安裝

你需要 uv 套件管理器。不必另外安裝伺服器；uv 會在第一次執行時下載。

在 Claude Code 中設定

使用一個指令就能將伺服器連接到所有專案，並固定版本：

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 個套件，最多需要一分鐘；之後伺服器只需一兩秒就會啟動。

指令需要這兩個變數的原因如下。ORT_DISABLE_TELEMETRY=1 會停用伺服器內 onnxruntime 引擎在 Mac 和 Linux 上預設傳送給 Microsoft 的統計資料。UV_PYTHON=3.12 會以 Python 3.12 執行伺服器，因為 Windows、Linux 和搭載 Apple Silicon 的 Mac 都有預先建置的套件。在 Intel Mac 和 macOS 13 及更早版本上，伺服器無法在 Python 3.14 下安裝。Intel 裝置使用 Python 3.12 時有一項注意事項：自 2026 年 6 月起，Intel 沒有可用的預先建置套件，因此 uv 會從原始碼建置 cryptography 程式庫。安裝時間會更長，也可能失敗。如果你沒有 Python 3.12，uv 會替你下載。

伺服器會直接在你的電腦上執行，並能開啟你有權存取的任何檔案。如果 Claude Code 當時已開啟，請重新啟動；接著 MCP 伺服器清單中就會出現 markitdown。

使用方式

在 Claude Code 中，只要說：

將 /Users/your-user/Documents/report.pdf 轉換成 Markdown，並分析重點。

Claude 會自行呼叫 convert_to_markdown(uri)、取得 Markdown 並使用內容進行工作——PDF 不會載入上下文。

支援的 URI

• file:// - 本機檔案
• http://、https:// - 線上文件
• data: - 內嵌資料（Base64）

安全性

摘自官方 README：

預設情況下，它會綁定 localhost。如果透過 HTTP/SSE 執行（選項 --http --host 127.0.0.1 --port 3001），請勿在沒有經過驗證的反向代理時將連接埠對外公開。

該根據任務選擇哪種方法？#

詳細比較表：

Marker 在基準測試中公布了出色的準確度數據：

但 Marker 要有 GPU 才能達到良好速度，而且會一併使用機器學習模型。對大多數任務而言（一般文字 PDF），PyMuPDF4LLM 或 MarkItDown 不需要 GPU，幾秒鐘就能完成工作。

簡單的選擇原則

1. 只有一兩份 PDF，而且要快速完成 - MarkItDown CLI。
2. 有數十份 PDF，需要自動化處理 - MarkItDown MCP 伺服器或指令碼中的 PyMuPDF4LLM。
3. PDF 含有連結和影像，且需要保留結構 - PyMuPDF4LLM。
4. 商業用途的正式環境 RAG，且表格穩定性很重要 - Docling。
5. 含公式的科學論文 - Marker。
6. 不想操心轉換，想交給 Claude 處理 - MarkItDown MCP 伺服器。

如何撰寫可直接使用的指令碼，自動轉換整個文件資料夾？#

舉個實用例子：假設你有 40 份客戶提供的 PDF 和 PPTX 報告放在同一個資料夾中，包括券商對帳單、合約和簡報。直接將整個資料夾上傳到 Claude 毫無用處：還沒收到第一個回覆，上下文視窗就會被資訊塞滿。先用以下指令碼一次處理整個資料夾，再改用輕量的 .md 檔案繼續工作，而不是使用龐大的 PDF。

將此指令碼儲存為專案根目錄中的 scripts/docs-to-md.sh：

#!/bin/bash
# docs-to-md.sh - 使用 MarkItDown 將資料夾中的所有文件轉換為 Markdown
# 用法：bash docs-to-md.sh ./documents

set -e

INPUT_DIR="${1:-./documents}"
OUTPUT_DIR="${INPUT_DIR}/_md"

mkdir -p "$OUTPUT_DIR"

echo "掃描 $INPUT_DIR..."

for file in "$INPUT_DIR"/*.{pdf,docx,pptx,xlsx}; do
  [ -f "$file" ] || continue

  basename=$(basename "$file")
  name="${basename%.*}"
  output="$OUTPUT_DIR/${name}.md"

  if [ -f "$output" ] && [ "$output" -nt "$file" ]; then
    echo "略過 $basename（已轉換）"
    continue
  fi

  echo "正在轉換 $basename..."
  markitdown "$file" > "$output"
done

echo "完成。結果位於 $OUTPUT_DIR"

將它設為可執行：

chmod +x scripts/docs-to-md.sh

執行它：

bash scripts/docs-to-md.sh ./reports

執行後，./reports/_md/ 會包含所有文件的 .md 版本。使用 @reports/_md/ 將它們載入 Claude Code，改用壓縮後的文字，而非 PDF 繼續工作。

指令碼會自動略過已轉換的檔案（.md 檔案比來源檔案新時）。重新執行的成本很低，也不會把所有內容重新轉換一次。

冪等性與增量轉換

如果要讓指令碼偵測以相同名稱重新儲存後有所變更的 PDF，請加入內容雜湊檢查：

hash=$(shasum -a 256 "$file" | cut -d' ' -f1)
hash_file="$OUTPUT_DIR/.${name}.sha256"

if [ -f "$hash_file" ] && [ "$(cat "$hash_file")" = "$hash" ]; then
  echo "略過 $basename（雜湊相符）"
  continue
fi

markitdown "$file" > "$output"
echo "$hash" > "$hash_file"

這個版本只有在檔案內容變更時才會重新轉換。

什麼時候在 Claude 中使用 PDF 會比 Markdown 更好？#

Markdown 轉換無法滿足需求的 3 種情況：

1. 視覺分析示意圖和圖表

如果 Claude 需要「讀取」圖表——例如價格曲線、流程圖或架構圖——這些資訊不會出現在 Markdown 中。Markdown 只會保留圖說，圖本身會遺失。

解決方案：上傳 PDF 並明確啟用視覺模式。在 Claude API 上，這個旗標會自動生效；在 AWS Bedrock 上，則需要 citations 旗標。

2. 含合併儲存格的複雜表格

Markdown 表格是扁平的。如果 PDF 中的表格有合併儲存格、多層標題或巢狀子表格，轉換器可能會將表格扁平化，或遺失其中的關聯。

解決方案：直接使用 PDF、使用 Docling（它最擅長處理複雜表格），或在轉換後手動排版。

3. 需要標示頁碼的文件成品

法律文件、合約和會議紀錄需要能引用「第 7 頁第 3 段」。轉成 Markdown 後，頁碼會遺失。

解決方案：使用 PDF + Files API + 提示快取。上傳一次，接著透過 file_id 引用；Claude 會保留頁碼，並能引用特定頁面。

短文件

如果 PDF 不到 2 頁，而且只會用一次，就不值得轉換。PDF 需要 5,000 個 token，Markdown 需要 800 個 token，節省的幅度還不足以值得安裝 MarkItDown。

損益平衡點約為 5 頁以上，或同一份文件使用 2 次以上。低於這個範圍時直接上傳 PDF；超過時則轉換。

在 Claude 中處理 PDF 時，最常見的 5 個錯誤是什麼？#

1. 每次都在新對話中上傳同一份 PDF

Claude Pro 設有 5 小時內的訊息上限——一份 50 頁報告就可能在你提出第二個問題前耗盡額度。

有個簡單原則可以遵循：一項任務，一個對話。當 AI 開始消耗數量驚人的 token，代表你把所有內容都塞進同一個對話，並一次又一次載入 PDF。每個視窗只處理一項小任務。先將文件轉換成 Markdown，之後在每個新視窗中，將 .md 檔案與專案一同加入。上下文視窗的圓圈就不會變黃。

解決方案：先轉換成 Markdown，或使用搭配 file_id 和提示快取的 Files API。

2. 用螢幕截圖取代文字

常見的例子是：有人想讓 Claude 看程式碼或表格，於是截下整個 1920×1080 螢幕，接著不明白為什麼才提出 5 次請求，額度就用完了。

一張 1000×1000 像素的螢幕截圖約消耗 1,300 個 token。手動複製相同文字只要 50–100 個 token，相差 13–26 倍。

解決方案：將截圖範圍精確裁切至重要部分，或更好的做法是直接複製文字。

3. 沒有 OCR 的掃描 PDF

MarkItDown 無法執行 OCR。轉換掃描檔後，會得到空白的 .md 檔案（或 3 行雜訊）。

解決方案：處理掃描檔時，使用內建智慧 OCR 的 PyMuPDF4LLM 或 Docling。

4. 忽略 100 頁上限

Anthropic 的文件列出的每個請求上限是 600 頁，但實際上，上下文為 200K 的模型（Sonnet 4.x、Opus 4.x）上限是100 頁。600 頁的限制是為較舊的模型或特殊方案設定的。

如果你將一份 150 頁的報告上傳到 Sonnet 4.6，可能會收到錯誤訊息；更糟的情況是，Claude 只處理前 100 頁，卻表現得好像讀完了整份文件。

解決方案：上傳前先將長 PDF 拆分成多個部分，或轉換成 Markdown——沒有頁數限制，只有 token 數量限制。

5. 重複請求時沒有使用提示快取

如果透過 API 處理同一份文件，請使用 cache_control: ephemeral。5 分鐘內的重複呼叫只需支付初次價格的 10%。第一個請求較貴，其餘請求則享有 90% 折扣。

解決方案：對任何會重複上傳的內容，預設啟用提示快取。

接下來：上下文工程#

將 PDF 轉換成 Markdown 是節省 token 的一種方法。光靠這項做法並不會讓 Claude 的回答更準確。準確度來自上下文工程——也就是研究在提問前，該在模型上下文中放入哪些內容。

如果你的 CLAUDE.md 有 800 行、專案有 10 個不必要的 MCP 伺服器，而且你還載入一份 100 頁的 PDF，Markdown 轉換只能防止其中一項浪費，另外三項仍然存在。因此，我們提供以下指南：

• Claude Code 中的 token 都用到哪裡了 - 9 種上下文流失模式，不只有 PDF。
• 2026 年的上下文工程 - 系統化管理上下文的方法。
• Claude Code 中的 Plan Mode - Claude 開始撰寫程式碼前使用的規劃模式。