Đánh dấu nó xuống

[!QUAN TRỌNG] MarkItDown thực hiện I/O với các đặc quyền của quy trình hiện tại. Giống như open() hoặc request.get(), nó sẽ truy cập các tài nguyên mà chính tiến trình đó có thể truy cập. Vệ sinh đầu vào của bạn trong môi trường không đáng tin cậy và gọi mức hẹp nhất convert_* chức năng cần thiết cho trường hợp sử dụng của bạn (ví dụ: convert_stream()hoặc convert_local()). Xem Cân nhắc về bảo mật phần tài liệu để biết thêm thông tin.

MarkItDown là một tiện ích Python nhẹ để chuyển đổi các tệp khác nhau sang Markdown để sử dụng với LLM và quy trình phân tích văn bản liên quan. Về mặt này, nó có thể so sánh được nhất với văn bản, nhưng tập trung vào việc duy trì cấu trúc và nội dung tài liệu quan trọng dưới dạng Markdown (bao gồm: tiêu đề, danh sách, bảng, liên kết, v.v.) Mặc dù đầu ra thường trình bày hợp lý và thân thiện với con người, nhưng nó được sử dụng bởi các công cụ phân tích văn bản -- và có thể không phải là lựa chọn tốt nhất để chuyển đổi tài liệu có độ chính xác cao cho con người.

MarkItDown hiện hỗ trợ chuyển đổi từ:

• PDF
• PowerPoint
• từ
• Excel
• Hình ảnh (siêu dữ liệu EXIF ​​và OCR)
• Âm thanh (siêu dữ liệu EXIF ​​và phiên âm giọng nói)
• HTML
• Các định dạng dựa trên văn bản (CSV, JSON, XML)
• Tệp ZIP (lặp lại nội dung)
• URL YouTube
• EPub
• ... và hơn thế nữa!

Tại sao lại đánh dấu?

Markdown cực kỳ gần với văn bản thuần túy, với đánh dấu hoặc định dạng tối thiểu nhưng vẫn cung cấp cách thể hiện cấu trúc tài liệu quan trọng. LLM chính thống, chẳng hạn như GPT-4o của OpenAI, nguyên bản "nói" Markdown và thường kết hợp Markdown vào các câu trả lời của họ mà không được nhắc nhở. Điều này cho thấy rằng họ đã được đào tạo về số lượng lớn văn bản có định dạng Markdown và hiểu rõ về nó. Là một lợi ích phụ, các quy ước Markdown cũng mang lại hiệu quả cao về mã thông báo.

Điều kiện tiên quyết

MarkItDown yêu cầu Python 3.10 trở lên. Nên sử dụng môi trường ảo để tránh xung đột phụ thuộc.

Với cài đặt Python tiêu chuẩn, bạn có thể tạo và kích hoạt môi trường ảo bằng các lệnh sau:

python -m venv .venv
source .venv/bin/activate

Nếu sử dụng uv, bạn có thể tạo một môi trường ảo với:

uv venv --python=3.12 .venv
source .venv/bin/activate
# NOTE: Be sure to use 'uv pip install' rather than just 'pip install' to install packages in this virtual environment

Nếu bạn đang sử dụng Anaconda, bạn có thể tạo môi trường ảo bằng:

conda create -n markitdown python=3.12
conda activate markitdown

Cài đặt

Để cài đặt MarkItDown, hãy sử dụng pip: pip install 'markitdown[all]'. Ngoài ra, bạn có thể cài đặt nó từ nguồn:

git clone [email protected]:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

Cách sử dụng

Dòng lệnh

markitdown path-to-file.pdf > document.md

Hoặc sử dụng -o để chỉ định tệp đầu ra:

markitdown path-to-file.pdf -o document.md

Bạn cũng có thể chuyển nội dung:

cat path-to-file.pdf | markitdown

Phụ thuộc tùy chọn

MarkItDown có các phần phụ thuộc tùy chọn để kích hoạt các định dạng tệp khác nhau. Trước đó trong tài liệu này, chúng tôi đã cài đặt tất cả các phần phụ thuộc tùy chọn với [all] tùy chọn. Tuy nhiên, bạn cũng có thể cài đặt chúng riêng lẻ để kiểm soát nhiều hơn. Ví dụ:

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

sẽ chỉ cài đặt các phần phụ thuộc cho các tệp PDF, DOCX và PPTX.

Hiện tại, có sẵn các phần phụ thuộc tùy chọn sau:

• [all] Cài đặt tất cả các phụ thuộc tùy chọn
• [pptx] Cài đặt phần phụ thuộc cho tệp PowerPoint
• [docx] Cài đặt phần phụ thuộc cho tệp Word
• [xlsx] Cài đặt phần phụ thuộc cho tệp Excel
• [xls] Cài đặt phần phụ thuộc cho các tệp Excel cũ hơn
• [pdf] Cài đặt phụ thuộc cho tệp PDF
• [outlook] Cài đặt phần phụ thuộc cho thư Outlook
• [az-doc-intel] Cài đặt các phần phụ thuộc cho Azure Document Intelligence
• [az-content-understanding] Cài đặt các phần phụ thuộc để hiểu nội dung Azure
• [audio-transcription] Cài đặt các phần phụ thuộc để phiên âm âm thanh của tệp wav và mp3
• [youtube-transcription] Cài đặt các phần phụ thuộc để tìm nạp bản ghi video YouTube

Plugin

MarkItDown cũng hỗ trợ plugin của bên thứ 3. Các plugin bị tắt theo mặc định. Để liệt kê các plugin đã cài đặt:

markitdown --list-plugins

Để kích hoạt plugin, hãy sử dụng:

markitdown --use-plugins path-to-file.pdf

Để tìm các plugin có sẵn, hãy tìm kiếm GitHub cho hashtag #markitdown-plugin. Để phát triển một plugin, hãy xem packages/markitdown-sample-plugin.

Plugin markitdown-ocr

các markitdown-ocr plugin bổ sung hỗ trợ OCR cho các trình chuyển đổi PDF, DOCX, PPTX và XLSX, trích xuất văn bản từ các hình ảnh được nhúng bằng cách sử dụng LLM Vision - tương tự llm_client / llm_model mẫu mà MarkItDown đã sử dụng để mô tả hình ảnh. Không cần có thư viện ML mới hoặc phụ thuộc nhị phân.

Cài đặt:

pip install markitdown-ocr
pip install openai  # or any OpenAI-compatible client

Cách sử dụng:

Vượt qua tương tự llm_client và llm_model bạn sẽ sử dụng để mô tả hình ảnh:

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)
result = md.convert("document_with_images.pdf")
print(result.text_content)

Nếu không llm_client được cung cấp là plugin vẫn tải nhưng OCR bị bỏ qua một cách âm thầm và bộ chuyển đổi tích hợp tiêu chuẩn được sử dụng thay thế.

Xem packages/markitdown-ocr/README.md để biết tài liệu chi tiết.

Hiểu nội dung Azure

Hiểu nội dung Azure cung cấp chuyển đổi chất lượng cao hơn với tính năng trích xuất trường có cấu trúc (YAML nội dung phía trước), hỗ trợ đa phương thức (tài liệu, hình ảnh, âm thanh, video) và bộ phân tích có thể định cấu hình.

Cài đặt: pip install 'markitdown[az-content-understanding]'

Khi nào nên sử dụng Hiểu nội dung

Hiểu nội dung là giải pháp lý tưởng khi bạn cần các khả năng vượt xa những gì trình chuyển đổi Thông minh tài liệu hoặc tích hợp sẵn cung cấp:

• Tập tin âm thanh và video — CU là tùy chọn duy nhất cho video và tùy chọn đám mây chất lượng cao hơn cho âm thanh. Bộ chuyển đổi tích hợp không hỗ trợ video và chỉ phiên âm âm thanh cơ bản.
• Trích xuất trường có cấu trúc — dựng sẵn hoặc tùy chỉnh được xây dựng máy phân tích trích xuất các trường theo miền cụ thể (số hóa đơn, ngày nhận, điều khoản hợp đồng) được tuần tự hóa dưới dạng nội dung phía trước YAML. Cả tích hợp tích hợp và tích hợp Doc Intel đều không hiển thị các trường.
• Trích xuất tài liệu chất lượng cao hơn — Phân tích bố cục và OCR dựa trên đám mây cho các tệp PDF được quét, các bảng phức tạp và tài liệu nhiều trang.
• API đơn cho tất cả các phương thức - Một cu_endpoint xử lý tài liệu, hình ảnh, âm thanh và video bằng cách định tuyến máy phân tích tự động.

Khả năng	Bộ chuyển đổi tích hợp	Thông tin tài liệu Azure	Hiểu nội dung Azure
Chuyển đổi tài liệu	Trích xuất ngoại tuyến, theo định dạng cụ thể	Trích xuất bố cục đám mây	Trích xuất đa phương thức trên đám mây
Trường có cấu trúc	Không có sẵn	Không bị lộ bởi sự tích hợp này	YAML vật chất phía trước từ trường phân tích
Máy phân tích tùy chỉnh	Không có sẵn	Không thể cấu hình trong tích hợp này	Được hỗ trợ với cu_analyzer_id
Âm thanh và video	Âm thanh cơ bản, không có video	Không được hỗ trợ	Máy phân tích âm thanh và video
Chi phí	Chỉ tính toán cục bộ	Cuộc gọi Azure API phải trả phí	Cuộc gọi Azure API phải trả phí

CLI:

markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"

Python API:

from markitdown import MarkItDown

# Zero-config — auto-selects analyzer per file type
md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf")   # documents → prebuilt-documentSearch
result = md.convert("meeting.mp4")  # video → prebuilt-videoSearch
result = md.convert("call.wav")     # audio → prebuilt-audioSearch
print(result.markdown)

Với máy phân tích tùy chỉnh (để trích xuất trường theo tên miền cụ thể):

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_analyzer_id="my-invoice-analyzer",
)
result = md.convert("invoice.pdf")
print(result.markdown)
# Output includes YAML front matter with extracted fields:
# ---
# contentType: document
# fields:
#   VendorName: CONTOSO LTD.
#   InvoiceDate: '2019-11-15'
# ---
# <!-- page 1 -->
# ...

Khi nào cu_analyzer_id được thiết lập, bộ chuyển đổi sẽ tự động xác định phạm vi của nó thành các loại tệp tương thích dựa trên phương thức của máy phân tích. Các loại không tương thích (ví dụ: tệp âm thanh có bộ phân tích tài liệu) tự động định tuyến đến các bộ phân tích dựng sẵn mặc định.

Lưu ý chi phí: Mỗi convert() cuộc gọi cho định dạng định tuyến CU là cuộc gọi Azure API có thể tính phí. sử dụng cu_file_types để hạn chế các định dạng định tuyến tới CU:

from markitdown.converters import ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],  # only PDFs use CU
)

Bạn có thể tìm thêm thông tin về Hiểu nội dung Azure ở đây.

Thông tin tài liệu Azure

Để sử dụng Microsoft Document Intelligence để chuyển đổi:

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

Bạn có thể tìm thêm thông tin về cách thiết lập Tài nguyên thông minh tài liệu Azure ở đây

Python API

Cách sử dụng cơ bản trong Python:

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # Set to True to enable plugins
result = md.convert("test.xlsx")
print(result.text_content)

Chuyển đổi Thông tin Tài liệu trong Python:

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

Để sử dụng Mô hình ngôn ngữ lớn cho mô tả hình ảnh (hiện chỉ dành cho tệp pptx và hình ảnh), hãy cung cấp llm_client và llm_model:

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.text_content)

Docker

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

Đóng góp

Dự án này hoan nghênh những đóng góp và đề xuất. Hầu hết các đóng góp đều yêu cầu bạn đồng ý với Thỏa thuận cấp phép cộng tác viên (CLA) tuyên bố rằng bạn có quyền và thực sự cấp cho chúng tôi quyền sử dụng đóng góp của bạn. Để biết chi tiết, hãy truy cập https://cla.opensource.microsoft.com.

Khi bạn gửi yêu cầu kéo, bot CLA sẽ tự động xác định xem bạn có cần cung cấp CLA và trang trí PR phù hợp hay không (ví dụ: kiểm tra trạng thái, nhận xét). Chỉ cần làm theo hướng dẫn do bot cung cấp. Bạn sẽ chỉ cần thực hiện việc này một lần trên tất cả các kho lưu trữ bằng CLA của chúng tôi.

Dự án này đã áp dụng Quy tắc ứng xử mã nguồn mở của Microsoft. Để biết thêm thông tin, hãy xem Câu hỏi thường gặp về Quy tắc ứng xử hoặc liên hệ [email protected] với bất kỳ câu hỏi hoặc ý kiến bổ sung.

Cách đóng góp

Bạn có thể trợ giúp bằng cách xem xét các vấn đề hoặc giúp xem xét các PR. Mọi vấn đề hoặc quan hệ công chúng đều được hoan nghênh, nhưng chúng tôi cũng đã đánh dấu một số vấn đề là 'mở để đóng góp' và 'mở để xem xét' nhằm giúp tạo điều kiện thuận lợi cho sự đóng góp của cộng đồng. Tất nhiên đây chỉ là những gợi ý và bạn có thể đóng góp theo bất kỳ cách nào bạn muốn.

Chạy thử nghiệm và kiểm tra

• Điều hướng đến gói MarkItDown:

  cd packages/markitdown
  

• cài đặt hatch trong môi trường của bạn và chạy thử nghiệm:

  pip install hatch  # Other ways of installing hatch: https://hatch.pypa.io/dev/install/
  hatch shell
  hatch test
  

  (Thay thế) Sử dụng Devcontainer đã cài đặt tất cả các phụ thuộc:

  # Reopen the project in Devcontainer and run:
  hatch test
  

• Chạy kiểm tra trước khi cam kết trước khi gửi PR: pre-commit run --all-files

Cân nhắc về bảo mật

MarkItDown thực hiện I/O với các đặc quyền của quy trình hiện tại. thích open() hoặc requests.get(), nó sẽ truy cập các tài nguyên mà chính tiến trình đó có thể truy cập.

Vệ sinh đầu vào của bạn: Không chuyển trực tiếp dữ liệu đầu vào không đáng tin cậy vào MarkItDown. Nếu bất kỳ phần nào của đầu vào có thể được kiểm soát bởi người dùng hoặc hệ thống không đáng tin cậy, chẳng hạn như trong các ứng dụng được lưu trữ hoặc phía máy chủ, thì phần đó phải được xác thực và hạn chế trước khi gọi MarkItDown. Tùy thuộc vào môi trường của bạn, điều này có thể bao gồm việc hạn chế đường dẫn tệp, hạn chế lược đồ URI và đích mạng cũng như chặn quyền truy cập vào các địa chỉ dịch vụ riêng tư, vòng lặp, liên kết cục bộ hoặc siêu dữ liệu.

Chỉ gọi phương thức chuyển đổi bạn cần: Ưu tiên chuyển đổi hẹp nhất API phù hợp với trường hợp sử dụng của bạn. MarkItDown's convert() phương thức này được cho phép có chủ ý và có thể xử lý các tệp cục bộ, URI từ xa và luồng byte. Nếu ứng dụng của bạn chỉ cần đọc các tệp cục bộ, hãy gọi convert_local() thay vào đó. Nếu bạn cần kiểm soát nhiều hơn việc tìm nạp URI, hãy gọi requests.get() chính bạn và chuyển đối tượng phản hồi cho convert_response(). Để kiểm soát tối đa, hãy mở luồng tới đầu vào bạn muốn chuyển đổi và gọi convert_stream().

Đóng góp plugin của bên thứ 3

Bạn cũng có thể đóng góp bằng cách tạo và chia sẻ plugin của bên thứ 3. Nhìn thấy packages/markitdown-sample-plugin để biết thêm chi tiết.

Nhãn hiệu

Dự án này có thể chứa nhãn hiệu hoặc logo cho dự án, sản phẩm hoặc dịch vụ. Việc sử dụng nhãn hiệu hoặc logo của Microsoft được ủy quyền phải tuân theo và phải tuân theo Nguyên tắc về nhãn hiệu và thương hiệu của Microsoft. Việc sử dụng nhãn hiệu hoặc logo của Microsoft trong các phiên bản sửa đổi của dự án này không được gây nhầm lẫn hoặc ngụ ý sự tài trợ của Microsoft. Mọi việc sử dụng nhãn hiệu hoặc logo của bên thứ ba đều phải tuân theo chính sách của bên thứ ba đó.