Как конвертировать PDF в Markdown на Python

Почему Markdown — и почему это сложнее, чем кажется

LLM отлично работают с Markdown: заголовки размечают границы разделов, pipe-таблицы держат табличные данные выровненными, списки остаются списками. Скормить модели сырой текст, вытащенный из PDF, — значит потерять всё это, а передать сам PDF-бинарник в большинстве пайплайнов просто невозможно. Поэтому почти каждый серьёзный RAG-стек конвертирует документы в Markdown перед чанкингом и эмбеддингом.

Сложность в том, что в PDF нет структуры — там есть символы, расставленные по координатам x/y. Конвертеру приходится восстанавливать её обратной разработкой: какие строки — заголовки (по размеру шрифта), какие слова образуют таблицу (по выравниванию), каков порядок чтения (по анализу вёрстки). Библиотеки справляются с этим очень по-разному — именно поэтому выбор так важен.

Второе осложнение: в сканированных PDF текста нет вовсе — только картинки страниц. С ними справляются лишь некоторые из вариантов ниже, через OCR.

Вариант 1: PyMuPDF4LLM — быстро и легковесно

PyMuPDF4LLM — тонкая обёртка над PyMuPDF (fitz), сделанная специально под LLM-пайплайны: pip install pymupdf4llm, затем md = pymupdf4llm.to_markdown("doc.pdf") — одна строка, и очень быстро: большинство документов обрабатывается значительно меньше чем за секунду.

Она определяет заголовки по размерам шрифта, выводит таблицы как pipe-таблицы и умеет отдавать постраничные чанки с метаданными для прямой загрузки в LlamaIndex или LangChain. Для «цифровых» PDF с несложной вёрсткой — отчётов, документации, статей без экзотического форматирования — это отличный вариант по умолчанию.

Ограничения: нет OCR, поэтому сканированные страницы возвращаются пустыми. Сложные многоколоночные макеты и замысловатые таблицы могут выйти перепутанными — эвристики внутри рассчитаны на скорость, а не на глубокий анализ вёрстки. Про лицензию: PyMuPDF распространяется под AGPL — для внутренних инструментов это нормально, но перед включением в коммерческий продукт посоветуйтесь с юристами.

Вариант 2: Marker — максимальное качество, нужен GPU

Marker использует пайплайн из глубоких нейросетей для детекции вёрстки, порядка чтения и структуры таблиц и выдаёт самый точный Markdown среди open-source-вариантов — он справляется с многоколоночными научными статьями, сложными таблицами и даже формулами.

Цена — инфраструктура: веса моделей на несколько гигабайт, GPU для приемлемой скорости (на CPU работает, но медленно — зачастую десятки секунд на документ) и тяжёлое дерево зависимостей, которое требует реальных усилий при деплое в продакшен или serverless-окружения.

Выбирайте Marker, когда качество вывода на сложных документах — главный приоритет и есть железо: массовая конвертация научного корпуса на машине с GPU — его идеальный сценарий. Для лёгкого сервиса или serverless-функции операционный вес обычно ставит на нём крест.

Вариант 3: MarkItDown — всеядный конвертер от Microsoft

MarkItDown — open-source-библиотека Microsoft, конвертирующая «всё в Markdown»: pip install markitdown, затем MarkItDown().convert("doc.pdf").text_content. Её сила — широта: один и тот же API конвертирует PDF, DOCX, PPTX, XLSX, HTML и не только — именно поэтому она стала вирусной для подготовки данных под LLM.

Конкретно для PDF её извлечение проще, чем у специализированных вариантов: она опирается на базовое извлечение текста, поэтому по детекции заголовков и точности таблиц уступает PyMuPDF4LLM и Marker, а для сканированных PDF нужна дополнительная настройка OCR.

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

Вариант 4: размещённый API — вообще без зависимостей

Четвёртый вариант — не запускать конвертацию локально: отправить PDF в парсинг-API и получить Markdown в ответ. С ParseJet это выглядит так: resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": open("doc.pdf", "rb")}) — поле "text" в JSON-ответе и есть Markdown.

У этого пути встроенный OCR для сканированных страниц, никаких весов моделей и нативных библиотек, и он одинаково работает в serverless-функции, контейнере и ноутбуке. Вопрос AGPL он тоже снимает полностью. Компромисс — сетевой запрос и стоимость за документ после бесплатного лимита (300 кредитов/мес бесплатно; PDF стоит 3 кредита).

Выбирайте API, когда пайплайн нужен уже сегодня, когда среди PDF есть сканы или когда вы деплоитесь туда, где тяжёлые зависимости больно бьют — Lambda, Cloud Run, Vercel.

Что в итоге выбрать?

«Цифровые» PDF, простая или средняя вёрстка, важна скорость: PyMuPDF4LLM. Лучшее соотношение усилий и качества в чистом Python.

Сложные документы (многоколоночные статьи, замысловатые таблицы) и есть GPU: Marker. По качеству вывода его не обходит ничто из open source.

Много разных типов файлов через одну библиотеку, среднее качество устраивает: MarkItDown.

В потоке есть сканированные PDF, деплой в serverless или ноль желания возиться с зависимостями: размещённый API. Один HTTP-вызов, OCR включён, одна и та же схема вывода для любого документа.

Полный пример: папка PDF в Markdown-файлы

Какой бы путь вы ни выбрали, форма пайплайна одна и та же: итерируем, конвертируем, записываем. Вот версия с API (замените внутренний вызов на pymupdf4llm.to_markdown(), чтобы выполнять локально):

import httpx; from pathlib import Path — затем для каждого pdf в Path("pdfs/").glob("*.pdf"): resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": pdf.read_bytes()}); Path("md/", pdf.stem + ".md").write_text(resp.json()["text"], encoding="utf-8").

Для загрузки в RAG чанкуйте Markdown по заголовкам, а не по фиксированному числу символов — чанки, учитывающие заголовки, сохраняют разделы целиком и извлекаются заметно лучше. Ради этой структурной точности и стоило делать конвертацию аккуратно.