API VEGA

MarkItDown

MarkItDown — легковесная утилита на Python для преобразования различных файлов в Markdown для использования с LLM и соответствующими конвейерами анализа текста. В этом отношении он наиболее близок к textract, но с упором на сохранение важной структуру документа и содержимого в Markdown (включая заголовки, списки, таблицы, ссылки и т. д.). Хотя вывод часто бывает достаточно презентабельным и удобочитаемым, он предназначен для инструментов анализа текста — и может не быть лучшим вариантом для высокоточного преобразования документов для чтения человеком.

MarkItDown в настоящее время поддерживает конвертацию из:

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

Почему Markdown?

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

Требования

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

При обычной установке 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 также поддерживает плагины сторонних производителей. Плагины отключены по умолчанию. Чтобы увидеть установленные плагины:

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, извлекая текст из встроенных изображений с помощью Vision LLM — тот же паттерн 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 не expose-ят поля.
  • Высококачественное извлечение документов — анализ макета и OCR в облаке для сканов, сложных таблиц и многостраничных документов.
  • Единый API для всех модальностей — один cu_endpoint обрабатывает документы, изображения, аудио и видео с автоматической маршрутизацией анализаторов.
ВозможностьВстроенные конвертерыAzure Document IntelligenceAzure Content Understanding
Конвертация документовОффлайн, извлечение по форматуРаспознавание макета в облакеРаспознавание по многим модальностям в облаке
Структурированные поляНедоступныНе доступны через этот интеграторYAML front matter из полей анализатора
Пользовательские анализаторыНедоступныНе настраиваются в этом интегратореПоддерживаются с cu_analyzer_id
Аудио и видеоБазовое аудио, без видеоНе поддерживаетсяАнализ аудио и видео
СтоимостьТолько локальные вычисленияОплата вызовов к Azure APIОплата вызовов к 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")   # documents → prebuilt-documentSearch
result = md.convert("meeting.mp4")  # video → prebuilt-videoSearch
result = md.convert("call.wav")     # audio → 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 конвертер автоматически ограничивает маршрутизацию под compatible file types в зависимости от модальности анализатора. Несовместимые типы (например, аудио для анализатора документов) автоматически перенаправляются к дефолтным предобработчикам.

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

from markitdown.converters import ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],  # только PDF используют CU
)

Более подробную информацию об 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

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

from markitdown import MarkItDown

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

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

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

Вклад

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

Когда вы отправляете PR, CLA-бот автоматически определит, нужно ли вам предоставить CLA и пометит PR соответствующим образом. Следуйте инструкциям бота. Это нужно сделать лишь однажды для всех репозиториев с нашей CLA.

Этот проект принял Microsoft Open Source Code of Conduct.

Дополнительную информацию смотрите в разделах FAQ про кодекс поведения или свяжитесь с opencode@microsoft.com с любыми дополнительными вопросами.

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

Вы можете помогать, исследуя проблемы или помогая с обзором PR. Любая проблема или PR приветствуются, но у нас есть пометки «open for contribution» и «open for reviewing», чтобы облегчить участие сообщества. Это — рекомендации, и вы можете вносить вклад любым удобным для вас способом.

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

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

  • Перейдите в пакет 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 run --all-files

Соображения по безопасности

MarkItDown выполняет ввод/вывод с привилегиями текущего процесса. Как и open() или requests.get(), он будет получать доступ к ресурсам, доступным самому процессу.

Очистка входных данных: Не передавайте непроверенный ввод напрямую в MarkItDown. Если какая-либо часть входа может находиться под контролем ненадёжного пользователя или системы, например в размещённых или серверных приложениях, её следует валидировать и ограничивать до вызова MarkItDown. В зависимости от окружения это может включать ограничение путей к файлам, ограничение схем URI и сетевых направлений и блокировку доступа к частным, локальным, адресам с меткой link-local или к сервисам метаданных.

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

Вклад в плагины 3-й стороны

Вы также можете вносить вклад, создавая и делясь плагинами третьих сторон. См. packages/markitdown-sample-plugin для дополнительной информации.

Торговые марки

Этот проект может содержать товарные знаки или логотипы проектов, продуктов или услуг. Правильное использование товарных знаков Microsoft подлежит и должно соответствовать руководству по товарным знакам и брендам Microsoft.

Использование товарных знаков или логотипов Microsoft в изменённых версиях проекта не должно вводить в заблуждение и не должно подразумевать поддержку со стороны Microsoft.

Любое использование товарных знаков третьих сторон или логотипов подпадает под правила соответствующих третьих лиц.