GroupDocs.Markdown cho Python qua .NET — Xuất tài liệu sang Markdown

Mang tài liệu của bạn vào các pipeline AI — trực tiếp từ Python, tại chỗ, chỉ với một pip install.

Hôm nay chúng tôi phát hành phiên bản công khai đầu tiên của GroupDocs.Markdown cho Python qua .NET trên PyPI. Thư viện chuyển đổi PDF, Word, Excel, EPUB và hơn 20 định dạng khác thành Markdown sạch, có ngữ nghĩa — định dạng mà LLM, các pipeline RAG và các trình tạo trang tĩnh làm việc tốt nhất.

Nếu bạn đã theo dõi bản phát hành .NET từ tháng 9 [/markdown/groupdocs-markdown-for-net-first-public-release/] (hoặc cuộc cải tổ API toàn diện trong 26.3 (https://releases.groupdocs.com/markdown/net/release-notes/2026/groupdocs-markdown-for-net-26-3-release-notes/)), lý do vẫn giống nhau: định dạng tài liệu mang lại ngữ nghĩa, và việc bảo tồn cấu trúc ngữ nghĩa là điều khiến một hệ thống RAG đưa ra câu trả lời tốt. Bài viết trước đã đề cập vấn đề (OCR làm phẳng cấu trúc, LLM cần markdown) và giải pháp (bộ render dựa trên DOM duyệt tài liệu và xuất Markdown) một cách chi tiết — chúng tôi sẽ không lặp lại câu chuyện đó ở đây.

Thay vào đó, hãy tập trung vào những gì mới dành cho các nhà phát triển Python.

Những gì bạn nhận được

Một wheel duy nhất, không có phụ thuộc thời gian chạy. pip install groupdocs-markdown-net tải về một wheel tự chứa, gói sẵn runtime .NET và mọi thư viện native cần thiết. Không cần cài dotnet, không cần Microsoft Office, không cần Adobe Acrobat, không cần dịch vụ đám mây.
Đa nền tảng. Windows x64/x86, Linux x64, macOS x64 và Apple Silicon (ARM64). Python 3.5 tới 3.14.
API pythonic. Các lớp dùng PascalCase, phương thức và thuộc tính dùng snake_case, giá trị enum dùng UPPER_SNAKE_CASE. Các context manager giải phóng tài liệu đã tải một cách quyết đoán.
Thực sự async. Mỗi phương thức tĩnh và instance đều có phiên bản _async. I/O file được thực hiện bất đồng bộ và quá trình chuyển đổi tốn CPU chạy trên một worker thread — vòng lặp asyncio của bạn vẫn tự do.
Thân thiện với AI-agent. Wheel được cài đặt kèm theo một tệp AGENTS.md để các trợ lý lập trình (Claude Code, Cursor, GitHub Copilot, Codex) tự động khám phá bề mặt API, các mẫu sử dụng idiomatic và các mẹo khắc phục sự cố. Tài liệu cũng được xuất dưới dạng llms.txt, một corpus đơn tệp (llms-full.txt), Markdown theo trang, và một server MCP — xem phần AI-friendly by design dưới đây để biết chi tiết.

Bắt đầu

pip install groupdocs-markdown-net

Chuyển đổi đơn giản nhất chỉ cần một dòng:

from groupdocs.markdown import MarkdownConverter

# Chuyển đổi thành chuỗi
md = MarkdownConverter.to_markdown("business-plan.docx")

# Hoặc ghi trực tiếp vào tệp
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

Thế là xong — không cấu hình, không tùy chọn, không boilerplate. Chế độ đánh giá chỉ xử lý 3 trang đầu và thêm watermark. Để bỏ giới hạn, áp dụng giấy phép:

from groupdocs.markdown import License

License().set_license("path/to/license.lic")

Hoặc đặt biến môi trường GROUPDOCS_LIC_PATH và nó sẽ được áp dụng tự động khi import.

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

Gói Python xử lý cùng một dải định dạng như thư viện .NET:

PDF — .pdf
Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
Bảng tính — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
eBooks — .epub, .mobi
Văn bản / Markup / Trợ giúp — .txt, .xml, .chm

Các ví dụ pythonic

Tùy chọn chuyển đổi và chiến lược hình ảnh

from groupdocs.markdown import (
    MarkdownConverter,
    ConvertOptions,
    MarkdownFlavor,
    ExportImagesToFileSystemStrategy,
)

strategy = ExportImagesToFileSystemStrategy("output/images")
strategy.images_relative_path = "images"  # ![](images/img-001.png)

options = ConvertOptions()
options.flavor = MarkdownFlavor.GIT_HUB
options.heading_level_offset = 1      # # Title -> ## Title
options.include_front_matter = True    # prepend YAML metadata
options.image_export_strategy = strategy

MarkdownConverter.to_file("report.docx", "output/report.md", convert_options=options)

Kiểm tra tài liệu mà không chuyển đổi

from groupdocs.markdown import MarkdownConverter

info = MarkdownConverter.get_info("business-plan.docx")
print(f"{info.file_format}, {info.page_count} pages, author: {info.author}")

Tải tệp được bảo vệ bằng mật khẩu

from groupdocs.markdown import MarkdownConverter, LoadOptions, FileFormat

load_opts = LoadOptions(FileFormat.DOCX)
load_opts.password = "secret"

MarkdownConverter.to_file("protected.docx", "output.md", load_options=load_opts)

Streams và context managers

from groupdocs.markdown import MarkdownConverter

with open("document.docx", "rb") as stream:
    with MarkdownConverter(stream) as converter:
        converter.convert("document.md")

API async — chuyển đổi nhiều tài liệu đồng thời

Vì I/O file là bất đồng bộ, asyncio.gather() cho phép một worker duy nhất xử lý nhiều tài liệu mà không bị chặn:

import asyncio
from groupdocs.markdown import MarkdownConverter

async def convert_many():
    await asyncio.gather(
        MarkdownConverter.to_file_async("a.docx", "a.md", None),
        MarkdownConverter.to_file_async("b.pdf",  "b.md", None),
        MarkdownConverter.to_file_async("c.xlsx", "c.md", None),
    )

asyncio.run(convert_many())

Điều này làm cho thư viện trở nên tự nhiên cho các framework ASGI như FastAPI — một worker duy nhất có thể phục vụ nhiều yêu cầu chuyển đổi đồng thời mà không gây tranh chấp thread.

Xử lý lỗi

Tất cả các phương thức chuyển đổi sẽ ném ngoại lệ khi thất bại, với các loại ngoại lệ cụ thể cho các kịch bản phổ biến:

from groupdocs.markdown import (
    MarkdownConverter,
    DocumentProtectedException,
    InvalidFormatException,
    GroupDocsMarkdownException,
)

try:
    MarkdownConverter.to_file("annual-report.docx", "annual-report.md")
except DocumentProtectedException:
    print("Wrong or missing password.")
except InvalidFormatException:
    print("File is corrupt or unsupported.")
except GroupDocsMarkdownException as ex:
    print(f"Conversion failed: {ex}")

Xây dựng cho RAG và pipeline LLM

Markdown là định dạng đầu vào ưu tiên cho các mô hình embedding và pipeline truy xuất — nó bảo tồn tiêu đề, danh sách, bảng và nhấn mạnh trong khi dễ dàng chia nhỏ và token hoá. Một quy trình RAG điển hình trông như sau:

import re
from groupdocs.markdown import MarkdownConverter, ConvertOptions, SkipImagesStrategy, MarkdownFlavor

options = ConvertOptions()
options.image_export_strategy = SkipImagesStrategy()   # text-only for RAG
options.flavor = MarkdownFlavor.COMMON_MARK

MarkdownConverter.to_file("business-plan.pdf", "business-plan.md", convert_options=options)

with open("business-plan.md", "r", encoding="utf-8") as f:
    markdown = f.read()

# Split by top-level headings, then embed/index each chunk
chunks = [c for c in re.split(r"\n#{1,2} ", markdown) if c.strip()]

Vì thư viện chạy hoàn toàn tại chỗ, tài liệu nhạy cảm không bao giờ rời khỏi môi trường của bạn — một yêu cầu phổ biến cho các ngành công nghiệp được quy định, đội ngũ pháp lý và các kho tri thức nội bộ.

Thiết kế thân thiện AI

Hầu hết các SDK Python coi trợ lý AI như một phần phụ — nhà phát triển vẫn phải chỉ đường cho agent tới tài liệu, dán ví dụ, hoặc gỡ lỗi qua thử nghiệm. GroupDocs.Markdown cho Python qua .NET đảo ngược điều này: thư viện được thiết kế để các agent như Claude Code, Cursor, GitHub Copilot và Codex có thể tiếp cận mà không cần thiết lập thủ công.

`AGENTS.md` đi kèm trong wheel

Đây là gói GroupDocs đầu tiên đóng gói một tệp AGENTS.md trực tiếp trong wheel đã cài đặt. Tệp này tuân theo chuẩn AGENTS.md đang nổi — một README Markdown thuần dành riêng cho các trợ lý lập trình AI thay vì con người.

Khi bạn chạy pip install groupdocs-markdown-net, một tệp sẽ xuất hiện tại:

site-packages/groupdocs/markdown/AGENTS.md

Một trợ lý AI mở dự án của bạn có thể đọc tệp này và ngay lập tức hiểu:

Toàn bộ bề mặt API công khai (lớp, phương thức, enum, ngoại lệ) và cách chúng liên quan.
Mẫu sử dụng idiomatic cho các kịch bản phổ biến — API tĩnh vs instance, sync vs async, chiến lược hình ảnh, front matter, xử lý lỗi.
Những cạm bẫy thường gặp và cách tránh — ví dụ, overload ConvertOptions nào chấp nhận None, cách xử lý tệp bảo vệ bằng mật khẩu, cách bắt cảnh báo chuyển đổi.
Khắc phục sự cố cho các vấn đề đặc thù nền tảng (libSkiaSharp trên macOS, ICU trên Linux).

Trong thực tế, điều này có nghĩa là bạn có thể nói “sử dụng groupdocs-markdown-net để chuyển đổi thư mục PDF này sang Markdown cho pipeline RAG của tôi” và agent sẽ viết mã hoạt động ngay lần đầu — không có tên phương thức bịa ra, không có thứ tự đối số sai, không có import đoán mò.

Tài liệu máy đọc được

Đối với các agent cần tra cứu thông tin không có trong AGENTS.md, toàn bộ tài liệu sản phẩm cũng được xuất dưới dạng máy đọc được:

Corpus đơn tệp — toàn bộ docs dưới dạng một file Markdown nối liền, sẵn sàng đưa vào cửa sổ ngữ cảnh của agent:
https://docs.groupdocs.com/markdown/python-net/llms-full.txt
Markdown theo trang — thêm .md vào bất kỳ URL docs nào để lấy nguồn thô:
https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
Chỉ mục llms.txt — một bảng nội dung kiểu llms.txt chỉ dẫn agent tới các trang cần thiết:
https://docs.groupdocs.com/markdown/python-net/llms.txt

Server MCP cho tra cứu tài liệu trực tiếp

Đối với các agent sử dụng Model Context Protocol, chúng tôi cung cấp tài liệu dưới dạng server MCP. Thêm cấu hình này vào Claude Code hoặc Cursor của bạn:

{
  "mcpServers": {
    "groupdocs-docs": {
      "url": "https://docs.groupdocs.com/mcp"
    }
  }
}

Sau đó, agent của bạn có thể truy vấn tài liệu theo yêu cầu thay vì dựa vào dữ liệu huấn luyện có thể đã lỗi thời.

Markdown vào, Markdown ra

Có một sự đối xứng đẹp ở đây: đầu ra của thư viện là Markdown — định dạng LLM phân tích tốt nhất cho RAG — và tài liệu của nó cũng là Markdown, được phục vụ dưới dạng một file duy nhất để dễ dàng đưa vào cửa sổ ngữ cảnh. Dù bạn yêu cầu một agent viết mã sử dụng thư viện, hay yêu cầu agent hiểu tài liệu của bạn qua thư viện, Markdown là phương tiện chung.

Ví dụ xuất

Các đoạn mã trên gần như là chương trình ngắn gọn nhất bạn có thể viết với thư viện. Dưới đây là cùng một ý tưởng được đóng gói thành một dự án có thể chạy — tài liệu nguồn, script Python, output đã tạo sẵn, requirements.txt, và một Dockerfile — để bạn có thể thử end‑to‑end mà không cần viết gì từ đầu.

DOCX nguồn

Tệp nguồn business-plan.docx là một kế hoạch kinh doanh ngắn, giàu định dạng với tiêu đề, bảng, hình ảnh và metadata.

Script Python

from groupdocs.markdown import MarkdownConverter, ConvertOptions, MarkdownFlavor

def quick_example():
    """Convert a Word document to Markdown with GitHub flavor and YAML front matter."""

    # One-liner — returns a Markdown string
    md = MarkdownConverter.to_markdown("business-plan.docx")

    # With options — writes to a file
    options = ConvertOptions()
    options.flavor = MarkdownFlavor.GIT_HUB
    options.include_front_matter = True
    options.heading_level_offset = 1
    MarkdownConverter.to_file("business-plan.docx", "quick-example.md", convert_options=options)

if __name__ == "__main__":
    quick_example()

Markdown output

Output quick-example.md bắt đầu bằng một khối front‑matter YAML tự động trích xuất từ metadata của tài liệu, tiếp theo là nội dung đã chuyển đổi với bảng kiểu GitHub Flavored và cấp độ tiêu đề đã dịch chuyển (sẵn sàng nhúng vào tài liệu lớn hơn).

Ứng dụng mẫu có thể chạy

Mọi thứ được đóng gói cùng nhau: sample-app.zip. Giải nén, sau đó:

cd src
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python quick_example.py

Hoặc chạy trong Docker — Dockerfile đi kèm đã cài đặt phụ thuộc ICU mà runtime .NET gói trong Linux cần:

cd src
docker build -t groupdocs-markdown-python-example .
docker run --rm -v "$(pwd)/output:/app/output" groupdocs-markdown-python-example

Tóm tắt

GroupDocs.Markdown cho Python qua .NET mang toàn bộ engine chuyển đổi tài liệu‑to‑Markdown vào Python dưới dạng wheel tự chứa — không runtime bên ngoài, không đám mây, không bất ngờ. API pythonic, hỗ trợ async, và tích hợp công cụ AI hạng nhất khiến nó trở thành lựa chọn thực tế cho các đội Python xây dựng hệ thống RAG, trình tạo trang tĩnh, hoặc pipeline xử lý tài liệu.

Tìm hiểu thêm

Gói PyPI: https://pypi.org/project/groupdocs-markdown-net/
Trang sản phẩm: https://products.groupdocs.com/markdown/python-net/
Tài liệu: https://docs.groupdocs.com/markdown/python-net/
Ghi chú phát hành: https://releases.groupdocs.com/markdown/python-net/release-notes/
Ví dụ mã trên GitHub: https://github.com/groupdocs-markdown/GroupDocs.Markdown-for-Python-via-.NET
Thông tin giấy phép: https://about.groupdocs.com/legal/
Bài viết phát hành .NET liên quan: GroupDocs.Markdown for .NET — First Public Release

Hỗ trợ & phản hồi

Đối với câu hỏi hoặc hỗ trợ kỹ thuật, vui lòng sử dụng Free Support Forum — chúng tôi sẽ sẵn sàng giúp đỡ.

Những gì bạn nhận được#

Bắt đầu#

Định dạng được hỗ trợ#

Các ví dụ pythonic#

Tùy chọn chuyển đổi và chiến lược hình ảnh#

Kiểm tra tài liệu mà không chuyển đổi#

Tải tệp được bảo vệ bằng mật khẩu#

Streams và context managers#

API async — chuyển đổi nhiều tài liệu đồng thời#

Xử lý lỗi#

Xây dựng cho RAG và pipeline LLM#

Thiết kế thân thiện AI#

AGENTS.md đi kèm trong wheel#

Tài liệu máy đọc được#

Server MCP cho tra cứu tài liệu trực tiếp#

Markdown vào, Markdown ra#

Ví dụ xuất#

Tóm tắt#

Tìm hiểu thêm#

Hỗ trợ & phản hồi#