PDF trong Claude Code: Chuyển đổi, token và bảo toàn cấu trúc

PDF được xử lý thế nào trong Claude và vì sao mỗi trang tốn 1,500–3,000 token?#

Tài liệu chính thức của Anthropic mô tả quy trình bằng ba bước đơn giản:

Nghe có vẻ hợp lý, nhưng chi phí xử lý tăng tuyến tính theo số trang. Và đây là con số giải thích vì sao giới hạn gói đăng ký của bạn cạn kiệt chỉ vì một tệp PDF:

Để hình dung con số đó lớn đến đâu, Anthropic đã đo cùng một tệp PDF 3 trang trên Bedrock ở hai chế độ. Ở chế độ văn bản (Converse Document Chat), tệp dùng ~1,000 token. Với phân tích hình ảnh (Claude PDF Chat), tệp dùng ~7,000 token. Việc đưa hình ảnh vào khiến xử lý tốn kém hơn 7 lần.

Ảnh chụp màn hình của trang còn tốn kém hơn. Ảnh chụp màn hình 1000×1000 pixel tốn khoảng 1,300 token.

Cơ chế rất đơn giản: PDF tốn kém vì Claude không tin OCR của chính nó. Claude dùng cả văn bản lẫn hình ảnh để đối chiếu — và bạn phải trả phí cho cả hai lớp cùng lúc. Với tài liệu lớn, bạn có thể làm theo cách khác: lưu tệp dưới dạng Markdown trong thư mục dự án rồi bảo Claude: “đây là tài liệu có chứa thông tin — hãy chia nội dung ra”. Claude sẽ phân phối nội dung vào các tệp riêng và tiếp tục làm việc với phần văn bản đã được sắp xếp, thay vì xử lý mọi thứ cùng lúc.

PDF tiêu tốn bao nhiêu trong một tác vụ thông thường?#

Các con số cụ thể (mô hình Sonnet 4.x, đầu vào có giá $3 cho mỗi triệu token):

Và đó mới chỉ là một chu kỳ gồm 4 yêu cầu. Sau đó, prompt caching sẽ phát huy tác dụng (TTL mặc định 5 phút, tối đa 1 giờ ở cấp mở rộng, giảm đến 90% cho các lần gọi lại trong khoảng thời gian đó) — mức tiết kiệm sẽ nhân lên.

Mỗi lần tải cùng một PDF lên một cuộc trò chuyện mới, Claude lại đọc nó; bộ nhớ đệm không được dùng chung giữa các cuộc trò chuyện.

Nếu chuyển PDF 15 trang một lần sang Markdown rồi dùng .md trong bốn chat mới, ví dụ dùng 15 × 300 × 4 = 18,000 token đầu vào thay 135,000. 300 token mỗi trang chuyển và 2,250 mỗi trang PDF là giả định tính, không hằng số đo cho mọi PDF. Đếm tài liệu thật và kiểm chất lượng chuyển trước ước tính.

Phép tính này càng có ý nghĩa hơn khi dùng gói Claude Pro. Chỉ một báo cáo 100 trang cũng có thể tiêu hết giới hạn 5 giờ. Sau khi chuyển sang Markdown, hơn 10 tài liệu như vậy vẫn nằm trong cùng hạn mức.

Giới hạn API của Anthropic đối với PDF trong năm 2026 là gì?#

Tài liệu của Anthropic liệt kê các giới hạn ở đầu trang (cập nhật đến ngày 31 tháng 5 năm 2026):

Claude.ai (ứng dụng web dành cho người dùng) có giới hạn khác: tối đa 500 MB mỗi tệp và tối đa 20 tệp trong một cuộc trò chuyện. Tuy nhiên, phân tích hình ảnh chỉ hoạt động với PDF tối đa 100 trang — vượt quá giới hạn này Claude chỉ thấy văn bản, không có biểu đồ hay sơ đồ.

Có ba cách gửi PDF qua API:

1. Qua URL - "source": {"type": "url", "url": "..."} - đơn giản nhất khi tài liệu đang có trên mạng.
2. Ở dạng Base64 - "source": {"type": "base64", "media_type": "application/pdf", "data": "..."} - dành cho tệp cục bộ.
3. Qua Files API - "source": {"type": "file", "file_id": "file_abc123"} - dành cho yêu cầu lặp lại; cần tiêu đề beta anthropic-beta: files-api-2025-04-14.

Files API là cách chính để tiết kiệm khi làm việc với cùng một PDF qua nhiều cuộc trò chuyện. Tải tệp lên một lần, nhận file_id, rồi dùng ID đó cho mọi tương tác. Với cache_control: ephemeral, các lần gọi lại có chi phí bằng 10% giá thông thường.

Anthropic cũng đưa ra lời khuyên chính thức về cách giảm mức sử dụng:

Phương pháp 1: Thiết lập MarkItDown trong 5 phút như thế nào?#

MarkItDown là dự án chính thức của Microsoft do nhóm AutoGen duy trì. Trên GitHub, dự án có 134 nghìn sao và 9.2 nghìn fork (tính đến cuối tháng 5 năm 2026). Mục đích của dự án được nêu trực tiếp trong README:

Các định dạng được hỗ trợ:

• Tài liệu: PDF, DOCX, PPTX, XLSX
• Web: HTML, JSON, XML, CSV
• Phương tiện: âm thanh có bản chép lời, hình ảnh có EXIF và OCR, video YouTube (qua phụ đề)
• Tệp lưu trữ: ZIP, EPub
• Khác: mọi tệp đính kèm trong tệp Outlook MSG

Cài đặt

Yêu cầu: Python 3.10+ (thường đã có trên macOS; trên Windows cần cài riêng).

pip install 'markitdown[all]'

Nếu không cần mọi định dạng, bạn có thể chỉ cài những định dạng được chọn:

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

Chuyển đổi một tệp

Trường hợp đơn giản nhất:

markitdown document.pdf > document.md

Sau đó, document.md sẽ xuất hiện trong thư mục hiện tại. Đưa tệp vào Claude Code bằng @document.md hoặc đặt ngay cạnh dự án.

Python API

Nếu muốn tích hợp vào tập lệnh của bạn:

from markitdown import MarkItDown

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

# Có thể lưu ngay:
with open("research-paper.md", "w") as f:
    f.write(result.text_content)

MarkItDown KHÔNG thể làm gì

• OCR cho PDF scan - không trả về nội dung. Tệp scan cần PyMuPDF4LLM hoặc Docling.
• Bố cục phức tạp có nhiều cột - thứ tự đọc có thể bị xáo trộn.
• URL nhúng trong PDF - không được giữ lại.

Với PDF đơn giản (báo cáo, bài viết, tài liệu hướng dẫn), MarkItDown là lựa chọn tốt nhất: một công cụ đa năng, cài đặt trong một phút và không cần kiến thức Python. Hiệu quả trên tài liệu có chữ Cyrillic và bản scan được thể hiện trong số liệu ở phân tích về cách chuyển PDF thành văn bản cho AI.

Phương pháp 2: PyMuPDF4LLM có gì và khi nào tốt hơn?#

MarkItDown cung cấp nhiều định dạng; PyMuPDF4LLM xử lý PDF chuyên sâu.

Phiên bản tính đến ngày 31 tháng 5 năm 2026 là 1.27.2.3 (phát hành ngày 24 tháng 4 năm 2026).

Những gì được cung cấp

• Trang nhiều cột với thứ tự đọc chính xác
• Chuyển bảng thành Markdown theo kiểu GitHub
• Tự động loại bỏ đầu trang và chân trang
• Trích xuất hình ảnh với liên kết tương đối tới một thư mục riêng
• Smart OCR: chỉ áp dụng cho vùng không đọc được, tiết kiệm ~50% thời gian xử lý
• Engine C gốc, không cần GPU

Cài đặt

pip install pymupdf4llm

Cách dùng

import pymupdf4llm

# Cách dùng cơ bản - chuyển thẳng sang Markdown:
md_text = pymupdf4llm.to_markdown("document.pdf")

# Lưu lại:
with open("document.md", "w") as f:
    f.write(md_text)

Trong một dòng như đã hứa:

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

Khi nào nên chọn PyMuPDF4LLM thay cho MarkItDown

• Khi PDF có nhiều liên kết bạn cần giữ lại (MarkItDown làm mất chúng).
• Khi tài liệu là bản scan và bạn cần OCR.
• Khi cần xử lý nhanh hàng nghìn tệp cục bộ — engine C gốc nhanh hơn các wrapper Python.
• Khi cần hình ảnh từ PDF trong một thư mục riêng để xử lý tiếp.

Chi tiết giấy phép (quan trọng với doanh nghiệp)

PyMuPDF4LLM có giấy phép kép: AGPL v3 HOẶC Artifex thương mại.

AGPL có nghĩa là: nếu dùng thư viện trong SaaS công khai, bạn phải phát hành toàn bộ mã nguồn dịch vụ theo cùng giấy phép AGPL. Với mục đích nội bộ (tập lệnh chạy trên máy tính xách tay của bạn), không có hạn chế.

Để phát triển thương mại mà không công khai mã nguồn, hãy mua giấy phép của Artifex (artifex.com). Giá không được công bố; hãy yêu cầu bộ phận bán hàng báo giá.

Nếu đang xây dựng sản phẩm cho khách hàng, hãy kiểm tra giấy phép ngay từ đầu. MarkItDown (MIT) và Docling (MIT) an toàn hơn cho SaaS.

Phương pháp 3: Kết nối máy chủ MarkItDown MCP với Claude Code như thế nào?#

MarkItDown ở chế độ CLI có nghĩa là “tôi tự chuyển đổi tệp trước”; máy chủ MCP có nghĩa là “Claude Code tự quyết định khi nào cần chuyển đổi”.

Cài đặt

Bạn cần trình quản lý gói uv. Không cần cài máy chủ riêng; uv sẽ tải máy chủ về trong lần chạy đầu tiên.

Cấu hình trong Claude Code

Một lệnh kết nối máy chủ với mọi dự án của bạn, đồng thời ghim phiên bản:

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

Mục markitdown sẽ hiển thị “Connected.” Lần đầu khởi chạy, uv tải khoảng 70 gói và mất tối đa một phút; sau đó máy chủ khởi động trong một hoặc hai giây.

Đây là lý do lệnh cần hai biến. ORT_DISABLE_TELEMETRY=1 tắt dữ liệu thống kê mà engine onnxruntime bên trong máy chủ mặc định gửi tới Microsoft trên Mac và Linux. UV_PYTHON=3.12 chạy máy chủ bằng Python 3.12, phiên bản có sẵn các gói dựng sẵn cho Windows, Linux và Mac dùng Apple Silicon. Trên Mac Intel và macOS 13 trở xuống, máy chủ không cài được dưới Python 3.14. Có lưu ý đối với Intel và 3.12: uv sẽ dựng thư viện cryptography từ mã nguồn vì không có gói Intel dựng sẵn kể từ tháng 6 năm 2026. Quá trình cài đặt sẽ lâu hơn và có thể thất bại. Nếu bạn chưa có Python 3.12, uv sẽ tải phiên bản này về.

Máy chủ chạy trực tiếp trên máy tính của bạn và có thể mở bất kỳ tệp nào bạn có quyền truy cập. Nếu Claude Code đang mở, hãy khởi động lại; markitdown sẽ xuất hiện trong danh sách máy chủ MCP.

Cách sử dụng

Trong Claude Code, chỉ cần nói:

Chuyển /Users/your-user/Documents/report.pdf sang Markdown và phân tích các ý chính.

Claude tự gọi convert_to_markdown(uri), nhận Markdown và làm việc với nội dung đó — PDF hoàn toàn không được tải vào ngữ cảnh.

URI được hỗ trợ

• file:// - tệp cục bộ
• http://, https:// - tài liệu trực tuyến
• data: - dữ liệu nội tuyến (Base64)

Bảo mật

Trích từ README chính thức:

Theo mặc định, máy chủ chỉ bind với localhost. Nếu chạy qua HTTP/SSE (tùy chọn --http --host 127.0.0.1 --port 3001), đừng mở cổng ra bên ngoài nếu không có reverse proxy được xác thực.

Nên chọn phương pháp nào cho công việc của bạn?#

Bảng so sánh mở rộng:

Marker đưa ra những con số chính xác ấn tượng trong các bài kiểm tra chuẩn:

Nhưng Marker cần GPU để đạt tốc độ tốt và đi kèm các mô hình học máy. Với hầu hết tác vụ (PDF văn bản thông thường), PyMuPDF4LLM hoặc MarkItDown sẽ xử lý được trong vài giây mà không cần GPU.

Quy tắc chọn đơn giản

1. Một hoặc hai PDF, cần xử lý nhanh - MarkItDown CLI.
2. Hàng chục PDF, cần tự động hóa - máy chủ MarkItDown MCP hoặc PyMuPDF4LLM trong tập lệnh.
3. PDF có liên kết và hình ảnh, cần giữ nguyên cấu trúc - PyMuPDF4LLM.
4. RAG production cho doanh nghiệp, cần bảng ổn định - Docling.
5. Bài báo khoa học có công thức - Marker.
6. Không muốn bận tâm, để Claude chuyển đổi - máy chủ MarkItDown MCP.

Viết tập lệnh sẵn dùng để tự động chuyển đổi một thư mục tài liệu như thế nào?#

Ví dụ thực tế: giả sử bạn có 40 báo cáo PDF và PPTX từ khách hàng trong một thư mục — sao kê môi giới, hợp đồng, bản trình bày. Tải cả thư mục trực tiếp lên Claude sẽ vô ích: cửa sổ ngữ cảnh sẽ đầy thông tin trước khi nhận được câu trả lời đầu tiên. Chạy tập lệnh dưới đây một lượt trên toàn bộ thư mục, rồi tiếp tục làm việc với các tệp .md nhẹ thay vì PDF cồng kềnh.

Lưu tập lệnh này thành scripts/docs-to-md.sh trong thư mục gốc của dự án:

#!/bin/bash
# docs-to-md.sh - chuyển đổi mọi tài liệu trong thư mục sang Markdown bằng MarkItDown
# Cách dùng: bash docs-to-md.sh ./documents

set -e

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

mkdir -p "$OUTPUT_DIR"

echo "Scanning $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 "Skipping $basename (already converted)"
    continue
  fi

  echo "Converting $basename..."
  markitdown "$file" > "$output"
done

echo "Done. Results are in $OUTPUT_DIR"

Cho tập lệnh quyền thực thi:

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

Chạy tập lệnh:

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

Sau khi chạy xong, ./reports/_md/ sẽ chứa các phiên bản .md của mọi tài liệu. Đưa chúng vào Claude Code bằng @reports/_md/ và làm việc với văn bản đã nén gọn thay vì PDF.

Tập lệnh tự động bỏ qua những tệp đã được chuyển đổi (nếu tệp .md mới hơn tệp nguồn) — chạy lại rất ít tốn kém và không phải tính toán lại mọi thứ.

Chuyển đổi tăng dần và idempotency

Nếu muốn tập lệnh phát hiện các PDF đã thay đổi (được lưu lại dưới cùng tên), hãy thêm bước kiểm tra content hash:

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

if [ -f "$hash_file" ] && [ "$(cat "$hash_file")" = "$hash" ]; then
  echo "Skipping $basename (hash matches)"
  continue
fi

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

Phiên bản này chỉ chuyển đổi lại tệp khi nội dung của tệp đã thay đổi.

Khi nào dùng PDF trong Claude vẫn tốt hơn Markdown?#

Có ba trường hợp chuyển đổi sang Markdown không đáp ứng được:

1. Phân tích hình ảnh của sơ đồ và biểu đồ

Nếu Claude cần “đọc” biểu đồ — đường giá, sơ đồ quy trình hoặc sơ đồ kiến trúc — thông tin đó không có trong Markdown. Markdown chỉ giữ chú thích hình; bản thân hình ảnh sẽ bị mất.

Giải pháp: tải PDF lên và bật rõ chế độ hình ảnh. Trên Claude API, cờ này hoạt động tự động; trên AWS Bedrock, bạn cần cờ citations.

2. Bảng phức tạp có ô gộp

Bảng Markdown là dạng phẳng. Nếu PDF có bảng chứa ô gộp, tiêu đề nhiều cấp hoặc bảng con lồng nhau, trình chuyển đổi sẽ làm phẳng bảng hoặc làm mất các mối liên hệ.

Giải pháp: dùng PDF trực tiếp, dùng Docling (công cụ xử lý bảng phức tạp tốt nhất) hoặc tự định dạng lại sau khi chuyển đổi.

3. Tài liệu cần trích dẫn theo trang

Với văn bản pháp lý, hợp đồng và biên bản, việc có thể trích dẫn “trang 7, đoạn 3” rất quan trọng. Số trang bị mất trong Markdown.

Giải pháp: PDF + Files API + prompt caching. Tải tệp lên một lần, sau đó tham chiếu bằng file_id; Claude sẽ thấy số trang và có thể trích dẫn trang cụ thể.

Tài liệu ngắn

Nếu PDF ngắn hơn 2 trang và bạn chỉ dùng một lần, chuyển đổi không đáng công. 5,000 token cho PDF so với 800 token cho Markdown không tiết kiệm đủ để biện minh cho việc cài MarkItDown.

Điểm hòa vốn là khoảng 5+ trang hoặc dùng cùng tài liệu 2+ lần. Ít hơn mức đó thì tải PDF trực tiếp; nhiều hơn thì chuyển đổi.

5 lỗi phổ biến nhất khi dùng PDF trong Claude là gì?#

1. Mỗi lần lại tải cùng một PDF lên cuộc trò chuyện mới

Claude Pro giới hạn số tin nhắn trong 5 giờ — một báo cáo 50 trang có thể dùng hết giới hạn trước khi bạn đặt câu hỏi thứ hai.

Có một nguyên tắc đơn giản: một tác vụ — một cuộc trò chuyện. Khi AI bắt đầu tiêu tốn lượng token vô lý, điều đó có nghĩa là bạn đang nhồi nhét mọi thứ vào một cuộc trò chuyện và liên tục đưa PDF vào lại. Hãy dành mỗi cửa sổ cho một tác vụ nhỏ. Chuyển tài liệu sang Markdown một lần, sau đó thêm tệp .md vào mỗi cửa sổ mới cùng với dự án. Vòng tròn cửa sổ ngữ cảnh sẽ không chuyển sang màu vàng.

Giải pháp: chuyển tài liệu sang Markdown một lần hoặc dùng Files API với file_id và prompt caching.

2. Dùng ảnh chụp màn hình thay vì văn bản

Ví dụ điển hình: ai đó muốn cho Claude xem một đoạn mã hoặc bảng, chụp toàn bộ màn hình 1920×1080 rồi thắc mắc vì sao giới hạn cạn sau 5 yêu cầu.

Ảnh chụp màn hình 1000×1000 pixel tốn ~1,300 token. Cùng văn bản đó nếu tự sao chép chỉ tốn 50–100 token. Chênh lệch từ 13 đến 26 lần.

Giải pháp: cắt ảnh thật gọn (chỉ lấy phần quan trọng), hoặc tốt hơn nữa, sao chép trực tiếp văn bản.

3. PDF scan không có OCR

MarkItDown không thể OCR. Nếu chuyển đổi bản scan, kết quả sẽ là tệp .md trống (hoặc 3 dòng nhiễu).

Giải pháp: với bản scan, dùng PyMuPDF4LLM (có smart OCR tích hợp) hoặc Docling.

4. Bỏ qua giới hạn 100 trang

Tài liệu của Anthropic nêu giới hạn 600 trang cho mỗi yêu cầu — nhưng trên thực tế, giới hạn với các mô hình có ngữ cảnh 200K (Sonnet 4.x, Opus 4.x) là 100 trang. Giới hạn 600 trang dành cho mô hình cũ hơn hoặc các gói đặc biệt.

Nếu tải báo cáo 150 trang lên Sonnet 4.6, bạn sẽ nhận lỗi hoặc, tệ hơn, Claude chỉ xử lý 100 trang đầu rồi hành xử như thể đã đọc toàn bộ tài liệu.

Giải pháp: chia PDF dài thành nhiều phần trước khi tải lên. Hoặc chuyển sang Markdown — không có giới hạn trang, chỉ có giới hạn token.

5. Không dùng prompt caching cho yêu cầu lặp lại

Nếu làm việc với cùng một tài liệu qua API, hãy đặt tài liệu trong cache_control: ephemeral. Các lần gọi lại trong vòng 5 phút chỉ tốn 10% giá ban đầu. Yêu cầu đầu tiên tốn nhiều hơn; các yêu cầu còn lại được giảm 90%.

Giải pháp: bật prompt caching theo mặc định cho mọi nội dung bạn tải lên nhiều hơn một lần.

Tiếp theo: context engineering#

PDF-to-Markdown là một cách tiết kiệm token. Tự nó không giúp câu trả lời của Claude chính xác hơn. Độ chính xác đến từ context engineering — lĩnh vực nghiên cứu những gì bạn đưa vào ngữ cảnh của mô hình trước khi đặt câu hỏi.

Nếu CLAUDE.md của bạn có 800 dòng, dự án có 10 máy chủ MCP không cần thiết và bạn đưa vào một PDF 100 trang, chuyển đổi Markdown sẽ ngăn được một chỗ thất thoát, nhưng ba chỗ còn lại vẫn còn đó. Đó là lý do các hướng dẫn này đề cập đến:

• Token được dùng vào đâu trong Claude Code - 9 kiểu thất thoát ngữ cảnh, không chỉ riêng PDF.
• Context Engineering in 2026 - quản lý ngữ cảnh một cách có hệ thống.
• Plan Mode trong Claude Code - chế độ lập kế hoạch trước khi Claude bắt đầu viết mã.