Блог

MarkItDown 2026: как преобразовать PDF и Word в текст для ИИ

Markdown

MarkItDown от Microsoft извлекает текст из офисных файлов и PDF для ИИ. Разбираем установку, ограничения PDF и сканов, кириллицу, MCP и альтернативы.

Читать статью полностью

Главное

MarkItDown — бесплатная утилита Microsoft, которая преобразует документы Word, таблицы Excel, презентации и PDF в размеченный текст для языковых моделей. Офисные форматы она обрабатывает быстро и аккуратно. На сложных PDF результат может стать нечитаемым, а из скана инструмент возвращает пустой файл с кодом завершения 0. Далее — команда установки, замеры на документах с кириллицей и правило выбора другого средства.

Дополнительные инструкции доступны в документации Ailoot.

Что такое MarkItDown и для чего он нужен?

Главное

MarkItDown — созданная Microsoft утилита на Python. Она читает файл и возвращает его содержимое с разметкой: заголовки остаются заголовками, а таблицы — таблицами. Проект опубликован на GitHub под лицензией MIT, устанавливается одной командой и работает на вашем компьютере. Его основная задача — подготовить документ так, чтобы модель получила и текст, и его структуру.

Бывает, что вы отправляете модели договор, отчёт или бухгалтерскую выгрузку, а ответ почти не связан с документом. Часто дело не в самой модели, а в формате файла. Word хранит содержимое вместе с разметкой, Excel — таблицы и связи между ячейками, а PDF — символы и их координаты на странице. Модели нужен текст, поэтому сначала его требуется извлечь.

Этим и занимается MarkItDown. Репозиторий проекта находится по адресу github.com/microsoft/markitdown, лицензия — MIT, поэтому его можно использовать и в рабочих целях. По состоянию на 18 августа 2026 года у проекта 174 412 звёзд и 12 756 ответвлений. Последний выпуск 0.1.7 вышел 29 июля. Проект продолжает поддерживаться, хотя развитие замедлилось: открытых предложений изменений 481, а за всё время принято 183.

Microsoft описывает назначение инструмента так:

MarkItDown — лёгкая утилита на Python, преобразующая различные файлы в Markdown для языковых моделей и связанных с ними процессов текстового анализа.

— Microsoft, описание проекта (перевод): https://github.com/microsoft/markitdown

Следующая оговорка в описании объясняет многие претензии к инструменту:

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

— Microsoft, описание проекта (перевод): https://github.com/microsoft/markitdown

MarkItDown выдаёт материал для модели, а не готовый красиво оформленный документ. Microsoft прямо предупреждает об этом в начале описания.

Разработчики объясняют выбор Markdown тем, что ведущие модели часто используют эту разметку в ответах: они видели её в большом количестве обучающих данных. Кроме того, Markdown экономит место — заголовок можно обозначить тремя символами решётки вместо множества служебных строк.

Чем MarkItDown отличается от обычного конвертера?

Главное

Конвертеры вроде pandoc переводят один формат разметки в другой, стараясь сохранить оформление для человека. Сам pandoc не принимает PDF на вход. MarkItDown выполняет другую задачу: извлекает содержимое офисных файлов и размещает его в форме, которую модель может быстро обработать. Сохранение исходной красоты оформления для него не является целью.

Разницу легко заметить на практике. Попробуйте обработать через pandoc папку с двадцатью PDF: инструмент не сможет их прочитать. pandoc умеет создавать PDF, но не принимать его для конвертации. Между тем запрос «у меня есть папка документов, подготовь их для модели» — один из самых обычных сценариев.

Microsoft сравнивает MarkItDown с библиотекой textract, которая извлекает текст из самых разных источников. Отличие MarkItDown в том, что он старается сохранить структуру: заголовки, списки, таблицы и ссылки.

ПризнакpandocMarkItDown
Читает PDFнетда, с оговорками
Читает Word, Excel и презентациичастичнода
Для кого предназначен результатдля человекадля модели
Основная задачасохранить оформлениесохранить структуру и сократить число знаков
Способ установкиотдельная программаодна команда Python

Выбор зависит от цели. Для подготовки статьи к публикации используйте pandoc. Если нужно дать нейросети разобраться в двадцати договорах — подойдёт MarkItDown.

Как установить MarkItDown и избежать установки старой версии?

Главное

Выпуск 0.1.8 устанавливается на Python 3.14 и 3.12 командой из описания проекта; это проверено в восьми чистых окружениях. Однако незаметный откат на версию 0.0.2 всё ещё возможен: на Python 3.15, на Intel Mac с Python 3.14, а также на Mac со старой macOS при Python 3.13 и 3.14. Установщик при этом сообщает об успехе. Надёжный вариант — Python 3.12, установка только нужных дополнений и немедленная проверка номера версии.

Сначала выполните установку, затем проверьте её результат.

  1. Узнайте версию Python

    Самый надёжный выбор — Python 3.12: во всех проверенных окружениях с ним устанавливается свежий MarkItDown. Команда python3 --version покажет текущую версию. На Intel Mac с Python 3.13 или 3.14 возможен незаметный откат, как и на Python 3.15, который пока не поддерживается. Подробности приведены ниже.

  2. Установите только необходимые форматы

    Запустите pip install 'markitdown[pdf,docx,xlsx,pptx]'. Кавычки нужны, чтобы командная оболочка не обработала квадратные скобки отдельно. На Intel Mac добавьте после install параметр --prefer-binary.

  3. Сразу проверьте установленную версию

    Выполните markitdown --version. Ожидаемый ответ — markitdown 0.1.8 или более поздняя версия. Если номер меньше, установщик выбрал более старый выпуск. Причины разобраны в этом разделе.

pip install 'markitdown[pdf,docx,xlsx,pptx]'
markitdown --version

В основной инструкции проекта предлагается команда pip install 'markitdown[all]', устанавливающая все дополнения. 28 сентября 2026 года, через неделю после выхода 0.1.8, четыре способа установки проверили в чистых окружениях на Mac с Apple Silicon, используя Python 3.14.6 и 3.12.12:

КомандаРезультат на Python 3.14Результат на Python 3.12
pip install markitdown0.1.80.1.8
pip install 'markitdown[pdf,docx,xlsx,pptx]'0.1.80.1.8
pip install 'markitdown[all]'0.1.80.1.8
pip install 'markitdown[all]==0.1.8'0.1.80.1.8

Все восемь установок завершились сообщением «Successfully installed», а команда markitdown --version каждый раз показывала 0.1.8. В августе, когда актуальной была версия 0.1.7, третий вариант на Python 3.14 устанавливал 0.0.2 — выпуск от 8 марта 2025 года, второй по счёту в истории проекта. На тот момент было одиннадцать стабильных версий, от 0.0.1 до 0.1.8, и двадцать шесть вместе с предварительными.

Причина крылась в зависимостях. В версии 0.1.7 набор [all] устанавливал библиотеку для субтитров YouTube из линейки, где все выпуски заявляли несовместимость с Python 3.14. Установщик исключал эти версии и, поскольку версия MarkItDown не была зафиксирована, перебирал более старые выпуски. В итоге он находил и ставил 0.0.2 — версию полуторагодовой давности. В MarkItDown 0.1.8 зависимость обновили до линейки, совместимой с Python 3.14, и этот сбой исчез.

Сам механизм отката никуда не делся. Если установщик не находит обязательную зависимость для вашей системы, он может без явной ошибки вернуться к 0.0.2. В актуальных выпусках одна из таких зависимостей — onnxruntime, движок определителя типов файлов. Для Mac его собирают для Python 3.12 начиная с macOS 11, для Python 3.13 — начиная с macOS 13, а для Python 3.14 — только на Apple Silicon с macOS 14 или новее. На системах, не подходящих под эти требования, даже команда pip install markitdown может установить 0.0.2. Проверка на Intel Mac с Python 3.14 через Rosetta дала именно такой результат: «Successfully installed», без предупреждений, но внутри оказалась версия 0.0.2.

На Intel Mac есть и ещё одна особенность. С июня 2026 года для используемой при чтении PDF библиотеки cryptography не выпускают готовую сборку для этого процессора, поэтому установщик пытается собрать её из исходников. Добавьте в команду --prefer-binary, чтобы выбрать предыдущую версию с готовой сборкой. При проверке на Intel с Python 3.13 так установилась версия 0.1.8, и PDF открылся. Этот параметр устанавливает cryptography 48.0.1, у которой известны три уязвимости: две связаны с расшифровкой PKCS#7, одна — с проверкой цепочек сертификатов. MarkItDown использует библиотеку только для расшифровки защищённых PDF и не обращается к этим уязвимым участкам при чтении документов.

На Python 3.15 откат возможен сразу по двум причинам. Версия 0.1.8 поддерживает Python с 3.10 по 3.14, а сборки onnxruntime для 3.15 пока нет. Проверка установки на Python 3.15 подтвердила, что и базовая команда, и команда с форматами приводят к версии 0.0.2.

При откате предупреждение выглядит так — отдельная строка для каждого дополнения:

WARNING: markitdown 0.0.2 does not provide the extra 'all'

Эта строка теряется среди множества сообщений о загрузке, и она не объясняет, что версия подменена. Если дополнения не указаны, предупреждения вообще не будет. Итоговая сводка всё равно сообщает: «Successfully installed».

Устанавливать пакет без дополнений — тоже плохой вариант. Базовая версия установится, но PDF читать не сможет:

PdfConverter recognized the input as a potential .pdf file, but the
dependencies needed to read .pdf files have not been installed. To resolve
this error, include the optional dependency [pdf] or [all] when installing
MarkItDown. For example:

* pip install 'markitdown[pdf]'
* pip install 'markitdown[all]'

Сам инструмент предлагает набор [all], и для версии 0.1.8 этот совет снова работает на Python 3.14 и 3.12. Тем не менее лучше перечислять нужные форматы явно: [all] добавляет ещё примерно пятнадцать пакетов и около 55 мегабайт. Среди них — предварительный выпуск библиотеки Azure и зависимость YouTube, уже вызывавшая проблему с установкой.

Установщик самостоятельно справляется с предварительным выпуском Azure. Обычно pip не выбирает предварительные версии, но здесь они указаны в требовании напрямую. На Python 3.12 проверили четыре версии pip — от 23.2 до 26.2, — и все выбрали MarkItDown 0.1.8.

Внимание

Сразу после установки выполните markitdown --version. Это займёт несколько секунд и покажет, действительно ли установилась нужная версия. Сообщение об успешной установке само по себе этого не подтверждает.

В августе установка в другом чистом окружении дала такой же результат: версия 0.0.2 при сообщении «Successfully».

Перед установкой полезно учесть ещё несколько практических деталей.

Пакет довольно крупный: базовая установка занимает 143 мегабайта, а с четырьмя форматами — 303. Самая тяжёлая часть — определитель типов файлов размером 81 мегабайт, который входит даже в базовый набор. На обычном ноутбуке это несущественно, а в облачной функции с ограничением размера может стать проблемой.

Не стоит полагаться на зеркала как на запасной способ установки. У проверенного зеркала индекс и файлы MarkItDown присутствовали, но одной обязательной зависимости не нашлось; установка не прошла ни на Python 3.14, ни на 3.12.

Сама установка — простая часть задачи. Чаще проблема в том, что модели передают неподходящий материал или неверно его подготавливают. Выбор контекста для модели называют контекстной инженерией, и подготовка документов тоже к ней относится.

Как преобразовать первый документ в текст?

Главное

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

Минимальная команда выглядит так:

markitdown dogovor.docx

Результат появится в терминале. Чтобы сохранить его, используйте один из двух вариантов:

markitdown dogovor.docx -o dogovor.md
markitdown dogovor.docx > dogovor.md

На Mac и Linux разница невелика, а в Windows перенаправление через > иногда приводит к сбою на кириллице.

Можно передать файл через поток. В таком случае укажите расширение:

cat dogovor.docx | markitdown -x docx

Основные параметры из справки версии 0.1.8:

ФлагНазначение
-o, --outputсохранить результат в файл вместо вывода в терминал
-x, --extensionзадать расширение, если файл передан потоком
-m, --mime-typeуказать тип содержимого
-c, --charsetуказать кодировку
-d, --use-docintelзапустить распознавание через платный облачный сервис Microsoft
-v, --versionвывести номер версии

В справке перечислены ещё три полезных параметра, каждый из них проверен: --list-plugins выводит установленные дополнения, -p включает их для текущего запуска, а --keep-data-uris сохраняет в результате изображения, встроенные в документ. По умолчанию такие изображения обрезаются. Остальные параметры относятся к облачным службам Microsoft.

Пример обёртки на Python — три строки:

from markitdown import MarkItDown

md = MarkItDown()
print(md.convert("ostatki.xlsx").text_content)

В тот же вызов можно передать сетевой адрес. Для простой веб-страницы результатом стали 167 знаков с заголовком и ссылкой, без меню и нижнего колонтитула:

r = md.convert("https://example.com")

Какие форматы поддерживает MarkItDown и как именно?

Главное

В описании проекта перечислены офисные документы, PDF, изображения, аудио, архивы, ссылки YouTube и электронные книги. Однако некоторые возможности ограничены. Бесплатного распознавания текста на изображениях нет. Для речи используется англоязычный механизм. В ZIP-архиве файлы, которые не удалось прочитать, могут пропасть без предупреждения.

Сопоставим заявленные возможности с их фактическим поведением.

ФорматЗаявленная возможностьПрактический результат
Word, Excel, презентациидаобрабатываются аккуратно; сильная сторона инструмента
CSV, JSON, XML, HTMLдаработают, но при чтении CSV есть проблема с разделителем
PDFдарезультат зависит от макета: одна колонка обычно читается, две могут смешаться
Изображения«метаданные и распознавание»распознавания нет; доступны только метаданные или платная модель зрения
Аудио«распознавание речи»запрос отправляется в англоязычный сервис Google
ZIP-архивы«обход содержимого»неподдерживаемые файлы могут пропасть без сообщения
Ссылки YouTubeдаподдерживается полная ссылка формата '<OFFICIAL_URL>'?...
Электронные книги EPUBдаобрабатываются

Разберём три неоднозначных случая.

Изображения. В описании упомянут OCR, поэтому можно ожидать, что программа прочитает текст на фотографии. Она этого не делает. Метаданные извлекаются отдельной программой exiftool. Если подключить модель зрения с собственным ключом, изображение можно отправить ей для описания. В материалах проекта Microsoft указано:

MarkItDown пока не умеет извлекать текст, встроенный в изображения внутри PDF, поскольку в нём отсутствует распознавание изображений.

— Microsoft, сведения об ограничениях распознавания (перевод): https://github.com/microsoft/markitdown

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

Архивы. Программа распаковывает ZIP, обрабатывает файлы внутри и объединяет результат. Если отдельный файл прочитать не удалось, ошибка перехватывается и подавляется. Такой файл просто не попадёт в результат, и вы не получите уведомления.

Как MarkItDown работает с кириллицей?

Главное

Свежую версию проверили на трёх русскоязычных документах: договоре Word, таблице остатков Excel и презентации. Кириллица и номера сохранились во всех случаях. Сбои обнаружились в трёх ситуациях: CSV с разделителем-точкой с запятой, формат валюты в ячейках Excel и вывод в консоль Windows. Для всех есть обходные решения.

Файлы для проверки созданы специально; все содержащиеся в них данные вымышлены.

Таблица остатков из Excel преобразовалась без ошибок, а название листа стало заголовком:

## Остатки
| Позиция | На складе | Резерв | Доступно |
| --- | --- | --- | --- |
| Кофе зерновой, кг | 420 | 38 | 382 |
| Чай листовой, кг | 180 | 52 | 128 |

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

Однако есть три конкретных ограничения.

CSV с точкой с запятой. Для сравнения обработали два одинаковых файла с выгрузкой счетов. В варианте с запятыми получилась таблица из четырёх столбцов. При использовании точки с запятой вся строка оказалась в одной ячейке.

Кодировка при этом определилась правильно, ошибки не возникло, а параметр -c ситуацию не исправляет. Модель получит таблицу без разделённых значений. Повторно выгрузите файл с явным разделителем-запятой и правильной кодировкой, сохранив оригинал. Не заменяйте точки с запятой глобально: разделители внутри кавычек и десятичные запятые могут быть частью значений. Если повторный экспорт невозможен, прочитайте исходник CSV-парсером с настоящим разделителем и запишите новый CSV с сохранением кавычек и значений. До анализа сравните число строк и столбцов и контрольные итоги с исходной выгрузкой.

Формат валюты в Excel. Символ валюты может храниться в настройках отображения ячейки отдельно от самого значения. В результате модель увидит только числа и не сможет определить их валюту. Для счёта или прайс-листа это существенное ограничение.

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

Если консоль не умеет выводить нужный символ, обработка может завершиться сбоем и не вернуть текста. На документах с кириллицей, французскими, немецкими и английскими символами результат зависит от содержимого; простой файл может обработаться успешно.

— Microsoft, сведения о работе консоли Windows (перевод): https://github.com/microsoft/markitdown

В сообщениях об ошибке встречается кодировка cp1251, характерная для консоли Windows. Сам документ может обработаться нормально, а сбой произойдёт при печати результата. Используйте один из двух вариантов:

markitdown dogovor.docx -o dogovor.md
$env:PYTHONUTF8 = "1"; markitdown dogovor.docx > dogovor.md

Первый вариант направляет результат сразу в файл и не использует консоль для его вывода. Второй включает для Python кодировку UTF-8. Исправления этой проблемы предлагались неоднократно, но часть изменений не была принята, а остальные остаются открытыми. Пока проблему можно обходить этими способами.

В PDF встречается и другой признак ошибки: строки вида (cid:1090) вместо букв. Обычно это означает, что символы в файле связаны с нестандартной таблицей шрифтов и не смогли быть расшифрованы. Для такого документа MarkItDown не подходит — используйте другое средство.

Почему PDF превращается в нечитаемый текст?

Главное

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

Для проверки обработали научную статью размером 2,16 мегабайта с двумя колонками. Программа вернула код 0 и за 0,9 секунды выдала 88 тысяч знаков, большая часть которых оказалась непригодной для чтения. Объём результата создаёт впечатление успеха, пока не открыть файл:

|     | Hybrid |          | OCR-LLM     |     | Framework  |
| --- | ------ | -------- | ----------- | --- | ---------- |
...
Informationextractionfromcopy-heavydoc-
5202 tcO 11  ]LC.sc[  1v83101.0152:viXra

Здесь видны сразу три проблемы. Две колонки превратились в таблицы, которых в статье не было, слова слиплись, а строка с боковой вертикальной плашки попала в текст в обратном порядке.

В результате проверки обнаружилась дополнительная особенность: сама статья была посвящена измерению и сравнению инструментов извлечения текста. Фрагмент с результатами MarkItDown превратил в такую последовательность:

cues. This name-matching error could be miti-  OCRpreprocessingoverhead(0.056s),whileDo-
gatedthroughpromptengineeringtoprovidemore  clingandMinerUadoptmorecomputationallyin-
explicit matching instructions or fine-tuning the  tensive strategies with OCR latencies of approxi-

Строки из левой и правой колонок соединились. Модель, получившая такой текст, может прочитать начало предложения из одного абзаца, а продолжение — из другого.

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

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

Ранее опубликованные сторонние измерения также показывали низкое качество извлечения заголовков из PDF. Учитывайте, что результаты зависят от набора документов и способа оценки. В исходном коде проекта действительно нет отдельного механизма для определения заголовков в PDF.

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

В сети встречается утверждение, будто MarkItDown обеспечивает точность 82%, однако проверить методику и первичный источник не удалось. Поэтому это число нельзя считать подтверждённым измерением.

Для офисных форматов результат обычно лучше. MarkItDown предназначен в том числе для чтения Word и Excel, где структура хранится в самом файле. При обработке таких документов он может быстро сохранить полезные элементы содержимого, хотя итог зависит от конкретного файла.

Что произойдёт со сканом договора?

Главное

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

Это ограничение особенно опасно тем, что внешне обработка выглядит успешной.

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

Входные данныеКод завершенияЗнаков в результатеСообщение об ошибке
PDF из изображения, запуск 100нет
PDF из изображения, запуск 200нет
Изображение PNG напрямую01 (перевод строки)нет

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

Внимание

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

Есть два платных обходных варианта. Первый — флаг -d, отправляющий документ в облачный сервис распознавания Microsoft; справка требует указать рабочий адрес этого сервиса. Второй — отдельный пакет, отправляющий страницы в модель зрения с вашим ключом. В этом случае оплата зависит от тарифа поставщика модели. Для второго способа с апреля 2026 года остаётся открытым вопрос: при обработке многостраничного скана может извлекаться только первая страница.

Можно запустить модель распознавания на собственном компьютере, но настройка такого решения — отдельная задача.

Для одного документа проще открыть файл и скопировать текст вручную. Если сканов много, нужен инструмент со встроенным распознаванием текста.

Безопасно ли загружать файл на сайт-конвертер?

Главное

Технически это возможно: сайтов с похожим названием много, однако ни один из них не принадлежит Microsoft. Заявление, что файл обрабатывается в браузере, можно проверить по сетевым запросам, и оно подтверждается не всегда. Перед загрузкой договора или файла с персональными данными проверьте, куда передаётся содержимое.

Запрос «markitdown онлайн» часто появляется в поисковых подсказках, и соответствующие сайты действительно существуют. Однако у оригинального инструмента Microsoft нет веб-сайта для конвертации: он распространяется как программа для установки на компьютер. Онлайн-сервисы с похожим названием созданы сторонними разработчиками.

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

Внимание

Договоры, счета и списки сотрудников могут содержать персональные данные. Загружая их на внешний сайт, вы передаёте эти сведения его владельцу. Локальная утилита позволяет выполнять обработку на компьютере без отправки документа.

Локальная обработка полезна, когда документы нельзя выносить за пределы рабочего компьютера. Например, на устройстве могут запрещать произвольные программы, но разрешать библиотеки Python; в такой ситуации MarkItDown может оказаться доступным способом извлечения текста.

Сколько ресурсов экономит MarkItDown?

Главное

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

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

ФайлРазмер разметкиРазмер готового текстаСокращение объёма, раз
Договор в Word3 701 байт711 байт5,2
Таблица в Excel1 561 байт262 байта6,0
Презентация2 203 байта296 байт7,4

Эти файлы небольшие, а на более крупных документах соотношение может быть иным. Универсального показателя экономии нет. Если в обзоре приводят одно круглое число, уточните, каким способом его получили.

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

Подробнее о расходе контекста читайте в материалах о токенах в Claude и лимитах тарифов.

Как подключить MarkItDown к Claude через MCP?

Главное

Для MarkItDown выпущен отдельный пакет, который запускает MCP-сервер с одной командой: передать путь к файлу и получить текст. В сентябре 2026 года пакет обновили до 0.0.1a7, однако он всё ещё имеет статус предварительного выпуска и по умолчанию отправляет статистику Microsoft. Команда ниже запускает сервер через uv, фиксирует версию, выбирает Python 3.12 и отключает статистику. Аутентификации нет; согласно документации, сервер может читать файлы, доступные его пользователю.

MCP позволяет нейросети пользоваться внешними инструментами. Подробнее о механизме и других серверах рассказывает материал об MCP-серверах для Claude Code.

Сервер MarkItDown предоставляет один инструмент: преобразование документа в текст. На вход можно передать путь к локальному файлу, веб-адрес или содержимое, включённое непосредственно в запрос.

Подключение к Claude Code выполняется одной командой с зафиксированной версией сервера. Для этого понадобится пакетный менеджер uv:

claude mcp add --scope user --env 'ORT_DISABLE_TELEMETRY=1' --env 'UV_PYTHON=3.12' --transport stdio markitdown -- uvx markitdown-mcp@0.0.1a7
claude mcp list

В выводе второй команды для markitdown должно быть указано «Connected». При первом запуске загружается около семидесяти пакетов, и это может занять до минуты. Затем сервер обычно запускается за одну-две секунды.

Учитывайте несколько условий.

Выпуск 0.0.1a7 опубликован 14 сентября 2026 года. До этого пакет более года оставался на версии 0.0.1a4 от мая 2025-го. Текущий номер по-прежнему обозначает предварительный выпуск.

Установка на свежий Python зависит от системы. Для Python 3.14 на Mac onnxruntime выпущен только для Apple Silicon с macOS 14 или новее. Поэтому на Intel Mac и на macOS 13 или более ранней версии такая установка не собирается. На Mac с Apple Silicon сервер проверили на Python 3.14, 3.13 и 3.12; во всех трёх случаях он установился. В приведённой команде задан UV_PYTHON=3.12: готовые сборки для этой версии доступны на Windows, Linux и Mac с Apple Silicon. Если Python 3.12 отсутствует, uv загрузит его самостоятельно. Для Intel Mac остаётся оговорка: cryptography придётся собирать из исходников, поскольку с июня 2026 года готовых сборок для Intel нет. Установка может занять больше времени или завершиться неудачно.

Установленная версия MarkItDown зависит от версии uv. Начиная с MarkItDown 0.1.6 набор [all] требует предварительную версию библиотеки Azure. uv версии 0.12 и новее устанавливает её и свежий MarkItDown 0.1.8, а более старый uv возвращается к версии 0.1.5. Проверить версию uv можно командой uv --version.

С сервера могут передаваться два типа данных. Первый — статистика: на Mac и Linux движок onnxruntime внутри сервера по умолчанию отправляет её Microsoft. Параметр ORT_DISABLE_TELEMETRY=1 в команде отключает эту отправку. Во время проверки без него сервер обращался к адресам статистики Microsoft. С параметром статистики при обработке локальных файлов сетевых соединений не наблюдалось.

Второй тип — аудиофайлы. WAV, MP3, M4A и MP4 отправляются в сервис распознавания речи Google обычным HTTP, без шифрования. Не используйте этот путь для записей разговоров с клиентами.

Большие документы могут не поместиться в ответ. В описанной проблеме ответ сервера объёмом 51 тысяча токенов превысил лимит в 25 тысяч, а инструмента для разбиения документа на части нет.

Отдельно учитывайте безопасность. В документации пакета Microsoft указывает:

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

— Microsoft, описание пакета markitdown-mcp (перевод): https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp

Иными словами, агент с доступом к этому инструменту может прочитать все файлы, доступные вам. Для работы на личном компьютере это может быть приемлемо, но открывать сервер во внешнюю сеть или подключать его к непроверенному агенту нельзя.

Внимание

В документации проекта нет настроек именно для Claude Code: там описаны Claude Desktop и запуск в контейнере. Если где-либо приводят готовую конфигурацию для Claude Code и называют её официальной, проверьте это утверждение по репозиторию — такого примера там нет.

Для регулярных задач проще запускать программу командой и сохранять преобразованный текст в проекте. Тогда файл хранится рядом с остальными материалами и доступен модели при последующих запросах.

Когда лучше выбрать другой инструмент?

Главное

Если структура уже записана в файле, выбирайте MarkItDown: он работает быстро и бесплатно. Если её нужно восстанавливать по изображению страницы, используйте средство с моделями анализа макета. Docling помогает с таблицами и сложным оформлением, MinerU — с формулами и несколькими колонками, а облачный сервис может сэкономить время, если настройкой заниматься некогда.

Сравнение по типичным задачам:

ИнструментОсновное преимуществоОграничение
MarkItDownофисные документы, скорость, бесплатное использованиеплохо справляется со сложными PDF и сканами
Doclingтаблицы и оформление благодаря специализированным моделямобработка документа может занимать десятки секунд
MinerUнесколько колонок, формулы и плотные таблицысложнее установить
Markerвысокая точность, обработка формул и изображенийтребуется видеокарта; лицензия ограничивает использование в зависимости от выручки
unstructuredвыдаёт части документа с описанием структурырезультат сложнее использовать
Облачные средства извлеченияне требуют настройкиплатные и передают документ внешнему сервису

У Marker есть лицензионное условие, которое часто упускают из виду. С июля 2026 года исходный код распространяется под свободной лицензией, но для весов моделей действует отдельная лицензия. Бесплатно пользоваться ими можно, если выручка компании за прошлый год и объём привлечённых средств не превышали по пять миллионов долларов. Также запрещено использование компаниями, создающими конкурирующий продукт. Для большинства пользователей это может быть несущественно, но растущему бизнесу следует изучить лицензию перед внедрением.

Скорость обработки можно оценить на примере одного регламента объёмом 14 страниц без видеокарты: MarkItDown завершил работу за 0,6 секунды, Docling — за 41 секунду, Marker — за 2 минуты 14 секунд. На скане MarkItDown вернул пустой результат, как и в описанной выше проверке.

Для повседневной работы подойдёт такая последовательность:

  1. Обработайте документы с помощью MarkItDown — это бесплатно и быстро.
  2. Проверьте размер полученного текста.
  3. Если текст читаемый, на этом можно остановиться.
  4. Если получилась бессмыслица или пустой результат, запустите для этого файла более сложный инструмент.

Так дополнительные время и сложность потребуются только для документов, с которыми MarkItDown не справился.

Как встроить MarkItDown в рабочий процесс?

Главное

Anthropic указывает, что MarkItDown помогает быстро прочитать документ, но по его результату нельзя планировать изменения. Ниже описаны три подходящих сценария: пакетная обработка однотипных документов, подготовка постоянных материалов проекта и разбор выгрузок из учётной системы.

Anthropic использует MarkItDown в готовых навыках для работы с офисными файлами. В инструкции по таблицам отдельно отмечено ограничение:

Быстро просмотреть лист можно командой markitdown file.xlsx. Координат ячеек в результате нет, поэтому планировать изменения по нему не следует.

— Anthropic, инструкция по работе с таблицами (перевод): https://github.com/anthropics/skills/blob/main/skills/xlsx/SKILL.md

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

Пакет однотипных документов — актов, счетов, анкет или откликов. Сложите файлы в каталог и выполните одну команду:

for f in dokumenty/*.docx; do markitdown "$f" -o "text/$(basename "$f" .docx).md"; done

Затем передайте модели каталог с результатами и попросите свести нужные данные в таблицу. Это подходит для цифровых документов; сканы не распознаются, и их можно заметить по нулевому размеру результата.

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

Выгрузки из учётных систем. Excel из бухгалтерской программы или интернет-банка можно преобразовать для расчётов. Проверьте экспорт или чтение CSV с настоящими разделителем, кавычками и кодировкой, сравните строки, столбцы и контрольные итоги. Не нормализуйте разделители поиском и заменой. Явно укажите валюту: символ, заданный только форматированием ячейки Excel, не попадёт в извлечённый текст.

Для тяжёлых PDF обработка в терминале может потребовать отдельного внимания к расходу контекста. Подробнее об этом — в материале о работе с PDF в Claude Code. Если вы только настраиваете рабочее окружение, начните с установки Claude Code.

Чтобы попробовать инструмент, выполните pip install 'markitdown[pdf,docx,xlsx,pptx]', обработайте любой договор в Word и сравните размер результата с исходным документом. Несколько минут работы покажут, насколько хорошо утилита подходит вашим файлам.

Частые вопросы

MarkItDown бесплатный?

Да. Инструмент распространяется по лицензии MIT, которая не запрещает коммерческое использование. Плата потребуется только за необязательные функции: облачное распознавание Microsoft с параметром -d и передачу изображения модели зрения по вашему ключу. Остальные операции выполняются локально и бесплатно.

Передаются ли данные на сервер?

При обычной обработке офисных документов и PDF — нет: преобразование выполняется на компьютере. Исключения — распознавание аудио через Google, отправка файла в облако Microsoft с параметром -d и обработка изображения моделью по вашему ключу. Эти функции не запускаются автоматически.

Почему после установки команда markitdown не находится?

Обычно программа установлена в окружении, путь к которому не добавлен в поисковые пути. Попробуйте запустить её по полному пути внутри окружения. Другая частая причина — пакет установлен для одной версии Python, а запускается другая. Также учтите: на Python старше версии, которую поддерживает установленный пакет, при установке может появиться пустой пакет без ошибки. Для MarkItDown требуется Python 3.10 или новее.

Что делать, если вместо букв отображается (cid:1090)?

В PDF не удалось расшифровать таблицу шрифтов. Настройкой MarkItDown это не исправить: попробуйте Docling или MinerU. Для одного документа быстрее скопировать текст из просмотрщика PDF вручную.

Можно ли обработать сразу целую папку?

Отдельного режима обработки каталога у программы нет, но его можно запустить циклом в терминале: for f in papka/*.docx; do markitdown "$f" -o "$f.md"; done. Другой вариант — упаковать файлы в ZIP и передать архив. Программа обработает его содержимое, однако нераспознанные файлы могут исчезнуть без предупреждения.

Чем результат отличается от ручного копирования текста?

Сохраняется структура. При копировании вы получаете сплошной текст, в котором заголовок неотличим от обычного абзаца, а таблица может распасться. MarkItDown сохраняет заголовки, списки и таблицы, поэтому модели проще понять содержимое. Для одного небольшого документа разница может быть небольшой, а для двадцати документов — существенной.

Можно ли открыть файл, защищённый паролем?

Нет. MarkItDown не откроет защищённый документ, и передать ему пароль нельзя. Сначала снимите защиту в программе, которой она была установлена.

Познакомьтесь с Ailoot.

Подробнее

Вопросы и ответы

Можно ли исправить CSV, заменив все точки с запятой запятыми?

Нет. Такие символы могут быть внутри текста в кавычках и десятичных чисел. Повторите экспорт с нужным разделителем либо используйте CSV-парсер и запись с явными разделителем, кодировкой и кавычками. Сравните столбцы, строки и контрольные итоги с оригиналом.

Означает ли нулевой код завершения полезное преобразование PDF?

Нет. Пример со сканом дал пустой вывод без ошибки, а сложный PDF — нечитаемый текст. Откройте результат, проверьте длину и структуру. При пустом или испорченном тексте используйте инструмент распознавания или анализа макета.

Все статьи