MarkItDown Hướng dẫn cài đặt chi tiết, tiết kiệm token

Mỗi lần tải một file PDF lên Claude, chi phí thực tế cao hơn nhiều so với lượng chữ có trong tài liệu. Nguyên nhân nằm ở cách Claude xử lý PDF, và đã có một công cụ miễn phí giải quyết được việc này.

Tài liệu trình bày rõ chi phí phát sinh từ đâu, hướng dẫn cài đặt từng bước, các lệnh dùng hằng ngày, cách thiết lập để Claude tự động chuyển đổi file, cùng những trường hợp không nên dùng MarkItDown.

Người đọc không cần biết lập trình. Toàn bộ thao tác chỉ gồm sao chép và dán một dòng lệnh.

1. Giải thích các thuật ngữ trong tài liệu

Tài liệu có một số thuật ngữ chuyên môn. Bấm vào thuật ngữ nào chưa rõ để mở phần giải thích, chỗ nào đã biết thì bỏ qua.

2. Vì sao mỗi trang PDF bị tính hai lần

Đây là thông tin ít người biết, dù được ghi rõ trong tài liệu chính thức của Anthropic (công ty phát triển Claude).[1]

Khi nhận một file PDF, Claude không chỉ đọc phần chữ. Quy trình thực tế gồm ba bước:

1. Claude biến từng trang PDF thành một tấm ảnh.
2. Claude rút chữ của từng trang ra.
3. Claude nhận cả hai, ảnh và chữ, cùng lúc cho mỗi trang.

Nguyên văn tài liệu của Anthropic ghi rằng hệ thống chuyển mỗi trang của tài liệu thành một ảnh, rồi phần chữ của trang đó được rút ra và đưa kèm theo ảnh. Tức là tài liệu được nạp vào dưới dạng chữ cộng ảnh.[1]

Cách xử lý này có lý do hợp lý: Nhờ có ảnh, Claude đọc được biểu đồ, sơ đồ, chữ ký và bảng vẽ phức tạp. Vấn đề nằm ở chỗ người dùng phải trả cho cả hai phần, kể cả khi tài liệu chỉ có chữ và phần ảnh không mang thêm thông tin nào.

Minh hoạ bằng con số

Các giới hạn cần biết

Cũng theo tài liệu Anthropic, một yêu cầu gửi kèm PDF bị giới hạn 32 MB và tối đa 600 trang (chỉ 100 trang nếu bạn dùng model có cửa sổ ngữ cảnh nhỏ hơn 1 triệu token). Tài liệu cũng cảnh báo rằng PDF dày đặc, chữ nhỏ, bảng phức tạp, nhiều hình có thể làm tràn bộ nhớ ngữ cảnh trước khi chạm tới giới hạn số trang.[1]

Nói cách khác, không phải cứ dưới 600 trang là an toàn. Chuyển sang markdown là cách đơn giản nhất để nới rộng cả hai giới hạn này.

3. MarkItDown là gì và giải quyết được vấn đề gì

MarkItDown là công cụ mã nguồn mở, miễn phí, do Microsoft phát hành. Chức năng của công cụ gói gọn trong một câu: Nhận vào một file tài liệu và trả ra file markdown sạch để AI đọc.[3]

Repo của nó đang có hơn 180.000 sao trên GitHub (tính tới tháng 9/2026), thuộc nhóm những dự án được quan tâm nhất trong lĩnh vực xử lý tài liệu cho AI.[3]

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

Theo tài liệu của repo, MarkItDown xử lý được: PDF, Word, Excel, PowerPoint, ảnh (đọc thông tin EXIF và OCR), âm thanh (đọc EXIF và tạo bản ghi lời nói), HTML, các định dạng bảng biểu như CSV, JSON, XML, file ZIP, EPub, và cả link YouTube.[3]

• Tài liệu văn phòng: PDF, .docx, .xlsx, .pptx. Đây là nhóm định dạng được dùng nhiều nhất.
• Dữ liệu: CSV, JSON, XML. Bảng số liệu ra bảng markdown gọn gàng.
• Web và sách: HTML, EPub, và link YouTube (lấy phần transcript).
• File nén: Với một file ZIP, công cụ tự mở và chuyển đổi từng file bên trong.

Quy trình tổng quan

4. Cài MarkItDown trong 5 phút

Phần này dành cho người chưa từng mở Terminal. Thực hiện lần lượt bốn bước dưới đây.

python3 --version

pip install 'markitdown[all]'

pip install "markitdown[all]"

markitdown tailieu.pdf -o tailieu.md

markitdown baocao.xlsx -o baocao.md
markitdown ketoan.docx -o ketoan.md

5. Những lệnh bạn sẽ dùng hằng ngày

Trong thực tế chỉ cần nhớ khoảng năm lệnh, tất cả đều có trong tài liệu chính thức của repo.[3]

Ghi kết quả ra file

markitdown baocao.pdf -o baocao.md
markitdown baocao.pdf > baocao.md

Dòng thứ hai dùng dấu lớn hơn để ghi kết quả vào file. Cả hai cách cho kết quả như nhau.

Xem nhanh mà không tạo file

Bỏ phần -o thì kết quả in thẳng ra màn hình. Cách này hữu ích khi chỉ cần kiểm tra nhanh xem file có đọc được hay không.

markitdown baocao.pdf

Chuyển cả một thư mục trong một lần

Lệnh này hữu ích khi cần xử lý tài liệu theo lô. Nó duyệt qua mọi file PDF trong thư mục hiện tại và tạo file markdown tương ứng.

for f in *.pdf; do markitdown "$f" -o "${f%.pdf}.md"; done

Nếu không muốn gõ dòng lệnh trên, phần 7 có sẵn script thực hiện đúng việc này cho cả Mac và Windows, chỉ cần tải về và chạy.

Bật OCR cho PDF scan

MarkItDown có thể sử dụng dịch vụ Azure Document Intelligence của Microsoft để đọc PDF scan. Dịch vụ này yêu cầu tài khoản Azure và có phí riêng, nên phần này dành cho người đã sử dụng Azure.

markitdown banscan.pdf -o banscan.md -d -e "<endpoint-cua-ban>"

Xem các plugin đang có

MarkItDown cho phép cài thêm plugin, là các bản mở rộng do cộng đồng viết để hỗ trợ thêm những định dạng ít gặp.

markitdown --list-plugins
markitdown --use-plugins tailieu.pdf -o tailieu.md

6. Cài MCP server: Để Claude tự chuyển file

Phần này dành cho người dùng Claude Desktop hằng ngày. Microsoft phát hành một MCP server chính thức cho MarkItDown. Sau khi cài, Claude tự chuyển file sang markdown khi cần và người dùng không phải mở Terminal nữa.[5]

{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp"
    }
  }
}

Chức năng của MCP server

MCP server cung cấp cho Claude đúng một công cụ tên convert_to_markdown, nhận vào một địa chỉ file và trả về markdown. Địa chỉ có thể là http:, https:, file: hoặc data:.[5] Nhờ đó Claude chuyển đổi được cả một trang web hoặc một file trên máy, không riêng PDF.

7. Script và prompt copy là dùng

Năm nội dung dưới đây copy thẳng từ trang này, khỏi phải gõ lại. Bấm Copy ở góc phải mỗi ô, dán vào đúng chỗ theo chú thích là xong.

Bộ công cụ MarkItDown cho người mới

4 file Mac và Windows Không cần biết code

Gồm file cấu hình MCP dán thẳng vào Claude Desktop, hai script chuyển đổi cả thư mục (một cho Mac và Linux, một cho Windows), và một file hướng dẫn ngắn. Script tự tạo thư mục markdown bên trong thư mục nguồn và đặt kết quả vào đó, nên file gốc không bị thay đổi.

{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp"
    }
  }
}

#!/usr/bin/env bash
# ------------------------------------------------------------
# Chuyen doi ca thu muc sang Markdown bang MarkItDown
# Danh cho Mac va Linux. Yeu cau: da cai markitdown truoc
#   pip install 'markitdown[all]'
#
# Cach dung trong Terminal:
#   bash chuyen-doi-ca-thu-muc.sh "/duong/dan/den/thu-muc"
# Bo trong duong dan thi script chay tren thu muc hien tai.
# Ket qua duoc dat trong thu muc con ten "markdown".
# File goc khong bi thay doi.
# ------------------------------------------------------------
set -uo pipefail

SRC="${1:-.}"

if [ ! -d "$SRC" ]; then
  echo "Khong tim thay thu muc: $SRC"
  exit 1
fi

OUT="$SRC/markdown"
mkdir -p "$OUT"

shopt -s nullglob nocaseglob

ok=0
fail=0

for f in "$SRC"/*.pdf "$SRC"/*.docx "$SRC"/*.pptx "$SRC"/*.xlsx "$SRC"/*.csv "$SRC"/*.html "$SRC"/*.epub; do
  base="$(basename "$f")"
  name="${base%.*}"
  echo "Dang chuyen: $base"
  if markitdown "$f" -o "$OUT/$name.md" 2>/dev/null; then
    ok=$((ok + 1))
  else
    echo "  Bo qua, khong doc duoc: $base"
    fail=$((fail + 1))
  fi
done

echo ""
echo "Xong. Thanh cong: $ok file. Bo qua: $fail file."
echo "Ket qua nam trong: $OUT"
echo "Luu y: File nao ra gan nhu trong thi ban goc la ban scan, can OCR."

@echo off
REM ------------------------------------------------------------
REM Chuyen doi ca thu muc sang Markdown bang MarkItDown
REM Danh cho Windows. Yeu cau: da cai markitdown truoc
REM   pip install "markitdown[all]"
REM
REM Cach dung de nhat: Keo-tha thu muc can chuyen vao file .bat nay.
REM Hoac chay trong Command Prompt:
REM   chuyen-doi-ca-thu-muc.bat "D:\Tai lieu\Hop dong"
REM
REM Ket qua duoc dat trong thu muc con ten "markdown".
REM File goc khong bi thay doi.
REM ------------------------------------------------------------
setlocal enabledelayedexpansion

set "SRC=%~1"
if "%SRC%"=="" set "SRC=%CD%"

if not exist "%SRC%\" (
  echo Khong tim thay thu muc: %SRC%
  pause
  exit /b 1
)

set "OUT=%SRC%\markdown"
if not exist "%OUT%" mkdir "%OUT%"

set /a OK=0
set /a FAIL=0

for %%E in (pdf docx pptx xlsx csv html epub) do (
  for %%F in ("%SRC%\*.%%E") do (
    echo Dang chuyen: %%~nxF
    markitdown "%%~fF" -o "%OUT%\%%~nF.md" 2>nul
    if errorlevel 1 (
      echo   Bo qua, khong doc duoc: %%~nxF
      set /a FAIL+=1
    ) else (
      set /a OK+=1
    )
  )
)

echo.
echo Xong. Thanh cong: !OK! file. Bo qua: !FAIL! file.
echo Ket qua nam trong: %OUT%
echo Luu y: File nao ra gan nhu trong thi ban goc la ban scan, can OCR.
pause

# Bộ công cụ MarkItDown cho người mới

Tài liệu kèm theo bài hướng dẫn của kênh Cường Mê AI.
Các file trong gói này do kênh soạn, không phải file gốc của Microsoft.
Bản gốc của MarkItDown: https://github.com/microsoft/markitdown

## Trong gói có gì

1. `claude-desktop/claude_desktop_config.json`
   Cấu hình để cắm MarkItDown vào Claude Desktop qua MCP.
2. `scripts/chuyen-doi-ca-thu-muc.sh`
   Script chuyển cả thư mục sang markdown, dùng cho Mac và Linux.
3. `scripts/chuyen-doi-ca-thu-muc.bat`
   Script tương tự, dùng cho Windows.
4. `prompt/doc-tai-lieu-markdown.txt`
   Prompt để nhờ Claude phân tích tài liệu sau khi đã chuyển đổi.

## Bước 1: Cài MarkItDown

Mở Terminal (Mac) hoặc Command Prompt (Windows), chạy:

    pip install 'markitdown[all]'

Trên Windows PowerShell dùng dấu nháy kép:

    pip install "markitdown[all]"

Nếu trên Mac báo lỗi externally-managed-environment, cài qua pipx:

    brew install pipx
    pipx install 'markitdown[all]'

## Bước 2: Chuyển thử một file

    markitdown tailieu.pdf -o tailieu.md

Mở file .md vừa tạo ra xem. Nếu gần như trống, file gốc là bản scan.

## Bước 3: Chuyển cả thư mục

Mac và Linux:

    bash scripts/chuyen-doi-ca-thu-muc.sh "/duong/dan/den/thu-muc"

Windows: Kéo thư mục cần chuyển thả vào file
`scripts/chuyen-doi-ca-thu-muc.bat`.

Kết quả nằm trong thư mục con tên `markdown`. File gốc không bị đụng tới.

## Bước 4: Cắm vào Claude Desktop (tuỳ chọn)

    pip install markitdown-mcp

Mở Claude Desktop, vào Settings, tab Developer, bấm Edit Config,
dán nội dung file `claude-desktop/claude_desktop_config.json` vào,
lưu lại, rồi tắt hẳn Claude Desktop và mở lại.

Nếu file cấu hình của bạn đã có mục mcpServers với công cụ khác,
chỉ thêm khối markitdown vào bên trong và nhớ dấu phẩy phân tách.

## Lưu ý quan trọng

- MarkItDown không tự đọc được PDF scan. Cần bật OCR qua Azure
  Document Intelligence, hoặc dùng cách khác cho nhóm file đó.
- Tài liệu mà thông tin nằm ở biểu đồ, sơ đồ, hình vẽ thì bản
  markdown sẽ mất phần đó. Trường hợp này nên giữ file gốc.
- Luôn mở file .md ra soát nhanh trước khi tin vào nội dung.

Prompt đọc tài liệu sau khi chuyển đổi

1 prompt Dán là dùng

Prompt dành cho tài liệu dài sau khi đã chuyển đổi. Nội dung prompt buộc Claude trích dẫn đúng vị trí trong tài liệu và nêu rõ khi không tìm thấy thông tin, thay vì suy đoán.

Bạn là trợ lý đọc tài liệu. Dưới đây là một tài liệu đã được chuyển
sang markdown, nên phần chữ là chính xác nhưng hình ảnh, biểu đồ và
sơ đồ trong bản gốc đã không còn.

Hãy làm theo đúng thứ tự sau:

1. Tóm tắt tài liệu trong tối đa 8 gạch đầu dòng. Mỗi dòng một ý,
   viết bằng tiếng Việt đơn giản, không dùng từ chuyên môn nếu
   không cần thiết.

2. Liệt kê những con số, ngày tháng, tên riêng và điều khoản quan
   trọng. Với mỗi mục, ghi kèm tiêu đề của phần chứa nó trong tài
   liệu để tôi tra lại được.

3. Nêu tối đa 5 điểm cần chú ý: Chỗ nào có thể gây rủi ro, mâu
   thuẫn, hoặc diễn đạt mơ hồ.

4. Nêu những chỗ tài liệu nhắc tới hình ảnh, biểu đồ, bảng vẽ hoặc
   phụ lục mà nội dung không có trong phần chữ. Đây là những chỗ
   tôi cần mở lại bản gốc để xem.

Quy tắc bắt buộc:

- Chỉ dùng thông tin có trong tài liệu. Không suy đoán, không bổ
  sung kiến thức bên ngoài.
- Nếu tôi hỏi một điều mà tài liệu không nói, hãy trả lời thẳng:
  "Tài liệu không đề cập chuyện này."
- Khi trích một câu, trích nguyên văn và đặt trong ngoặc kép.
- Nếu phát hiện phần nội dung bị cắt hoặc lỗi định dạng, nói cho
  tôi biết ngay ở đầu câu trả lời.

Tài liệu bắt đầu từ đây:

8. Khi nào MarkItDown không phù hợp

Phần này ít được đề cập nhưng rất quan trọng. Chuyển sang markdown là một sự đánh đổi: Bỏ phần hình ảnh để tiết kiệm token. Trong một số trường hợp, chính phần hình ảnh mới là thông tin cần thiết.

Ba trường hợp nên giữ file gốc

• PDF là bản scan: Tức ảnh chụp hoặc bản quét của trang giấy. MarkItDown không có chữ để trích xuất nên file markdown gần như trống. Ngược lại, Claude đọc bản scan khá tốt chính vì nó xử lý được ảnh. Với nhóm file này, cần bổ sung OCR hoặc giữ nguyên bản gốc.
• Thông tin nằm ở biểu đồ, sơ đồ, hình vẽ: Báo cáo tài chính có đồ thị, bản vẽ kỹ thuật, sơ đồ quy trình. Phần chữ chỉ chứa một phần thông tin, phần còn lại nằm trong hình, và chuyển sang markdown sẽ mất phần hình.
• Bố cục quyết định ý nghĩa: Biểu mẫu nhiều ô, hoá đơn, bảng lồng bảng, tài liệu hai cột. Khi bố cục bị làm phẳng thành chữ, thứ tự đọc có thể lệch và số liệu dễ ghép sai chỗ.

Phương án dung hoà

Không nhất thiết phải chọn một trong hai. Với tài liệu vừa nhiều chữ vừa có hình, có thể làm như sau:

1. Chuyển sang markdown để Claude đọc toàn bộ phần chữ với chi phí thấp.
2. Đặt câu hỏi và làm việc chủ yếu trên bản markdown.
3. Khi cần đúng một biểu đồ hoặc một trang cụ thể, chỉ cắt riêng trang đó để gửi kèm. Chi phí khi đó chỉ tính cho một ảnh thay vì hai mươi ảnh.

9. Thói quen giúp tiết kiệm lượt dùng lâu dài

• Từ vài trang trở lên nên chuyển đổi: Với file một hai trang, khác biệt không đáng kể. Từ khoảng năm trang trở lên, chi phí phát sinh từ ảnh bắt đầu rõ rệt. Hợp đồng, báo cáo và hồ sơ dài là nhóm tiết kiệm được nhiều nhất.
• Đưa việc chuyển đổi thành bước cố định: Nếu công việc hằng ngày là xử lý tài liệu khách hàng, không nên chuyển từng file khi cần. Chạy script chuyển cả thư mục một lần vào đầu ngày.
• Giữ lại file markdown: File nhẹ, tìm kiếm được bằng công cụ tìm kiếm của máy tính và dùng lại cho những lần sau mà không phải chuyển đổi lại.
• Cắt bớt phần không cần thiết: File markdown là chữ thuần nên việc xoá vài chương không liên quan chỉ mất vài giây, điều không làm được với PDF. Đây là khoản tiết kiệm ít người để ý.
• Chia nhỏ tài liệu quá dài: Tài liệu của Anthropic cũng khuyến nghị chia tài liệu lớn thành từng phần thay vì nạp toàn bộ một lần.[1] Với markdown, việc chia theo chương rất dễ thực hiện.
• Dùng MCP server nếu làm việc thường xuyên trong Claude Desktop: Cài một lần và dùng lâu dài, chỉ cần nhớ gửi đường dẫn thay vì kéo file vào khung chat.

10. Câu hỏi thường gặp

11. Tóm tắt nhanh