Главная Программы Офис и продуктивность Средства конвертации документов MinerU: инструкция от гика, локальный парсер документов, OCR, таблицы, формулы и API

MinerU: инструкция от гика, локальный парсер документов, OCR, таблицы, формулы и API

MinerU — открытый инструмент OpenDataLab для преобразования документов в структурированные данные. Его основная задача не редактирование PDF, а извлечение содержимого с сохранением логики документа: заголовков, абзацев, списков, таблиц, формул, изображений и порядка чтения. Локальная версия принимает PDF, изображения, DOCX, PPTX и XLSX и формирует Markdown, JSON и служебные результаты для контроля качества. Это делает MinerU подходящим прежде всего для подготовки данных для поиска, RAG-систем, языковых моделей, архивов и автоматической обработки, а не для ручной правки страниц.

Что такое MinerU и какой продукт рассматривается

Название MinerU относится к экосистеме OpenDataLab, в которой есть открытый Python-пакет, локальные командные инструменты, FastAPI-сервис, Gradio WebUI, официальный веб-сервис и отдельный настольный клиент. В этом обзоре основным продуктом считается открытая поставка MinerU из репозитория opendatalab/MinerU и PyPI. Облачная версия и настольный клиент рассматриваются отдельно, чтобы не смешивать их ограничения с возможностями локального пакета.

По состоянию на 4 сентября 2026 года актуальный стабильный выпуск на PyPI — MinerU 3.4.5 от 14 августа 2026 года. На той же площадке опубликована предварительная ветка 4.0.0a6, помеченная как pre-release. Поэтому функции, команды и требования ниже относятся к стабильной серии 3.4.x, если прямо не сказано обратное.

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

Основные параметры

Параметр	Актуальное состояние
Разработчик и проект	OpenDataLab, репозиторий opendatalab/MinerU
Тип	Открытый парсер документов с CLI, FastAPI и Gradio WebUI; отдельно доступны веб-сервис и настольный клиент
Стабильная версия	3.4.5, опубликована 14 августа 2026 года
Локальные платформы	Linux, Windows и macOS; Docker поддерживается на Linux и Windows через WSL2
Python	3.10–3.13; в Windows из-за зависимости ray поддерживаются 3.10–3.12
Вход локальной версии	PDF, изображения, DOCX, PPTX, XLSX; один файл или каталог
Основной выход	Markdown, content_list JSON, middle JSON и визуальные файлы контроля; точный набор зависит от backend и типа документа
OCR	Автоматическое определение сканов и повреждённого текстового слоя; OCR распознаёт 109 языков
Таблицы и формулы	Таблицы преобразуются в HTML-представление, формулы — в LaTeX
Вычисления	Pipeline работает на CPU; локальные VLM/Hybrid engine требуют более производительного оборудования; доступны CUDA, NPU и MPS
Лицензия	MinerU Open Source License на основе Apache License 2.0 с дополнительными условиями
Интерфейс Gradio	Встроенные локализации на английский и китайский; русской локализации в исходном WebUI нет

Главное различие между вариантами поставки связано не с форматом проекта, а с местом выполнения. Локальный пакет можно развернуть на своей машине или сервере. WebUI остаётся оболочкой над тем же локальным сервисом. Официальная веб-версия переносит обработку на инфраструктуру MinerU и требует входа в аккаунт, а упрощённая публичная Gradio-демонстрация предоставляет только базовый разбор без регистрации.

Платформы, варианты поставки и актуальный статус

Локальный Python-пакет

Основная открытая поставка устанавливается из PyPI либо из исходного кода. Она совместима с Linux, Windows и macOS. В Linux поддерживаемый диапазон начинается с дистрибутивов 2019 года и новее. Для macOS требуется версия 14.0 или новее. В Windows поддержка Python 3.13 ограничена зависимостью ray, поэтому рабочий диапазон там — Python 3.10–3.12.

Локальная установка включает несколько режимов разбора. Pipeline рассчитан на совместимость и допускает работу только на процессоре. Локальные engine-варианты VLM и Hybrid рассчитаны на GPU либо Apple Silicon и требуют существенно больше видеопамяти. Отдельные http-client варианты позволяют вынести крупную модель на OpenAI-совместимый сервер, оставив клиентскую часть на менее мощной машине.

Gradio WebUI и FastAPI

В пакет включены команды mineru-gradio и mineru-api. Первая поднимает браузерный интерфейс для загрузки документа и просмотра результата, вторая — HTTP-сервис для автоматизации. CLI mineru в современной архитектуре сам является клиентом mineru-api: без явно заданного адреса он запускает временный локальный API, а с параметром —api-url подключается к уже работающему сервису.

Официальный веб-сервис и настольный клиент

Официальная веб-версия работает без локальной установки, но требует входа в аккаунт. Настольный клиент предлагается для Windows, Apple silicon и Intel chip. Linux-сборка настольного клиента не перечислена; открытый Python-пакет при этом поддерживает Linux.

Состояние разработки

Проект активно обновляется. Стабильная серия 3.4 продолжает линию 3.x, в которой архитектура стала сервисно-ориентированной, появились native-парсеры офисных форматов, Hybrid backend, новые структурированные выходы и обновления OCR. Одновременно публикуются альфа-сборки 4.0.0a, поэтому для производственной интеграции разумно отделять стабильный 3.4.x от предварительной ветки и не строить обработчик вокруг поведения alpha-релизов.

Интерфейс и рабочие зоны

Gradio WebUI

Локальный WebUI построен на Gradio и группирует управление исходником, режимом распознавания и результатом в одном браузерном окне. В исходном интерфейсе используются англоязычные подписи Select or paste a file to upload, Max convert pages, Backend, Recognition Options и Advanced options. Для обработки предусмотрены кнопки Convert и Clear. Отдельные области показывают Document preview и Conversion Status.

После обработки интерфейс выводит несколько представлений одного результата: Result file для итогового архива или файла, Markdown rendering для визуального просмотра разметки, Markdown text для исходного текста разметки и JSON Content List для структурированного представления. Такой набор полезнее обычного окна OCR: пользователь видит не только итоговый текст, но и структуру, которую затем сможет читать программа.

Панель параметров распознавания

Backend выбирает архитектуру обработки. В актуальном интерфейсе встречаются Hybrid, Pipeline, VLM и удалённые варианты. Для Hybrid есть параметр Hybrid effort со значениями Medium и High. Medium ориентирован на меньшие затраты времени, High — на более точную обработку и более тяжёлый вычислительный режим. Важное ограничение: при Hybrid Medium анализ изображений и диаграмм автоматически отключается.

Recognition Options объединяет распознавание таблиц, формул, OCR и анализ графического содержимого. Переключатель Enable table recognition отвечает за структурный разбор таблиц; при отключении таблицы сохраняются как изображения. Формульный переключатель меняет смысл в зависимости от backend. OCR Language влияет на распознавание сканов, а Force enable OCR предназначен для документов, где автоматический выбор дал плохой результат.

CLI

Командный интерфейс предназначен для повторяемых обработок и каталогов. Основные параметры — -p или —path для входного файла либо каталога, -o или —output для каталога результата, -b или —backend для режима, -m или —method для auto, txt или ocr, —effort для Hybrid, -s и -e для диапазона страниц, -f и -t для формул и таблиц, —image-analysis для графики. Такой интерфейс удобен там, где документы поступают регулярно и ручная загрузка через браузер становится лишней операцией.

FastAPI

mineru-api превращает обработчик в локальный сервис. По умолчанию он слушает 127.0.0.1:8000. Автоматическая документация FastAPI включена по умолчанию и может быть отключена настройкой MINERU_API_ENABLE_FASTAPI_DOCS. Сервис подходит для интеграции с внутренними приложениями, очередями и веб-интерфейсами, но состояние задач хранится в процессе и не должно считаться долговременным хранилищем очереди.

Основные функции MinerU

Разбор структуры страницы и порядок чтения

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

OCR сканов и документов с плохим текстовым слоем

Программа определяет сканированные PDF и файлы с некорректным текстовым слоем и может задействовать OCR. OCR поддерживает распознавание 109 языков. В CLI режим auto выбирает способ автоматически, а режим ocr принудительно переводит совместимые backend в оптическое распознавание. Для Pipeline можно задавать языковую группу, что уменьшает неоднозначность при распознавании.

Таблицы

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

Математические формулы

Формулы преобразуются в LaTeX. Для научных статей это принципиальное отличие от обычного извлечения текста, где символы формулы часто превращаются в нечитаемую строку. Pipeline, VLM и Hybrid управляют формульным распознаванием немного по-разному: WebUI меняет подпись переключателя в зависимости от выбранного backend, а CLI предоставляет общий параметр включения формул.

Изображения и диаграммы

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

Структурированный JSON

Помимо Markdown программа создаёт машинно-читаемые представления. content_list.json содержит последовательность блоков в порядке чтения. content_list_v2.json, появившийся в 3.0, группирует данные по страницам и использует унифицированную структуру type + content, но официально помечен как development version, subject to change. middle.json хранит более подробные промежуточные данные и сведения о backend и версии.

Визуальный контроль качества

Файл с суффиксом _layout.pdf показывает распознанные области страницы, типы блоков и номер чтения. Это позволяет быстро определить, где ошибка относится к геометрии страницы, а не к самому OCR. Для Pipeline дополнительно создаётся _span.pdf с разметкой текстовых span, полезной при пропущенном тексте, проблемах сегментации и проверке строчных формул.

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

Путь -p принимает не только один файл, но и каталог. Это делает CLI пригодным для коллекций документов. В 3.x также развивалась сервисная архитектура и многопоточная обработка; фактическую пропускную способность определяют backend, разрешение страниц, количество OCR-страниц, доступная память и вычислитель, поэтому универсального времени на страницу у проекта нет.

Карта форматов и совместимости

Исходник	Локальная поддержка	Что извлекается	Основной переносимый результат	Что требует проверки
PDF с текстовым слоем	Да	Текст, структура, таблицы, формулы, изображения	Markdown и JSON	Порядок колонок, сложные таблицы, формулы
Сканированный PDF	Да	OCR-текст и структура страницы	Markdown и JSON	Язык OCR, качество скана, мелкий текст
Изображение	Да	OCR, области, таблицы и формулы при подходящем backend	Markdown и JSON	Ориентация, разрешение, фон и контраст
DOCX	Да	Содержимое и структура офисного документа	Markdown и JSON	Сложные плавающие объекты и нестандартная верстка
PPTX	Да	Содержимое слайдов и структурные элементы	Markdown и JSON	Слои, декоративные объекты, смысловая последовательность
XLSX	Да	Табличное содержимое	Структурированный результат MinerU	Сложные книги, формулы ячеек и оформление не следует считать полностью переносимыми

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

Облачный Precision Extract API принимает более широкий набор, включая старые DOC, PPT и XLS, а также изображения разных расширений. Эти возможности нельзя автоматически переносить на локальную CLI-поставку: для локального входа поддерживаются PDF, изображения, DOCX, PPTX и XLSX.

Задача → инструмент → результат → что проверить

Задача	Инструмент MinerU	Результат	Контроль
Подготовить научный PDF для LLM	Hybrid или VLM с распознаванием формул	Markdown, LaTeX-формулы, JSON	Порядок чтения, формулы, ссылки на рисунки
Оцифровать скан	OCR и подходящая языковая настройка	Распознанный Markdown и структурированные блоки	Пропуски, похожие символы, номера и таблицы
Разобрать таблицы	Table recognition	HTML-представление таблиц в результате	Границы ячеек, объединения, заголовки
Подготовить корпус для RAG	CLI по каталогу и content_list JSON	Набор документов с упорядоченными блоками	Стабильность схемы и соответствие страниц
Встроить разбор во внутренний сервис	mineru-api	Локальный HTTP-интерфейс обработки	Очередь, тайм-ауты, хранение результатов вне процесса
Понять причину ошибки распознавания	_layout.pdf и для Pipeline _span.pdf	Визуальная карта распознанных блоков	Номер чтения, тип блока, границы span

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

Требования, производительность и зависимость от оборудования

Для локального развёртывания требуется минимум 16 ГБ оперативной памяти; для полноценных локальных режимов рекомендовано 32 ГБ и более. Для Pipeline минимальная видеопамять при GPU-ускорении составляет 4 ГБ, но этот backend также работает на CPU. Локальные VLM/Hybrid engine не поддерживают режим только на CPU и требуют не менее 8 ГБ VRAM. Клиентские http-client режимы рассчитаны на подключение к OpenAI-совместимому серверу и снимают с клиентской машины основную нагрузку большой модели.

Для полной локальной установки требуется около 20 ГБ дискового пространства; предпочтителен SSD. Это связано не с размером самого wheel-файла, который заметно меньше, а с зависимостями и моделями. Первый запуск или смена моделей может зависеть от доступа к хранилищу моделей. После наличия необходимых файлов локальный Pipeline и локальный engine не требуют отправки документа в облачный MinerU API.

Производительность нельзя описать одной цифрой. OCR тяжелее прямого извлечения текста; High у Hybrid требует больше вычислений, чем Medium; анализ диаграмм добавляет работу VLM; большие страницы и длинные документы увеличивают память и время. В CLI есть параметры диапазона страниц, а в WebUI — Max convert pages, поэтому для диагностики удобно ограничивать вход небольшим фрагментом документа, не меняя сам исходник.

В Windows наличие NVIDIA-видеокарты ещё не гарантирует CUDA-ускорение. Документация отдельно предупреждает, что после обычной установки может потребоваться совместимая сборка torch и torchvision с CUDA. На Apple Silicon доступно MPS-ускорение. Для Linux и серверных установок выбор конкретного engine зависит от поддерживаемого оборудования и установленных расширений.

Интернет, приватность и безопасность

Локальная обработка даёт принципиально другой контур данных, чем официальный веб-сервис. При локальном Pipeline или локальном VLM/Hybrid engine исходный документ обрабатывается на собственной машине или сервере. Интернет нужен для установки пакетов и получения моделей, пока они не находятся в локальном кеше. При http-client документ и промежуточные данные передаются на настроенный пользователем сервер модели, поэтому приватность определяется уже архитектурой этого сервера.

Официальный веб-сервис и Precision Extract API предполагают передачу файла или доступной по URL копии в инфраструктуру MinerU. В API выдаются ссылки на загрузку и результаты через CDN. Для документов с персональными, коммерческими или договорными данными это означает необходимость сверить облачный сценарий с правилами организации до загрузки. Локальная поставка остаётся предпочтительнее там, где документ не должен покидать контролируемый контур.

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

Лицензирование, цена и ограничения поставок

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

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

Официальный облачный API — отдельная услуга со своими лимитами. Precision Extract использует Bearer Token, допускает файлы до 200 МБ и публикует дневной объём в 1000 страниц с высшим приоритетом, после которого приоритет обработки снижается. Agent Lightweight API работает без входа и Token, ограничивается по IP, принимает файл до 10 МБ и до 20 страниц и возвращает только Markdown; в этом режиме таблицы и формулы для PDF и изображений отключены. Денежные тарифы в обзор не включены, потому что они не нужны для описания лицензии локального продукта и не являются стабильным параметром открытой поставки.

Что перестанет работать первым

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

При недоступности внешнего inference-сервера. Варианты vlm-http-client и hybrid-http-client зависят от OpenAI-совместимого сервера, заданного для backend. Клиент MinerU продолжит запускаться, но модельная часть обработки не выполнится до восстановления сервера или переключения на локальный backend.

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

При нехватке VRAM. Локальные VLM/Hybrid engine требуют не менее 8 ГБ видеопамяти по официальной матрице. При дефиците ресурсов практическим резервным режимом остаётся Pipeline или http-client с вынесенной моделью.

При отключении аккаунта или Token. Это относится к официальному веб-сервису и Precision Extract API, а не к локальному пакету. Веб-приложение требует входа, Precision API — Token. Agent Lightweight API, напротив, не требует регистрации, но имеет более жёсткие ограничения и IP rate limiting.

Как пользоваться программой — советы гика

Установка стабильной локальной версии

Цель. Получить локальный MinerU 3.4.x с полным набором основных backend. Подготовка. Нужен Python 3.10–3.13, а в Windows — 3.10–3.12; при полном локальном развёртывании ориентируйтесь минимум на 16 ГБ RAM и около 20 ГБ диска. В Linux общую логику установки пакетов можно сверить с материалом про установку приложений в Linux.

Откройте терминал в созданном для MinerU виртуальном окружении Python.
Обновите pip командой pip install —upgrade pip.
Установите uv командой pip install uv.
Установите пакет командой uv pip install -U «mineru[all]».
Проверьте доступность командой mineru —version и затем mineru —help.

Проверка результата. mineru —help должен вывести параметры -p, -o, -b, -m и другие актуальные опции. Типичная ошибка. Команда не находится после установки из-за другого виртуального окружения или PATH. Безопасный откат. Не удаляйте системный Python; деактивируйте неудачное окружение и создайте новое с поддерживаемой версией Python.

Запуск локального Gradio WebUI

Цель. Работать через браузер без написания собственного интерфейса. Подготовка. MinerU уже установлен, локальный backend соответствует ресурсам машины.

Запустите mineru-gradio —server-name 127.0.0.1 —server-port 7860.
Откройте в браузере локальный адрес 127.0.0.1:7860.
Убедитесь, что отображается заголовок MinerU 3: Document Extraction Demo и область Select or paste a file to upload.
Для машины без подходящего GPU выберите Pipeline, а не локальный VLM или Hybrid engine.

Важные параметры. —api-url подключает WebUI к уже работающему mineru-api; без него WebUI поднимает повторно используемый локальный сервис. —max-convert-pages задаёт ограничение числа обрабатываемых PDF-страниц. Проверка. В окне должны быть Document preview, Conversion Status и области результата. Типичная ошибка. Порт 7860 занят другим приложением. Безопасный откат. Завершите только процесс MinerU и перезапустите WebUI на другом свободном порту; исходные документы при этом не изменяются.

Разбор обычного PDF через WebUI

Цель. Получить Markdown и структурированный JSON из PDF с нормальным текстовым слоем. Подготовка. Для первого документа используйте небольшой PDF, где известен правильный порядок чтения.

В области Select or paste a file to upload выберите PDF.
В Backend оставьте Hybrid для рекомендуемого современного режима либо выберите Pipeline при работе только на CPU.
Для обычного текстового PDF не включайте Force enable OCR.
Оставьте Enable table recognition и распознавание формул включёнными, когда эти элементы присутствуют в документе.
Нажмите Convert.
Дождитесь статуса Completed в Conversion Status.
Сравните Document preview с Markdown rendering, затем откройте Markdown text и JSON Content List.

Проверка результата. Заголовки и абзацы должны идти в смысловом порядке, а таблицы не должны превращаться в случайный поток ячеек. Типичная ошибка. Принудительный OCR включён для качественного цифрового PDF и ухудшает чистый текст. Безопасный откат. Нажмите Clear, загрузите тот же исходник заново и повторите обработку без Force enable OCR; исходный PDF не меняется.

Выбор Pipeline, Hybrid и VLM

Цель. Соотнести точность и ресурсы с содержимым документа. Подготовка. Определите, есть ли GPU с достаточной VRAM и важны ли диаграммы, сложная верстка и формулы.

Для CPU-машины выберите Pipeline.
Для локальной машины с подходящим GPU выберите Hybrid либо VLM.
В Hybrid установите Hybrid effort: Medium для более лёгкого режима или High для максимального качества и анализа графики.
При удалённой модели используйте Remote VLM или Remote Hybrid и заполните Server URL адресом OpenAI-совместимого сервера.
Обработайте контрольный документ и сравните структуру, а не только визуально похожие строки текста.

Проверка результата. _layout.pdf должен подтверждать правильные границы и порядок блоков. Типичная ошибка. Ожидание анализа изображений в Hybrid Medium, хотя этот режим автоматически отключает image/chart analysis. Безопасный откат. Переключитесь на High либо отключите требования к анализу графики; исходные файлы и уже созданные результаты сохраняются отдельно.

OCR сканированного документа

Цель. Извлечь текст из PDF-скана или изображения. Подготовка. Определите язык документа и убедитесь, что страницы ориентированы правильно.

Загрузите скан в WebUI.
Выберите OCR Language, соответствующий документу; для Pipeline язык особенно важен.
Сначала оставьте автоматическое определение OCR и нажмите Convert.
При явно плохом результате включите Force enable OCR.
Повторите Convert и сравните распознанные абзацы, числа и таблицы с Document preview.

Важные параметры. В CLI аналогичная принудительная обработка задаётся -m ocr; режим -m auto остаётся безопасной исходной настройкой для смешанных документов. Проверка. Контролируйте имена, числовые значения и похожие символы, а не только общий объём текста. Типичная ошибка. Неправильно выбранная языковая группа снижает качество. Безопасный откат. Верните auto и правильный OCR Language, не переписывая предыдущий каталог результата.

Распознавание таблиц, формул и диаграмм

Цель. Сохранить нетекстовые элементы как структурные данные. Подготовка. Выберите документ, где есть известная таблица, формула и график.

Откройте Recognition Options или Advanced options.
Включите Enable table recognition для таблиц.
Оставьте формульный переключатель включённым; его подпись зависит от backend.
Для анализа изображения или диаграммы включите Enable image analysis.
При Hybrid выберите High, поскольку Medium отключает анализ изображений и диаграмм.
Запустите Convert.
Сверьте формулы в Markdown text, таблицы в результате и графические блоки в JSON Content List.

Проверка. Формула должна иметь LaTeX-представление, таблица — структурированное HTML-представление, а связанный графический блок — корректное место в порядке чтения. Типичная ошибка. Выключенный table recognition оставляет таблицу изображением. Безопасный откат. Повторите обработку с включённым распознаванием; исходный документ не модифицируется.

Пакетная обработка каталога через CLI

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

Для CPU-режима выполните mineru -p ./input -o ./output -b pipeline.
Для современной локальной конфигурации с достаточным GPU используйте подходящий Hybrid backend и при необходимости —effort high.
Не используйте каталог исходников как каталог результата.
После завершения проверьте наличие отдельных результатов для нескольких входных файлов.
Откройте по одному документу каждого типа и сравните его Markdown и JSON с оригиналом.

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

Запуск локального FastAPI для интеграции

Цель. Предоставить MinerU внутреннему приложению как сервис. Подготовка. Сначала убедитесь, что выбранный backend работает локально через CLI.

Запустите mineru-api —host 127.0.0.1 —port 8000.
Откройте 127.0.0.1:8000/docs и убедитесь, что FastAPI-документация доступна.
Для ручной CLI-проверки выполните mineru -p document.pdf -o ./output —api-url http://127.0.0.1:8000.
После успешного результата подключайте собственное приложение к тому же API.
Храните состояние задания и связь с исходным документом во внешнем приложении, а не только в памяти mineru-api.

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

Проверка результата по layout, span, Markdown и JSON

Цель. Отделить ошибку сегментации страницы от ошибки OCR или структурного экспорта. Подготовка. Сохраните исходник и полный каталог результата.

Откройте файл с суффиксом _layout.pdf.
Проверьте номера порядка чтения и границы блоков вокруг колонок, таблиц, подписей и формул.
При Pipeline откройте также _span.pdf и найдите область с потерянным текстом.
Сопоставьте эту область с Markdown text.
Затем найдите тот же фрагмент в content_list.json.
Для программной интеграции дополнительно проверяйте _backend и _version_name в middle.json.

Проверка. Причина должна локализоваться: неверная геометрия видна в layout, проблема span — в pipeline-визуализации, потеря при сериализации — в расхождении JSON и Markdown. Типичная ошибка. Использование content_list_v2 как неизменяемого контракта, хотя он помечен как development version. Безопасный откат. Сохраняйте совместимый парсер для стабильного content_list.json и обновляйте обработчик v2 только после проверки схемы новой версии.

Сквозной сценарий: PDF в проверенный Markdown и JSON

Цель. Получить воспроизводимый набор данных для RAG или архива. Подготовка. Возьмите PDF на 5–20 страниц с заголовками, одной таблицей и хотя бы одним рисунком; создайте отдельный каталог source и отдельный каталог result.

Зафиксируйте стабильную версию MinerU и убедитесь, что mineru —version показывает ожидаемую 3.4.x.
Оцените ресурсы: при CPU выберите Pipeline, при подходящем GPU — Hybrid.
Обработайте документ командой mineru -p ./source/document.pdf -o ./result -b pipeline либо соответствующим Hybrid backend.
Откройте _layout.pdf и проверьте порядок колонок, заголовков, таблицы и подписи рисунка.
Сравните Markdown с исходником по нескольким контрольным местам: начало раздела, таблица, формула или числовой фрагмент.
Откройте content_list.json и убедитесь, что эти же блоки идут в правильном порядке.
Сохраните исходный PDF, Markdown, JSON и визуальные файлы контроля как один набор артефактов.
Перед загрузкой в RAG удалите из дальнейшего конвейера только те вспомогательные файлы, которые действительно не нужны; исходник и проверенный JSON оставьте для аудита.

Проверка результата. Входной PDF остаётся неизменным, Markdown пригоден для чтения, JSON пригоден для автоматической обработки, а layout подтверждает порядок блоков. Типичная ошибка. В систему индексации отправляется Markdown без проверки, и ошибка порядка колонок обнаруживается уже в ответах модели. Безопасный откат. Исключите проблемный документ из индекса, повторите разбор с другим backend или параметрами и замените только его производные файлы.

Плюсы

Локальная обработка PDF, изображений, DOCX, PPTX и XLSX без обязательной отправки исходника в официальный облачный сервис.
Один конвейер объединяет распознавание макета, OCR, таблицы, формулы, изображения и порядок чтения.
Результат не ограничивается Markdown: доступны content_list JSON, middle JSON и визуальные файлы для отладки.
Pipeline позволяет работать только на CPU, поэтому базовый сценарий не требует дискретной видеокарты.
VLM, Hybrid и http-client режимы позволяют масштабировать качество и вычислительную архитектуру от рабочей станции до отдельного inference-сервера.
CLI принимает каталог, а FastAPI делает MinerU пригодным для автоматизации и внутренней интеграции.
Формулы преобразуются в LaTeX, а таблицы — в HTML-представление, что полезно для научных и технических документов.
_layout.pdf и _span.pdf дают диагностическую информацию, которой нет у многих простых конвертеров PDF в текст.

Минусы

Локальные VLM/Hybrid engine требуют не менее 8 ГБ VRAM и не рассчитаны на чистый CPU-режим.
Полная установка заметно тяжелее обычной библиотеки извлечения текста: требуется минимум 16 ГБ RAM и около 20 ГБ диска.
Gradio WebUI имеет встроенные английскую и китайскую локализации, но не русскую.
MinerU извлекает структуру, а не восстанавливает полностью редактируемый исходный макет PDF.
content_list_v2 пока помечен как развивающийся формат, поэтому его схема не подходит для интеграции, которая требует неизменяемого контракта без версии.
Структурированные результаты VLM после изменений 2.5 не совместимы напрямую со старой схемой Pipeline, что нужно учитывать в собственных обработчиках.
Встроенное состояние задач mineru-api не является постоянной очередью и теряется при перезапуске процесса.
Качество на сложной верстке, сканах и рукописном содержимом не гарантируется; проект прямо рекомендует оценивать подходящий режим на собственных документах.

Кому подойдёт

Разработчикам RAG и поисковых систем. Markdown и JSON дают два удобных уровня представления, а порядок чтения помогает готовить фрагменты для индексации.
Исследователям и инженерам. Распознавание формул в LaTeX и таблиц в структуру полезно для научных PDF, отчётов и документации.
Организациям с закрытым контуром. Локальный Pipeline или локальный engine позволяют не передавать документы официальному облачному сервису.
Командам, которые обрабатывают каталоги документов. CLI и FastAPI позволяют уйти от ручной загрузки по одному файлу.
Пользователям, которым важен аудит результата. layout, span и промежуточный JSON дают больше информации для диагностики, чем один итоговый текст.

Кому не подойдёт

Тем, кому нужен PDF-редактор. MinerU не заменяет инструменты правки, подписи, аннотирования и точного сохранения исходной верстки.
Пользователям слабого ПК, которым нужен максимальный VLM/Hybrid режим. Для него требуется подходящий GPU; на CPU остаётся Pipeline.
Тем, кому нужен русский графический интерфейс. Встроенный Gradio предлагает английский и китайский языки.
Интеграциям с абсолютно фиксированной схемой нового content_list_v2. Этот формат официально остаётся development version.
Разовым пользователям, которым нужен только обычный текст из простого PDF. Лёгкая библиотека или встроенное копирование текста могут потребовать меньше установки и ресурсов.

Сравнение с другими аналогами

Критерий	MinerU	Docling	Unstructured	PyMuPDF4LLM
Основная задача	Глубокий разбор документов для Markdown, JSON, RAG и LLM	Унифицированное преобразование большого числа типов документов в DoclingDocument	Разбиение документов на элементы для data/AI-конвейеров	Лёгкое извлечение PDF в Markdown, JSON и текст
Платформа	Python, Linux/Windows/macOS; WebUI и API	Python, CLI и сервисное развёртывание	Python-библиотека и серверные/облачные варианты	Python на базе PyMuPDF
Входные форматы	Локально PDF, изображения, DOCX, PPTX, XLSX	PDF, Office, OpenDocument, HTML, Markdown, изображения, EPUB, email, аудио/видео и другие	Широкий набор документов и изображений, ориентированный на partition-процесс	Главным образом PDF; Office расширяется через PyMuPDF Pro
Выход	Markdown, несколько JSON-представлений, визуальная диагностика	Markdown, HTML, JSON, DocLang, текст, LaTeX и другие представления	Нормализованные элементы для дальнейшей обработки	Markdown, JSON, TXT
Автоматизация	CLI по каталогам, FastAPI, http-client backends	CLI, Python API, пакетная конвертация, docling-serve	Python API и конвейеры partition	Компактный Python API и интеграции LlamaIndex/LangChain
Порог освоения	Средний или высокий из-за backend и моделей	Средний	Средний, особенно при настройке стратегий PDF	Низкий для PDF
Модель распространения	Open-source license с дополнительными коммерческими условиями; отдельный облачный сервис	Открытый проект	Открытая библиотека плюс коммерческие облачные сервисы	Локальная библиотека; Office через PyMuPDF Pro
Главное ограничение	Ресурсоёмкие engine-режимы и изменяемая схема некоторых структурированных выходов	Более широкая архитектура может быть избыточной для узкого PDF-сценария	Фокус на элементах и data pipeline, а не на визуальной проверке MinerU-типа	Более узкий базовый набор входов и меньше собственной тяжёлой VLM-логики
Подходящий сценарий	Сложные PDF, формулы, таблицы, локальный RAG	Разнородный архив с множеством типов файлов	Подготовка элементов для ETL и AI-конвейера	Быстрый PDF → Markdown/JSON без GPU

Docling рациональнее там, где одна система должна принимать очень разные документы: кроме Office и PDF, он поддерживает OpenDocument, EPUB, HTML, электронную почту, ряд XML-форматов и даже аудио/видео с дополнительными зависимостями. MinerU выигрывает в сценарии, где внимание сосредоточено на сложной структуре страниц, формулах, таблицах, OCR и визуальной диагностике результата.

PyMuPDF4LLM проще для преимущественно PDF-потока. Он формирует Markdown, JSON и TXT, умеет анализировать layout и автоматически подключать OCR на страницах без нормального текста, причём не требует GPU. Office-файлы в нём относятся к расширению через PyMuPDF Pro. Это делает его хорошей альтернативой MinerU, когда важнее лёгкость установки и PDF, чем VLM/Hybrid и разбор офисных файлов из коробки.

Unstructured разумнее рассматривать как компонент data-конвейера: его модель работы строится вокруг partition и нормализованных элементов. MinerU на этом фоне предоставляет более выраженный путь контроля документа через Markdown, content list, middle JSON и PDF-визуализации. Выбор зависит от того, нужен ли прежде всего унифицированный ETL-слой или подробный парсер документа с диагностикой структуры.

Типичные проблемы и диагностика

MinerU не устанавливается на выбранной версии Python

Симптом: менеджер пакетов сообщает о несовместимой версии Python или зависимостей. Причина: стабильный MinerU рассчитан на Python 3.10–3.13, а Windows из-за ray — на 3.10–3.12. Диагностика: проверьте python —version внутри активного окружения, а не системную версию в другом терминале. Исправление: создайте отдельное окружение с поддерживаемой версией. Проверка: mineru —version и mineru —help завершаются без ошибки.

Команда mineru не находится после установки

Симптом: оболочка сообщает, что mineru не является командой. Причина: пакет установлен в другом виртуальном окружении либо каталог скриптов отсутствует в PATH. Диагностика: сравните путь активного python и путь, куда установился пакет. Исправление: активируйте правильное окружение или повторите установку в текущее. Проверка: mineru —version выводит номер стабильной ветки.

Первый запуск долго ждёт модель или не может её получить

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

NVIDIA GPU в Windows не ускоряет обработку

Симптом: MinerU работает на CPU, хотя в компьютере есть совместимая видеокарта. Причина: установлена CPU-сборка torch/torchvision или несовместимая CUDA-среда. Диагностика: проверьте доступность CUDA в используемом Python-окружении. Исправление: установите совместимые CUDA-сборки torch и torchvision для используемой версии драйвера. Проверка: после перезапуска backend обнаруживает GPU и загрузка модели проходит без перехода на CPU.

VLM или Hybrid завершается из-за нехватки видеопамяти

Симптом: engine не стартует либо обработка завершается ошибкой памяти. Причина: локальные VLM/Hybrid engine требуют минимум 8 ГБ VRAM, а параллельные процессы дополнительно занимают память. Диагностика: сравните доступную VRAM с матрицей требований и завершите посторонние GPU-процессы. Исправление: переключитесь на Pipeline, используйте http-client с удалённым сервером либо освободите достаточный объём VRAM. Проверка: контрольный документ обрабатывается полностью без OOM.

Скан распознаётся хуже ожидаемого

Симптом: в тексте много замен символов, потерянных слов и неверных чисел. Причина: автоматический режим неверно оценил страницу, выбран неподходящий язык OCR либо исходник низкого качества. Диагностика: сравните проблемную страницу в оригинале, _layout.pdf и распознанном Markdown; проверьте OCR Language. Исправление: задайте правильную языковую группу и примените принудительный OCR только к документу, где автоматический результат действительно плох. Проверка: повторно сверяйте имена, даты и числа на той же странице.

Таблица осталась картинкой

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

Диаграмма не получила текстового анализа

Симптом: графический блок присутствует, но содержательная интерпретация отсутствует. Причина: Enable image analysis выключен или Hybrid работает с effort Medium, который автоматически отключает анализ изображений и диаграмм. Диагностика: проверьте Backend, Hybrid effort и состояние image analysis. Исправление: для такого документа используйте High и включённый анализ. Проверка: JSON и мультимодальный Markdown содержат соответствующий графический блок с ожидаемыми данными.

Интеграция ломается после смены backend или версии

Симптом: собственный парсер JSON перестаёт находить поля или типы блоков. Причина: VLM-структура после 2.5 имеет существенные отличия от Pipeline, а content_list_v2 официально остаётся развивающимся форматом. Диагностика: прочитайте _backend и _version_name в middle.json и сравните их с версией, на которой написана интеграция. Исправление: версионируйте собственную схему, поддерживайте разные backend явно и не считайте content_list_v2 неизменяемым. Проверка: тестовые документы каждого backend проходят автоматические проверки структуры.

После перезапуска API пропал статус задания

Симптом: ранее выданный task_id больше не отображает ожидаемое состояние. Причина: встроенный менеджер задач mineru-api хранит состояние в процессе; завершённые и неуспешные задачи также имеют ограниченный период хранения, по умолчанию 24 часа. Диагностика: установите факт рестарта, reload или истечения retention. Исправление: храните метаданные, исходник и связь с результатом во внешней системе и повторно запускайте задачу при потере процесса. Проверка: восстановление сервиса не уничтожает информацию о том, какой документ необходимо обработать повторно.

MinerU не может записать результат в Linux

Симптом: обработка стартует, но запись в output завершается Permission denied. Причина: пользователь процесса не имеет прав на выбранный каталог. Диагностика: проверьте владельца и разрешения каталога; общие принципы разобраны в материале о правах доступа Linux. Исправление: выберите каталог, доступный текущему пользователю, либо исправьте права только для нужного рабочего каталога. Проверка: MinerU создаёт результат без запуска от root и без расширения прав на посторонние каталоги.

FAQ

Можно ли обработать только часть PDF?

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

Для чего нужен параметр —client-side-output-generation?

Он включает формирование Markdown и content list на стороне клиента из middle JSON, изображений и исходных файлов, полученных от серверной части. Параметр полезен в разделённой архитектуре, где inference выполняется на другом сервере, а финальная сборка файлов должна оставаться на клиенте.

Можно ли изменить delimiters для LaTeX в Gradio?

Да. mineru-gradio принимает —latex-delimiters-type со значениями a, b и all. Вариант a использует долларовые delimiters, b — скобочные варианты, all включает оба типа для Markdown rendering.

Можно ли отключить страницу /docs у mineru-api?

Да. Переменная MINERU_API_ENABLE_FASTAPI_DOCS управляет автоматическими страницами FastAPI, включая /docs, /openapi.json и /redoc. По умолчанию они включены. В закрытом внутреннем контуре это удобно для разработки, а на постоянном сервисе их можно отключить вместе с обычным сетевым ограничением доступа.

Какие тайм-ауты есть у встроенного клиента API?

MINERU_TASK_RESULT_TIMEOUT_SECONDS по умолчанию равен 3600 секундам и ограничивает ожидание перехода задачи в конечное состояние. MINERU_TASK_RESULT_DOWNLOAD_TIMEOUT_SECONDS по умолчанию равен 600 секундам и задаёт тайм-аут чтения при подготовке и получении итогового ZIP; это не жёсткий предел общей длительности загрузки, пока сервер продолжает передавать данные.

Сколько параллельных обработок принимает mineru-api?

Переменная MINERU_API_MAX_CONCURRENT_REQUESTS управляет максимальным числом одновременных обработок; значение по умолчанию — 3. При тяжёлых локальных engine этот параметр связан с доступной VRAM и RAM, поэтому увеличение параллелизма без запаса памяти способно привести к ошибкам ресурсов.

Где MinerU хранит каталог результатов API?

Для mineru-api корень вывода задаётся переменной MINERU_API_OUTPUT_ROOT. Значение по умолчанию — каталог ./output относительно текущей рабочей директории. Для сервисной установки лучше задавать предсказуемый отдельный путь, права на который принадлежат пользователю процесса.

Можно ли изменить количество потоков рендера PDF?

Да. MINERU_PDF_RENDER_THREADS задаёт число параллельных workers рендера PDF в изображения; значение по умолчанию — 4. Отдельно MINERU_PDF_RENDER_TIMEOUT задаёт тайм-аут рендера и по умолчанию равен 300 секундам. Эти параметры действуют в Linux, macOS и Windows.

Зачем нужен MINERU_PROCESSING_WINDOW_SIZE?

Параметр управляет размером окна обработки длинных документов и влияет на баланс между использованием памяти и пропускной способностью. Значение по умолчанию — 64. Менять его стоит только после измерения нагрузки на собственных документах, поскольку увеличение окна повышает требования к памяти.

Чем локальный —api-url отличается от —url?

—api-url задаёт адрес MinerU FastAPI, к которому подключается CLI или WebUI. —url в современной архитектуре не является адресом MinerU API: он передаёт серверной стороне адрес OpenAI-совместимого backend для vlm-http-client или hybrid-http-client. Смешение этих двух параметров приводит к подключению не к тому уровню сервиса.

Вывод

MinerU имеет смысл выбирать не как универсальный PDF-инструмент, а как компонент извлечения структуры. Для цифровых и сканированных PDF с таблицами, формулами и многоколоночной версткой он даёт полноценный набор: Markdown для чтения, JSON для программной обработки и визуальные PDF для аудита. На слабой машине практичным режимом остаётся Pipeline; при достаточном GPU и сложном содержимом доступны Hybrid и VLM.

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

При разнородном архиве с EPUB, HTML, почтой, OpenDocument и медиа Docling предоставляет заметно более широкий спектр входов. При простом потоке PDF и требовании минимальной установки PyMuPDF4LLM проще. MinerU оправдывает более тяжёлую установку тогда, когда ценность дают именно сложная структура документа, OCR, формулы, таблицы, выбор backend и возможность проверить, почему тот или иной блок был распознан именно так.