اجلب مستنداتك إلى خطوط أنابيب الذكاء الاصطناعي — مباشرة من بايثون، داخل المؤسسة، بنقرة pip install واحدة.

اليوم نطلق الإصدار العام الأول لـ GroupDocs.Markdown للبايثون عبر .NET على PyPI. المكتبة تحوّل PDF وWord وExcel وEPUB وأكثر من 20 صيغة أخرى إلى Markdown نظيف وذو بنية دلالية — الصيغة التي تعمل معها نماذج LLMs، خطوط أنابيب RAG، ومولدات المواقع الثابتة بأفضل شكل.

إذا كنت تتابع الإصدار الخاص بـ .NET من سبتمبر (/markdown/groupdocs-markdown-for-net-first-public-release/) (أو إعادة هيكلة API الكاملة في 26.3 (https://releases.groupdocs.com/markdown/net/release-notes/2026/groupdocs-markdown-for-net-26-3-release-notes/))، فالدافع هو نفسه: تنسيق المستند يحمل دلالات، والحفاظ على تلك البنية الدلالية هو ما يجعل نظام RAG يقدم إجابات جيدة. المنشور السابق يغطي المشكلة (OCR يسطّح البنية، LLMs تحتاج إلى markdown) والحل (مُعالج يعتمد على DOM يتجول في المستند ويُنتج Markdown) بعمق — لن نعيد سرد القصة هنا.

بدلاً من ذلك، دعنا نركز على ما هو جديد لمطوري بايثون.

ما ستحصل عليه

  • عجلة واحدة، بدون تبعيات وقت التشغيل. pip install groupdocs-markdown-net يجلب عجلة ذاتية الاكتفاء تُضمّن بيئة تشغيل .NET وكل المكتبة الأصلية التي تحتاجها. لا تثبيت dotnet، لا Microsoft Office، لا Adobe Acrobat، لا خدمات سحابية.
  • متعددة المنصات. Windows x64/x86، Linux x64، macOS x64 وApple Silicon (ARM64). بايثون 3.5 حتى 3.14.
  • واجهة برمجة تطبيقات بايثونية. الفئات تستخدم PascalCase، والطرق والخصائص تستخدم snake_case، وقيم التعداد تستخدم UPPER_SNAKE_CASE. مدراء السياق يفرغون المستندات المحمّلة بشكل حتمي.
  • متزامنة حقًا. كل طريقة ثابتة أو مثيلة لها نظير _async. عمليات الإدخال/الإخراج للملفات غير متزامنة والتحويل المكثف للمعالجة يُجرى على خيط عامل — حلقة أحداث asyncio تبقى حرة.
  • ملائمة للوكيل الذكي. العجلة المثبتة تضم ملف 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")

هذا كل شيء — لا إعدادات، لا خيارات، لا قالب مبدئي. وضع التقييم يعالج أول 3 صفحات ويضيف علامة مائية. لإزالة الحدود، طبّق ترخيصًا:

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 غير متزامن — تحويل مستندات متعددة بالتوازي

نظرًا لأن الإدخال/الإخراج للملفات غير متزامن، يسمح 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 هو صيغة الإدخال المفضلة لنماذج التضمين وخطوط أنابيب الاسترجاع — فهو يحافظ على العناوين والقوائم والجداول والتنسيق مع سهولة التجزئة والرمز. مثال نموذجي لإدخال 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()]

نظرًا لأن المكتبة تعمل بالكامل داخل المؤسسة، لا تغادر المستندات الحساسة بيئتك — وهو مطلب شائع للقطاعات المنظمة، الفرق القانونية، وقواعد المعرفة الداخلية.

صديقة للذكاء الاصطناعي بحكم التصميم

معظم SDKs للبايثون تعتبر المساعدين البرمجيين للذكاء الاصطناعي فكرة لاحقة — لا يزال المطور بحاجة إلى توجيه الوكيل إلى الوثائق، لصق أمثلة، أو تصحيح الأخطاء بالتجربة والخطأ. GroupDocs.Markdown للبايثون عبر .NET يغيّر ذلك: المكتبة مصممة بحيث يمكن للوكيل مثل Claude Code، Cursor، GitHub Copilot، وCodex الاستفادة منها دون أي إعداد يدوي.

AGENTS.md يُضمّن داخل العجلة

هذه هي الحزمة الأولى من GroupDocs التي تُضمّن ملف AGENTS.md مباشرة داخل العجلة المثبتة. يتبع الملف اتفاقية AGENTS.md الناشئة — README بصيغة Markdown موجه خصيصًا للمساعدين البرمجيين للذكاء الاصطناعي بدلاً من البشر.

عند تشغيل pip install groupdocs-markdown-net، يُوضع الملف في:

site-packages/groupdocs/markdown/AGENTS.md

يمكن لمساعد ذكاء اصطناعي يفتح مشروعك قراءته وتعلمه فورًا:

  • سطح API العام (الفئات، الطرق، التعدادات، الاستثناءات) وكيفية ترابطها.
  • أنماط الاستخدام الشائعة لأكثر السيناريوهات انتشارًا — API ثابتة مقابل مثيلة، متزامنة مقابل غير متزامنة، استراتيجيات الصور، front matter، معالجة الأخطاء.
  • المخاطر الشائعة وكيفية تجنّبها — مثلاً أي تحميلات ConvertOptions تقبل None، كيفية التعامل مع الملفات المحمية بكلمة مرور، كيفية التقاط تحذيرات التحويل.
  • استكشاف الأخطاء للمنصات المختلفة (libSkiaSharp على macOS، ICU على Linux).

في الممارسة العملية يعني ذلك أنه يمكنك قول “استخدم groupdocs-markdown-net لتحويل هذا المجلد من PDFs إلى 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 — الصيغة التي تُفسّرها LLMs بأفضل شكل لـ 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 وتدرج عناوين مُعدَّل (جاهز للتضمين داخل مستند أكبر).

تطبيق تجريبي قابل للتنفيذ

كل شيء مُجمَّع معًا: 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 المضمَّنة على Linux:

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 إلى بايثون كعجلة ذاتية الاكتفاء — بدون بيئة تشغيل خارجية، بدون سحابة، بدون مفاجآت. API بايثونية، دعم غير متزامن، وتكامل أولي مع أدوات الذكاء الاصطناعي تجعلها خيارًا عمليًا لفرق بايثون التي تبني أنظمة RAG، مولدات مواقع ثابتة، أو خطوط أنابيب معالجة مستندات.

تعرف على المزيد

الدعم والتعليقات

للأسئلة أو المساعدة التقنية، يرجى استخدام Free Support Forum (https://forum.groupdocs.com/) — سنكون سعداء بمساعدتك.