olmOCR преобразует PDF, PNG и JPEG в читаемый Markdown, восстанавливает естественный порядок фрагментов на многоколоночной странице, переносит таблицы и формулы в текстовую разметку, распознаёт рукописные участки и помогает проверить результат рядом с исходной страницей через Dolma Viewer.

Работа строится вокруг команды olmocr: в ней указывают рабочую папку, один файл или маску набора документов, способ запуска модели и формат результата. Конвейер растеризует страницы, извлекает доступный текстовый слой с координатами, формирует подсказку для зрительно-языковой модели, повторяет неудачные запросы и собирает ответы страниц в цельный документ.

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

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

Минимальное задание состоит из трёх частей: пути к рабочему пространству, переключателя --pdfs с входными файлами и, когда нужен удобный для чтения результат, флага --markdown. Например, команда olmocr ./workspace --markdown --pdfs report.pdf создаёт служебные каталоги внутри workspace, обрабатывает страницы и помещает собранный текст в подкаталог markdown. Исходный документ не перезаписывается: его можно держать рядом, перемещать после завершения задания или оставить в отдельном хранилище.

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

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

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

Основные входы — PDF, PNG и JPEG. Для PDF обрабатываются отдельные страницы, поэтому один файл может сочетать цифровой текст, сканы, формулы и иллюстрации. PNG и JPEG проходят через тот же аргумент --pdfs, несмотря на его название: файл изображения трактуется как одностраничный документ. Это удобно для фотографий рукописей, отдельных листов технической документации и страниц, заранее извлечённых из большой коллекции.

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

Аргумент принимает маски оболочки, поэтому набор однотипных файлов можно передать одной командой, например docs/*.pdf. Раскрытие маски обычно выполняет командная оболочка. Если в путях есть пробелы, каждый путь заключают в кавычки; если файлов очень много, удобнее разбивать их по папкам или использовать объектное хранилище, чтобы не превысить допустимую длину командной строки.

Рабочая папка и результаты

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

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

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

Подготовка Python и системных компонентов

Для предсказуемой установки создают чистое окружение Python 3.11. Это не формальность: пакет объединяет библиотеки обработки PDF, асинхронные запросы, схемы данных и, при собственном запуске модели, тяжёлый стек PyTorch, Transformers и vLLM. Попытка добавить их в давно используемое окружение часто приводит к конфликтам версий CUDA, Pydantic или вспомогательных библиотек. Отдельное окружение позволяет удалить неудачную конфигурацию без риска для других проектов.

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

Есть два практических профиля. Базовая установка pip install olmocr подходит для обращения к совместимому серверу через --server и не тянет весь набор вычислительных зависимостей. Вариант с дополнением gpu нужен, когда vLLM и модель запускаются на собственной NVIDIA-карте. Для кластера предусмотрено дополнение beaker, а для воспроизводимых измерений — bench. Смешивать дополнения можно, но каждое увеличивает число зависимостей, поэтому устанавливают только действительно нужные.

Первый запуск на одном PDF

Начинать лучше не со всего собрания, а с документа на три–пять страниц, где есть обычный текст, таблица и хотя бы один сложный элемент. Команда olmocr ./test-workspace --markdown --pdfs sample.pdf одновременно проверяет Poppler, доступность модели, права на запись и сборку Markdown. После завершения откройте файл из test-workspace/markdown и сравните границы абзацев, порядок колонок, подписи и номера страниц с оригиналом.

Если используется внешний сервер, к заданию добавляют --server SERVER_URL и --model MODEL_NAME. Имя должно совпадать с идентификатором, который сервер публикует в совместимом API. Ошибка в имени часто выглядит как ответ модель не найдена, хотя сеть и сервер работают. Сначала запросите список доступных моделей средствами сервера, скопируйте точный идентификатор, затем повторите один лист.

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

Преобразование PNG и JPEG

Для отдельного изображения применяется та же схема: olmocr ./image-workspace --markdown --pdfs page.png. Страница не нуждается в предварительном помещении в PDF. Это избавляет от лишней перекодировки и позволяет сохранять исходное разрешение скана. JPEG подходит для фотографий и уже сжатых цифровых коллекций, а PNG предпочтителен для схем, мелкого шрифта и скриншотов, где артефакты сжатия могут исказить тонкие линии.

При пакетной подаче изображений порядок файлов определяется их именами и очередью, а не визуальной последовательностью страниц. Если отдельные PNG должны образовать книгу, заранее используйте нумерацию с одинаковой длиной: page-0001.png, page-0002.png и далее. Иначе лексикографическая сортировка может поставить десятую страницу перед второй. Для гарантированного единого документа проще сначала собрать корректный PDF или объединить Markdown после проверки метаданных.

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

Как olmOCR восстанавливает порядок чтения

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

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

Врезки и подписи не всегда имеют однозначное место. Модель выбирает последовательность, подходящую для чтения, но не формирует координатно точную копию макета. Если downstream-система должна отвечать, где именно на странице находился каждый фрагмент, одного Markdown недостаточно: сохраняйте JSONL и исходный PDF, а координаты проверяйте отдельно. Смысловая последовательность и геометрическое позиционирование — разные задачи.

Document Anchoring: зачем нужен текстовый слой PDF

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

Якорь не следует считать готовым ответом. В PDF может быть повреждённая кодировка, невидимый OCR-слой, повторённые символы или текст, скрытый под иллюстрацией. Модель должна сопоставить сырой слой с изображением и вернуть читаемое содержание. Поэтому увеличение --target_anchor_text_len не всегда улучшает результат: слишком длинная подсказка занимает контекст и может принести больше мусора. Уменьшение значения полезно при PDF с загрязнённым скрытым текстом; увеличение — когда мелкие, но важные фрагменты не попадают в якорь.

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

Размер растеризованной страницы

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

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

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

Таблицы в Markdown

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

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

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

Формулы, индексы и математические страницы

Формулы возвращаются в LaTeX-подобной разметке внутри Markdown. Это позволяет передавать материал в системы, понимающие математические разделители, и сохранять структуру дробей, корней, сумм и индексов. Главная проверка — не внешний вид исходного PDF, а семантическая эквивалентность выражения. Похожие символы l, 1, I, ноль и буква O требуют особого внимания.

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

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

Рукописный текст и исторические сканы

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

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

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

Колонтитулы, номера страниц и сноски

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

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

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

Автоповорот и страницы без текста

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

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

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

Фильтрация документов

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

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

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

Markdown как итоговый формат

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

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

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

JSONL и структура документа

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

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

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

Проверка результата в Dolma Viewer

Модуль olmocr.viewer.dolmaviewer строит HTML-представления из JSONL. В просмотрщике распознанный текст располагается рядом с изображением исходной страницы, поэтому можно быстро сверять абзацы, формулы и пропуски без переключения между двумя программами. Команда получает маску файлов результатов и создаёт каталог страниц для открытия в браузере.

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

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

Удалённый сервер через параметр --server

Режим внешнего сервера разделяет подготовку документов и инференс. Машина с PDF выполняет рендеринг, формирует запросы и принимает ответы, а модель работает на отдельном узле с видеокартой. В команде задают --server SERVER_URL и --model MODEL_NAME. Сервер должен предоставлять совместимый интерфейс чата с передачей изображения и возвращать ответ ожидаемого формата.

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

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

Запуск модели через vLLM

При использовании собственного GPU конвейер опирается на vLLM. Для модели класса 7B требуется современная NVIDIA-карта; в документации перечислены RTX 4090, L40S, A100 и H100 как проверенные варианты, а минимальный ориентир памяти составляет 12 ГБ. Кроме весов нужна память под KV-кэш, визуальные представления и параллельные запросы, поэтому формально достаточный объём не гарантирует высокую пропускную способность.

--gpu-memory-utilization ограничивает долю памяти, которую vLLM старается занять. Слишком высокое значение оставляет мало резерва драйверу и другим процессам; слишком низкое уменьшает кэш и допустимый параллелизм. После ошибки нехватки памяти сначала снижайте число одновременно обрабатываемых страниц, затем долю памяти или размер изображения. Изменение всех параметров сразу затрудняет диагностику.

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

Tensor Parallel и Data Parallel

--tensor-parallel-size распределяет одну модель между несколькими GPU. Этот режим нужен, когда веса и рабочие буферы не помещаются на одной карте или когда конфигурация модели рассчитана на совместное исполнение. Карты должны быть доступны одному процессу и иметь подходящее соединение. Увеличение числа устройств не всегда линейно ускоряет обработку: обмен данными между картами добавляет задержку.

--data-parallel-size создаёт несколько копий модели для независимых запросов. Он полезен, когда каждая копия помещается на отдельной карте, а очередь содержит много страниц. В таком случае пропускная способность может расти лучше, чем при разделении одной модели. Цена — повторное размещение весов и больший суммарный объём памяти.

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

Воркеры, группы страниц и параллелизм

--workers определяет число рабочих процессов, которые готовят и отправляют задания. Увеличение помогает скрыть время рендеринга и сетевые задержки, но создаёт больше открытых файлов и одновременных запросов. На слабом CPU большое число воркеров конкурирует за ресурсы Poppler; на ограниченном сервере оно переполняет очередь модели.

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

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

Повторы и допустимая доля ошибок

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

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

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

Guided decoding и схема ответа

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

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

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

Статистика обработки

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

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

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

Объектное хранилище S3

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

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

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

Несколько узлов и общая очередь

Для масштабирования несколько воркеров могут подключаться к общему рабочему пространству и забирать независимые элементы очереди. Такая схема позволяет обрабатывать коллекцию на нескольких GPU-узлах без ручного деления PDF. Ключевое условие — единые параметры задания и доступ к тем же исходникам. Воркеры с разными моделями или размерами растра создадут неоднородный корпус.

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

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

Контейнеры Docker

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

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

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

Внешний сервер на компьютере без NVIDIA

Базовый пакет можно использовать на машине без NVIDIA, если инференс выполняет другой совместимый сервер. На компьютере остаются Python, Poppler, подготовка запроса и сборка результатов. Это позволяет работать с удалённым GPU или с программой, которая публикует совместимый API для квантованной модели. Качество и доступные функции в таком случае зависят от выбранной модели и сервера.

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

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

Графические оболочки и веб-формы

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

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

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

Beaker и пакетные задания

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

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

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

Ошибка Too many open files

При большом числе воркеров процесс одновременно держит PDF, временные изображения, сетевые соединения и файлы очереди. Когда системный лимит дескрипторов слишком мал, появляется сообщение too many open files. Рекомендованная рабочая мера для текущего сеанса — поднять лимит командой ulimit -n 65536 перед запуском.

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

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

Конфликты зависимостей Python

Ошибки импорта, несовместимые требования к Pydantic, Transformers, Torch или vLLM чаще всего возникают в окружении, где уже установлены другие ML-проекты. Не пытайтесь исправлять десятки конфликтов последовательным обновлением случайных пакетов. Создайте чистое окружение Python 3.11, установите выбранный профиль olmOCR и только затем добавляйте собственные утилиты.

Зафиксируйте список установленных версий после успешного теста. Если окружение нужно воспроизвести на другом узле, сравнивайте не только Python-пакеты, но и драйвер NVIDIA, версию CUDA, Poppler и шрифты. Одинаковый requirements не гарантирует одинаковую работу vLLM при разных драйверах.

Когда базовый режим с удалённым сервером работает, а профиль GPU нет, проблема почти наверняка находится в вычислительном стеке. Проверьте доступность CUDA в PyTorch и видимость карты до запуска olmOCR. Когда не работает даже базовая команда справки, ищите конфликт пакетов или повреждённую установку, не тратя время на параметры модели.

Сервер отвечает, но страницы не обрабатываются

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

Проверьте запрос на одной странице, имя модели и поддержку изображений. Затем сравните максимальную длину и параметры guided decoding. Если сервер возвращает HTML вместо JSON, возможно, указан адрес панели управления, а не API. В команду подставляют базовый адрес совместимого интерфейса, без маршрута конкретного метода, если документация сервера не требует иначе.

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

Ошибка памяти GPU

Нехватка памяти возникает при загрузке весов, создании KV-кэша или обработке плотной страницы. Если сбой происходит до первого запроса, уменьшение воркеров не поможет: модель или конфигурация параллелизма не помещается. Нужна карта с большим объёмом, распределение по нескольким GPU либо подходящий внешний сервер.

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

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

Документ останавливается возле последних страниц

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

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

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

Пустой результат и сообщение No document text

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

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

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

Повторы, дубли и смешанные результаты

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

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

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

Координаты изображений и схем

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

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

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

Контроль качества на выборке

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

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

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

Практический конвейер для базы знаний

Для базы знаний сначала отделяют поступление файлов от распознавания. Новый PDF получает стабильный идентификатор и хэш, затем попадает в очередь olmOCR. После завершения Markdown проходит проверку структуры, а JSONL сохраняется как доказательство связи со страницами. Только проверенная копия отправляется на разбиение и индексацию.

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

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

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

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

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

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

Практический конвейер для исторических коллекций

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

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

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

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

Когда цель — данные из таблиц, olmOCR используют как этап реконструкции, а не как окончательный импорт. Markdown сначала разбирают в строки и столбцы, затем проверяют типы: даты, валюты, проценты и идентификаторы. Значения с пробелами, запятыми и точками приводят к правилам конкретного документа.

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

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

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

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

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

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

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

Программа	Лучше подходит для	Главное ограничение
olmOCR	Пакетного преобразования PDF и изображений в Markdown с естественным порядком чтения, таблицами, формулами и общей очередью для нескольких GPU	Для собственной модели требуется мощная NVIDIA-видеокарта и техническая настройка конвейера
Marker	Быстрого получения Markdown, JSON, HTML или фрагментов из PDF с выборочным применением зрительной модели	Результат и скорость заметно зависят от режима, выбранных моделей и качества текстового слоя
MinerU	Разбора PDF, изображений и офисных документов в Markdown или JSON с отдельными OCR- и VLM-маршрутами	Широкий набор движков и параметров усложняет воспроизводимую настройку окружения
PaddleOCR-VL	Многоязычного анализа макета, формул, таблиц и документов в экосистеме PaddlePaddle	Для полного пакетного процесса нужно собрать и настроить несколько компонентов PaddleX
Mistral Document AI	Облачного OCR и структурированного извлечения через управляемый API без обслуживания собственной модели	Документы передаются внешнему API, а ограничения запроса зависят от сервиса
PDF Commander	Ручного редактирования, сборки, подписания и подготовки обычных PDF в графическом интерфейсе	Не предназначен для GPU-конвейера, JSONL и массового преобразования страниц в Markdown

olmOCR выбирают, когда нужен контролируемый конвейер именно для PDF и изображений, собственное хранение результатов и масштабирование очереди. Marker удобнее для разнообразных выходных форматов и быстрого старта, MinerU — для более широкого набора офисных входов, PaddleOCR-VL — для многоязычных задач и детального анализа макета, а Mistral Document AI — когда приемлем внешний API. PDF Commander подходит не вместо распознающего конвейера, а для последующей ручной правки, объединения и оформления PDF.

Что olmOCR не делает

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

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

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

Как подобрать настройки без лишних прогонов

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

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

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

Автоматизация командой и сценарием

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

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

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

Проверка обновления модели или окружения

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

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

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

Итоговый практический выбор

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

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

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