marker-pdf преобразует PDF и изображения в структурированный Markdown, HTML, JSON или плоские блоки для RAG: распознаёт текст, колонки, таблицы, формулы, код и иллюстрации, удаляет повторяющиеся колонтитулы и позволяет обрабатывать отдельные страницы, папки документов или только найденные таблицы.

Основной рабочий путь строится вокруг команды marker_single, пакетной команды marker и интерфейса marker_gui. В интерфейсе слева выбирают файл, диапазон страниц, формат результата и режим распознавания, а справа получают Markdown, HTML или JSON; в командной строке те же параметры задаются ключами, поэтому проверенный профиль легко перенести из ручного теста в автоматический конвейер.

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

Как устроен рабочий процесс marker-pdf

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

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

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

После распознавания процессоры исправляют структуру. Они объединяют соседние строки в абзацы, связывают подписи с рисунками и таблицами, превращают математические области в LaTeX, сохраняют код в ограждённых блоках и подготавливают изображения как отдельные файлы. Рендерер уже не анализирует страницу заново: он получает дерево блоков и записывает его в Markdown, HTML, JSON либо формат chunks.

При диагностике полезно отделять ошибку распознавания от ошибки структуры. Неверная буква или пропущенный фрагмент обычно указывает на необходимость OCR. Правильные слова в неправильном порядке чаще означают проблему макета. Таблица, в которой значения попали не в тот столбец, требует настройки табличного конвейера или LLM-коррекции. Такое разделение экономит время: разные симптомы исправляются разными ключами.

Установка и подготовка окружения

Для запуска нужен Python 3.10 или новее и PyTorch. Базовый пакет устанавливается командой pip install marker-pdf. Он рассчитан на PDF; поддержка DOCX, PPTX, XLSX, HTML и EPUB подключается вариантом pip install marker-pdf[full]. После установки становятся доступны команды marker_single, marker, marker_gui и marker_server.

Перед первым большим заданием стоит проверить, какой режим выберется автоматически. На машине с подходящим GPU применяется режим balanced, на CPU и Apple Silicon — fast. Автовыбор удобен для начала, но в воспроизводимом конвейере режим лучше задавать явно: одинаковая команда на сервере с NVIDIA и на ноутбуке без дискретной графики иначе даст различное соотношение скорости и качества.

Визуальная модель Surya обслуживается отдельным процессом вывода. На NVIDIA обычно используется vLLM, для чего требуются Docker и NVIDIA Container Toolkit. На CPU и Apple Silicon нужен исполняемый файл llama-server из llama.cpp. marker-pdf запускает сервер автоматически при необходимости, но допускает подключение к уже работающему экземпляру через переменную SURYA_INFERENCE_URL.

Если задача ограничена чистыми цифровыми PDF без формул и сканов, можно начать с --disable_ocr. В этом режиме сервер визуальной модели не стартует, а содержимое берётся из текстового слоя с анализом структуры. Это ускоряет пробный прогон и позволяет проверить порядок чтения, заголовки, списки и простые таблицы до загрузки более тяжёлых компонентов.

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

Минимальная проверка после установки

Сначала вызовите marker_single --help и убедитесь, что команда видна в текущем виртуальном окружении. Затем обработайте одну страницу цифрового PDF в режиме fast без OCR и проверьте, появился ли файл результата в каталоге вывода. После этого повторите тест с формулой или сканом, чтобы убедиться, что сервер Surya действительно запускается и возвращает текст.

Для графического интерфейса дополнительно устанавливаются Streamlit и streamlit-ace. Команда marker_gui открывает страницу с загрузкой документа и основными параметрами. Этот интерфейс удобен не как отдельный редактор результата, а как стенд: можно быстро менять диапазон, формат и режим, сравнивая одну и ту же страницу без переписывания длинной команды.

Интерфейс marker_gui

В верхней части страницы отображается название Marker Demo и краткое пояснение о преобразовании PDF или изображения в Markdown, HTML и JSON. Основные параметры находятся в боковой панели. Поле загрузки принимает PDF, PNG, JPG, JPEG, GIF, PPTX, DOCX, XLSX, HTML и EPUB; для форматов, отличных от PDF, должны быть установлены дополнительные зависимости.

После выбора файла левая половина рабочей области показывает страницу документа. Поле Page number позволяет перейти к конкретной странице, причём нумерация начинается с нуля. Рядом формируется диапазон по умолчанию для выбранной страницы. Это удобно для теста: вместо обработки сотен страниц можно открыть один проблемный разворот, настроить режим и только затем запускать весь файл.

Поле Page range принимает номера и интервалы через запятую. Запись 0,5-10,20 означает первую страницу, страницы с шестой по одиннадцатую и двадцать первую в привычной человеческой нумерации. Смешанный диапазон полезен для контрольной выборки, когда нужно одновременно проверить титульный лист, середину документа и приложение с таблицами.

Список Output format содержит Markdown, JSON, HTML и chunks. Markdown выводится как отформатированный текст с внедрёнными извлечёнными изображениями. JSON и chunks показываются структурированным деревом. HTML отображается как готовая разметка. Переключение формата не меняет исходный анализ страницы, но меняет представление и состав доступных полей результата.

Список Mode предлагает auto, balanced и fast. Auto оставляет выбор устройству. Balanced отдаёт приоритет качеству макета и OCR, поэтому лучше подходит для GPU и сложных документов. Fast применяет облегчённый детектор макета и старается использовать визуальную модель только там, где текст пустой, испорчен или требует специального распознавания.

Флажок Use LLM включает дополнительную коррекцию. Force OCR заставляет распознавать все страницы по изображению. Disable OCR, напротив, полностью исключает вызовы VLM, поэтому сканы и формулы могут остаться без содержимого. Strip existing OCR удаляет прежний слой распознанного текста и создаёт новый; эта опция полезна, когда PDF уже содержит невидимый, но ошибочный текст.

Флажок Show page headers/footers сохраняет повторяющиеся верхние и нижние колонтитулы, которые обычно удаляются. Debug включает диагностические материалы: исходное изображение страницы, изображение с найденным макетом и сырой результат. Кнопка Run Marker запускает обработку; справа появляется отрендерированный результат выбранного формата.

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

Преобразование одного файла через marker_single

Базовая команда выглядит как marker_single путь/к/файлу.pdf. По умолчанию создаётся результат в настроенном каталоге вывода, а формат — Markdown. Явный ключ --output_dir помогает отделить результат от исходников и делает команду безопаснее для пакетных сценариев, где входная папка доступна только для чтения.

Ключ --output_format принимает значения markdown, json, html и chunks. При автоматизации формат лучше задавать всегда, даже если нужен Markdown: это защищает сценарий от изменения конфигурационного файла и делает журнал запуска самодостаточным.

--page_range ограничивает обработку. Номера страниц нулевые, поэтому диапазон 0-2 охватывает первые три страницы. Перед длительной задачей полезно прогнать выборку 0,5-7,20: она быстро выявит проблемы титула, многоуровневых заголовков, таблиц и приложений, не расходуя время на весь документ.

--paginate_output добавляет в текст разделители страниц с номером. Разделители нужны, когда по Markdown должна сохраняться привязка к исходному PDF, например для проверки цитат, обратной навигации или формирования метаданных RAG. Без них текст получается чище, но после объединения абзацев определить границу страниц сложнее.

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

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

Ключ --debug создаёт дополнительные изображения и JSON с координатами блоков. Диагностику стоит включать только для небольшого диапазона: на длинном PDF она занимает заметное место. Зато по изображению макета сразу видно, что именно программа считает таблицей, подписью, рисунком, формулой или обычным текстом.

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

Режимы balanced, fast и обработка без OCR

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

Fast использует облегчённый детектор макета и извлекает текст через pdftext. Визуальная модель подключается точечно: к формулам, пустым или искажённым блокам, страницам-сканам и таблицам с низкой уверенностью. Чистый цифровой документ без формул может быть обработан без запуска VLM, что заметно ускоряет большие коллекции.

--disable_ocr запрещает любые вызовы VLM, включая распознавание формул. Этот вариант полезен для быстрого извлечения текста из качественных PDF и для диагностики: если без OCR порядок и символы правильны, дополнительное распознавание не требуется. На сканах результат будет пустым или неполным, поскольку текста для извлечения нет.

Выбор режима следует делать по типу страниц, а не по размеру файла. Двухсотстраничная электронная книга с чистым текстовым слоем может быстрее и точнее пройти в fast, чем десятистраничный скан договора. Напротив, короткая научная статья с формулами, таблицами и двумя колонками часто выигрывает от balanced.

В смешанной коллекции разумен двухпроходный процесс. Сначала выполняют fast и анализируют метаданные page_stats, где для каждой страницы указан метод извлечения и количество блоков. Затем страницы с пустым текстом, необычно малым числом блоков или ошибками повторно обрабатывают с --force_ocr либо balanced.

В режиме fast можно отдельно включить распознавание встроенной математики ключом --ocr_inline_math. Принудительный OCR также активирует полноценную обработку математических фрагментов, но увеличивает время. Если документ содержит только несколько формул, точечный вариант обычно рациональнее полного повторного чтения каждой страницы.

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

Цифровые PDF, сканы и повреждённый текстовый слой

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

Если результат содержит бессмысленные знаки, используйте --force_ocr. Программа проигнорирует предположение, что встроенный текст пригоден, и прочитает страницу визуально. Это увеличивает время, зато исправляет документы, где копирование из обычного PDF-просмотрщика уже даёт мусор.

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

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

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

Для многоязычного документа язык отдельно задавать не требуется: Surya рассчитана на распознавание разных языков. Однако смешение кириллицы и латиницы в артикулах, формулах, коде и библиографических ссылках остаётся сложным случаем. Такие области следует проверять по исходнику, особенно если результат затем индексируется и используется для точного поиска.

Метаданные page_stats помогают понять, как была прочитана каждая страница. Если метод извлечения меняется внутри одного файла, это нормально: marker-pdf может использовать текстовый слой на чистых страницах и OCR там, где слой отсутствует или признан плохим. Такой смешанный режим экономит время без ручного разделения документа.

Markdown: структура, формулы, код и изображения

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

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

Блочные формулы ограждаются двойными знаками доллара. Встроенная математика обрабатывается отдельно и сложнее, потому что формула находится внутри строки и должна быть отделена от обычных слов. В balanced это выполняется автоматически; в fast следует включить OCR математики или принудительное распознавание, если символы теряются.

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

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

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

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

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

JSON и дерево блоков

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

Поле id уникально внутри результата и включает путь к странице и типу блока. block_type показывает роль элемента: Text, SectionHeader, Table, Figure, Picture, Equation, Code, ListItem, Caption, Form, PageHeader, PageFooter и другие. По этому полю можно отобрать только таблицы, формулы или рисунки, не разбирая итоговый Markdown регулярными выражениями.

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

Поле html хранит разметку блока и ссылки content-ref на дочерние элементы. Чтобы получить полный HTML, эти ссылки нужно рекурсивно заменить содержимым детей; в поставке есть функция, выполняющая такое разворачивание. Простое объединение строк html без обхода дерева приведёт к пропущенным вложенным блокам.

section_hierarchy связывает элемент с заголовками, внутри которых он расположен. Это особенно полезно для RAG: текстовый фрагмент можно снабдить метаданными глава — подраздел — пункт, даже если сами заголовки находятся на предыдущей странице. Поиск получает контекст, а ответ легче сопоставить с документом.

Изображения могут храниться в поле images в кодировке base64. Такой JSON самодостаточен, но быстро растёт. Для больших коллекций чаще выгодно сохранять изображения отдельными файлами и в индексе хранить путь, хеш и идентификатор блока. Самодостаточный вариант удобнее для передачи одного документа через очередь или API.

Метаданные включают вычисленное оглавление и page_stats. В оглавлении есть название, уровень и идентификатор страницы с координатами. Page_stats описывает метод извлечения текста и количество блоков по типам. Эти данные можно использовать для контроля качества: страница с нулём Text и одной Picture, вероятно, требует OCR.

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

Формат chunks для RAG

Chunks похож на JSON, но вместо вложенного дерева выдаёт плоский список верхнеуровневых блоков страниц. В каждом элементе уже находится полный HTML блока, поэтому потребителю не нужно рекурсивно проходить content-ref. Такой формат удобен как промежуточный слой перед разбиением, эмбеддингами и загрузкой в векторную базу.

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

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

Для цитирования добавляйте к каждому фрагменту номер страницы и block id. Номер страницы нужен человеку, block id — программе для обратной связи с JSON и диагностикой. Если включена пагинация Markdown, не используйте только текстовый разделитель как единственную опору для номера: после дополнительной обработки он может исчезнуть, а метаданные остаются стабильнее.

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

Качество RAG зависит не только от распознавания. Даже точный текст даст слабые ответы, если объединить разные разделы, потерять заголовки или разбить таблицу на бессвязные куски. Chunks предоставляет удобную исходную структуру, но правила финальной нарезки должны учитывать тип блока и задачу поиска.

HTML как результат преобразования

HTML сохраняет те же смысловые блоки, что и Markdown, но выражает их тегами. Изображения подключаются через img, код помещается в pre, а математические области — в math. Формат удобен, когда результат сразу показывается в веб-интерфейсе или проходит дальнейшую обработку DOM-инструментами.

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

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

Для сравнения качества полезно открыть HTML и Markdown рядом. Если структура совпадает, но таблица лучше выглядит в HTML, проблема не в распознавании, а в ограничениях Markdown. Если отсутствует целый блок в обоих форматах, нужно возвращаться к макету, OCR или диапазону страниц.

В графическом интерфейсе HTML показывается встроенным компонентом. Это быстрый способ увидеть, правильно ли закрыты теги и как браузер интерпретирует таблицы, формулы и изображения. Однако окончательную проверку следует проводить в той системе, куда результат будет загружен, потому что её CSS и фильтры могут изменить вид.

Извлечение таблиц

Для полного документа таблицы распознаются как один из типов блоков. Если нужны только они, используется TableConverter. Он принимает те же параметры, что и PdfConverter, но ограничивает конвейер табличным содержимым. В командной строке класс конвертера задаётся через --converter_cls marker.converters.table.TableConverter.

Конфигурация force_layout_block=Table заставляет считать каждую страницу таблицей. Это полезно для банковских выписок, прейскурантов и отчётов, где вся страница представляет единую сетку, а обычный детектор может разделить её на несколько областей. Для смешанного документа такой режим применять нельзя: обычные абзацы будут интерпретированы как ячейки.

Таблицы выводятся HTML-блоками; JSON дополнительно сохраняет координаты. Координаты нужны для проверки, но не гарантируют правильную сетку. Основные ошибки возникают в многоуровневых заголовках, объединённых ячейках, строках без видимых границ и случаях, когда текст одной ячейки переносится на несколько строк.

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

Если столбцы сливаются, попробуйте balanced, принудительный OCR или LLM-коррекцию. LLM умеет объединять таблицы через границы страниц и исправлять формат, но не отменяет необходимость проверки. Модель может привести структуру к правдоподобному виду и одновременно неверно распределить редкие значения.

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

Если задача состоит в извлечении нескольких полей из формы, TableConverter не всегда лучший выбор. Формы могут сочетать подписи, значения, линии и свободно расположенные области, а в известных ограничениях отмечено, что сложные формы и вложенные таблицы обрабатываются неидеально. Для них разумнее JSON с блоками Form и последующая предметная логика.

Формулы и встроенная математика

Блочная формула занимает отдельную область и обычно распознаётся надёжнее, чем короткая формула внутри абзаца. marker-pdf преобразует математические изображения в LaTeX и помещает блочные выражения в двойные знаки доллара. В JSON формула получает собственный тип и координаты.

Встроенная математика сложнее из-за границы между словами и символами. В balanced она распознаётся автоматически. В fast можно включить --ocr_inline_math, а для максимальной коррекции вместе с LLM применяется --redo_inline_math. Последний вариант медленнее и нужен не каждому документу.

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

Формула может быть ошибочно распознана как обычный текст или рисунок. В debug-изображении проверьте тип рамки. Если область макета неверна, повторный OCR текста не исправит классификацию; потребуется другой режим, настройка процессоров или ручная коррекция блока.

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

Пакетная обработка папки

Команда marker путь/к/папке применяет тот же набор параметров, что и marker_single, но обрабатывает несколько файлов. Количество рабочих процессов регулируется --workers. Увеличение значения повышает загрузку CPU и потенциальную пропускную способность, однако не должно превышать возможности диска, памяти и сервера VLM.

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

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

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

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

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

Для чистых цифровых PDF пакетный режим без OCR масштабируется по ядрам CPU и не запускает сервер VLM. Для смешанной коллекции fast обычно даёт лучший стартовый баланс. Balanced стоит резервировать для документов, где структура и распознавание важнее времени, либо для повторной обработки неудачных страниц.

Журналируйте команду, дату, хеш входного файла, формат, режим и каталог моделей. Без этих данных трудно объяснить, почему два одинаковых PDF дали разные результаты после изменения окружения. Сам Markdown не содержит полного профиля запуска, поэтому воспроизводимость должна обеспечиваться внешним манифестом.

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

Класс PdfConverter позволяет встроить обработку в приложение. Ему передают словарь моделей, после чего объект вызывают с путём к файлу. Результат зависит от рендерера: для Markdown доступны текст, метаданные и изображения; для JSON — дочерние блоки, типы и координаты.

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

Функция text_from_rendered извлекает текст, расширение и изображения из отрендерированного результата. Не игнорируйте словарь изображений, если Markdown содержит ссылки: при сохранении только строки ссылки останутся, но файлы не появятся. Названия следует сохранять точно так, как они указаны в тексте.

Метод build_document возвращает внутреннюю модель до финального рендеринга. Через contained_blocks можно выбрать блоки заданных типов, например формы. Это полезно, когда нужен не весь документ, а только конкретные элементы с координатами и связями.

Архитектура разделена на providers, builders, processors, renderers, schema и converters. Provider читает входной файл, builder создаёт начальные блоки, processor исправляет определённый тип, renderer формирует результат, schema описывает блоки, converter связывает этапы. Расширение следует помещать на соответствующий уровень, а не переписывать весь конвейер.

Чтобы добавить собственную постобработку, можно передать список процессоров. Например, предметный процессор способен нормализовать артикулы, пометить предупреждения или объединить блоки по корпоративному шаблону. Важно не изменять исходные координаты без необходимости: они нужны для аудита и обратной ссылки на страницу.

Новый формат вывода реализуется рендерером. Если системе нужен XML, особый JSON или сообщения для очереди, лучше преобразовать дерево блоков напрямую, чем разбирать Markdown. Markdown уже потерял часть пространственных сведений и может неоднозначно представлять объединённые таблицы.

Пользовательский provider нужен для нового входного формата. Для DOCX, PPTX, XLSX, HTML и EPUB предусмотрены дополнительные зависимости. Если нестандартный формат можно надёжно преобразовать в PDF до marker-pdf, это проще, но промежуточная конверсия иногда меняет шрифты, страницы и порядок объектов; результат следует проверять на типовых документах.

LLM-коррекция и выбор сервиса

Ключ --use_llm добавляет этап, который может исправлять таблицы, объединять их через страницы, улучшать встроенную математику, обрабатывать формы и применять пользовательскую инструкцию. Это не замена базовому распознаванию: LLM получает уже найденные блоки и помогает устранить сложные случаи.

Поддерживаются Gemini, Google Vertex, Ollama, Claude, OpenAI-совместимые конечные точки, Azure OpenAI и OpenRouter. Конкретный класс задаётся --llm_service, а ключи и имена моделей — параметрами выбранного сервиса. Не смешивайте параметры разных провайдеров в одном профиле: неизвестные значения затрудняют диагностику.

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

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

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

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

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

Профили конфигурации и воспроизводимый запуск

Длинную команду удобно превращать в отдельный JSON-профиль. В нём фиксируют режим, формат, диапазон, параметры OCR, правила сохранения изображений, пагинацию, список процессоров и настройки LLM. Профиль должен описывать одну понятную задачу: например, быстрый разбор цифровых инструкций, усиленное распознавание сканов или извлечение таблиц. Смешивание взаимоисключающих целей в одном файле усложняет проверку и делает результат непредсказуемым.

Имена параметров и допустимые значения лучше брать из вывода marker_single --help. Там перечисляются не только основные ключи команды, но и настройки компонентов, которые собираются в конвертер. Это надёжнее случайного копирования старого примера: неизвестный ключ может быть проигнорирован или вызвать ошибку, а изменившийся тип значения — остановить запуск до чтения документа.

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

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

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

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

Формат вывода также следует фиксировать в профиле. Markdown и HTML предназначены для чтения и дальнейшей публикации, JSON — для структурной обработки и аудита, chunks — для плоской выдачи блоков. Переключение формата меняет не только расширение файла: меняется доступная глубина структуры, способ представления таблиц, координаты и обработка изображений. Сравнивать два запуска корректно только при одинаковом рендерере.

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

Настройка VLM-сервера и распределение нагрузки

Balanced и другие сценарии с визуальным распознаванием обращаются к серверу Surya. Бэкенд выбирается переменной SURYA_INFERENCE_BACKEND: на машине с NVIDIA используется путь через vLLM, а для CPU и Apple Silicon — llama.cpp. Автоматический выбор удобен для первого запуска, но на сервере с несколькими типами ускорителей лучше задать бэкенд явно и проверить его отдельным коротким документом.

SURYA_INFERENCE_URL подключает marker-pdf к уже запущенному серверу. Такой вариант полезен, когда несколько рабочих процессов или служб должны использовать одну загруженную модель. Адрес должен быть доступен из того же окружения, где выполняется конвертер; ошибка соединения проявится как сбой OCR, даже если чтение текстового слоя и анализ макета работают нормально.

Число параллельных запросов регулируется SURYA_INFERENCE_PARALLEL. Повышать его следует постепенно. Если сервер способен обрабатывать только несколько изображений одновременно, слишком длинная очередь увеличит задержку, память и вероятность тайм-аута, но не даст пропорционального ускорения. Измеряйте страницы в минуту на одном и том же тестовом файле, а не ориентируйтесь только на загрузку GPU.

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

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

Рабочие процессы marker не должны запускать независимую копию модели для каждого файла. Они совместно используют один VLM-сервер и отправляют ему запросы. Поэтому увеличение --workers ускоряет подготовку страниц и работу CPU только до момента, когда сервер визуального вывода становится узким местом. После этого новые процессы создают очередь и потребляют память без роста пропускной способности.

При оценке быстродействия разделяйте цифровые и сканированные страницы. Цифровой PDF в режиме без OCR измеряет извлечение текста, анализ макета и рендеринг; скан дополнительно включает подготовку изображения и VLM. Среднее время по смешанному файлу трудно сравнивать между запусками, если доля страниц, направленных на OCR, изменилась.

Если сервер не запускается, сначала проверьте сам бэкенд: доступность Docker и NVIDIA Container Toolkit для vLLM либо путь к llama-server для llama.cpp. Затем проверьте URL, свободную память и журнал процесса. Переустановка всего marker-pdf редко помогает при ошибке контейнера, драйвера или недоступном исполняемом файле.

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

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

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

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

Для таблиц создайте предметные проверки. Финансовая таблица должна сохранять число столбцов, даты, валюты, знак минуса и пустые значения. Таблица спецификации — артикулы, единицы и порядок характеристик. Сверка только первой строки не обнаруживает сдвиг, который начинается после объединённой ячейки или переноса на следующую страницу.

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

Изображения требуют двух проверок. Сначала убедитесь, что каждый относительный путь из Markdown или HTML существует. Затем сравните число извлечённых файлов с числом блоков Picture и Figure в JSON. Расхождение может означать пропущенную запись, дубликат или рисунок, который был встроен в другой объект. Хеши позволяют обнаружить повторное сохранение одного кадра под разными именами.

Для OCR-текста полезны словари и шаблоны, но они не должны автоматически исправлять исходный результат без журнала. Регулярное выражение способно заметить неверную длину идентификатора, а словарь — редкое слово, однако автоматическая замена может уничтожить фамилию, формулу или артикул. Безопаснее пометить фрагмент для проверки и сохранить исходное распознавание рядом с исправленным.

Ошибочные страницы направляйте в повторный профиль, а не запускайте заново весь документ. Сначала попробуйте принудительный OCR или удаление плохого слоя, затем balanced, после этого — LLM-коррекцию для конкретных блоков. Сохраняйте причину повторной обработки и сравнение результатов, чтобы усиленный режим не заменил корректный текст менее точной догадкой.

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

Организация файлов результата

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

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

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

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

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

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

Встроенный API-сервер

Команда marker_server --port 8001 запускает FastAPI-сервер. Для него требуются uvicorn, fastapi и python-multipart. После старта доступна автоматически сформированная документация методов, а запрос к маршруту marker передаёт путь к файлу и ограниченный набор параметров.

Сервер принимает page_range, mode, force_ocr, paginate_output и output_format. Гибридный путь --use_llm и --disable_ocr через этот простой интерфейс не предоставляются. Если они нужны, используйте Python API, собственный сервисный слой или командную строку.

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

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

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

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

Отладка макета и качества

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

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

Если таблица потеряла столбец, проверьте, захвачена ли вся область Table. Неполная рамка означает ошибку макета. Полная рамка при неверных ячейках указывает на реконструкцию сетки. В первом случае помогает режим balanced или принудительный тип блока, во втором — LLM-коррекция и последующая валидация.

Если рисунок отсутствует, найдите блок Figure или Picture и проверьте словарь images. Блок может быть обнаружен, но файл не сохранён из-за отключённого извлечения. Или изображение может быть встроено необычным способом и не попасть в provider. Эти случаи требуют разных исправлений.

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

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

Типовые ошибки и способы исправления

В результате бессмысленные символы

Сначала попробуйте --force_ocr. Если PDF содержит старый невидимый слой распознавания, добавьте --strip_existing_ocr. Проверьте одну страницу и сравните числа и специальные знаки: повторное OCR может исправить слова, но изменить редкие символы.

Скан даёт пустой текст

Убедитесь, что не включён --disable_ocr и доступен сервер Surya. В режиме без OCR скан не содержит извлекаемых символов. Если сервер не стартует, проверьте vLLM и NVIDIA Container Toolkit на GPU либо llama-server на CPU и Apple Silicon.

Не хватает памяти

Уменьшите число workers, обработайте меньший диапазон или разделите длинный PDF. На пакетной задаче сначала установите один рабочий процесс и измерьте пик памяти. Увеличивайте параллелизм постепенно, контролируя не только VRAM, но и обычную RAM и размер временных изображений.

Файл обрабатывается слишком долго

Проверьте, не включены ли принудительный OCR, LLM и повторная математика для чистого цифрового документа. Попробуйте fast или --disable_ocr на нескольких страницах. Если качество приемлемо, этот профиль даст значительный выигрыш на всей коллекции.

Текст идёт в неправильном порядке

Включите debug и посмотрите рамки колонок. Ошибка порядка обычно связана с макетом, а не с OCR. Balanced чаще лучше справляется со сложной композицией. Для повторяющегося корпоративного шаблона можно добавить процессор, сортирующий блоки по известным зонам.

Таблица выглядит аккуратно, но числа сдвинуты

Сравните несколько строк по всем столбцам и найдите первую пустую или объединённую ячейку. Попробуйте HTML-таблицу, TableConverter, balanced и LLM. После коррекции используйте автоматические проверки: количество столбцов, тип данных, диапазоны и контрольные суммы.

Исчезли рисунки

Проверьте, не задан ли --disable_image_extraction, и переносится ли каталог изображений вместе с Markdown. В JSON найдите Picture и Figure. Если блок есть, но файла нет, проблема в сохранении; если блока нет, исследуйте макет в debug.

Колонтитул удалён вместе с важной строкой

Включите --keep_pageheader_in_output и --keep_pagefooter_in_output. После этого удаляйте только точные повторения собственным правилом. Для юридических документов безопаснее сохранить лишнюю строку, чем потерять реквизит.

Команда marker_gui не запускается

Установите Streamlit и streamlit-ace в то же виртуальное окружение, где находится marker-pdf. Проверьте вывод which marker_gui или аналогичную команду оболочки. Если интерфейс стартует, но останавливается на моделях, проблема относится уже к бэкенду распознавания.

Пакетный запуск повторно обрабатывает готовые файлы

Используйте --skip_existing и отдельный каталог вывода. Убедитесь, что имена результатов уникальны: два исходника с одинаковым именем из разных подпапок могут конфликтовать. Для надёжности добавляйте к каталогу идентификатор или хеш входного пути.

Практические сценарии

Подготовка научных статей для поиска

Выберите balanced для статей с формулами и двумя колонками, включите пагинацию и сохранение изображений. Получите chunks или JSON, прикрепите section_hierarchy и номера страниц, а таблицы индексируйте отдельными блоками. Формулы проверяйте визуальным рендерингом LaTeX.

Массовая обработка электронных книг

Начните с fast и отключите OCR на контрольной выборке. Если текстовый слой чистый, пакетный режим без VLM даст высокую скорость. Удаление повторяющихся колонтитулов особенно полезно для книг, а вычисленное оглавление помогает разбивать материал по главам.

Коллекция сканов

Сначала оцените качество изображений и старого OCR. Для плохого невидимого слоя используйте strip_existing_ocr, для страниц без текста — force_ocr. Храните page_stats и выделяйте страницы с подозрительно малым количеством блоков для ручной проверки.

Извлечение таблиц из отчётов

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

Построение корпоративного RAG

Используйте chunks как исходные единицы, но выполняйте собственную нарезку по типам блоков. Добавляйте заголовки разделов, номер страницы, block id, хеш документа и признак OCR. Изображения снабжайте подписями или описаниями, не теряя оригинальные файлы.

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

Сохраняйте исходный PDF, JSON, Markdown, изображения и манифест параметров. По координатам из JSON можно открыть точное место исходника для каждого спорного абзаца. Такой набор позволяет редактору исправлять Markdown, не теряя доказательство происхождения.

Сервис преобразования внутри команды

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

Ограничения, которые нужно учитывать

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

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

Markdown ограничен собственной моделью. Он не умеет точно выражать объединённые ячейки, сложную типографику, плавающие элементы и координатную верстку. Потеря визуального вида не всегда является ошибкой marker-pdf; иногда информация присутствует в JSON или HTML, но не помещается в простой синтаксис Markdown.

Качество OCR зависит от исходного изображения. Модель не может восстановить символ, которого нет из-за размытия или обрезки. Повторный запуск с LLM способен угадать контекст, но угадывание неприемлемо для номеров, сумм и формул. В таких случаях нужна ручная сверка или лучший скан.

Использование VLM и LLM повышает требования к вычислениям, настройке и контролю данных. Без OCR программа быстрее, но пропускает сканы и формулы; с balanced качество выше, но нужен сервер вывода; с облачным LLM документы могут покидать инфраструктуру. Профиль выбирают по риску и типу документа, а не по максимальному числу включённых функций.

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

Сравнение marker-pdf с аналогами

Программа	Лучше подходит для	Главное ограничение
marker-pdf	PDF со сложным макетом, формулами и контролируемой подготовкой Markdown, JSON или chunks	OCR требует настройки VLM-бэкенда, а сложные таблицы нужно проверять
MinerU	Научные документы, CJK-контент и извлечение Markdown/JSON с широкой аппаратной поддержкой	Тяжёлый многомодельный конвейер и значительные требования к окружению
Docling	Единое представление разных офисных и мультимедийных форматов для RAG	На плотных таблицах и отдельных макетах требуется дополнительная проверка
MarkItDown	Быстрое превращение разнородных файлов в текстовый Markdown для LLM	PDF-структура, таблицы и заголовки восстанавливаются слабее специализированных парсеров
LlamaParse	Облачный агентный разбор сложных PDF, сканов, таблиц и диаграмм	Нужны учётная запись, API-ключ и передача документов внешнему сервису

marker-pdf разумно выбирать, когда важны формулы, изображения, координаты блоков и возможность управлять балансом между текстовым слоем и OCR. MinerU полезен для сложных научных коллекций и разнообразного оборудования. Docling удобен как единая модель документа для множества форматов. MarkItDown выигрывает простотой на файлах, где достаточно текста. LlamaParse подходит, когда допустима облачная обработка и приоритетом является готовый сервис без настройки моделей.

Как проверить результат перед использованием

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

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

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

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

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

Вопросы по настройке marker-pdf

Какой формат выбирать для обычной базы знаний?

Markdown удобен для просмотра и простого индексирования. Chunks лучше, если нужен плоский список блоков с готовым HTML. JSON выбирают, когда важны координаты, типы, вложенность и обратная ссылка на страницу. Нередко хранят JSON как основной доказательный слой, а Markdown — как читаемое представление.

Нужно ли всегда включать force_ocr?

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

Можно ли обработать только часть документа?

Да. Page range принимает отдельные номера и интервалы через запятую. Нумерация начинается с нуля. Это подходит для теста, повторной обработки проблемных страниц и извлечения конкретного приложения без запуска всего PDF.

Как сохранить номер страницы в RAG?

Используйте метаданные страницы и block id из JSON или chunks. Пагинация Markdown полезна для чтения, но структурное поле надёжнее. При объединении фрагментов сохраняйте минимальный и максимальный номер страницы.

Почему таблица лучше выглядит в HTML, чем в Markdown?

HTML поддерживает более сложную структуру ячеек. Стандартный Markdown рассчитан на прямоугольные таблицы без объединений. Если данные распознаны правильно, но разметка теряет уровни заголовка, оставьте таблицу в HTML или храните JSON.

Что делать с документами без GPU?

Используйте fast; для чистого текста можно добавить --disable_ocr. Для визуального распознавания на CPU и Apple Silicon нужен llama-server. Обработка будет медленнее, поэтому сначала ограничьте диапазон и оцените время.

Как не потерять изображения?

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

Можно ли извлечь только таблицы?

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

Когда включать LLM?

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

Итоговый порядок работы

Начните с одной цифровой и одной сложной страницы в marker_gui или marker_single. Сравните fast, balanced и режим без OCR, выберите формат и решите, нужны ли изображения, колонтитулы и пагинация. Для сканов отдельно проверьте force_ocr и strip_existing_ocr.

Затем сохраните параметры в конфигурации, выполните ограниченную пакетную выборку и проверьте текст, таблицы, формулы, изображения и метаданные. Только после этого увеличивайте workers или распределяйте коллекцию по машинам. Ошибочные документы направляйте во второй профиль с усиленным OCR или LLM-коррекцией.

Для читаемой публикации используйте Markdown или HTML; для проверяемого конвейера храните JSON с координатами; для RAG начинайте с chunks и добавляйте собственные правила разбиения. Такой разделённый процесс позволяет получать удобный результат, не теряя связь с исходной страницей и не превращая единичную ошибку распознавания в проблему всей коллекции.