Перенесите свои документы в 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‑runtime и все необходимые нативные библиотеки. Нет необходимости устанавливать dotnet, Microsoft Office, Adobe Acrobat или облачные сервисы.
  • Кроссплатформенность. Windows x64/x86, Linux x64, macOS x64 и Apple Silicon (ARM64). Python 3.5 – 3.14.
  • Питонический API. Классы используют PascalCase, методы и свойства — snake_case, значения перечислений — UPPER_SNAKE_CASE. Контекстные менеджеры детерминированно освобождают загруженные документы.
  • По‑настоящему асинхронный. Каждый статический и экземплярный метод имеет асинхронный аналог с суффиксом _async. Операции ввода‑вывода файлов асинхронны, а CPU‑интенсивное преобразование выполняется в рабочем потоке — ваш цикл событий 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")

И всё — без конфигураций, без опций, без шаблонного кода. Режим оценки обрабатывает первые 3 страницы и добавляет водяной знак. Чтобы снять ограничения, примените лицензию:

from groupdocs.markdown import License

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

Или задайте переменную окружения GROUPDOCS_LIC_PATH, и лицензия будет применена автоматически при импорте.

Поддерживаемые форматы

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 — одновременная конвертация множества документов

Поскольку ввод‑вывод файлов асинхронен, 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()   # 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()]

Поскольку библиотека полностью работает локально, конфиденциальные документы никогда не покидают вашу среду — частое требование для регулируемых отраслей, юридических команд и внутренних баз знаний.

AI‑friendly by design

Большинство Python‑SDK рассматривают AI‑ассистентов как второстепенный момент — разработчику всё равно приходится указывать агенту документацию, копировать примеры или отлаживать методом проб и ошибок. GroupDocs.Markdown для Python через .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 (классы, методы, перечисления, исключения) и их взаимосвязи.
  • Идиоматические шаблоны для самых распространённых сценариев — статический vs экземплярный API, синхронный vs асинхронный, стратегии изображений, front‑matter, обработка ошибок.
  • Распространённые подводные камни и способы их обхода — какие перегрузки 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 на выходе

Здесь есть приятная симметрия: выход библиотеки — Markdown — формат, который LLM лучше всего обрабатывают в RAG, а её документация тоже в Markdown, предоставленная как единый файл для лёгкого захвата контекстом. Будь то запрос к агенту написать код, использующий библиотеку, или запрос к агенту понять ваши документы через библиотеку, Markdown служит общим посредником.

Пример экспорта

Приведённые выше фрагменты почти являются самым коротким полезным приложением, которое можно написать с этой библиотекой. Ниже тот же подход упакован в готовый проект — исходный документ, скрипт Python, заранее сгенерированный вывод, requirements.txt и Dockerfile — чтобы вы могли попробовать всё от начала до конца без написания кода с нуля.

Исходный DOCX

Исходный файл business-plan.docx — короткий, богато отформатированный бизнес‑план с заголовками, таблицами, изображениями и метаданными.

Скрипт 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

Файл quick-example.md начинается с блока YAML‑front‑matter, автоматически извлечённого из метаданных документа, за которым следует преобразованное содержимое с таблицами 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‑runtime на Linux:

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

Итоги

GroupDocs.Markdown для Python через .NET переносит полностью готовый движок конвертации документов в Markdown в мир Python как самодостаточный wheel — без внешних рантаймов, без облака, без сюрпризов. Питонический API, поддержка async и первоклассная интеграция с AI‑инструментами делают её практичным выбором для команд Python, создающих RAG‑системы, генераторы статических сайтов или конвейеры обработки документов.

Узнать больше

Поддержка и обратная связь

По вопросам или технической помощи, пожалуйста, используйте наш Free Support Forum — будем рады помочь.