Делайте миниатюры для длинных PDF-файлов, сначала рассчитайте пиксели и память.

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

• После перевода необходимо проверить правильность соответствия названия, текста и иллюстраций, а не просто плавность текста.

При пакетном создании эскизов для 200 страниц инженерных чертежей скрипт был убит системой из-за OOM при достижении 30-й страницы. Это типичный сбой, с которым сталкиваются многие разработчики при первой обработке длинных документов. Проблема обычно не в самой библиотеке, а в недооценке временного объема памяти, занимаемого процессом растеризации. Когда страница формата A3 отображается как изображение RGB с разрешением 150 точек на дюйм, только исходные пиксельные данные требуют около 35 МБ; если Pixmap не освобождается вовремя в цикле или альфа-канал открыт по ошибке, пик памяти может превысить уровень ГБ за несколько секунд.

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

Как избежать переполнения памяти для длинных миниатюр PDF? Вывод в одно предложение

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

Точное преобразование размера пикселей и использования памяти

Прежде чем вызывать какой-либо API рендеринга, установите соответствие физических размеров байтам.

От физических размеров к пикселям

• Размер страницы PDF измеряется в пунктах, где 1 пункт равен 1/72 дюйма. Информацию о системе координат см. в PyMuPDF Описание координатной системы координат.

— При указании растеризации DPI фактическая ширина и высота пикселей равны int(page_width_pt / 72 dpi) и int(page_height_pt / 72 dpi).

• Если взять в качестве примера стандартную бумагу формата А4 (595×842 точек), то размер изображения, создаваемого при разрешении 144 точек на дюйм, составляет 1190×1684 пикселей.

Как оценить использование памяти

• Цветовое пространство RGB имеет 3 байта на пиксель, RGBA — 4 байта.
• Если взять приведенный выше A4 в качестве примера, несжатые данные одного кадра в режиме RGB составляют около 6,0 МБ (1190×1684×3), который увеличивается до 8,0 МБ после включения альфа-канала, увеличение примерно на 33%.
• В сценах предварительного просмотра миниатюр альфа-канал всегда следует отключать, если не требуется наложение прозрачного фона.
• В пакетном цикле, если буфер предыдущего кадра не очищается сборщиком мусора вовремя, фактический объем резидентной памяти может в несколько раз превышать теоретическое значение.

Входные границы и ожидаемое поведение синтетических примеров

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

Введите правильно

Правильные входные данные должны включать виртуальную страницу известных размеров, явные параметры DPI и флаг для отключения альфа-канала. Например, при создании квадратной страницы размером 100×100 точек, отображаемой в виде изображения RGB с разрешением 72 DPI, ожидаемым результатом будет буфер размером 100×100 пикселей и 30 000 байт.

Распространенные ошибки ввода

• Отрицательный или нулевой DPI: некоторые библиотеки выдают исключения, но что более опасно, так это передача очень большого значения (например, 1200) без проверки верхнего предела. В настоящее время рендеринг одной страницы может занимать сотни МБ памяти, в результате чего последующие страницы не смогут выделить пространство.
• Поворот страницы: если буфер по-прежнему рассчитывается на основе исходной ширины и высоты после поворота страницы на 90 градусов, это приведет к обрезке или растяжению.

Метод обработки заключается в добавлении утверждений перед рендерингом: DPI должен быть больше 0 и меньше заданного порога (в статье в качестве примера используется 300), а размер страницы не должен превышать разумный диапазон (в статье в качестве примера используется A0). Эти пороговые значения не являются отраслевыми стандартами, а представляют собой инженерные ограничения, основанные на доступной памяти работающей среды.

Безопасная реализация постраничного рендеринга PyMuPDF

В следующем примере показано, как безопасно создавать миниатюры в среде с ограниченной памятью. В коде используется PyMuPDF, для которого требуется установка pymupdf>=1.24.0. Все операции выполняются в памяти и не зависят от внешних файлов. Описание параметров Page.get_pixmap, используемых при рендеринге, см. в PyMuPDF Page.get_pixmap официальная документация. Этот пример представляет собой синтетический сценарий, созданный в учебных целях. Запустите проверку в своей собственной среде с заблокированными зависимостями.

import pymupdf

def generate_thumbnail_safe(doc_bytes: bytes, dpi: int = 144) -> bytes:
    """安全生成首页缩略图，含资源预算校验"""
    assert 0 < dpi <= 300, "DPI must be in (0, 300]"
    doc = pymupdf.open(stream=doc_bytes, filetype="pdf")
    try:
        page = doc[0]
        rect = page.rect
        # 计算旋转后实际尺寸
        if page.rotation in (90, 270):
            width_px = int(rect.height * dpi / 72)
            height_px = int(rect.width * dpi / 72)
        else:
            width_px = int(rect.width * dpi / 72)
            height_px = int(rect.height * dpi / 72)

        # 内存预算检查（假设最大允许50MB）
        mem_estimate = width_px * height_px * 3
        assert mem_estimate < 50 * 1024 * 1024, f"Estimated {mem_estimate}B exceeds limit"

        pix = page.get_pixmap(dpi=dpi, alpha=False)
        thumbnail_bytes = pix.tobytes("png")
        pix = None  # 显式释放
        return thumbnail_bytes
    finally:
        doc.close()

# 合成测试：创建100x100点空白PDF
blank_pdf = pymupdf.open()
page = blank_pdf.new_page(width=100, height=100)
blank_bytes = blank_pdf.tobytes()
blank_pdf.close()

result = generate_thumbnail_safe(blank_bytes, dpi=72)
assert len(result) > 0, "Thumbnail generation failed"

Ключевые моменты включают в себя:

• Используйте alpha=False, чтобы избежать дублирования каналов.
• Пересчитать размеры пикселей на основе состояния вращения.
• Оцените память перед рендерингом и установите жесткое ограничение.

— Обнулите ссылку на растровое изображение сразу после рендеринга.

Эти меры не могут гарантировать отсутствие побочных эффектов, но они могут контролировать риск в пределах предсказуемого диапазона.

Критерии приемки и границы ручной проверки

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

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

Используйте чек-листы для перевода документов

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

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

📊 Сравнение ядра

🎯 Какой способ тебе подходит?

Если нужно быстро сгенерировать миниатюры

Используйте режим RGB, чтобы отключить альфу, прорендерить страницу за страницей и быстро освободить Pixmap.

Если вам нужен прозрачный фон

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

Если вы работаете с зашифрованными или сложными векторными файлами

Не полагайтесь полностью на автоматические скрипты; обрабатывайте неисправные страницы вручную и решайте — пропускать их или делать это специально.

❓ Часто задаваемые вопросы (FAQ)

1. Почему система убивает сценарий уже после нескольких десятков страниц?

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

2. Почему миниатюры отключают канал Alpha?

Если не требуется прозрачное фоновое наложение, Alpha только увеличивает память. Например, A4 с 144 DPI увеличивает объём одного кадра с 6,0 МБ до 8,0 МБ.

3. Почему вращающаяся страница искажается?

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

4. Всегда ли лимит DPI 300?

Не обязательно. Упомянутый здесь порог в 300 — это лишь пример порога, а не отраслевой стандарт; его следует устанавливать на основе доступной памяти в среде выполнения.

5. Может ли код стать доступным после прохождения проверки образцов?

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

📝 Краткое содержание

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

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