MarkItDown: конвертация файлов в Markdown для LLM

MarkItDown — лёгкая Python-утилита для конвертации различных файлов в Markdown, предназначенная для использования с языковыми моделями (LLM) и смежными конвейерами анализа текста.

Внимание

MarkItDown выполняет ввод-вывод с привилегиями текущего процесса. Подобно open() или requests.get(), он обращается к любым ресурсам, доступным этому процессу. В ненадёжных окружениях обязательно фильтруйте входные данные и вызывайте наиболее узкую из подходящих функций convert_* — например, convert_stream() или convert_local(). Подробнее см. раздел «Вопросы безопасности».

По своей задаче MarkItDown ближе всего к textract, однако акцент сделан на сохранении важной структуры и содержимого документа в формате Markdown: заголовков, списков, таблиц, ссылок и т. д. Результат нередко выглядит вполне читабельно, но в первую очередь он рассчитан на потребление инструментами анализа текста, а не на высококачественное воспроизведение документа для человека.

На данный момент MarkItDown поддерживает конвертацию из:

PDF
PowerPoint
Word
Excel
Изображений (EXIF-метаданные и OCR)
Аудиофайлов (EXIF-метаданные и транскрибирование речи)
HTML
Текстовых форматов (CSV, JSON, XML)
ZIP-архивов (с перебором содержимого)
YouTube-ссылок
EPub
… и многого другого!

Почему Markdown?

Markdown практически неотличим от обычного текста — минимум разметки и форматирования, — но при этом позволяет отражать важную структуру документа. Современные языковые модели, например GPT-4o от OpenAI, «говорят» на Markdown по умолчанию и нередко используют его в ответах без какого-либо указания. Это свидетельствует о том, что они обучены на огромных массивах текста в формате Markdown и хорошо его понимают. Дополнительный бонус: соглашения Markdown весьма экономны с точки зрения токенов.

Предварительные требования

MarkItDown требует Python 3.10 или выше. Рекомендуется использовать виртуальное окружение (virtual environment), чтобы избежать конфликтов зависимостей.

При стандартной установке Python создать и активировать виртуальное окружение можно следующими командами:

python -m venv .venv
source .venv/bin/activate

При использовании uv виртуальное окружение создаётся так:

uv venv --python=3.12 .venv
source .venv/bin/activate
# ПРИМЕЧАНИЕ: для установки пакетов в это окружение используйте 'uv pip install', а не просто 'pip install'

При использовании Anaconda:

conda create -n markitdown python=3.12
conda activate markitdown

Установка

Для установки MarkItDown используйте pip: pip install 'markitdown[all]'. Либо установите из исходников:

git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

Использование

Командная строка

markitdown path-to-file.pdf > document.md

Или укажите выходной файл с помощью флага -o:

markitdown path-to-file.pdf -o document.md

Также поддерживается передача данных через пайп:

cat path-to-file.pdf | markitdown

Опциональные зависимости

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

pip install 'markitdown[pdf, docx, pptx]'

установит только зависимости для форматов PDF, DOCX и PPTX.

На данный момент доступны следующие опциональные зависимости:

[all] — устанавливает все опциональные зависимости
[pptx] — зависимости для файлов PowerPoint
[docx] — зависимости для файлов Word
[xlsx] — зависимости для файлов Excel
[xls] — зависимости для файлов Excel старых форматов
[pdf] — зависимости для PDF-файлов
[outlook] — зависимости для сообщений Outlook
[az-doc-intel] — зависимости для Azure Document Intelligence
[az-content-understanding] — зависимости для Azure Content Understanding
[audio-transcription] — зависимости для транскрибирования аудиофайлов wav и mp3
[youtube-transcription] — зависимости для получения транскрипций YouTube-видео

Плагины

MarkItDown поддерживает сторонние плагины (plugins). По умолчанию плагины отключены. Чтобы посмотреть список установленных плагинов:

markitdown --list-plugins

Чтобы включить плагины:

markitdown --use-plugins path-to-file.pdf

Найти доступные плагины можно на GitHub по хэштегу #markitdown-plugin. Для разработки собственного плагина обратитесь к packages/markitdown-sample-plugin.

Плагин markitdown-ocr

Плагин markitdown-ocr добавляет поддержку OCR в конвертеры PDF, DOCX, PPTX и XLSX, извлекая текст из встроенных изображений с помощью LLM Vision — по той же схеме llm_client / llm_model, которую MarkItDown уже использует для описания изображений. Никаких дополнительных ML-библиотек или бинарных зависимостей не требуется.

Установка:

pip install markitdown-ocr
pip install openai  # или любой OpenAI-совместимый клиент

Использование:

Передайте те же llm_client и llm_model, что используете для описания изображений:

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)
result = md.convert("document_with_images.pdf")
print(result.text_content)

Если llm_client не задан, плагин всё равно загружается, однако OCR молча пропускается и вместо него используется стандартный встроенный конвертер.

Подробная документация — в файле packages/markitdown-ocr/README.md.

Azure Content Understanding

Azure Content Understanding обеспечивает более качественную конвертацию: извлечение структурированных полей (в виде YAML front matter), мультимодальную поддержку (документы, изображения, аудио, видео) и настраиваемые анализаторы.

Установка: pip install 'markitdown[az-content-understanding]'

Когда использовать Content Understanding

Content Understanding оптимален, когда встроенные конвертеры или Document Intelligence не справляются с задачей:

Аудио и видеофайлы — CU является единственным вариантом для видео и более качественным облачным вариантом для аудио. Встроенные конвертеры не поддерживают видео и обеспечивают лишь базовую транскрипцию аудио.
Извлечение структурированных полей — Предварительно созданные или пользовательские анализаторы извлекают специфичные для предметной области поля (суммы в счетах, даты в чеках, пункты договоров) и сериализуют их в YAML front matter. Ни встроенная интеграция, ни Doc Intel эту возможность не предоставляют.
Более высокое качество извлечения данных из документов — облачный анализ разметки и OCR для сканированных PDF, сложных таблиц и многостраничных документов.
Единый API для всех модальностей — один параметр cu_endpoint обрабатывает документы, изображения, аудио и видео с автоматическим выбором анализатора.

Возможность Встроенные конвертеры Azure Document Intelligence Azure Content Understanding

Возможность	Встроенные конвертеры	Azure Document Intelligence	Azure Content Understanding
Конвертация документов	Офлайн, формато-специфичное извлечение	Облачное извлечение разметки	Облачное мультимодальное извлечение
Структурированные поля	Недоступно	Не предоставляется этой интеграцией	YAML front matter из полей анализатора
Пользовательские анализаторы	Недоступно	Не настраивается в этой интеграции	Поддерживается через `cu_analyzer_id`
Аудио и видео	Базовое аудио, видео не поддерживается	Не поддерживается	Анализаторы аудио и видео
Стоимость	Только локальные вычисления	Оплачиваемые вызовы Azure API	Оплачиваемые вызовы Azure API

Конвертация документов

Офлайн, формато-специфичное извлечение

Облачное извлечение разметки

Облачное мультимодальное извлечение

Структурированные поля

Недоступно

Не предоставляется этой интеграцией

YAML front matter из полей анализатора

Пользовательские анализаторы

Недоступно

Не настраивается в этой интеграции

Поддерживается через cu_analyzer_id

Аудио и видео

Базовое аудио, видео не поддерживается

Не поддерживается

Анализаторы аудио и видео

Стоимость

Только локальные вычисления

Оплачиваемые вызовы Azure API

CLI:

markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"

Python API:

from markitdown import MarkItDown

# Без настройки — анализатор выбирается автоматически по типу файла
md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf")   # документы → prebuilt-documentSearch
result = md.convert("meeting.mp4")  # видео → prebuilt-videoSearch
result = md.convert("call.wav")     # аудио → prebuilt-audioSearch
print(result.markdown)

С пользовательским анализатором (для извлечения предметно-специфичных полей):

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_analyzer_id="my-invoice-analyzer",
)
result = md.convert("invoice.pdf")
print(result.markdown)
# Вывод содержит YAML front matter с извлечёнными полями:
# ---
# contentType: document
# fields:
#   VendorName: CONTOSO LTD.
#   InvoiceDate: '2019-11-15'
# ---
# <!-- page 1 -->
# ...

Если задан cu_analyzer_id, конвертер автоматически применяет его только к совместимым типам файлов на основе модальности анализатора. Несовместимые типы (например, аудиофайлы с анализатором для документов) автоматически перенаправляются к стандартным предварительно созданным анализаторам.

Замечание о стоимости: каждый вызов convert() для формата, маршрутизируемого через CU, является оплачиваемым вызовом Azure API. Используйте cu_file_types, чтобы ограничить форматы, передаваемые в CU:

from markitdown.converters import ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],  # через CU обрабатываются только PDF
)

Подробнее об Azure Content Understanding — в официальной документации.

Azure Document Intelligence

Для конвертации с помощью Microsoft Document Intelligence:

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

Подробнее о настройке ресурса Azure Document Intelligence — в официальной документации.

Python API

Базовое использование:

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # Установите True, чтобы включить плагины
result = md.convert("test.xlsx")
print(result.text_content)

Конвертация через Document Intelligence:

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

Чтобы использовать большие языковые модели для описания изображений (в настоящее время поддерживается для файлов pptx и изображений), передайте llm_client и llm_model:

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.text_content)

Docker

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

Участие в разработке

Проект открыт для вкладов (contributions) и предложений. Большинство вкладов требует принятия Лицензионного соглашения для участников (Contributor License Agreement, CLA), подтверждающего ваше право предоставлять нам права на использование вашего кода. Подробности — на https://cla.opensource.microsoft.com.

При отправке pull request CLA-бот автоматически определит, нужно ли вам подписать CLA, и соответствующим образом оформит PR (проверка статуса, комментарий). Просто следуйте инструкциям бота. Это нужно сделать лишь один раз для всех репозиториев, использующих наш CLA.

Проект придерживается Кодекса поведения Microsoft Open Source. Дополнительная информация — в FAQ по Кодексу поведения; с вопросами и комментариями также можно обратиться на opencode@microsoft.com.

Как внести вклад

Вы можете помочь, разбирая задачи (issues) или участвуя в ревью pull request-ов. Любые issue и PR приветствуются, однако некоторые из них помечены метками «open for contribution» и «open for reviewing», чтобы облегчить участие сообщества. Это лишь рекомендации — вы можете участвовать в любой форме.

	Все	Особенно нуждаются в помощи сообщества
Issues	Все issues	Issues, открытые для вклада
PRs	Все PRs	PRs, открытые для ревью

Все

Особенно нуждаются в помощи сообщества

Issues

Все issues

Issues, открытые для вклада

PRs

Все PRs

PRs, открытые для ревью

Запуск тестов и проверок

Перейдите в каталог пакета MarkItDown:
```
cd packages/markitdown
```

Установите hatch и запустите тесты:

pip install hatch  # Другие способы установки hatch: https://hatch.pypa.io/dev/install/
hatch shell
hatch test

(Альтернатива) Используйте Devcontainer со всеми установленными зависимостями:

# Откройте проект в Devcontainer и выполните:
hatch test

Перед отправкой PR запустите pre-commit проверки: pre-commit run --all-files

Вопросы безопасности

MarkItDown выполняет ввод-вывод с привилегиями текущего процесса. Подобно open() или requests.get(), он обращается к любым ресурсам, доступным этому процессу.

Фильтруйте входные данные: не передавайте в MarkItDown непроверенные данные напрямую. Если какая-либо часть входных данных может контролироваться ненадёжным пользователем или системой — например, в hosted- или серверных приложениях — их необходимо проверить и ограничить до вызова MarkItDown. В зависимости от окружения это может включать: ограничение путей к файлам, фильтрацию URI-схем и сетевых назначений, блокировку доступа к приватным, loopback-, link-local- и metadata-service-адресам.

Вызывайте только нужный метод конвертации: используйте наиболее узкий API, подходящий для вашего случая. Метод convert() намеренно сделан универсальным и умеет работать с локальными файлами, удалёнными URI и байтовыми потоками. Если приложению нужны только локальные файлы — вызывайте convert_local(). Если требуется более точный контроль над загрузкой URI, выполните requests.get() самостоятельно и передайте объект ответа в convert_response(). Для максимального контроля откройте поток к нужному источнику и вызовите convert_stream().

Разработка сторонних плагинов

Вы также можете участвовать, создавая и публикуя сторонние плагины. Подробности — в packages/markitdown-sample-plugin.

Товарные знаки

Этот проект может содержать товарные знаки или логотипы проектов, продуктов или сервисов. Авторизованное использование товарных знаков или логотипов Microsoft подчиняется Руководству Microsoft по товарным знакам и фирменному стилю и должно ему соответствовать. Использование товарных знаков или логотипов Microsoft в модифицированных версиях проекта не должно вводить в заблуждение или создавать впечатление о спонсорстве Microsoft. Использование товарных знаков или логотипов третьих сторон регулируется политиками этих сторон.