اسناد خود را به خطوط لوله هوش مصنوعی وارد کنید — مستقیم از پایتون، در محل، با یک pip install.

امروز اولین نسخه عمومی GroupDocs.Markdown برای پایتون از طریق .NET را در PyPI منتشر می‌کنیم. این کتابخانه PDF، Word، Excel، EPUB و بیش از ۲۰ فرمت دیگر را به Markdown تمیز و معنایی تبدیل می‌کند — فرمت‌ایی که مدل‌های زبانی بزرگ (LLM)، خطوط لوله RAG و مولدهای سایت ایستا بهترین کارایی را با آن دارند.

اگر از انتشار .NET در سپتامبر (یا بازنگری کامل API در نسخه 26.3) پیگیری کرده‌اید، دلیل این کار همان است: قالب‌بندی سند حاوی معناست و حفظ این ساختار معنایی همان چیزی است که یک سیستم RAG را به ارائه پاسخ‌های خوب می‌رساند. پست قبلی مسئله (OCR ساختار را صاف می‌کند، LLMها به markdown نیاز دارند) و راه‌حل (یک رندرکننده مبتنی بر DOM که سند را می‌پیماید و Markdown تولید می‌کند) را به‌صورت عمیق بررسی کرده بود — اینجا آن داستان را تکرار نمی‌کنیم.

در عوض، تمرکزمان بر موارد جدید برای توسعه‌دهندگان پایتون است.

آنچه دریافت می‌کنید

  • یک wheel تک، بدون وابستگی‌های زمان اجرا. pip install groupdocs-markdown-net یک wheel خودکفا را می‌کشد که زمان اجرا .NET و تمام کتابخانه‌های بومی مورد نیاز را در خود دارد. نیازی به نصب dotnet، Microsoft Office، Adobe Acrobat یا سرویس‌های ابری نیست.
  • قابل اجرا بر روی همه پلتفرم‌ها. Windows x64/x86، Linux x64، macOS x64 و Apple Silicon (ARM64). پایتون 3.5 تا 3.14.
  • API پایتونیک. کلاس‌ها از PascalCase استفاده می‌کنند، متدها و ویژگی‌ها از snake_case، مقادیر enum از UPPER_SNAKE_CASE. مدیران زمینه (context managers) اسناد بارگذاری‌شده را به‌صورت قطعی آزاد می‌کنند.
  • به‌صورت واقعی async. هر متد استاتیک و نمونه یک همتای _async دارد. I/O فایل به‌صورت ناهمزمان است و تبدیل‌های CPU‑بندی‌شده روی یک رشته کاری اجرا می‌شود — حلقه رویداد asyncio شما آزاد می‌ماند.
  • دوست‌دار عامل‌های هوش مصنوعی. wheel نصب‌شده شامل فایلی به نام AGENTS.md است تا دستیارهای کدنویسی (Claude Code، Cursor، GitHub Copilot، Codex) به‌صورت خودکار سطح API، الگوهای استفاده ایدئوماتیک و نکات عیب‌یابی را کشف کنند. مستندات همچنین به صورت llms.txt، یک کورپوس تک‌فایلی (llms-full.txt)، Markdown صفحه به صفحه، و یک سرور MCP منتشر می‌شود — جزئیات بیشتر در بخش AI-friendly by design آمده است.

شروع کنید

pip install groupdocs-markdown-net

ساده‌ترین تبدیل یک خطی است:

from groupdocs.markdown import MarkdownConverter

# تبدیل به یک رشته
md = MarkdownConverter.to_markdown("business-plan.docx")

# یا نوشتن مستقیم به فایل
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

همین! بدون پیکربندی، بدون گزینه، بدون کدهای اضافی. حالت ارزیابی اولین ۳ صفحه را پردازش می‌کند و یک واترمارک اضافه می‌نماید. برای حذف محدودیت‌ها، یک لایسنس اعمال کنید:

from groupdocs.markdown import License

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

یا متغیر محیطی GROUPDOCS_LIC_PATH را تنظیم کنید تا به‌صورت خودکار هنگام ایمپورت اعمال شود.

فرمت‌های پشتیبانی‌شده

بسته پایتون همان گستره فرمت‌های کتابخانه .NET را پشتیبانی می‌کند:

  • PDF — .pdf
  • Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
  • Spreadsheets — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
  • eBooks — .epub, .mobi
  • Text / Markup / Help — .txt, .xml, .chm

مثال‌های پایتونیک

گزینه‌های تبدیل و استراتژی‌های تصویر

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)

بازرسی سند بدون تبدیل

from groupdocs.markdown import MarkdownConverter

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

بارگذاری فایلی با رمز عبور

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)

استریم‌ها و مدیران زمینه

from groupdocs.markdown import MarkdownConverter

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

API ناهمزمان — تبدیل همزمان چندین سند

از آنجا که I/O فایل ناهمزمان است، asyncio.gather() اجازه می‌دهد یک کارگر واحد بسیاری از اسناد را بدون بلوکه شدن پردازش کند:

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())

این کتابخانه به‌طور طبیعی برای فریم‌ورک‌های ASGI مانند FastAPI مناسب است — یک کارگر می‌تواند درخواست‌های تبدیل همزمان زیادی را بدون رقابت رشته‌ها سرو کند.

مدیریت خطا

تمام متدهای تبدیل در صورت شکست استثنا می‌اندازند و برای سناریوهای رایج انواع خاصی از استثناها وجود دارد:

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}")

ساخته‌شده برای RAG و خطوط لوله LLM

Markdown فرمت ورودی ترجیحی برای مدل‌های تعبیه (embedding) و خطوط لوله بازیابی است — سرفصل‌ها، فهرست‌ها، جدول‌ها و تأکیدها را حفظ می‌کند و در عین حال برای تقسیم و توکنیزه کردن آسان است. یک فرآیند معمولی جذب RAG به این شکل است:

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

options = ConvertOptions()
options.image_export_strategy = SkipImagesStrategy()   # متن‑محور برای 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()

# تقسیم بر اساس سرفصل‌های سطح بالا، سپس تعبیه/ایندکس هر بخش
chunks = [c for c in re.split(r"\n#{1,2} ", markdown) if c.strip()]

چون کتابخانه کاملاً در محل اجرا می‌شود، اسناد حساس هرگز از محیط شما خارج نمی‌شوند — یک نیاز رایج برای صنایع تحت‌نظارت، تیم‌های حقوقی و پایگاه‌های دانش داخلی.

AI‑friendly by design

اکثر SDKهای پایتون، دستیارهای کدنویسی هوش مصنوعی را به‌عنوان یک فکر پس‌زمینه در نظر می‌گیرند — توسعه‌دهنده هنوز باید عامل را به مستندات اشاره کند، مثال‌ها را بچسباند یا از طریق آزمون و خطا دیباگ کند. GroupDocs.Markdown برای پایتون از طریق .NET این رویکرد را معکوس می‌کند: کتابخانه طوری طراحی شده که Claude Code، Cursor، GitHub Copilot و Codex بتوانند بدون هیچ تنظیم دستی‌ای آن را درک کنند.

AGENTS.md داخل wheel می‌آید

این اولین بسته GroupDocs است که یک فایل AGENTS.md را مستقیماً داخل wheel نصب‌شده باندل می‌کند. این فایل از قرارداد نوظهور AGENTS.md پیروی می‌کند — یک README ساده‑Markdown که مخصوص دستیارهای کدنویسی هوش مصنوعی نوشته شده است نه برای انسان‌ها.

هنگامی که pip install groupdocs-markdown-net را اجرا می‌کنید، فایلی در مسیر زیر قرار می‌گیرد:

site-packages/groupdocs/markdown/AGENTS.md

یک دستیار هوش مصنوعی که پروژه شما را باز می‌کند می‌تواند فوراً آن را بخواند و یاد بگیرد:

  • سطح عمومی API (کلاس‌ها، متدها، enumها، استثناها) و نحوهٔ ارتباط آن‌ها.
  • الگوهای استفاده ایدئوماتیک برای رایج‌ترین سناریوها — API استاتیک در مقابل نمونه، هم‌زمان در مقابل ناهمزمان، استراتژی‌های تصویر، front matter، مدیریت خطا.
  • اشکالات رایج و چگونگی اجتناب از آن‌ها — مثلاً کدام overloadهای ConvertOptions می‌توانند None بپذیرند، چگونگی کار با فایل‌های رمز‑گذاری‌شده، چگونگی دریافت هشدارهای تبدیل.
  • عیب‌یابی برای مشکلات مخصوص پلتفرم (libSkiaSharp در macOS، ICU در Linux).

در عمل این به این معنی است که می‌توانید بگویید «از groupdocs-markdown-net برای تبدیل این پوشه PDFها به Markdown برای خط لوله RAG من استفاده کن» و عامل یک کد کارا در اولین تلاش می‌نویسد — بدون نام‌های متد تخیلی، بدون ترتیب نادرست آرگومان‌ها، بدون وارد کردن‌های حدس‌زده.

مستندات قابل خواندن توسط ماشین

برای عواملی که نیاز به جستجوی چیزی دارند که در AGENTS.md نیست، مستندات کامل محصول نیز به‌صورت ماشین‑قابل‑خواندن منتشر می‌شود:

  • کورپوس تک‑فایلی — تمام مستندات به‌صورت یک فایل Markdown ترکیبی، آمادهٔ قرارگیری در پنجرهٔ زمینهٔ عامل: https://docs.groupdocs.com/markdown/python-net/llms-full.txt
  • Markdown صفحه به صفحه — برای دریافت منبع خام، پسوند .md را به هر URL مستندات اضافه کنید: https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
  • فهرست llms.txt — یک فهرست‑مطابق با سبک llms.txt که عامل‌ها را به صفحات مورد نیازشان هدایت می‌کند: https://docs.groupdocs.com/markdown/python-net/llms.txt

سرور MCP برای جستجوی زنده مستندات

برای عامل‌هایی که از Model Context Protocol پشتیبانی می‌کنند، مستندات را به‌صورت یک سرور MCP در دسترس می‌گذاریم. این تنظیمات را به پیکربندی Claude Code یا Cursor خود اضافه کنید:

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

پس از آن، عامل می‌تواند به‌صورت درخواست‑به‑درخواست مستندات را جستجو کند به‌جای این‌که به داده‌های آموزشی که ممکن است منسوخ باشند، وابسته باشد.

Markdown به عنوان ورودی و خروجی

یک تقارن زیبا وجود دارد: خروجی کتابخانه Markdown است — فرمت‌ایی که LLMها برای RAG بهترین تجزیه را دارند — و مستندات نیز به صورت Markdown ارائه می‌شود، به‌صورت یک فایل تک برای آسان‌سازی ورود به پنجرهٔ زمینه. چه بخواهید از عامل بخواهید کدی بنویسد که از کتابخانه استفاده می‌کند، چه بخواهید از عامل بخواهید اسناد شما را از طریق کتابخانه درک کند، Markdown رسانهٔ مشترک است.

مثال خروجی

قطعات کد بالا نزدیک‌ترین برنامهٔ مفید کوتاهی هستند که می‌توانید با این کتابخانه بنویسید. در اینجا همان ایده به‌صورت یک پروژهٔ قابل اجرا بسته‌بندی شده است — سند منبع، اسکریپت پایتون، خروجی پیش‌تولید، requirements.txt و یک Dockerfile — تا بتوانید به‌صورت انتها‑به‑انتها بدون نوشتن چیزی از صفر آن را امتحان کنید.

DOCX منبع

فایل منبع business-plan.docx یک برنامهٔ تجاری کوتاه و با قالب‌بندی غنی است که شامل سرفصل‌ها، جدول‌ها، تصاویر و متادیتا می‌شود.

اسکریپت پایتون

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 خروجی

خروجی quick-example.md با یک بلوک front‑matter YAML که به‌صورت خودکار از متادیتای سند استخراج شده شروع می‌شود، سپس محتوای تبدیل‌شده با جدول‌های GitHub Flavored و سلسله‌مراتب سرفصل‌های جابجا شده (آماده برای تعبیه در یک سند بزرگتر) ادامه می‌یابد.

نمونهٔ برنامهٔ قابل اجرا

همه چیز در یک بسته: sample-app.zip. پس از استخراج:

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

یا در Docker اجرا کنید — Dockerfile گنجانده‌شده وابستگی ICU را که زمان اجرا .NET باندل‌شده در لینوکس به آن نیاز دارد، تنظیم می‌کند:

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

خلاصه

GroupDocs.Markdown برای پایتون از طریق .NET موتور کامل تبدیل سند‑به‑Markdown را به‌صورت یک wheel خودکفا به پایتون می‌آورد — بدون زمان اجرا خارجی، بدون ابر، بدون شگفتی. یک API پایتونیک، پشتیبانی از async و ادغام ابزارهای AI در سطح اول، آن را گزینه‌ای عملی برای تیم‌های پایتون که سیستم‌های RAG، مولدهای سایت ایستا یا خطوط لوله پردازش سند می‌سازند، می‌سازد.

بیشتر بیاموزید

پشتیبانی و بازخورد

برای سوالات یا کمک فنی، لطفاً از Free Support Forum استفاده کنید — خوشحال می‌شویم که کمک کنیم.