Cách chuyển tệp PDF và Word thành văn bản cho AI: MarkItDown của Microsoft

Xem thêm hướng dẫn trong tài liệu Ailoot.

MarkItDown là gì và dùng để làm gì?#

Bạn gửi cho AI một hợp đồng, báo cáo hoặc tệp xuất kế toán, rồi nhận được câu trả lời chẳng liên quan gì đến tài liệu. Nguyên nhân thường không phải do mô hình. Tệp chứa một định dạng: Word là kho lưu trữ có đánh dấu, Excel là bảng tính với các liên kết giữa ô, còn PDF là tập hợp ký tự có tọa độ trên trang. Mô hình làm việc với văn bản, và phải có người trích xuất văn bản đó.

Đó là việc MarkItDown đảm nhiệm. Kho mã nằm tại github.com/microsoft/markitdown, theo giấy phép MIT, vì vậy bạn có thể sử dụng mà không bị hạn chế. Tính đến ngày 18 tháng 8 năm 2026, dự án có 174,412 sao và 12,756 lượt phân nhánh; bản phát hành mới nhất, 0.1.7, ra mắt ngày 29 tháng 7. Dự án vẫn hoạt động, nhưng trọng tâm đã chuyển từ phát triển sang bảo trì: có 481 yêu cầu kéo đang mở, so với 183 yêu cầu đã được hợp nhất trong toàn bộ lịch sử dự án.

Nhà phát triển mô tả mục đích của công cụ như sau:

Câu tiếp theo trong phần mô tả giải thích một nửa những lời phàn nàn về công cụ này:

Kết quả là nguyên liệu thô cho mô hình. Nó sẽ không phải một tài liệu đẹp mắt, và dự án nói thẳng điều đó ngay trong phần đầu tiên.

Phần mô tả giải thích trực tiếp vì sao công cụ dùng Markdown: các mô hình hàng đầu đã “nói” được ngôn ngữ đánh dấu này và tự đưa nó vào câu trả lời mà không cần yêu cầu, vì chúng đã thấy khối lượng lớn nội dung dạng đó trong quá trình huấn luyện. Ngôn ngữ đánh dấu cũng gọn: ba dấu thăng cho một tiêu đề thay vì cả chục dòng siêu dữ liệu.

MarkItDown khác trình chuyển đổi thông thường như thế nào?#

Chỉ cần một ví dụ là thấy rõ sự khác biệt. Hãy lấy một thư mục có hai mươi tệp PDF và thử xử lý chúng bằng pandoc. Sẽ không được: pandoc có thể tạo PDF làm đầu ra, nhưng không thể đọc PDF làm đầu vào. Và tình huống “Tôi có cả chồng tài liệu; hãy đưa chúng cho mô hình” là tình huống thường gặp nhất.

Tác giả MarkItDown so sánh công cụ của họ với textract, một thư viện chỉ đơn giản trích xuất văn bản từ bất cứ đâu. Điểm khác biệt là MarkItDown cố gắng giữ lại cấu trúc: tiêu đề, danh sách, bảng và liên kết.

Kết luận thực tế rất đơn giản. Nếu bạn cần chuyển một bài viết thành bố cục để xuất bản, hãy dùng pandoc. Nếu bạn cần AI hiểu hai mươi hợp đồng, hãy dùng MarkItDown.

Cài đặt MarkItDown thế nào để không nhận nhầm bản phát hành đầu tiên?#

Trước tiên là lệnh đúng; sau đó là lý do vì sao nó đúng.

1. Kiểm tra phiên bản Python

   Python 3.12 đáng tin cậy nhất: MarkItDown mới nhất cài đặt được trong mọi môi trường đã thử nghiệm trên phiên bản này. Lệnh python3 --version cho biết bạn đang dùng phiên bản nào. Trên máy Mac Intel hoặc máy Mac chạy phiên bản macOS cũ hơn, Python 3.13 và 3.14 có thể âm thầm hạ phiên bản; Python 3.15 chưa được hỗ trợ, như giải thích bên dưới.

2. Cài đặt với các định dạng được liệt kê

   Chạy pip install 'markitdown[pdf,docx,xlsx,pptx]'. Dấu nháy là bắt buộc, nếu không shell sẽ diễn giải các dấu ngoặc vuông. Trên máy Mac Intel, thêm cờ --prefer-binary sau install.

3. Kiểm tra ngay xem đã cài đặt đúng chưa

   Chạy markitdown --version. Kết quả phải là markitdown 0.1.8 trở lên. Số thấp hơn nghĩa là quá trình cài đặt đã hạ phiên bản; phần này giải thích nguyên nhân.

pip install 'markitdown[pdf,docx,xlsx,pptx]'
markitdown --version

Phần mô tả dự án liệt kê pip install 'markitdown[all]' làm lệnh chính để cài tất cả cùng lúc. Ngày 28 tháng 9 năm 2026, một tuần sau khi 0.1.8 ra mắt, bốn biến thể đã được chạy trong các môi trường sạch trên máy Mac Apple Silicon với Python 3.14.6 và 3.12.12:

Cả tám lần cài đặt đều kết thúc bằng “Successfully installed”, và markitdown --version trả về 0.1.8 trong mọi trường hợp. Vào tháng 8, khi 0.1.7 là bản phát hành mới nhất, lệnh thứ ba trên Python 3.14 đã cài 0.0.2, phát hành ngày 8 tháng 3 năm 2025 — bản phát hành thứ hai trong lịch sử dự án. Hiện dự án có mười một bản phát hành ổn định, từ 0.0.1 đến 0.1.8, và hai mươi sáu bản nếu tính cả bản phát hành trước.

Nguyên nhân nằm ở chuỗi phụ thuộc. Trong 0.1.7, phần bổ sung [all] kéo theo một thư viện phụ đề YouTube thuộc một nhánh phát hành cụ thể; mọi bản phát hành trong nhánh đó đều tuyên bố không hoạt động trên Python 3.14. Trình cài đặt từ chối chúng và, vì không ghim phiên bản, lùi dần qua các phiên bản MarkItDown cho đến khi tìm được phiên bản có thể cài. Nó tìm thấy 0.0.2 và cài bản đó, đưa một bản phát hành từ một năm rưỡi trước lên máy bạn. Trong 0.1.8, yêu cầu về thư viện phụ đề được nâng lên một nhánh hoạt động trên 3.14, và việc hạ phiên bản dừng lại.

Cơ chế này vẫn còn đó. Nếu trình cài đặt không tìm thấy một thành phần bắt buộc cho hệ thống của bạn, nó vẫn âm thầm lùi về 0.0.2 theo cách tương tự. Trong các phiên bản gần đây, thành phần đó là bộ máy onnxruntime dùng để nhận diện loại tệp. Trên Mac, thành phần này được xây dựng như sau: với Python 3.12, macOS 11 trở lên; với 3.13, macOS 13; với 3.14, chỉ Apple Silicon chạy macOS 14 trở lên. Nếu máy Mac không đáp ứng các yêu cầu đó, ngay cả lệnh cơ bản pip install markitdown cũng cài 0.0.2. Một lần thử trên máy Mac Intel chạy Python 3.14 qua Rosetta cho kết quả đúng như vậy: “Successfully installed”, không cảnh báo và bên trong là 0.0.2.

Máy Mac Intel còn có một vấn đề khác. Từ tháng 6 năm 2026, thư viện cryptography được kéo theo để đọc PDF không còn được phát hành kèm bản dựng sẵn cho bộ xử lý này, nên trình cài đặt cố gắng biên dịch từ mã nguồn. Thêm cờ --prefer-binary vào lệnh để dùng phiên bản trước có gói dựng sẵn. Khi thử nghiệm trên Python 3.13 cho Intel, lệnh cài 0.1.8 và mở được PDF. Cờ này cài cryptography 48.0.1, phiên bản có ba lỗ hổng đã biết: trong giải mã PKCS#7 và xác minh chuỗi chứng chỉ. MarkItDown chỉ dùng nó để giải mã PDF được mã hóa, còn việc đọc tài liệu không chạm đến những phần đó.

Với Python 3.15, việc hạ phiên bản xảy ra vì hai lý do. Phiên bản 0.1.8 chỉ tuyên bố hỗ trợ từ 3.10 đến 3.14, và chưa có bộ máy cho 3.15. Kết quả phân giải của trình cài đặt cho 3.15 xác nhận điều này: cả lệnh cơ bản lẫn lệnh kèm định dạng đều cài cùng một bản 0.0.2.

Cảnh báo hạ phiên bản trông như sau, mỗi phần bổ sung trong lệnh có một dòng:

WARNING: markitdown 0.0.2 does not provide the extra 'all'

Dòng cảnh báo dễ bị lẫn giữa hàng chục dòng tải xuống, và không cho biết phiên bản nào đang được thay thế. Với lệnh cơ bản không có phần bổ sung, thậm chí cũng không có cảnh báo. Báo cáo cuối cùng vẫn rất vui vẻ: “Successfully installed.”

Cài đặt không có phần bổ sung cũng không giải quyết được vấn đề. Gói cơ bản được cài, nhưng không mở được 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]'

Bản thân công cụ khuyên dùng [all], và với 0.1.8, lời khuyên đó lại hoạt động trên Python 3.14 và 3.12. Dù vậy, tốt hơn là liệt kê tên các định dạng: [all] thêm khoảng mười lăm gói nữa và khoảng 55 megabyte, bao gồm một thư viện Azure phát hành trước và chính chuỗi phụ thuộc YouTube từng làm hỏng quá trình cài đặt.

Trình cài đặt tự xử lý bản phát hành trước của Azure. Thông thường pip bỏ qua các bản phát hành trước, nhưng ở đây yêu cầu ghi rõ một bản phát hành trước nên nó cài đặt bản đó. Bốn phiên bản pip, từ 23.2 đến 26.2, đã được thử trên Python 3.12; tất cả đều chọn 0.1.8.

Tháng 8, cài lại trong một môi trường sạch khác vẫn cho cùng kết quả: 0.0.2 và chữ “Successfully”.

Có một số chi tiết thực tế nên biết trước.

Gói khá lớn: cài đặt cơ bản chiếm 143 megabyte; với bốn định dạng là 303. Thành phần nặng nhất, 81 megabyte, là bộ nhận diện loại tệp, được kéo theo ngay cả trong cài đặt cơ bản. Điều này không quan trọng với máy tính xách tay, nhưng có thể quan trọng với hàm đám mây bị giới hạn kích thước.

Đừng trông cậy vào máy nhân bản làm phương án dự phòng. Một máy nhân bản đã thử cung cấp chỉ mục và có các tệp MarkItDown, nhưng thiếu một phụ thuộc bắt buộc nên cài đặt thất bại trên cả Python 3.14 và 3.12.

Cài đặt chỉ là chuyện nhỏ so với vấn đề chính. Thường thì AI tạo ra nội dung vô nghĩa vì thứ được đưa vào cửa sổ ngữ cảnh không phù hợp, hoặc được biểu diễn theo cách sai. Khả năng quyết định nên đưa gì cho mô hình trước khi giao nhiệm vụ được gọi là kỹ thuật ngữ cảnh, và chuẩn bị tài liệu là một phần của việc đó.

Làm thế nào để chuyển tài liệu đầu tiên thành văn bản?#

Cách ngắn nhất:

markitdown dogovor.docx

Văn bản sẽ in trong terminal. Có hai cách lưu thành tệp:

markitdown dogovor.docx -o dogovor.md
markitdown dogovor.docx > dogovor.md

Sự khác biệt không đáng kể trên Mac và Linux, nhưng quan trọng trên Windows: chuyển hướng bằng > có thể làm chương trình gặp sự cố khi đầu ra chứa chữ Cyrillic.

Bạn có thể truyền tệp dưới dạng luồng; trong trường hợp đó, gợi ý phần mở rộng sẽ hữu ích:

cat dogovor.docx | markitdown -x docx

Dưới đây là các cờ chính trong phần trợ giúp của 0.1.8:

Phần trợ giúp cũng liệt kê ba cờ hữu ích khác, mỗi cờ đều đã được thử nghiệm: --list-plugins hiển thị các plugin đã cài, -p bật chúng cho một lần chạy cụ thể, còn --keep-data-uris giữ lại hình ảnh được nhúng trong tài liệu trong đầu ra (mặc định chúng bị cắt bỏ). Các mục còn lại là cài đặt cho dịch vụ đám mây của Microsoft.

Lớp bao Python chỉ gồm ba dòng:

from markitdown import MarkItDown

md = MarkItDown()
print(md.convert("ostatki.xlsx").text_content)

Lệnh tương tự cũng chấp nhận URL. Một trang đơn giản trả về văn bản gọn gàng dài 167 ký tự, gồm một tiêu đề và một liên kết, không có menu và chân trang:

r = md.convert("https://example.com")

MarkItDown hiểu những định dạng nào, và điều đó thực sự có nghĩa gì?#

Bảng tóm tắt tuyên bố và ý nghĩa thực tế:

Chi tiết hơn về ba mục.

Hình ảnh. Phần mô tả có từ OCR, khiến mọi người kỳ vọng chương trình đọc được văn bản trong ảnh. Thực tế không phải vậy. Công cụ đọc siêu dữ liệu bằng một chương trình riêng là exiftool; nếu kết nối mô hình thị giác bằng khóa của bạn, nó có thể gửi ảnh đến mô hình để tạo mô tả.

Âm thanh. Có thể phiên âm lời nói, nhưng ngôn ngữ không được truyền đi và bộ máy mặc định mong đợi tiếng Anh. Công cụ còn gọi đến điểm cuối miễn phí không chính thức của Google, giới hạn khoảng năm mươi yêu cầu mỗi ngày cho mỗi khóa.

Kho lưu trữ. Chương trình giải nén tệp ZIP và duyệt qua các tệp bên trong, nối kết quả lại. Nếu không phân tích được một tệp, lỗi sẽ bị bắt và loại bỏ. Tệp đó đơn giản là không xuất hiện trong kết quả, còn bạn sẽ không biết.

Điều gì xảy ra với tài liệu có chữ Cyrillic?#

Các tệp bên dưới được tạo riêng để thử nghiệm; dữ liệu là giả.

Bảng kiểm kê Excel cũng cho kết quả gọn gàng, tên trang tính được chuyển thành tiêu đề:

## Stock
| Item | In stock | Reserved | Available |
| --- | --- | --- | --- |
| Coffee beans, kg | 420 | 38 | 382 |
| Loose-leaf tea, kg | 180 | 52 | 128 |

Bản trình bày được chuyển thành văn bản, số trang xuất hiện dưới dạng chú thích và tiêu đề trang trình bày trở thành tiêu đề. Chữ Cyrillic ở đây cũng nguyên vẹn. Tuyên bố chung rằng “MarkItDown không hiểu tiếng Cyrillic” là sai.

Giờ đến ba chỗ xảy ra lỗi.

CSV dùng dấu chấm phẩy. Hai tệp xuất hóa đơn giống hệt nhau đã được chạy để so sánh. Tệp dùng dấu phẩy tạo thành bảng bốn cột đúng chuẩn. Với dấu chấm phẩy, cả dòng bị đưa vào một ô.

Toàn bộ dòng nằm trong một ô. Mã hóa được nhận diện chính xác và không có lỗi; cờ -c không giúp được. Mô hình sẽ nhận bảng này mà không hiểu giá trị nào là số tiền, giá trị nào là trạng thái. Xuất lại với delimiter dấu phẩy tường minh và encoding đúng, giữ gốc nguyên. Không thay dấu chấm phẩy toàn cục: ký tự trong ô có nháy và dấu phẩy thập phân có thể thuộc giá trị. Nếu không xuất lại được, đọc gốc bằng delimiter thật rồi dùng trình ghi hiểu CSV để giữ quoting và giá trị ô. Trước phân tích, so số cột, dòng và tổng kiểm soát với bản xuất nguồn.

Định dạng tiền tệ trong Excel. Ký hiệu tiền tệ được lưu trong cài đặt hiển thị của ô, không nằm trong chính giá trị. Những người bảo trì dự án đã xác nhận nguyên nhân. Với bảng giá hoặc hóa đơn, điều này rất quan trọng: mô hình sẽ thấy các con số nhưng không biết chúng biểu thị loại tiền nào.

Console Windows. Với tệp có ký tự không phải chữ Latin, chương trình có thể gặp sự cố.

Dấu vết lỗi cho thấy mã hóa cp1251, tức console Windows. Bản thân tài liệu được phân tích đúng; việc in kết quả trong cửa sổ terminal mới là phần bị lỗi. Có hai cách khắc phục:

markitdown dogovor.docx -o dogovor.md
$env:PYTHONUTF8 = "1"; markitdown dogovor.docx > dogovor.md

Cách thứ nhất bỏ qua hoàn toàn console; cách thứ hai buộc Python ghi bằng UTF-8. Ít nhất sáu lần, mọi người đã gửi bản sửa cho chính công cụ: một số đề xuất bị đóng mà không hợp nhất, còn lại vẫn đang mở. Vì vậy bạn phải tự khắc phục.

PDF có một triệu chứng thứ tư: các chuỗi như (cid:1090) xuất hiện thay cho chữ cái. Điều đó có nghĩa tệp có bảng phông chữ không tiêu chuẩn và không thể giải mã ký tự. Không cần mất công xử lý tài liệu như vậy bằng MarkItDown; bạn cần công cụ khác.

Vì sao PDF cho ra một mớ hỗn độn?#

Để thử nghiệm, một bài báo khoa học hai cột dung lượng 2.16 megabyte đã được xử lý. Mã thoát bằng không; sau 0.9 giây, đầu ra có 88,000 ký tự, hầu hết đều vô nghĩa. Tám mươi tám nghìn ký tự tạo cảm giác mọi thứ đã chạy thành công. Cho đến khi bạn mở tệp:

|     | Hybrid |          | OCR-LLM     |     | Framework  |
| --- | ------ | -------- | ----------- | --- | ---------- |
...
Informationextractionfromcopy-heavydoc-
5202 tcO 11  ]LC.sc[  1v83101.0152:viXra

Ba việc sai xảy ra cùng lúc. Bố cục hai cột biến thành những bảng không có trong bài báo. Các từ dính vào nhau, không có dấu cách. Dòng cuối là thanh bên dọc trên trang, bị trích xuất ngược chiều.

Rồi đến phần buồn cười. Hóa ra bài báo dùng thử chính là công trình đã đo lường MarkItDown và so sánh nó với các công cụ khác. Công cụ biến đoạn văn mô tả các phép đo của chính nó thành thế này:

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-

Cột trái và cột phải bị nối từng dòng. Nếu đưa phần này cho mô hình, nó sẽ đọc nửa câu từ đoạn này và nửa câu từ đoạn khác.

Nguyên nhân mang tính kỹ thuật và đơn giản. Word ghi rõ “đây là tiêu đề” và “đây là ô bảng”. PDF chỉ ghi “đây là ký tự” và “đây là tọa độ của ký tự trên trang”. Khôi phục cấu trúc từ tọa độ là một nhiệm vụ riêng biệt và khó; MarkItDown gần như không cố gắng làm việc đó. Mã nguồn phân tích PDF không có bước nhận diện tiêu đề: nếu trang không được nhận diện là biểu mẫu hoặc bảng, toàn bộ tài liệu sẽ qua bước trích xuất văn bản cơ bản.

Người dùng thường xuyên báo cáo điều này trong kho mã của dự án, kể cả với bài báo khoa học và bảng.

Công cụ không tìm thấy một tiêu đề nào trong PDF, đúng như mã nguồn thể hiện.

Con số “MarkItDown đạt độ chính xác 82%” được lan truyền trên mạng mà không có phương pháp đo. Lần theo đến nguồn ban đầu cũng không tìm được gì: chuỗi liên kết kết thúc ở một trang không tải được. Không thể xem đây là một phép đo.

Điều gì xảy ra với hợp đồng được quét?#

Hành vi này nguy hiểm hơn những vấn đề khác vì nó không giống như thất bại.

Để thử nghiệm, một PDF được tạo từ ảnh có chứa văn bản — đúng loại tệp bạn nhận được khi hợp đồng được chụp hoặc quét. Lần chạy được lặp lại để loại trừ yếu tố ngẫu nhiên:

Không ký tự nào và không lỗi nào, hai lần liên tiếp. Mã thoát bằng không có nghĩa là “mọi thứ đều ổn”, và mọi tập lệnh kiểm tra thành công bằng mã thoát sẽ tính tài liệu là đã xử lý. Sau đó đầu ra rỗng được gửi cho mô hình; mô hình không thấy gì và bắt đầu bịa câu trả lời từ hư không.

Có hai cách khắc phục và cả hai đều mất phí. Cách thứ nhất là cờ -d, gửi tài liệu đến dịch vụ nhận diện đám mây của Microsoft; phần trợ giúp của cờ nêu rõ cần có điểm cuối dịch vụ hợp lệ. Cách thứ hai là một gói bổ trợ riêng gửi từng trang đến mô hình thị giác bằng khóa của bạn, vì vậy bạn trả tiền cho nhà cung cấp mô hình cho mỗi trang. Từ tháng 4 năm 2026, một thảo luận công khai về cách thứ hai cho biết chỉ trang đầu tiên của bản quét nhiều trang được xử lý.

Bạn cũng có thể chạy mô hình nhận diện trên máy riêng, nhưng đó là một dự án khác.

Với một tài liệu dùng một lần, mở tệp và tự sao chép văn bản sẽ dễ hơn. Với luồng bản quét, bạn cần công cụ có khả năng nhận diện tích hợp.

Có thể tải tệp lên trình chuyển đổi trực tuyến không?#

“MarkItDown online” là một trong những cụm từ tìm kiếm được gợi ý phổ biến nhất, và có những trang cung cấp dịch vụ này. Công cụ gốc của Microsoft hoàn toàn không có trang web; nó chỉ có sẵn dưới dạng chương trình do bạn tự cài đặt. Bất kỳ thứ gì có tên tương tự và mở trong trình duyệt đều do người khác tạo ra.

Bạn có thể kiểm tra dịch vụ như vậy trong một phút: mở công cụ dành cho nhà phát triển ở thẻ yêu cầu mạng, tải lên một tệp vô hại bất kỳ và xem tệp có được gửi đến máy chủ không. Nếu có, tuyên bố xử lý trong trình duyệt là sai, dù phần Câu hỏi thường gặp khẳng định chắc chắn đến đâu.

Đó là lý do MarkItDown được coi trọng ở những nơi không thể gửi tài liệu ra ngoài tổ chức. Trong một cuộc thảo luận, có người mô tả hoàn cảnh của mình: các chương trình tùy ý bị cấm trên máy tính công việc, nhưng được phép dùng thư viện Python, và tiện ích cục bộ hóa ra là lựa chọn duy nhất có thể dùng.

MarkItDown thực sự tiết kiệm được bao nhiêu?#

Tệp Office được cấu trúc như một kho lưu trữ chứa dữ liệu đánh dấu. Nếu giải nén ba tệp thử nghiệm và so sánh kích thước phần chứa nội dung với kích thước đầu ra, ta được kết quả sau:

Các tệp đều nhỏ; tỷ lệ sẽ khác với tệp lớn hơn và không có một con số tiết kiệm duy nhất. Khi các bài viết so sánh đưa ra số tròn, hãy hỏi về phương pháp đo.

Các nhà phát triển cũng nói về mức tiết kiệm: phần mô tả dự án nêu cụ thể rằng quy ước Markdown rất tiết kiệm ký tự. Điều đó đúng, nhưng không nên là điểm bán hàng chính. Khác biệt giữa “mô hình nhận ba nghìn ký tự thay vì mười lăm nghìn” và “mô hình nhận cấu trúc rõ ràng thay vì mớ hỗn độn” khác nhau về bản chất. Điều đầu tiên tiết kiệm chi phí; điều thứ hai quyết định câu trả lời có hợp lý hay không.

Nếu bạn quan tâm đến mức sử dụng ngữ cảnh, chủ đề này được đề cập riêng: Token được dùng ở đâu trong Claude và mỗi gói bao gồm bao nhiêu token.

Kết nối MarkItDown với Claude qua MCP như thế nào?#

MCP là cách cấp cho AI một công cụ bên ngoài để AI tự sử dụng. Để xem tổng quan về cơ chế này và các máy chủ khác, hãy xem bài đánh giá máy chủ MCP cho Claude Code.

Máy chủ MarkItDown cung cấp đúng một công cụ: chuyển tài liệu thành văn bản. Công cụ nhận đường dẫn tệp cục bộ, URL trang web hoặc dữ liệu nhúng trực tiếp trong yêu cầu.

Có thể kết nối với Claude Code bằng một lệnh duy nhất, ghim phiên bản máy chủ. Bạn cần trình quản lý gói uv:

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

Phản hồi của lệnh thứ hai phải hiển thị “Connected” cho markitdown. Lần khởi chạy đầu tiên tải khoảng bảy mươi gói và mất tối đa một phút; sau đó máy chủ khởi động trong một đến một giây rưỡi.

Dưới đây là các điểm cần lưu ý, mỗi điểm đều đã được kiểm tra thủ công.

Bản dựng 0.0.1a7 được phát hành ngày 14 tháng 9 năm 2026. Trước đó, máy chủ bị kẹt ở 0.0.1a4 từ tháng 5 năm 2025 trong hơn một năm. Số phiên bản mới nhất vẫn là bản phát hành trước.

Gói không cài được trên mọi hệ thống có phiên bản Python gần đây. Bộ máy onnxruntime mà nó phụ thuộc chỉ có cho Python 3.14 trên Mac dùng Apple Silicon chạy macOS 14 trở lên, vì vậy cài đặt thất bại trên máy Mac Intel và macOS 13 trở xuống khi dùng Python 3.14. Trên máy Mac Apple Silicon, máy chủ đã được chạy bằng Python 3.14, 3.13 và 3.12, và cài được trên cả ba. Lệnh sử dụng UV_PYTHON=3.12: các gói dựng sẵn cho 3.12 có trên Windows, Linux và máy Mac Apple Silicon; nếu chưa có phiên bản Python đó, uv sẽ tải về. Máy Mac Intel cũng có điểm cần lưu ý: uv sẽ biên dịch thư viện cryptography từ mã nguồn vì từ tháng 6 năm 2026 không có gói dựng sẵn cho Intel. Việc cài đặt mất nhiều thời gian hơn và có thể thất bại.

Phiên bản MarkItDown được cài bên trong phụ thuộc vào phiên bản uv. Từ MarkItDown 0.1.6, phần bổ sung [all] yêu cầu một thư viện Azure phát hành trước: uv 0.12 trở lên cài thư viện đó và MarkItDown 0.1.8 mới nhất, còn các phiên bản uv cũ hạ xuống 0.1.5. Kiểm tra phiên bản uv bằng uv --version.

Có hai thứ được gửi ra ngoài máy. Thứ nhất là dữ liệu đo lường từ xa: trên Mac và Linux, bộ máy onnxruntime bên trong máy chủ mặc định gửi dữ liệu này cho Microsoft. Biến ORT_DISABLE_TELEMETRY=1 trong lệnh sẽ tắt nó. Trong thử nghiệm, máy chủ kết nối với các điểm cuối đo lường từ xa của Microsoft khi không có biến này. Khi đặt biến, không có kết nối nào trong lúc xử lý tệp từ đĩa.

Thứ hai là âm thanh. Máy chủ gửi tệp WAV, MP3, M4A và MP4 đến dịch vụ nhận dạng giọng nói của Google để phiên âm qua HTTP thông thường, không mã hóa. Tốt hơn là đừng gửi bản ghi cuộc trò chuyện với khách hàng qua công cụ này.

Tài liệu lớn sẽ không vừa. Một thảo luận đang mở mô tả phản hồi từ máy chủ dài 51,000 token chạm giới hạn 25,000 token; công cụ không chia tệp thành các đoạn.

Còn vấn đề bảo mật. Tài liệu của chính gói nói rõ:

Nói cách khác, một tác nhân có công cụ này có thể đọc mọi thứ bạn đọc được. Điều đó chấp nhận được khi làm việc trên máy của chính bạn. Tuyệt đối không công khai máy chủ ra mạng hoặc cấp nó cho một tác nhân không đáng tin.

Trong công việc thường ngày, gọi chương trình bằng lệnh rồi đưa văn bản thu được vào dự án sẽ dễ hơn. Tệp nằm cạnh các tài liệu khác, nơi mô hình có thể tự tham khảo.

Khi nào nên thành thật mà dùng công cụ khác?#

So sánh theo nhiệm vụ; số sao GitHub chẳng liên quan:

Có một chi tiết về Marker mà các bài viết so sánh thường bỏ qua. Từ tháng 7 năm 2026, bản thân mã nguồn dùng giấy phép thoáng, còn trọng số mô hình dùng giấy phép riêng có ngưỡng: sử dụng miễn phí nếu doanh thu công ty không vượt quá năm triệu đô la và số vốn huy động trong năm trước cũng không vượt quá số tiền đó. Một điều khoản riêng cấm bất kỳ ai xây dựng sản phẩm cạnh tranh sử dụng. Điều này không ảnh hưởng đến hầu hết độc giả, nhưng là lý do để doanh nghiệp đang phát triển đọc kỹ giấy phép trước khi áp dụng.

Từ đó có quy trình thực tế gồm bốn bước:

1. Chạy mọi thứ qua MarkItDown — công cụ miễn phí và tức thì.
2. Mở kết quả và kiểm tra kích thước.
3. Nếu văn bản hợp lý, nhiệm vụ đã xong; không cần làm gì khác.
4. Nếu đầu ra rối hoặc rỗng, xử lý riêng tệp đó bằng công cụ mạnh hơn.

Như vậy, bạn chỉ tốn thời gian và công sức cho những tài liệu thực sự cần đến.

Đưa MarkItDown vào quy trình làm việc như thế nào?#

Anthropic dùng MarkItDown trong các kỹ năng có sẵn để làm việc với tệp Office, và các kỹ năng đó nói rõ ranh giới cần tuân theo:

Văn bản không còn tham chiếu ô và trang, vì vậy bạn không thể dùng nó để sửa tệp nguồn. Dưới đây là ba tình huống.

Một lô tài liệu tương tự nhau — biên bản nghiệm thu, hóa đơn, biểu mẫu, đơn đăng ký. Đặt chúng vào một thư mục và chạy bằng một dòng lệnh:

for f in dokumenty/*.docx; do markitdown "$f" -o "text/$(basename "$f" .docx).md"; done

Sau đó đưa thư mục tệp văn bản cho mô hình và yêu cầu tổng hợp thông tin liên quan thành bảng. Cách này hoạt động với tệp kỹ thuật số; bản quét sẽ thất bại, và bạn sẽ nhận ra ngay nhờ kích thước bằng không.

Tài liệu dự án thường dùng — bảng giá, mẫu hợp đồng, chính sách, mô tả dịch vụ. Chuyển chúng thành văn bản một lần rồi đặt cạnh dự án. Mô hình có thể đọc chúng trong mỗi yêu cầu, vì vậy bạn không phải đính kèm tệp vào cuộc trò chuyện mỗi lần. Bài viết về tải tệp lên Claude giải thích điều này khác với tải tệp lên khung trò chuyện như thế nào.

Tệp xuất từ hệ thống kế toán. Tệp Excel xuất từ phần mềm kế toán hoặc tài khoản ngân hàng trở thành bảng trong một phần ba giây, và mô hình có thể tính toán trực tiếp mà không cần thao tác trung gian. Kiểm CSV đã xuất hoặc đọc theo delimiter, quoting và encoding thật; so dòng, cột, tổng kiểm soát trước cấp mô hình. Không chuẩn hóa dấu bằng tìm-thay. Ghi tiền tệ rõ: ký hiệu chỉ nằm trong định dạng ô Excel sẽ không sống qua trích xuất.

Xử lý PDF lớn trong terminal không nằm trong danh sách này. Đó là vấn đề riêng liên quan đến mức sử dụng ngữ cảnh, được đề cập trong bài viết về PDF trong Claude Code mà không mất token. Nếu bạn chỉ đang thiết lập không gian làm việc, hãy bắt đầu với cài đặt Claude Code.

Để bắt đầu ngay, chạy pip install 'markitdown[pdf,docx,xlsx,pptx]', xử lý hợp đồng Word đầu tiên bạn tìm thấy và kiểm tra kích thước kết quả. Trong nửa phút, bạn sẽ biết công cụ có hoạt động với tệp của mình hay không.

Khi sẵn sàng, hãy gặp Ailoot.