הביאו את המסמכים שלכם לצינורות AI — ישירות מ‑Python, במקומי, עם פקודת pip install אחת.

היום אנחנו משחררים את הגרסה הציבורית הראשונה של GroupDocs.Markdown עבור Python דרך .NET ב‑PyPI. הספרייה ממירה PDF, Word, Excel, EPUB ועוד 20+ פורמטים נוספים ל‑Markdown נקי ותחבירי — הפורמט שבו מודלים גדולים של שפה (LLM), צינורות RAG, ומחוללי אתרי סטטיים עובדים בצורה הטובה ביותר.

אם עקבתם אחרי הגרסה של .NET משנת ספטמבר (או את שדרוג ה‑API המלא ב‑26.3), ההיגיון זהה: עיצוב המסמך נושא סמנטיקה, ושמירה על המבנה הסמנטי היא מה שמאפשר למערכת RAG לתת תשובות מדויקות. הפוסט הקודם מכסה את הבעיה (OCR משטחים את המבנה, LLMים צריכים Markdown) ו‑את הפתרון (רינדור מבוסס DOM שמטייל במסמך ופולט Markdown) בפירוט — לא נחזור על הסיפור כאן.

במקום זאת, נתרכז במה שחדש למפתחים ב‑Python.

מה אתם מקבלים

  • קובץ wheel יחיד, ללא תלות בזמן ריצה. pip install groupdocs-markdown-net מוריד קובץ wheel עצמאי שמאגד את סביבת .NET ואת כל הספריות הטבעיות שהוא צריך. אין צורך בהתקנת dotnet, אין צורך ב‑Microsoft Office, אין צורך ב‑Adobe Acrobat, ואין צורך בשירותי ענן.
  • רב‑פלטפורמי. Windows x64/x86, Linux x64, macOS x64 ו‑Apple Silicon (ARM64). Python 3.5 עד 3.14.
  • API פייתוני. שמות מחלקות ב‑PascalCase, שיטות ו‑properties ב‑snake_case, ערכי enum ב‑UPPER_SNAKE_CASE. מנהלי הקשר (context managers) משחררים מסמכים טעונים באופן דטרמיניסטי.
  • אסינכרוני באמת. לכל שיטה סטטית ולא סטטית יש מקביל _async. קריאת קבצים היא אסינכרונית והמרה שמצריכה CPU רצה על thread עובד — לולאת האירועים של asyncio נשארת פנויה.
  • ידידותי לסוכני AI. קובץ ה‑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 כמשתנה סביבתי והוא יוחל אוטומטית בעת ה‑import.

פורמטים נתמכים

חבילת ה‑Python מטפלת באותו מגוון פורמטים כמו ספריית .NET:

  • PDF — .pdf
  • Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
  • גיליונות — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
  • ספרים אלקטרוניים — .epub, .mobi
  • טקסט / סימון / עזרה — .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 הוא פורמט הקלט המועדף למודלים של הטמעה וצינורות אחזור — הוא משמר כותרות, רשימות, טבלאות והדגשות תוך שהוא קל לחיתוך וטוקניזציה. תהליך קלט טיפוסי ל‑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‑ים של Python מתייחסים לעוזרי קוד AI כאל תוספת אחרי‑העבודה — המפתח עדיין צריך להפנות את הסוכן לתיעוד, להדביק דוגמאות, או לתקן באגים דרך ניסוי וטעייה. GroupDocs.Markdown for Python via .NET משנה את זה: הספרייה נבנתה כך שסוכנים כמו Claude Code, Cursor, GitHub Copilot, ו‑Codex יכולים לקלוט אותה ללא שום הגדרה ידנית.

AGENTS.md נכלל בתוך ה‑wheel

זו החבילה הראשונה של GroupDocs שמארזת קובץ AGENTS.md ישירות בתוך ה‑wheel המותקן. הקובץ עומד על קונבנציית AGENTS.md המתפתחת — README בפורמט Markdown פשוט שנכתב במיוחד עבור עוזרי קוד AI ולא עבור בני אדם.

כאשר מריצים pip install groupdocs-markdown-net, הקובץ נופל ב‑:

site-packages/groupdocs/markdown/AGENTS.md

סוכן AI הפותח את הפרויקט שלכם יכול לקרוא אותו וללמוד מייד:

  • את משטח ה‑API הציבורי המלא (מחלקות, שיטות, enums, חריגות) ואת הקשרים ביניהם.
  • דפוסי שימוש אידיאומטיים לתרחישים הנפוצים ביותר — 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 יוצא

קיימת סימטריה נעימה כאן: הפלט של הספרייה הוא Markdown — הפורמט שה‑LLM קורא בצורה הטובה ביותר עבור RAG — והתיעוד שלה הוא גם Markdown, מוגש כקובץ יחיד לצריכת חלון הקשר. בין אם אתם מבקשים מסוכן לכתוב קוד שמשתמש בספרייה, או מבקשים מסוכן להבין את המסמכים שלכם דרך הספרייה, Markdown הוא המדיה המשותפת.

דוגמת ייצוא

הקטעים שלמעלה קרובים לתוכנית הקצרה והשימושית ביותר שניתן לכתוב עם הספרייה. הנה אותה רעיון ארוז כפרויקט שניתן להריץ — מסמך מקור, סקריפט Python, פלט שנוצר מראש, requirements.txt, ו‑Dockerfile — כך שתוכלו לנסות את הכול מקצה לקצה ללא כתיבת קוד מאפס.

קובץ DOCX מקור

קובץ המקור business-plan.docx הוא תכנית עסקית קצרה ועשירה בפורמט, עם כותרות, טבלאות, תמונות ו‑metadata.

סקריפט Python

from groupdocs.markdown import MarkdownConverter, ConvertOptions, MarkdownFlavor

def quick_example():
    """המרת מסמך Word ל‑Markdown עם טעם GitHub ו‑YAML front matter."""

    # שורת קוד אחת — מחזירה מחרוזת Markdown
    md = MarkdownConverter.to_markdown("business-plan.docx")

    # עם אפשרויות — כותב לקובץ
    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 שה‑runtime של .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 for Python via .NET מביא את מנוע ההמרה המלא של מסמך‑ל‑Markdown ל‑Python כחבילה wheel עצמאית — ללא runtime חיצוני, ללא ענן, ללא הפתעות. API פייתוני, תמיכה אסינכרונית, ושילוב כלי AI ברמה ראשונה הופכים אותה לבחירה מעשית לצוותי Python הבונים מערכות RAG, מחוללי אתרי סטטיים, או צינורות עיבוד מסמכים.

למידע נוסף

תמיכה ומשוב

לשאלות או סיוע טכני, אנא השתמשו ב‑Free Support Forum — נשמח לעזור.