MinerU: как превратить PDF в структурированный текст — разбор документного parser проекта OpenDataLab. Превратить PDF в структурированный текст с его помощью можно через разные точки входа: команду mineru parse, набор mineru-kit, локальный SDK, Tasks или WebUI. Сначала выбирают способ запуска, затем читают формат вывода именно этого способа. Название относится к инструменту разбора документов.
Что такое MinerU и как устроена текущая линия 4.x
MinerU — это command-line document reader для агентов: он разбирает локальные документы в читаемое содержимое, позволяет агенту продолжать по странице или блоку и возвращает стабильные локаторы для последующих чтений и цитирования. Так описывает назначение проекта его страница на GitHub. Там же прямо сказано, что MinerU не является RAG-фреймворком, векторной базой или приложением для чата с документом. Это рамка, которая задаёт место инструмента: он готовит структуру, а поиск и генерация строятся отдельно.
Второй важный момент — приватность по умолчанию. Документы не загружаются в официальный сервис автоматически; удалённый разбор требует явной настройки. Для внутреннего документа отдельно проверьте выбранный engine, сервис и весь маршрут обработки. Отсутствие автоматической отправки в официальный сервис описывает конкретный маршрут, а остальные сетевые компоненты своей конфигурации нужно уточнить.
Лицензирование устроено не как чистый Apache. Репозиторий распространяется под MinerU Open Source License, основанной на Apache 2.0 с дополнительными условиями. Условия кода и условия моделей стоит уточнять отдельно, прежде чем встраивать инструмент в продукт.
Текущую линию 4.x разбирают по GitHub и по двум полным разделам документации: OutputContract (форматы вывода) и Tiers (уровни разбора). Версия 4.0.0 в OutputContract названа иллюстративным примером producer, и превращать её в номер текущего релиза не стоит. В этой статье MinerU обозначает документный инструмент OpenDataLab.
Практический вывод для читателя: сначала определитесь с точкой входа, потом с форматом вывода, и только затем с уровнем качества. Это разные решения, которые проверяют последовательно: выбранная точка входа определяет доступные форматы и настройки разбора.
Выбор entrypoint: команда, kit, SDK, Tasks или WebUI
Точка входа определяет и формат ответа, и способ проверки. Форматы и поля одного способа не переносятся на другой: то, что вернёт WebUI, не равно тому, что вернёт команда.
| Entrypoint | Что получаете | Где проверять структуру |
|---|---|---|
mineru parse |
Markdown; при --json — ответ команды со статусом, содержимым и локаторами |
Markdown для чтения, --json для машинной обработки |
mineru-kit |
набор утилит вокруг разбора | документация набора |
| Локальный SDK | программный вызов и объект результата | structured_content() в коде |
| Tasks | задачный интерфейс | интерфейс задач и его экспорт |
| WebUI | визуальная проверка разметки и экспорт | превью с рамками регионов, меню загрузки |
Ключевое различие, которое ломает интеграции: ответ mineru parse --json — это ответ команды со статусом. MiddleJson представляет другой контракт данных. Непосредственно передавать ответ mineru parse --json в ParseResult.from_dict() нельзя. Так формулирует ограничение страница Output File Format в документации проекта. Если вы строите пайплайн, где команда должна питать SDK-объект, между ними нужен явный слой преобразования.
В WebUI предусмотрен визуальный контроль через предпросмотр. Когда вы проверяете разметку в WebUI, рамки регионов появляются поверх превью исходника, а PDF из меню загрузки отрисован из сохранённого результата. При просмотре проверьте, сохранились ли связи между строками и столбцами таблицы.
Порядок действий для нового проекта:
- Зафиксируйте, кто потребляет результат: человек, скрипт или агент.
- Выберите entrypoint под этого потребителя.
- Прочитайте формат вывода именно этого entrypoint в OutputContract.
- Проверьте структуру на одном документе до массовой обработки.
- Только после этого подключайте поиск или RAG.
Шаг 4 экономит больше времени, чем любой другой. Ошибка в структуре, найденная на одном файле, дешевле ошибки, найденной на тысяче.
Форматы вывода: Markdown, MiddleJson и StructuredContent
Три представления результата решают разные задачи, и путать их не следует.
Markdown и экспортные файлы — это результат для чтения. Их смотрит человек, их вставляют в вики, из них делают документацию.
ModelJson и MiddleJson — промежуточные протоколы. ModelJson хранит страницы анализа и page_index_map; MiddleJson хранит упорядоченные постобработанные страницы и семантические блоки. Так разводит их документация Output File Format.
StructuredContent — потребительское представление. Функция structured_content() возвращает именно его, Это отдельное представление данных с собственным назначением.
Отдельно про версии. schema и schema_version описывают сериализацию, а metadata.producer.version — версию производителя. Это разные вещи, и по ним нельзя судить о номере установленного релиза. Иллюстративное значение 4.0.0 из документации остаётся примером.
Практическая проверка формата: откройте результат и найдите в нём таблицу. JSON сам по себе не доказывает, что ячейки легли правильно. Структура может быть валидной и при этом перепутанной по смыслу — это ловушка, в которую попадают те, кто проверяет только схему.
Текстовый PDF и скан: tiers, backends и ресурсы
Tiers выражают качество и стоимость разбора. Small-model backends и VLM-движки настраиваются независимо и именами tier-ов не являются. PDF и изображения поддерживают все четыре уровня. Нативный разбор текста не требует inference-моделей, а Basic может работать на CPU. Скорость и память Standard и Advanced зависят от VLM-движка, размера входа и параллельности. Эти формулировки даёт страница Tiers and Runtimes.
Разделение текстового PDF и скана — первое, что стоит сделать до выбора уровня. У текстового PDF есть слой текста, и нативный разбор обходится без моделей. Скан требует распознавания. Flash имеет отдельные сценарии для нативного текста и для OCR, поэтому объявлять все сканы неподдерживаемыми для Flash неверно.
Второе разделение — backend и tier. Это независимые настройки. Ресурсы проверяют для выбранного сочетания tier и backend. Универсальных гарантий по объёму видеопамяти или оперативной памяти здесь нет: требования зависят от движка, документа и параллельности.
Третье — поведение при недоступности уровня. После обнаружения возможностей сервиса библиотека документов предпочитает Standard, затем Basic для PDF и изображений. Если ни один недоступен, возвращается quality_tier_unavailable вместо тихого выбора Flash или загрузки в официальный сервис. Это предсказуемое поведение, на которое можно опираться в автоматизации.
| Ситуация | Разумный старт | Что проверить |
|---|---|---|
| Текстовый PDF, простой макет | нативный разбор | сохранён ли порядок абзацев |
| Текстовый PDF, сложные таблицы | Standard | не перепутаны ли ячейки |
| Скан, простой макет | Basic или OCR-сценарий Flash | полнота текста |
| Скан, сложный макет | Advanced | связность блоков и подписей |
Чужие benchmark-и по скорости сюда не переносятся. В сравнительных обзорах встречаются случаи, когда установка MinerU падала из-за bundled-бинарника на конкретной машине, и авторы помечают такие таблицы как частные наблюдения. Измерением всех возможных установок они не являются. Такая неудача описывает одну конкретную конфигурацию. Старые команды и лицензионные трактовки линии 2.x в инструкцию для текущей версии тоже не переносятся.
Учебный пример: PDF «Каталог кружков» и ожидаемый Markdown
Ниже — полный учебный исходник. Это вымышленный пример автора, составленный вручную; реальный интерфейс не запускался, и результат не является выходом MinerU.
Каталог кружков
В нашем центре работают два направления для школьников.
Занятия проходят во второй половине дня, запись открыта.
Кружок День недели Время
Робототехника среда 18:00
Рисование пятница 17:00
Запись у администратора.
Шаги создания PDF в текстовом редакторе:
- Откройте текстовый редактор и вставьте текст выше.
- Оформите первую строку как заголовок первого уровня.
- Оставьте абзацы отдельными блоками с пустой строкой между ними.
- Вставьте таблицу с тремя колонками и двумя строками данных.
- Сохраните файл через «Экспорт в PDF» или «Печать в PDF».
- Проверьте, что в готовом PDF таблица видна как таблица.
Ожидаемый Markdown, составленный вручную как эталон:
# Каталог кружков
В нашем центре работают два направления для школьников.
Занятия проходят во второй половине дня, запись открыта.
| Кружок | День недели | Время |
|---|---|---|
| Робототехника | среда | 18:00 |
| Рисование | пятница | 17:00 |
Запись у администратора.
Эталон задаёт четыре проверки: заголовок сохранён, порядок абзацев сохранён, обе строки таблицы не перепутаны, дни недели связаны со своим кружком. Последняя проверка самая строгая. Ошибочный вариант выглядит так: строка «Рисование» получает день «среда», а «Робототехника» — «пятница». Схема при этом валидна, JSON корректен, а смысл разрушен.
Способ проверки: сравните полученный Markdown с эталоном построчно, проверяя содержание каждой связи. Для автоматизации подойдёт сопоставление пар «кружок — день — время» как кортежей.
Проверка структуры перед подключением RAG
RAG подключают после проверки структуры. Если блоки собраны неверно, поиск может передать модели неполный или искажённый контекст. Проверка извлечения помогает заметить этот дефект до оценки ответов.
Порядок проверки:
- Сравните заголовки: сохранилась ли иерархия.
- Проверьте порядок абзацев на двух-трёх страницах.
- Сверьте таблицы с исходником по строкам.
- Убедитесь, что подписи остались рядом со своими объектами.
- Проверьте локаторы: указывают ли они на реальные страницы.
- Только затем индексируйте блоки.
Отдельно про локаторы. Проект заявляет стабильные локаторы для последующих чтений и цитирования. Это значит, что после разбора агент может вернуться к конкретному месту документа. Для цитирования в ответах это полезнее, чем просто текст.
Если вы используете MinerU как один из парсеров в связке с LangChain, порядок остаётся тем же: сначала разбор и проверка структуры, потом загрузка в цепочку. Ошибка в структуре может повлиять на найденный контекст и ответ. Отдельная проверка извлечения упрощает последующую диагностику.
Как зафиксировать проверку своего PDF
Сохраните исходный документ отдельно от полученного результата. Рядом запишите выбранную точку входа, tier и формат экспорта. Для каждой строки учебной таблицы проверьте связку названия кружка, дня и времени. Одного совпадения всех слов недостаточно: день среды мог оказаться рядом с рисованием, хотя относился к робототехнике.
Отмечайте каждое расхождение конкретно: потерян заголовок, переставлен абзац, перепутан день, не найдено время. Затем меняйте только один элемент конфигурации и повторяйте ту же сверку. Это план проверки читателя. Реальный результат для вашего PDF появится после собственного запуска; приведённый ручной Markdown остаётся ожидаемым образцом для сравнения.
Частые вопросы
MinerU — это бесплатно?
Репозиторий распространяется под MinerU Open Source License, основанной на Apache 2.0 с дополнительными условиями. Условия кода и условия моделей уточняются отдельно. Устойчивый статус чистого Apache без проверки лицензий кода и моделей утверждать нельзя.
MinerU работает со сканами?
PDF и изображения поддерживают все четыре уровня разбора. Flash имеет отдельные сценарии для нативного текста и для OCR. Выбор уровня зависит от качества скана и требуемой точности.
Можно ли запустить MinerU на CPU?
Basic может работать на CPU, а нативный разбор текста не требует inference-моделей. Для Standard и Advanced требования зависят от VLM-движка, размера входа и параллельности. Ресурсы проверяют для конкретного сочетания tier и backend.
Чем MiddleJson отличается от StructuredContent?
MiddleJson — промежуточный протокол с упорядоченными постобработанными страницами и семантическими блоками. StructuredContent — потребительское представление, которое возвращает structured_content(). Ответ mineru parse --json относится к ответам команды и в ParseResult.from_dict() напрямую не передаётся.
Нужно ли подключать RAG сразу?
RAG подключают после проверки структуры. Сначала убеждаются, что заголовки, порядок абзацев, таблицы и локаторы соответствуют исходнику. Ошибка извлечения может исказить найденный контекст; проверка до индексации помогает обнаружить её раньше оценки ответов.
