MinerU: PDF в Markdown и JSON для RAG и ИИ-агентов

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

Результат можно сохранить в Markdown, получить через Python или передать в приложение по API. Markdown удобен для чтения: в нём видны заголовки, списки и таблицы. JSON нужен, когда программе важно знать тип блока, страницу и другие свойства содержимого. В MinerU 4 к преобразованию файлов добавлена локальная библиотека: она хранит результаты, помогает искать текст и читать длинные документы по частям.

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

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

Для офисного файла не нужно выбирать режим распознавания сложного PDF. Его содержимое разбирается напрямую через DocVortex, компонент обработки документов. В Python укажите tier="flash". Параметр выбора страниц относится к PDF: Word, таблица Excel или сохранённая веб-страница обрабатываются целиком.

mineru-kit parse report.docx -o report.md --tier flash
mineru-kit parse saved-page.mhtml -o saved-page.md --tier flash

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

Малые модели могут работать через ONNX или Torch. Для VLM используются llama.cpp, vLLM или LMDeploy. Это движки выполнения моделей: они определяют, как вычисления идут на процессоре или видеокарте. Пользователь выбирает качество обработки через Flash, Basic, Standard или Advanced, а движок настраивается отдельно.

Для обычного PDF с текстовым слоем можно начать с Flash. Если страницы отсканированы или в них сложные таблицы, понадобится OCR или модельный режим. Standard используется по умолчанию для PDF в mineru-kit parse и локальном Python SDK. Advanced включается явно и использует тот же набор моделей, что Standard.

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

MinerU 4 поддерживает Python 3.10–3.14. Для нового окружения подойдёт Python 3.12. Базовая установка включает WebUI, ONNX для малых моделей и llama.cpp для VLM. Дополнительные движки могут предъявлять свои требования к Python, драйверам и операционной системе.

python -m pip install uv
uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install -U "mineru>=4.0,<5"

В Windows PowerShell после создания окружения активируйте его командой .venv\Scripts\Activate.ps1, затем выполните ту же установку через uv pip. Если uv не используется, пакет можно установить командой python -m pip install -U "mineru>=4.0,<5" внутри активированного окружения.

mineru-kit parse document.pdf -o document.md --tier standard

Замените document.pdf на путь к своему файлу. При первом запуске модельного режима может начаться загрузка весов моделей. Для единственного Markdown-файла параметр -o указывает имя результата. При обработке папки он должен указывать каталог.

В MinerU 4 есть две команды с разными задачами. mineru-kit parse преобразует файлы напрямую и удобен для полного экспорта или пакетной обработки. mineru parse использует локальную библиотеку документов: сохраняет кеш и возвращает данные, с которыми агент может продолжить чтение.

mineru-kit parse ./documents -o ./output --format zip

По умолчанию mineru-kit parse берёт все страницы PDF, а mineru parse начинает с первых десяти. Для полного документа во втором случае добавьте --pages all. Чтобы обработать выбранные страницы, используйте номера с единицы и диапазоны: например, 1-5,8. Запись r1 обозначает последнюю страницу.

mineru parse document.pdf --pages all -o document.md
mineru parse document.pdf --pages "1-5,8" --json

OCR превращает изображение текста в символы. Он нужен для сканов, фотографий и PDF без текстового слоя. Если в таком файле выбрать Flash с ocr-mode txt, текст не появится: этот режим читает только уже существующие символы. Для сканов используйте ocr-mode ocr и подготовьте модели распознавания.

mineru-kit parse text.pdf -o text.md --tier flash --ocr-mode txt
mineru-kit parse scan.pdf -o scan.md --tier flash --ocr-mode ocr

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

MinerU распознаёт таблицы и формулы, а не только сплошной текст. Это помогает при работе с научными статьями, финансовыми отчётами и техническими инструкциями. На официальном сайте отдельно представлены обработка таблиц с объединёнными ячейками и переходами между страницами, а также преобразование математических формул в LaTeX и MathML.

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

В Basic используются малые модели для OCR, формул и таблиц. Standard добавляет VLM для сложной вёрстки. Для документов с математикой и несколькими колонками такой выбор особенно полезен: порядок блоков влияет на то, как ИИ прочитает объяснение и связанную с ним формулу.

Внутри используется единая модель документа. Через Python-рендерер доступны девять вариантов представления, включая HTML, LaTeX, Word, EPUB и PDF. У командной строки и API свой набор вариантов экспорта: возможность рендерера не означает, что такой же параметр есть у каждой команды.

Ответ mineru parse --json содержит служебные сведения команды и продолжение чтения. Для сохранения самого структурированного документа в Python используйте result.to_json(). В ZIP могут находиться текст и связанные изображения; их пути нужно сохранять вместе с документом.

Локальный SDK позволяет встроить обработку документов в существующее приложение. Функция parse возвращает ParseResult: из него можно получить Markdown и JSON. Этот интерфейс работает без создания библиотеки документов и по умолчанию выбирает все страницы PDF.

from pathlib import Path
from mineru.parser import parse

result = parse(
    "document.pdf",
    tier="flash",
    ocr_mode="txt",
    page_range="1-3",
)

Path("document.md").write_text(result.markdown(), encoding="utf-8")
Path("document.json").write_text(result.to_json(), encoding="utf-8")

Этот пример подходит для PDF со встроенным текстом. Для модельного разбора PDF выберите tier="standard" и загрузите нужные модели. Для Word используйте parse("report.docx", tier="flash") без выбора страниц. В асинхронном приложении доступна функция parse_async с теми же параметрами.

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

1. Преобразуйте документы в Markdown или структурированный JSON.
2. Сохраните имя исходного файла и доступные сведения о страницах и блоках.
3. Разделите содержимое по смыслу: заголовкам, разделам, абзацам. Таблицы сохраняйте с подписями.
4. Добавьте фрагменты в поисковый или векторный индекс своего приложения.
5. Передавайте найденные фрагменты языковой модели и показывайте пользователю ссылку на исходный документ.

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

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

mineru parse document.pdf --json
mineru search "условия поставки" --json

В результате ищите locator и next_request: адрес фрагмента и следующий запрос. Используйте возвращённый адрес в mineru read. Команда read читает готовый кеш; она не запускает новую обработку более высокого качества. Поэтому нужный режим разбора выбирается при подготовке документа.

Для работы через браузер запустите WebUI. Он даёт локальный интерфейс для загрузки документа и просмотра результата. Без параметра api-url интерфейс управляет собственным локальным API-сервером; с этим параметром подключается к уже работающему сервису.

mineru-kit webui --server-name 127.0.0.1 --server-port 7860

Откройте http://127.0.0.1:7860. Если обработку нужно подключить к другой программе, запустите отдельный API. Его описание OpenAPI доступно по адресу http://127.0.0.1:8000/docs. Сервис использует маршруты /v1/* для файлов, задач обработки и результатов.

mineru-kit api-server --host 127.0.0.1 --port 8000 --tier standard

from mineru.parser import MinerUApiParser

parser = MinerUApiParser(
    api_url="http://127.0.0.1:8000",
    tier="standard",
    include_images=True,
)
result = parser.parse("document.pdf", page_range="1-3")
print(result.markdown())

В api_url указывается корень сервиса без /v1. Когда API работает на другой машине, файл передаётся на эту машину для обработки. Для нескольких серверов или видеокарт доступен mineru-router: он объединяет сервисы за одним адресом и предоставляет тот же V1 API.

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

mineru-kit models download --tier standard --source huggingface
mineru-kit models verify --tier standard
mineru-kit models show
export MINERU_MODEL_SOURCE=local
mineru-kit parse document.pdf -o document.md --tier standard

Команда models show показывает выбранные движки и готовность моделей. models verify возвращает ошибку, если файлов не хватает. По умолчанию источник auto сначала проверяет Hugging Face и при его недоступности выбирает ModelScope. Настройки хранятся в config.yaml внутри каталога MINERU_HOME, обычно ~/.mineru.

В базовой установке малые модели работают на CPU через ONNX, а VLM использует llama.cpp. На Apple Silicon малые модели могут работать через Torch/MPS. На сервере Linux с ускорителем и дополнительными зависимостями доступны vLLM и LMDeploy. Выбор движка для малых моделей и для VLM независим, поэтому наличие видеокарты само по себе не означает, что все этапы обработки используют её.

Для NVIDIA есть Docker-сборка под Linux; в Windows она запускается через WSL2. На macOS для ускорения Apple Silicon используется прямая установка. Для крупного архива можно выделить отдельный сервер обработки и подключать приложения к его API, не устанавливая модели на каждый рабочий компьютер.

На mineru.net можно пользоваться онлайн-обработкой и скачать клиент. Сайт представляет работу с PDF, Word, PowerPoint, Excel, изображениями и веб-страницами, а также экспорт для Dify и Notion. Онлайн-сервис удобен, когда нужно получить результат без установки локальных моделей.

У официального сайта есть свой API с токеном, загрузкой файлов и пакетными задачами. Он отличается от локального V1 API MinerU 4: у него другие адреса и параметры запросов. Для интеграции с сайтом используйте его документацию; для собственного сервера используйте Python SDK или описание локального API.

MinerU распространяется по MinerU Open Source License: за основу взята Apache 2.0 с дополнительными условиями. Коммерческое использование разрешено без отдельной лицензии, пока компания вместе со связанными организациями не превышает один из порогов: 100 миллионов активных пользователей в месяц или 20 миллионов долларов совокупного месячного дохода. При превышении требуется отдельная коммерческая лицензия.

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

• Режим txt не заменяет OCR. Для PDF без текстового слоя нужно распознавание изображений.
• Полный документ и первые десять страниц выбираются по-разному в mineru и mineru-kit. Указывайте --pages all, если используете библиотечную команду и нужен весь PDF.
• Standard и Advanced требуют загрузки моделей. Их запуск и скорость зависят от выбранных движков и оборудования.
• Office, HTML и другие нативные форматы используют Flash. Для них не применяется выбор диапазона страниц PDF.
• Markdown удобен для чтения, но для обработки типов блоков и метаданных используйте структурированный результат.
• При подключении удалённого сервиса документы или их содержимое покидают локальную машину.

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

• MinerU на GitHub
• Официальный сайт MinerU
• Документация MinerU