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

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

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

Как устроен рабочий экран

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

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

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

Первое преобразование документа

Для первой проверки лучше взять PDF на пять–десять страниц с обычным текстом, одной таблицей и несколькими иллюстрациями. Такой файл позволяет сразу оценить три ключевых этапа: разметку страницы, извлечение текста и сохранение нетекстовых объектов. В поле количества страниц задают небольшой предел, язык оставляют в автоматическом режиме, а принудительный OCR не включают, если текст в исходнике выделяется мышью.

1. Добавьте документ в область загрузки и дождитесь появления имени файла.
2. Проверьте предел страниц: он защищает от случайной обработки огромного отчёта.
3. Оставьте автоматический язык либо выберите основной язык скана.
4. Включите распознавание формул и таблиц, если эти элементы важны для результата.
5. Запустите преобразование и следите за журналом, не закрывая процесс до создания архива.
6. Сравните предпросмотр страницы с отрисованным Markdown, затем скачайте полный результат.

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

Какие файлы можно подавать на вход

MinerU принимает PDF, растровые изображения и распространённые офисные документы. Для изображений подходят PNG и JPEG; многостраничный материал разумнее предварительно собрать в PDF, чтобы сохранить порядок страниц и единый набор параметров. Документы DOCX, PPTX и XLSX проходят предварительное преобразование, поэтому их результат следует проверять внимательнее: сложные диаграммы, плавающие объекты, заметки докладчика и нестандартные форматы ячеек могут передаваться не полностью.

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

Тип входа	Что извлекается лучше всего	Что проверить
Текстовый PDF	Абзацы, заголовки, структура	Порядок колонок и встроенные шрифты
Сканированный PDF	Текст после OCR, блоки страницы	Контраст, наклон, язык
PNG и JPEG	Одна страница или иллюстрация	Разрешение и обрезку краёв
DOCX	Текст, простые таблицы, рисунки	Плавающие объекты и колонтитулы
PPTX	Текстовые блоки и изображения	Слои, диаграммы и заметки
XLSX	Табличные данные после преобразования	Объединения, формулы и печатные области

Как MinerU распознаёт структуру страницы

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

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

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

Текстовый слой и принудительный OCR

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

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

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

Выбор языка и многоязычные документы

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

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

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

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

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

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

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

Формулы и математическая разметка

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

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

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

Рисунки, подписи и связанные области

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

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

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

Выходной Markdown

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

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

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

JSON и файлы промежуточной структуры

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

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

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

Диагностические изображения layout и span

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

Если рамка таблицы отсутствует уже на layout-изображении, проблему нужно искать в распознавании макета или качестве страницы. Если таблица выделена правильно, но ячейки перепутаны, причина находится на этапе структурирования таблицы. Если текстовые spans верны, а в Markdown абзац разорван, корректировать следует правила объединения. Такой диагноз экономит время: вместо бессистемного переключения параметров становится ясно, какой этап дал сбой.

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

Командная строка mineru

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

mineru --help
mineru -p document.pdf -o output
mineru -p input_folder -o output_folder

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

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

Пакетная обработка каталогов

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

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

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

Python API

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

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

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

API-сервер и очередь заданий

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

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

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

Работа через Gradio

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

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

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

Backend: pipeline, hybrid и VLM

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

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

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

Модели, кэш и источники загрузки

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

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

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

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

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

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

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

CPU, CUDA и Apple Silicon

Pipeline может работать на CPU, что удобно для проверки и небольших очередей. GPU ускоряет модели, но требует совместимых драйверов, сборки PyTorch и достаточной видеопамяти. На Apple Silicon используется аппаратное ускорение через MPS там, где его поддерживает набор операций. Производительность зависит от backend, размера страниц и типов элементов, поэтому универсального числа страниц в минуту нет.

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

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

Совместимость с операционными системами

MinerU используется в Linux, Windows и macOS при подходящей версии Python и зависимостей. Для Windows есть дополнительное ограничение, связанное с компонентами распределённого выполнения: безопаснее выбирать поддерживаемую версию Python в диапазоне 3.10–3.12. На Linux важны достаточно новые системные библиотеки, а на macOS — современная система и корректно собранные зависимости для процессора устройства.

Самая надёжная установка выполняется в отдельном виртуальном окружении. Она не смешивает библиотеки MinerU с проектами, где уже закреплены другие версии PyTorch, NumPy или серверных пакетов. После создания окружения устанавливают пакет, проверяют справку команды и выполняют тестовый файл. Только затем добавляют GPU-компоненты и сервер.

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

Установка через uv и pip

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

python -m venv .venv
# активируйте окружение средствами своей системы
python -m pip install --upgrade pip
python -m pip install -U "mineru[all]"
mineru --help

Если установка завершается конфликтом, не следует насильно понижать случайную библиотеку в общем окружении. Создайте чистое окружение с поддерживаемой версией Python и повторите операцию. Для GPU сначала подберите совместимую сборку PyTorch по драйверу, убедитесь, что она видит устройство, и только потом устанавливайте остальные зависимости.

После установки проверьте три уровня: импорт пакета в Python, вывод справки команды и преобразование короткого PDF. Успешный импорт не гарантирует наличие моделей, а работа справки не проверяет OCR и таблицы. Тестовый документ должен содержать именно те элементы, которые понадобятся в реальной задаче.

Профили обработки для разных документов

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

Профиль	Основные параметры	Контроль качества
Цифровой отчёт	Автоматический текст, таблицы	Колонтитулы и многостраничные таблицы
Архивный скан	OCR, явный язык, малый пакет	Даты, фамилии, поворот страниц
Научная статья	Формулы, таблицы, layout	Колонки, LaTeX, подписи рисунков
Презентация	Преобразование PPTX, изображения	Порядок блоков и диаграммы
База для RAG	JSON, координаты, ресурсы	Заголовки, чанки, ссылки на страницы

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

Подготовка данных для RAG

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

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

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

Научные статьи и техническая документация

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

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

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

Договоры, отчёты и деловые документы

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

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

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

DOCX, PPTX и XLSX в одном процессе

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

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

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

Контроль качества результата

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

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

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

Что делать при неправильном порядке чтения

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

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

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

Исправление ошибок OCR

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

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

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

Ошибки таблиц и формул

Если таблица не обнаружена, посмотрите layout: отсутствие общей рамки указывает на проблему детектора. Можно улучшить исходное изображение, увеличить масштаб или обрезать страницу до содержательной области. Если рамка есть, но структура неправильна, сравните HTML и изображение, затем решите, можно ли исправить объединения постобработкой.

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

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

Сбои установки и зависимостей

Сообщение о невозможности собрать пакет обычно связано с неподходящей версией Python, отсутствующим компилятором или несовместимым двоичным колесом. Начните с чистого окружения и поддерживаемой версии Python. Обновите менеджер пакетов, затем повторите установку без сторонних библиотек. Журнал нужно читать с первой реальной ошибки, а не с последней строки общего отказа.

Конфликт PyTorch и CUDA проявляется тем, что устройство не видно или операция завершается ошибкой загрузки библиотеки. Сначала добейтесь работы минимального теста PyTorch. Версия драйвера, сборка библиотеки и архитектура GPU должны быть совместимы. Установка случайных вариантов поверх друг друга обычно оставляет смешанное окружение; быстрее создать новое.

Если команда не найдена после успешной установки, проверьте активацию окружения и каталог скриптов. Запуск через модуль Python помогает отличить проблему PATH от отсутствующего пакета. На Windows также следует убедиться, что терминал открыт после активации нужного окружения, а не использует другой интерпретатор.

Недостаток памяти и остановка процесса

Признаки нехватки памяти — внезапное завершение без итогового архива, системное убийство процесса, ошибка выделения CUDA или резкое замедление из-за подкачки. Уменьшите параллелизм до одного задания, ограничьте число страниц и повторите тест. Если короткий фрагмент проходит, причина почти наверняка связана с объёмом.

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

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

Производительность и измерение скорости

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

Тестовый набор прогревают: первый запуск включает загрузку моделей и компиляцию отдельных операций. Затем выполняют несколько повторов и берут медиану. Отдельно измеряют время подготовки входа, инференса, сборки Markdown и упаковки файлов. Это показывает, ускорит ли GPU реальный процесс или узким местом остаётся диск.

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

Безопасность и конфиденциальность

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

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

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

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

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

Программа	Лучше подходит для	Главное ограничение
MinerU	Преобразование сложных PDF в Markdown и JSON с координатами	Требует настройки моделей и ресурсов
PDF Commander	Ручное редактирование, сборка, подпись и конвертация PDF	Не создаёт структурный корпус Markdown/JSON
Docling	Программная конвертация документов и подготовка данных для ИИ	Качество сложной верстки нужно проверять
Marker	Быстрое преобразование PDF и изображений в Markdown	Модельный стек требователен к ресурсам
Unstructured	Разбиение разнородных документов на элементы для ETL и RAG	Формулы и сложные таблицы требуют контроля
PaddleOCR	OCR, распознавание макета и построение собственных конвейеров	Результат нужно собирать программно

Для исправления страниц, объединения файлов и ручной работы выбирают PDF Commander. Для готового программного конвейера с акцентом на унификацию форматов удобны Docling или Unstructured. Marker подходит, когда главным выходом должен быть Markdown. PaddleOCR уместен как набор компонентов для собственной архитектуры. MinerU стоит выбирать, когда в одном процессе важны порядок чтения, формулы, таблицы, изображения, Markdown, JSON и визуальная диагностика.

Практический сценарий: от папки PDF до базы знаний

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

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

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

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

Практический сценарий: архив сканов

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

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

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

Практический сценарий: извлечение таблиц из отчётов

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

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

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

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

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

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

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

Ответы на практические вопросы

Почему из PDF получился почти пустой Markdown?

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

Почему абзацы идут в неправильном порядке?

Причина обычно в колонках, боковых вставках или пересекающихся областях. Сравните layout и координаты. Для повторяющегося шаблона добавьте правило постобработки по колонкам, а для единичного документа исправьте порядок в Markdown.

Нужно ли всегда включать принудительный OCR?

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

Где искать извлечённые рисунки?

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

Можно ли получить координаты элемента?

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

Почему таблица сохранена как HTML?

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

Почему первый запуск заметно дольше?

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

Как понять, что результат можно индексировать?

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

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

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

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

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

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

После изменения языка, backend или режима OCR повторно прогоняют один и тот же эталонный набор. Сравнивают не только общий текст, но и количество блоков каждого типа, порядок заголовков, HTML таблиц и LaTeX формул. Автоматический diff должен игнорировать несущественные пробелы, но сохранять различия в цифрах, знаках и структуре.

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

Организация журналов

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

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

Сборка единого документа из частей

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

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

Тестирование API-клиента

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

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

Хранение и именование результатов

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

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

Проверка документов с паролем и повреждениями

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

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

Обработка повёрнутых и широких страниц

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

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

Работа с колонтитулами и повторяющимися блоками

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

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

Нормализация Markdown перед публикацией

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

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

Аномалии, которые можно обнаружить автоматически

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

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

Передача результата следующей системе

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

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