Как конвертировать документы в Markdown для ИИ на Python

Многие приложения, использующие LLM или ИИ-агентов, должны обрабатывать отчёты, PDF-файлы, электронные таблицы и презентации в рамках своего рабочего процесса. Эти файлы хранят содержимое в разных структурах, зависящих от формата, поэтому приложениям может потребоваться извлечь и нормализовать их содержимое, прежде чем использовать его в текстовых ИИ-процессах. Преобразование в Markdown обеспечивает согласованное, доступное для проверки текстовое представление, которое последующие компоненты могут читать, хранить и обрабатывать без необходимости разбираться в логике парсинга, специфичной для конкретного формата.

В этом руководстве показано, как преобразовать документы Word, PDF, Excel и PowerPoint в Markdown на Python с помощью Spire.Office for Python, а затем демонстрируется, как передать полученное содержимое Markdown в реальный вызов API LLM для создания краткого изложения. Цель — проиллюстрировать практический процесс предварительной обработки, а не утверждать, что каждая модель ИИ требует Markdown или что преобразование документа автоматически делает его содержимое пригодным для любой задачи ИИ.

1. Почему стоит использовать Markdown для обработки документов с помощью ИИ?

Markdown занимает полезное место в конвейере обработки документов с помощью ИИ. Он представляет структуру документа с помощью облегчённого синтаксиса: заголовки становятся маркерами #, абзацы остаются обычным текстом, списки используют префиксы - или 1., а таблицы сохраняют связи строк и столбцов с помощью символов вертикальной черты. Такое представление удобочитаемо для человека, легко сохраняется и просто преобразуется программно.

Когда вы преобразуете документы в Markdown, полученный текст может служить входными данными для целого ряда задач ИИ. LLM может суммировать содержимое, извлекать ключевые сущности, отвечать на вопросы о нём или создавать переработанную версию. Конвейер поиска может проиндексировать текст для семантического поиска. Агент может прочитать Markdown, чтобы понять, что содержит документ, прежде чем решить, какой инструмент вызвать дальше.

Стоит отличать предварительную обработку в формате Markdown от прямой подачи файлов. Некоторые API моделей принимают исходные файлы — изображения, PDF-файлы или документы Office — через мультимодальные конечные точки или специализированные функции обработки документов. В таких случаях преобразование в Markdown не требуется. Markdown — это необязательное промежуточное представление, выбираемое тогда, когда приложению полезен текстовый формат, который оно может проверить и контролировать перед отправкой содержимого в модель. Решение зависит от требований приложения, а не от универсального правила о том, что все ИИ-процессы обязаны использовать Markdown.

2. Преобразование документов в Markdown на Python

Spire.Office for Python — это набор автономных библиотек Python, которые позволяют создавать, читать, редактировать и преобразовывать документы Office без установки Microsoft Office. Он включает четыре компонента, каждый из которых ориентирован на определённый формат документов:

Установите необходимые пакеты:

pip install spire.doc spire.pdf spire.xls spire.presentation

Поддержка преобразования в Markdown была добавлена в разных версиях для разных компонентов. В таблице ниже перечислены минимальные версии, в которых доступны API, используемые в этой статье:

Spire.Doc 12.6.0, Spire.PDF 11.6.1, Spire.XLS 16.4.0 и Spire.Presentation 10.11.1 — это минимальные версии с поддержкой преобразования в Markdown. Рекомендуется использовать последнюю версию каждого компонента.

Каждый компонент предоставляет свой API для преобразования в Markdown. В следующей таблице приведены проверенные методы преобразования:

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

import os
from spire.doc import Document, FileFormat as DocFileFormat
from spire.pdf import PdfToMarkdownConverter
from spire.xls import Workbook, MarkdownOptions as XlsMarkdownOptions
from spire.presentation import Presentation, FileFormat as PresentationFileFormat


def convert_to_markdown(input_path: str, output_path: str = None) -> str:
    """Convert a Word, PDF, Excel, or PowerPoint file to Markdown.

    Args:
        input_path: Path to the source document.
        output_path: Path for the output .md file. If None, uses the
            input filename with a .md extension in the same directory.

    Returns:
        The path to the generated Markdown file.
    """
    if not os.path.isfile(input_path):
        raise FileNotFoundError(f"Input file not found: {input_path}")

    ext = os.path.splitext(input_path)[1].lower()

    if output_path is None:
        output_path = os.path.splitext(input_path)[0] + ".md"

    if ext in (".doc", ".docx"):
        # Spire.Doc for Python: load and save as Markdown
        doc = Document()
        try:
            doc.LoadFromFile(input_path)
            doc.SaveToFile(output_path, DocFileFormat.Markdown)
        finally:
            doc.Close()

    elif ext == ".pdf":
        # Spire.PDF for Python: use PdfToMarkdownConverter
        # IgnoreImage=True skips images in the PDF; set to False if
        # charts or screenshots contain important information.
        converter = PdfToMarkdownConverter(input_path)
        try:
            converter.MarkdownOptions.IgnoreImage = True
            converter.ConvertToMarkdown(output_path)
        finally:
            converter.Dispose()

    elif ext in (".xls", ".xlsx"):
        # Spire.XLS for Python: use SaveToMarkdown with MarkdownOptions
        workbook = Workbook()
        try:
            workbook.LoadFromFile(input_path)
            options = XlsMarkdownOptions()
            options.SavePicInRelativePath = True
            options.SaveHyperlinkAsRef = False
            workbook.SaveToMarkdown(output_path, options)
        finally:
            workbook.Dispose()

    elif ext in (".ppt", ".pptx"):
        # Spire.Presentation for Python: load and save as Markdown
        presentation = Presentation()
        try:
            presentation.LoadFromFile(input_path)
            presentation.SaveToFile(output_path, PresentationFileFormat.Markdown)
        finally:
            presentation.Dispose()

    else:
        raise ValueError(
            f"Unsupported file extension: {ext}. "
            f"Supported formats: .doc, .docx, .pdf, .xls, .xlsx, .ppt, .pptx"
        )

    return output_path


# Example usage
if __name__ == "__main__":
    result = convert_to_markdown("quarterly_report.docx")
    print(f"Markdown saved to: {result}")

    with open(result, "r", encoding="utf-8") as f:
        content = f.read()
    print(content[:500])  # Preview the first 500 characters

Результат преобразования документа Word в Markdown:

Подробности, специфичные для отдельных форматов, см. в руководствах по отдельным компонентам:

• Преобразование Word в Markdown с помощью Spire.Doc for Python
• Преобразование PDF в Markdown с помощью Spire.PDF for Python
• Преобразование Excel в Markdown с помощью Spire.XLS for Python

3. Отправка содержимого Markdown в LLM

После того как документ преобразован в Markdown, текст может служить входными данными для LLM в таких задачах, как суммирование, извлечение информации или ответы на вопросы. В следующем примере бизнес-отчёт преобразуется в Markdown, полученный файл считывается, а его содержимое отправляется в API OpenAI с инструкцией, специфичной для задачи.

Чтобы запустить этот пример, установите OpenAI Python SDK и задайте свой ключ API в качестве переменной среды:

pip install openai
export OPENAI_API_KEY="your-api-key"

Приведённый ниже код предполагает, что функция convert_to_markdown из предыдущего раздела сохранена в файле с именем convert_to_markdown.py в том же каталоге, или что оба блока кода объединены в один скрипт.

import os
from openai import OpenAI

# Step 1: Convert the document to Markdown
from convert_to_markdown import convert_to_markdown
md_path = convert_to_markdown("business_report.pdf")

# Step 2: Read the Markdown content
with open(md_path, "r", encoding="utf-8") as f:
    markdown_content = f.read()

# Step 3: Construct a task-specific instruction and call the LLM
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

response = client.chat.completions.create(
    model="gpt-6-luna",
    messages=[
        {
            "role": "system",
            "content": "You are a financial analyst. Read the document "
                       "and extract the three most important findings."
        },
        {
            "role": "user",
            "content": f"Here is the document content in Markdown:\n\n"
                       f"{markdown_content}\n\n"
                       f"Provide a concise summary of the key findings."
        }
    ],
    max_completion_tokens=1000
)

# Step 4: Read and display the response
summary = response.choices[0].message.content
print("=== LLM Summary ===")
print(summary)

В этом процессе Spire.Office for Python выполняет преобразование документов, а API OpenAI выполняет анализ с помощью ИИ. Spire.Office — это библиотека для обработки документов, а не фреймворк для ИИ-агентов; она создаёт текст Markdown, который затем потребляет LLM или конвейер агента. Для полноценного агента по обработке документов рассмотрите Spire.Agent.Office.

Одним из важных соображений является размер входных данных. У LLM есть ограничения контекстного окна, и длинный документ может создать Markdown, превышающий максимальную длину входных данных модели. Когда это происходит, приложение должно разбить Markdown на более мелкие фрагменты или выборочно извлечь соответствующие разделы перед отправкой их в модель. С этой задачей могут справиться такие библиотеки, как langchain-text-splitters, или собственная логика разбиения.

4. Использование Markdown для ИИ-агентов и процессов RAG

Markdown, полученный на этапе преобразования, может стать входными данными для более крупных ИИ-процессов. Два распространённых шаблона — это ИИ-агенты и генерация с дополненной выборкой (RAG).

Что касается ИИ-агентов, приложение может предоставить преобразованный Markdown в качестве контекста, который агент читает перед принятием решения о том, какие действия предпринять. Например, агент поддержки может получить Markdown клиентского договора и отвечать на вопросы об условиях продления, графике платежей или положениях о расторжении. Агент рассматривает Markdown как читаемый контекст, а не как структурированный запрос к базе данных.

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

Само по себе преобразование документов в Markdown не реализует полноценную систему агента или RAG. Векторные базы данных, модели встраивания, фреймворки оркестрации, протоколы вызова инструментов и ранжирование при поиске — это отдельные компоненты, работающие на последующих этапах. Этап преобразования создаёт текстовые входные данные; остальная часть конвейера определяет, как этот текст используется.

5. Проверка Markdown перед обработкой с помощью ИИ

Качество преобразованного Markdown напрямую влияет на качество последующих результатов ИИ. Если при преобразовании теряется структура, искажаются данные или пропускается содержимое, LLM или агент будут работать с неверным или неполным контекстом. Прежде чем полагаться на преобразованный Markdown для важных задач, проверьте вывод на наличие наиболее распространённых проблемных мест:

• Иерархия заголовков и порядок абзацев. Убедитесь, что уровни разделов (#, ##, ###) отражают структуру исходного документа и что абзацы расположены в правильной последовательности.
• Строки, столбцы и числовые значения таблиц. Проверьте, что связи строк и столбцов сохранены, а числа, даты и денежные значения соответствуют источнику. Если финансовая таблица теряет выравнивание, LLM может создать резюме на основе неверных связей — например, приписав показатель выручки не тому региону.
• Изображения, ссылки и сложные макеты. Markdown не может представить каждый визуальный элемент. Изображения могут быть пропущены или заменены ссылками на пути к файлам. Макеты с несколькими колонками, текстовые поля и встроенные объекты могут не сохраниться в исходном виде после преобразования.
• Отсканированные PDF-файлы. Если исходный PDF содержит отсканированные изображения, а не встроенный текст, результатом преобразования может быть пустой или почти пустой вывод. В таких случаях необходим этап OCR — до или вместо преобразования в Markdown.
• Длинные документы. Убедитесь, что был преобразован весь документ, а не только первый раздел. Для документов, превышающих контекстное окно модели, убедитесь, что Markdown можно разбить на осмысленные фрагменты, не нарушая таблицы и не отделяя заголовки от их содержимого.

Преобразование не гарантирует идеального сохранения каждой визуальной или смысловой особенности. Вывод в формате Markdown — это промежуточное представление, а не точная копия исходного документа. Проверка преобразованного текста перед передачей его в модель ИИ — практический шаг, который предотвращает распространение ошибок в резюме, извлечённые данные или решения агента.

6. Заключение

В этой статье был рассмотрен процесс предварительной обработки документов с преобразованием в Markdown для ИИ-приложений на Python. Процесс состоит из трёх этапов: преобразование поддерживаемых форматов документов (Word, PDF, Excel, PowerPoint) в Markdown с помощью Spire.Office for Python, проверка преобразованного вывода на структурную точность и передача содержимого Markdown соответствующему компоненту обработки ИИ — будь то вызов API LLM, контекст агента или конвейер разбиения для RAG.

Markdown — это один из полезных способов подготовить содержимое документа для ИИ-приложений, а не обязательный входной формат для каждой модели. Выбор в пользу преобразования документов в Markdown зависит от того, полезно ли приложению текстовое промежуточное представление, которое оно может проверить, сохранить и контролировать. Для получения дополнительной информации посетите страницу продукта Spire.Office for Python или документацию по преобразованию.

См. также

• Как преобразовать HTML в Markdown на Python: пошаговое руководство
• Как преобразовать Markdown в HTML на Python: пошаговое руководство
• Python: преобразование Markdown в PDF
• Преобразование PDF в HTML с помощью Python: полное руководство для разработчиков