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

> MarkItDown、PyMuPDF4LLM、MCP、完整轉換指令碼、PDF 限制，以及視覺分析比節省 token 更重要的情況。

Source: https://ailoot.ai/blog/zh-hant-tw/pdf-claude-code-markdown/
Canonical: https://ailoot.ai/blog/zh-hant-tw/pdf-claude-code-markdown/
Language: zh-Hant-TW
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-196
Revision: sha256-98695015d9795b42b239b0540ddcd530a3546e6cf1414d877c190ba663fb097a


<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

在 Claude Code 中，每一頁 PDF 都會在你提出第一個問題前消耗 1,500–3,000 個 token，而 Anthropic 在文件中明確說明了這點。下方示意中，15 頁報告在 4 個聊天使用，PDF 輸入為 135,000 token、約 $0.40，Markdown 為 18,000 token、$0.054，約少 87%。這假設每 PDF 頁 2,250、Markdown 頁 300 token，並用範例輸入費率；實際文件會不同。本指南介紹 3 種轉換方法（MarkItDown、PyMuPDF4LLM 和 MCP 伺服器），以及可直接使用、能處理整個文件資料夾的 bash 指令碼。

</div>



<div class="aside" data-semantic="ailoot-docs-link" aria-label="Ailoot documentation">

Ailoot 的實用操作說明請參閱[文件](https://ailoot.ai/docs/)。

</div>

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

將 PDF 上傳到 Claude Code 時，它不會像讀取文字檔那樣讀取 PDF。首先，每一頁都會轉換成影像，接著從中擷取文字，然後將這兩個層面——影像和文字——一起加入上下文。這就是為什麼一頁會占用 1,500–3,000 個 token，而一份 50 頁的文件可能會在你提出第一個問題前就用掉 75,000–150,000 個 token。

</div>

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

<figure>
<blockquote>
<p>系統會將文件的每一頁轉換成影像。系統會擷取每一頁的文字，並與該頁影像一併提供。Claude 會分析文字和影像，以更深入理解文件。</p>
</blockquote>
<figcaption>— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support</figcaption>
</figure>

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

<figure>
<blockquote>
<p>每頁通常會依內容密度使用 1,500–3,000 個 token。由於每一頁都會轉換成影像，因此適用與一般影像相同的成本。</p>
</blockquote>
<figcaption>— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support</figcaption>
</figure>

為了了解這個數字有多大，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？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

考慮 15 頁公開報告在分析、引文、翻譯及摘要四種脈絡使用。假設每 PDF 頁 2,250 輸入 token、Markdown 頁 300，且費率相同；重傳 PDF 為 135,000 token、約 $0.40，Markdown 為 18,000、$0.054。約 87% 的節省來自這些假設，不是每份 PDF 的實測。

</div>

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

| 方式 | Token 數（15 頁，4 個對話） | 費用 |
|------------------------------|-----------------------------|-------------|
| 直接上傳 PDF 4 次 | 15 × 2250 × 4 = **135,000** | 約 $0.40 |
| PDF → Markdown + 4 個對話 | 15 × 300 × 4 = **18,000** | 約 $0.054 |
| 節省 | **−87%** | **−$0.35** |

這只是執行一輪 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 有哪些限制？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

Anthropic 設有嚴格限制：每個請求最多 32 MB（包括所有內容，不只是 PDF），每個請求最多 600 頁。不過，對於上下文為 200K 的目前 Sonnet 4.x 和 Opus 4.x 模型，上限較低，為**100 頁**。你可以透過 URL、Base64，或 Files API 傳送 PDF，並使用 `file_id` 重複利用。處理長文件時會使用 Files API，並將文件拆分成多個部分。

</div>

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

| 要求 | 限制 |
|-----------------------------|--------------------------------------------|
| 請求大小上限 | 32 MB（依平台而異） |
| 每個請求的頁數上限 | 600（上下文為 200K token 的模型則為 100） |
| 格式 | 未設密碼或加密的標準 PDF |

<figure>
<blockquote>
<p>兩項限制都適用於整個請求本文，包括與 PDF 一同傳送的內容。對於大型 PDF，請使用 Files API，並以 <code>file_id</code> 引用，讓請求本文保持精簡。</p>
</blockquote>
<figcaption>— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support</figcaption>
</figure>

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 也提供了降低使用量的官方建議：

<figure>
<blockquote>
<p>內容密集的 PDF（有大量小字、複雜表格或大量圖形）可能會在達到頁數上限前就填滿上下文視窗。試著將文件拆分成多個章節；對於大型檔案，請在上傳前降低內嵌影像的解析度。</p>
</blockquote>
<figcaption>— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support</figcaption>
</figure>

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

MarkItDown 是 Microsoft AutoGen 團隊開發的 Python 工具，可將 PDF、DOCX、PPTX、XLSX、HTML、音訊、影像，甚至 YouTube 影片轉換成乾淨的 Markdown。它在 GitHub 上有 134 千顆星，採用 MIT 授權，只要一個指令就能安裝：`pip install 'markitdown[all]'`。使用同樣簡單：`markitdown document.pdf > document.md`。在使用 Claude Code 前轉換檔案時，這是用途最廣的工具。

</div>

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

<figure>
<blockquote>
<p>一款輕量的 Python 工具，可將檔案轉換成 Markdown，以便用於 LLM 和文字分析流程。</p>
</blockquote>
<figcaption>— Microsoft, https://github.com/microsoft/markitdown</figcaption>
</figure>

支援的格式：

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

### 安裝

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

```bash
pip install 'markitdown[all]'
```

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

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

### 轉換單一檔案

最簡單的情況：

```bash
markitdown document.pdf > document.md
```

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

### Python API

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

```python
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 使用的文字](https://ailoot.ai/blog/zh-hant-tw/markitdown-pdf-word-to-text/)分析中的測量結果。

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

PyMuPDF4LLM 是 Artifex Software 的專案，基於原生 C 語言 MuPDF 引擎。它是速度最快的 PDF 轉換器（不需要 GPU）；智慧 OCR 只會套用在無法讀取的區域，可減少 50% 的處理時間。它是唯一能保留 PDF 內嵌 URL 和影像的熱門工具。缺點是採用雙重授權：AGPL v3 或 Artifex 商業授權；對 SaaS 專案而言，AGPL 表示你必須公開程式碼。

</div>

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

<figure>
<blockquote>
<p>一款輕量的 PyMuPDF 擴充功能，只需最少設定，就能將 PDF 轉換成乾淨、結構化的資料。</p>
</blockquote>
<figcaption>— Artifex Software, https://pymupdf.readthedocs.io/en/latest/pymupdf4llm/</figcaption>
</figure>

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

### 功能內容

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

### 安裝

```bash
pip install pymupdf4llm
```

### 使用方式

```python
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)
```

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

```bash
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 商業授權。

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

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

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

MarkItDown MCP 伺服器就是以 MCP 協定包裝的 MarkItDown，因此 Claude Code 可以即時轉換 PDF，不必將原始檔案載入上下文。使用 uv，只要一個指令就能連線，且版本已固定：`markitdown-mcp@0.0.1a7`。Claude 可使用的工具是 `convert_to_markdown(uri)`。閒置時，技能說明約占 110 個 token，不需要時則為零。

</div>

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

### 安裝

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

### 在 Claude Code 中設定

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

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

指令需要這兩個變數的原因如下。`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：

<figure>
<blockquote>
<p>此伺服器不支援授權驗證，並會使用啟動它的使用者權限執行。</p>
</blockquote>
<figcaption>— Microsoft, https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp</figcaption>
</figure>

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

如果你會處理多種格式（PDF + DOCX + PPTX + YouTube），並需要快速的 CLI 指令，MarkItDown 是全能型工具。PyMuPDF4LLM 是 PDF 專用工具：速度更快，支援 OCR 和保留連結，但對 SaaS 來說，AGPL 可能是個陷阱。Docling 適合正式環境，尤其擅長處理表格和公式。Marker 適用於含數學內容的科學論文。如果你不想操心轉換工作，並想讓 Claude Code 自行決定，就用 MCP 伺服器。

</div>

詳細比較表：

| 工具 | GitHub 星數 | 最適用途 | 速度 | 授權 |
|----|----|----|----|----|
| **MarkItDown**（Microsoft） | 134k | PDF + DOCX + PPTX + YouTube + 音訊 | 中等 | MIT |
| **PyMuPDF4LLM**（Artifex） | \- | 原生 PDF、OCR、內嵌 URL | 最快（不需要 GPU） | AGPL v3 / 商業 |
| **Docling**（IBM Research） | 60.7k | 正式環境 RAG、表格、公式 | 中等 | MIT |
| **Marker**（datalab.to） | 35.6k | 科學 PDF、arXiv、公式 | 高（使用 GPU 時） | GPL-3.0 + Open Rail-M |
| **MinerU** | \- | CJK 文件（中文／日文） | 高 | Apache-2.0 |

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

<figure>
<blockquote>
<p>使用 H100 GPU 時，每頁需 0.18 秒（每秒 122 頁）。準確率為 95.67%，高於 Llamaparse（84.24%）和 Mathpix（86.43%）。處理科學論文時為 96.67%。</p>
</blockquote>
<figcaption>— datalab.to, https://github.com/datalab-to/marker</figcaption>
</figure>

但 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 伺服器。

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

最方便的做法是使用 bash 指令碼巡覽專案資料夾，將所有 PDF、DOCX 和 PPTX 檔案轉換成 Markdown，並放進 `_md/` 子資料夾。設定一次後，任何新文件資料夾都能透過一次處理變得「Claude 可讀」。接著使用 `@_md/` 將 `_md/` 載入 Claude Code，以壓縮後的文字繼續工作。

</div>

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

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

```bash
#!/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"
```

將它設為可執行：

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

執行它：

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

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

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

### 冪等性與增量轉換

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

```bash
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 更好？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

轉成 Markdown 會失去 3 項內容：視覺元素（示意圖、圖表、藍圖）、含合併儲存格和標題的複雜表格，以及作為成品的完整文件格式（例如需要依頁碼引用的合約）。如果這些內容對任務很重要，就保留 PDF、啟用視覺分析，並明確接受視覺處理成本。

</div>

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

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

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

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

<figure>
<blockquote>
<p>Claude 會分析文字和影像，以更深入理解文件。</p>
</blockquote>
<figcaption>— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support</figcaption>
</figure>

### 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 個錯誤是什麼？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

主要問題包括：在不同對話中重複上傳同一份 PDF，而不是轉換一次；重複請求時沒有使用提示快取；用螢幕截圖取代文字；沒有對掃描 PDF 執行 OCR；忽略上下文為 200K 的模型之 100 頁上限。這些錯誤每一項都會白白浪費數萬個 token。

</div>

### 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% 折扣。

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

## 接下來：上下文工程

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

將 PDF 轉換成 Markdown 是上下文工程的一種技巧；上下文工程也是使用 AI 的一種新素養。提示詞是一個問題。上下文則是 Claude 在問題之前及周遭看到的所有內容：系統提示詞、CLAUDE.md、檔案、MCP 伺服器和工作階段歷史。上下文越乾淨，答案越準確，成本也越低。請閱讀《2026 年的上下文工程》指南，了解完整分析。

</div>

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

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

- [Claude Code 中的 token 都用到哪裡了](https://ailoot.ai/blog/zh-hant-tw/where-claude-code-tokens-go/) - 9 種上下文流失模式，不只有 PDF。
- [2026 年的上下文工程](https://ailoot.ai/blog/zh-hant-tw/context-engineering/) - 系統化管理上下文的方法。
- [Claude Code 中的 Plan Mode](https://ailoot.ai/blog/zh-hant-tw/claude-code-plan-mode/) - Claude 開始撰寫程式碼前使用的規劃模式。

<div class="section" role="doc-bibliography" aria-label="Sources">

### 來源

- [Anthropic - PDF 支援（platform.claude.com）](https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support)
- [Anthropic - 將檔案上傳到 Claude（support.claude.com）](https://support.claude.com/en/articles/8241126-upload-files-to-claude)
- [Microsoft MarkItDown（GitHub）](https://github.com/microsoft/markitdown)
- [MarkItDown MCP 伺服器](https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp)
- [PyMuPDF4LLM - 官方文件](https://pymupdf.readthedocs.io/en/latest/pymupdf4llm/)
- [Docling（IBM Research，GitHub）](https://github.com/DS4SD/docling)
- [Marker（datalab.to，GitHub）](https://github.com/datalab-to/marker)

</div>







<div class="aside" data-semantic="ailoot-link" aria-label="Ailoot">

繼續探索 Ailoot，前往 [ailoot.ai](https://ailoot.ai/)。

</div>

## 常見問題：Claude Code 中的 PDF：轉換、Token 與結構保留

### 15 頁文件在四個聊天使用，Markdown 範例多少 token？

依本文每頁 300 token 假設，15 × 300 × 4 = 18,000 個輸入 token。這是示意估算，自己的文件應對轉換結果實際計數。

### 所有 PDF 都只轉文字就夠嗎？

不一定。請對照 PDF 查看 Markdown，尤其表格、頁序及依賴圖片的內容。確認任務需要的資訊保留下來後，再比較 token 用量。


## Ailoot · 公司及其專案組合

Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。

公司及其專案組合：數百萬客戶，每月銷售額達數十億。

Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。