Как превратить PDF и Word в текст для ИИ: MarkItDown от Microsoft

В Telegram-канале - что нового в вайб-кодинге: инструменты, находки, ошибки. Подпишись.

Что такое MarkItDown и зачем он нужен?

Ты скидываешь нейросети договор, отчёт или выгрузку из бухгалтерии и получаешь ответ, который к документу отношения не имеет. Причина обычно не в модели. Внутри файла лежит формат: Word - архив с разметкой, Excel - таблица со ссылками между ячейками, PDF - набор символов с координатами на странице. Модель работает с текстом, и кто-то должен этот текст оттуда достать.

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

Разработчики описывают задачу так:

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

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

Почему именно markdown, в описании отвечают прямо: ведущие модели изначально «говорят» на этой разметке и вставляют её в ответы без всякой просьбы, потому что видели её в огромных объёмах, когда их учили. Плюс сама разметка экономна - три решётки на заголовок вместо десятка служебных строк.

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

Разница видна на одном примере. Возьми папку с двадцатью PDF-ами и попробуй прогнать их через pandoc. Не выйдет: pandoc умеет отдавать PDF на выходе, но читать его на входе не умеет. А именно этот случай - «у меня лежит стопка документов, дай их модели» - встречается чаще всего.

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

Практический вывод простой. Нужно перегнать статью в вёрстку для публикации - это pandoc. Нужно, чтобы нейросеть разобралась в двадцати договорах, - это MarkItDown.

Как установить MarkItDown и не получить первую сборку?

Сначала правильная команда, дальше объясню, почему она такая.

1. Проверить версию Python

   Нужна 3.10 или выше. Команда python3 --version покажет, что стоит у тебя.

2. Поставить с перечислением форматов

   Выполнить pip install 'markitdown[pdf,docx,xlsx,pptx]'. Кавычки обязательны, иначе оболочка съест квадратные скобки.

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

   Выполнить markitdown --version. Ответ должен быть markitdown 0.1.7. Другой номер означает, что установка откатилась - почему так выходит, разобрано в этом же разделе.

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

В описании проекта основной командой стоит pip install 'markitdown[all]' - поставить всё сразу. Я прогнал четыре варианта в чистых окружениях на Python 3.14.6:

Версия 0.0.2 выложена 8 марта 2025 года и стоит второй от начала истории проекта. Стабильных выпусков там сейчас десять, от 0.0.1 до 0.1.7, а с предвыпусками двадцать три.

Причина в цепочке зависимостей. Набор [all] тянет за собой библиотеку для субтитров YouTube строго определённой линейки. Все выпуски этой линейки объявляют, что не работают на Python 3.14, и установщик их отбрасывает. Подходящих не остаётся, и раз версия не закреплена, установщик отматывается назад по версиям самого MarkItDown, пока не найдёт ту, чей набор [all] собирается, находит 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] - и на свежем Python это тихо откатывает установку на полтора года назад.

На Python 3.12 ловушка та же по сути, но причина другая: там [all] версии 0.1.7 требует предвыпускную сборку одной из библиотек Azure, а предвыпуски установщик по умолчанию не берёт. Отматывает он тогда не до 0.0.2, а до 0.1.5.

Я, честно говоря, сначала не поверил и повторил установку в другом чистом окружении. Результат тот же: 0.0.2 и слово «Successfully».

Пара бытовых моментов, о которых стоит знать заранее.

Весит это прилично. Я замерил свои окружения после того, как установка неожиданно долго качала пакеты: голая занимает 143 мегабайта, с четырьмя форматами - 303. Самый тяжёлый кусок в 81 мегабайт - определитель типов файлов, который тянется даже в базовой сборке. Для ноутбука неважно, для облачной функции с лимитом на размер уже критично.

PyPI из России открывается не всегда. Официальной блокировки нет, но 1 июня 2026 года хранилище пакетов перестало отвечать с российских адресов: соединение рвалось на установке защищённого канала. Про зеркала как запасной путь я бы не обольщался - у того, что я проверил, индекс отдаётся и файлы MarkItDown на месте, но одной обязательной зависимости в нём не оказалось, и установка не собралась ни на Python 3.14, ни на 3.12.

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

Практикум по вайб-кодингу

+Твой второй мозг

3 вечера - инструменты, метод, первый проект

Старт 25–27 августа  ·  2 000 ₽

Записаться →

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

Самый короткий вариант:

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.7 на моей установке:

Справка перечисляет не всё. Я проверил вслепую флаги, которых в ней нет, и они работают: --list-plugins показывает установленные дополнения, -p включает их для конкретного запуска, а --keep-data-uris оставляет в результате картинки, вшитые в документ (по умолчанию они обрезаются).

Обвязка на Python занимает три строки:

from markitdown import MarkItDown

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

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

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

Терминал нужен не всем. Есть сторонняя оболочка с окошком - markitdown-gui с готовыми сборками под Mac и Windows, и плагин для Obsidian, который превращает файл, перетащенный в заметку, в текст прямо внутри неё. Оба сделаны не Microsoft, так что для рабочих документов я бы сначала посмотрел, что там внутри.

Какие форматы MarkItDown понимает и что из этого правда?

Сводная таблица - что заявлено и что за этим стоит.

Три пункта разберу подробнее.

Картинки. В описании стоит слово OCR, и человек ждёт, что программа прочитает текст с фотографии. Она этого не делает. Внутри лежит чтение метаданных через отдельную программу exiftool и, если подключишь модель зрения по своему ключу, отправка картинки ей на описание. В обсуждении №1170 это сформулировали прямо:

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

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

Что происходит с русскими документами?

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

Договор в Word вышел вот так, дословно:

# Договор оказания услуг №14-А

Настоящий договор заключён 12 августа 2026 года между сторонами.

## 1. Предмет договора

Исполнитель обязуется оказать информационно-консультационные услуги.

Стоимость услуг составляет 148 000 рублей.

## 2. Сроки

Срок оказания услуг - 30 календарных дней с даты подписания.

| Этап | Срок | Сумма |
| --- | --- | --- |
| Аналитика | 10 дней | 48 000 ₽ |
| Внедрение | 20 дней | 100 000 ₽ |

Таблица остатков из Excel вышла так же чисто, причём имя листа стало заголовком:

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

Презентация превратилась в текст, где номера слайдов вынесены пометками, а заголовки слайдов стали заголовками. Кириллица цела и здесь. Утверждение «MarkItDown не понимает кириллицу» в общем виде неверно.

Теперь три места, где всё-таки ломается.

CSV с точкой с запятой. Excel в русской раскладке сохраняет CSV через точку с запятой. Я прогнал две одинаковые выгрузки счетов. С запятой получилась нормальная таблица на четыре колонки. С точкой с запятой - вот это:

| Контрагент;Номер;Сумма;Статус |
| --- |
| ООО Ромашка;114;48000;оплачен |
| ИП Петров;115;12500;ждёт |

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

Формат валюты в Excel. Ячейка, отформатированная как 2 000 ₽, приезжает в результат просто как 2000. Знак валюты хранится в настройках отображения ячейки и до самого значения не доходит. Об этом есть обсуждение №53, где сопровождающий проекта подтвердил причину. Для прейскуранта или счёта это существенно: модель увидит числа и не будет знать, рубли это или доллары.

Консоль Windows. В обсуждении №291, открытом в январе 2025 года и живом до сих пор, человек описывает падения на файлах с не-латинскими буквами:

В следах ошибки видна кодировка cp1251, то есть консоль Windows. Разбор документа при этом проходит нормально, спотыкается печать результата в окно терминала. Отсюда два рабочих приёма:

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

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

Четвёртый русский симптом встречается в PDF - последовательности вида (cid:1090) вместо букв. Это значит, что в файле нестандартная шрифтовая таблица и символы не расшифровались. Такой документ через MarkItDown гнать бесполезно, нужен другой инструмент.

Почему PDF выходит кашей?

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

|     | Hybrid |          | OCR-LLM     |     | Framework  |
| --- | ------ | -------- | ----------- | --- | ---------- |
...
ilardocumentsdaily(Gagieetal.,2017;Navarro,
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 нет ни строчки про определение заголовков: если страница не опознана как форма или таблица, весь документ уходит в простое извлечение текста.

Люди пишут об этом регулярно. Обсуждение №2226 от июля 2026 года так и называется - плохое качество конвертации научной статьи, и в нём перечислено ровно то, что увидел я. Обсуждение №1419 про таблицы открыто с сентября 2025 года и живо до сих пор.

Есть и цифры. Открытый стенд сравнения разборщиков гоняет их на корпусе из двухсот PDF; MarkItDown там прогоняли дважды с разницей в три месяца, на версиях 0.1.5 и 0.1.6, и числа совпали до третьего знака.

Ноль по заголовкам - не округление. Инструмент не находит в PDF ни одного заголовка, и это ровно то, что видно в его исходниках. По скорости он при этом обгоняет Docling в шесть с половиной раз, и вот это его настоящее преимущество.

Научное сравнение на 3 576 документах подтверждает то же самое на другом наборе: на статьях с arXiv средний балл MarkItDown 35,2 против 73,1 у MinerU, а по заголовкам снова около нуля. На простых текстовых файлах с GitHub, которые тоже входят в этот набор, он обгоняет Docling - 62,1 против 49,9. Спотыкается он именно на сложной вёрстке.

По сети гуляет цифра «MarkItDown даёт 82% точности» без всякой методики. Я пробовал дойти до первоисточника: цепочка ссылок упирается в страницу, которая не открывается. Считать её замером нельзя.

На офисных форматах картина обратная. Авторы той самой двухколоночной статьи прогнали 400 документов в четырёх форматах и намерили на Word предельную точность за 0,54 секунды, на Excel - предельную за 0,30 секунды. Excel из сравниваемых инструментов поддерживал вообще только MarkItDown, и офисные форматы остаются его законной территорией.

Что будет со сканом договора?

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

Я собрал PDF из картинки с текстом - то есть ровно то, что получается, когда договор сфотографировали или пропустили через сканер. Первый пустой файл я счёл случайностью и прогнал ещё раз:

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

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

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

Для разового документа проще открыть его и скопировать текст руками. Для потока сканов нужен инструмент с распознаванием на борту.

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

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

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

Именно так и вскрылась одна задокументированная история. В декабре 2024 года сервис-конвертер вышел на публику с обещанием, что файлы обрабатываются прямо в браузере. Читатель открыл панель разработчика и показал сетевой запрос, уходивший на сервер сервиса. Автор ответил честно: текст обещания сгенерировала нейросеть, он его не перечитал, и раздел он поправил. Домен сегодня продаётся.

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

Сколько MarkItDown экономит на самом деле?

Офисный файл устроен как архив с разметкой внутри. Я распаковал свои три тестовых файла и сравнил вес той части, где лежит содержимое, с весом результата:

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

Про экономию говорят и сами разработчики: в описании проекта есть отдельная мысль о том, что соглашения markdown очень экономны по знакам. Это правда, но ставить её на первое место я бы не стал. Разница между «модель получила три тысячи знаков вместо пятнадцати» и «модель получила понятную структуру вместо мешанины» - разного порядка. Первое экономит деньги, второе определяет, будет ответ осмысленным или нет.

Если тема расхода контекста для тебя больная, я разбирал её отдельно - куда уходят токены в Claude и сколько их даётся на тарифах.

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

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

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

Ставится он отдельным пакетом:

pip install markitdown-mcp
markitdown-mcp --help

Дальше оговорки, каждую из которых я проверил руками.

Пакет заморожен. На PyPI лежат только предвыпускные сборки: 0.0.1a1, a2, a3, a4. Последняя выложена в мае 2025 года. За это время основной пакет прошёл путь от 0.1.2 до 0.1.7, а сервер не обновляли больше года.

На свежем Python он не встанет. Сборка 0.0.1a4 тянет за собой тот самый набор [all], который на Python 3.14 не собирается. У меня установщик молча откатился на самую первую альфу, а она вообще не регистрирует исполняемый файл - команды markitdown-mcp в системе просто не появляется. На Python 3.12 всё встало нормально и справка вывелась.

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

И безопасность. В документации самого пакета написано без обиняков:

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

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

Когда честнее взять другой инструмент?

Сравниваю по задачам, а звёзды на GitHub тут ни при чём:

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

Разница в скорости заметна на глаз. В независимом замере от мая 2026 года на одном и том же регламенте на 14 страниц без видеокарты MarkItDown отработал за 0,6 секунды, Docling - за 41 секунду, Marker - за 2 минуты 14 секунд. На скане MarkItDown выдал пустоту, что совпадает с тем, что получил я.

Отсюда рабочая связка из четырёх шагов:

1. Прогони через MarkItDown всё подряд - он бесплатный и мгновенный.
2. Открой результат и посмотри на его размер.
3. Вышел осмысленный текст - задача решена, дальше ничего не нужно.
4. Вышла каша или пустота - гони этот конкретный файл через тяжёлый инструмент.

Так ты платишь временем и сложностью только за те документы, которые этого требуют.

Как встроить MarkItDown в свою работу?

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

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

Пачка однотипных документов - акты, счета, анкеты, отклики. Складываешь в папку и прогоняешь одной строкой:

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

Дальше отдаёшь модели папку с текстом и просишь свести нужное в таблицу. Работает это на цифровых файлах - сканы отвалятся, и по нулевому размеру ты их сразу увидишь.

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

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

Работа с тяжёлыми PDF внутри терминала в этот список не входит. Там своя история с расходом контекста, и я разбирал её отдельно в материале про PDF в Claude Code без потери токенов. А если ты только собираешь себе рабочее место, начни с установки Claude Code.

С чего начать прямо сейчас: выполни pip install 'markitdown[pdf,docx,xlsx,pptx]', прогони первый попавшийся договор в Word и посмотри на размер результата. Полминуты - и ты будешь знать, работает это на твоих файлах или нет.

Полная схема вайб-кодинга за три вечера: ИИ-клон + Второй мозг + Контекст-инжиниринг. Записи эфиров в личном кабинете, доступ минимум 30 дней.

Практикум по вайб-кодингу

+Твой второй мозг

3 вечера - инструменты, метод, первый проект

Старт 25–27 августа  ·  2 000 ₽

Записаться →

Новые материалы - дайджестом, без спама

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

Подписаться в Telegramили на email