긴 PDF의 축소판을 만들고 먼저 픽셀과 메모리를 계산합니다.

200페이지의 엔지니어링 도면에 대한 썸네일을 일괄 생성할 때 30페이지에 도달했을 때 OOM으로 인해 시스템에 의해 스크립트가 종료되었습니다. 이는 많은 개발자가 처음으로 긴 문서를 처리할 때 직면하는 일반적인 오류입니다. 문제는 일반적으로 라이브러리 자체에 있는 것이 아니라 래스터화 프로세스의 임시 메모리 공간을 과소평가하는 데 있습니다. A3 페이지가 150DPI의 RGB 이미지로 렌더링되면 원본 픽셀 데이터에만 약 35MB가 필요합니다. 루프에서 Pixmap이 시간 내에 해제되지 않거나 알파 채널이 실수로 열린 경우 메모리 피크가 몇 초 안에 GB 수준을 초과할 수 있습니다.

이 문서는 긴 PDF를 일괄 처리해야 하는 개발자를 위해 작성되었습니다. 이 내용을 읽고 나면 각 프레임에 대한 리소스 예산을 계산하고, 보다 안전한 방식으로 페이지별로 축소판을 렌더링하고, 어떤 결과를 수동으로 검토해야 하는지 알 수 있습니다. 본 글의 예시는 합성 샘플을 사용하여 시연되었으며, 코드는 격리된 환경에서 확인되었으나, 이것이 모든 실제 파일이나 제품 효과를 보장하는 것은 아닙니다. 중요한 서류를 처리하기 전, 원본을 보관하시고, 본문에 기재된 경계 및 허용 항목에 따라 검토하시기 바랍니다.

긴 PDF 축소판의 메모리 오버플로를 방지하는 방법은 무엇입니까? 한 문장 결론

먼저 DPI와 픽셀 수를 기준으로 각 페이지의 메모리 예산을 계산한 다음 RGB 모드에서 페이지별로 렌더링하고 시간에 맞춰 각 프레임의 버퍼를 해제합니다.

픽셀 크기 및 메모리 사용량의 정확한 변환

렌더링 API를 호출하기 전에 물리적 차원에서 바이트로의 매핑을 설정하세요.

실제 크기에서 픽셀까지

• PDF 페이지 크기는 포인트 단위로 측정되며, 1포인트는 1/72인치와 같습니다. 좌표계 관례는 PyMuPDF 좌표 좌표계 설명를 참조하십시오.
• DPI 래스터화를 지정할 때 실제 픽셀 너비와 높이는 int(page_width_pt / 72 dpi) 및 int(page_height_pt / 72 dpi)입니다.
• 표준 A4 용지(595×842 도트)를 예로 들면, 144 DPI에서 생성된 이미지 크기는 1190×1684 픽셀입니다.

메모리 사용량을 추정하는 방법

• RGB 색상 공간은 픽셀당 3바이트이고 RGBA는 4바이트입니다.
• 위의 A4를 예로 들면, RGB 모드에서 단일 프레임의 비압축 데이터는 약 6.0MB(1190×1684×3)이며, 알파 채널을 켜면 8.0MB로 약 33% 증가합니다.
• 썸네일 미리보기 장면에서는 투명한 배경 오버레이가 필요하지 않은 한 알파 채널을 항상 비활성화해야 합니다.
• 배치 사이클에서 이전 프레임의 버퍼가 가비지 컬렉터에 의해 제때에 클리어되지 않으면 실제 상주 메모리는 이론값의 몇 배가 될 수 있습니다.

합성 예제의 입력 범위 및 예상 동작

메모리 제어 논리를 검증하기 위해 재현할 수 없는 실제 파일에 의존하기보다는 제어된 합성 입력 세트를 구성했습니다.

정확하게 입력하세요

올바른 입력에는 알려진 크기의 가상 페이지, 명시적인 DPI 매개변수 및 알파를 끄는 플래그가 포함되어야 합니다. 예를 들어, 72 DPI에서 RGB 이미지로 렌더링되는 100×100 포인트 정사각형 페이지를 생성하면 예상되는 출력은 100×100 픽셀, 30,000바이트 버퍼입니다.

일반적인 입력 오류

• 음수 또는 0 DPI: 일부 라이브러리에서는 예외가 발생하지만 더 위험한 것은 상한을 확인하지 않고 매우 큰 값(예: 1200)을 전달하는 것입니다. 이때 단일 페이지 렌더링은 수백 MB의 메모리를 소비하여 후속 페이지에서 공간을 할당하지 못하게 될 수 있습니다.
• 페이지 회전: 페이지를 90도 회전한 후에도 여전히 원래 너비와 높이를 기준으로 버퍼가 계산되면 잘리거나 늘어납니다.

처리 방법은 렌더링 전에 어설션을 추가하는 것입니다. DPI는 0보다 크고 미리 설정된 임계값(300이 기사에서 예로 사용됨)보다 작아야 하며, 페이지 크기는 합리적인 범위를 초과해서는 안 됩니다(A0이 기사에서 예로 사용됨). 이러한 임계값은 업계 표준은 아니지만 실행 환경의 사용 가능한 메모리를 기반으로 한 엔지니어링 제약 조건입니다.

PyMuPDF 페이지별 렌더링의 안전한 구현

다음 예에서는 메모리가 제한된 환경에서 썸네일을 안전하게 생성하는 방법을 보여줍니다. 이 코드는 pymupdf>=1.24.0를 설치해야 하는 PyMuPDF를 사용합니다. 모든 작업은 메모리에서 완료되며 외부 파일에 의존하지 않습니다. 렌더링에 사용되는 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를 사용하세요.
• 회전 상태에 따라 픽셀 크기를 다시 계산합니다.
• 렌더링하기 전에 메모리를 추정하고 하드 캡을 설정합니다.
• 렌더링 직후 Pixmap 참조를 Null로 만듭니다.

이러한 조치는 유출이 없다는 것을 보장할 수는 없지만 예측 가능한 범위 내에서 위험을 제어할 수 있습니다.

허용 기준 및 직접 검토 경계

코드를 실행할 수 있다고 해서 프로덕션 준비가 완료되었다는 의미는 아닙니다. 다음 표에는 실제 배포 시 주의가 필요한 승인 항목이 나열되어 있으며, 자동화가 포함할 수 있는 범위와 수동 개입이 필요한 시나리오를 구분합니다.

이 표는 코드 데모 수준의 리소스 제어에만 적용됩니다. 엔드투엔드 효과를 수용하려면 색상 정확도 및 글꼴 포함 무결성과 같은 비즈니스 차원도 고려해야 합니다. 암호화된 PDF, 손상된 파일 또는 복잡한 벡터 그래픽이 포함된 페이지를 발견하면 자동 스크립트가 자동으로 실패하는 경우가 많습니다. 이 경우에는 생략할지, 특수처리를 할지 수동으로 판단해야 한다.

문서 번역을 위해 체크리스트를 사용하세요

썸네일 이후 문서를 번역해야 하는 경우에는 페이지 순서, 원본 위치, 텍스트 무결성을 먼저 확인한 후 동일한 민감도를 낮춘 샘플을 번역 프로세스에 제출하는 것이 좋습니다. 번역 후에도 제목, 텍스트, 일러스트레이션이 올바르게 일치하는지 확인해야 합니다. 텍스트가 매끄러운지 여부만 확인할 수는 없습니다.

OmniDoc(제품 포털)는 다양한 형식의 문서 번역 포털을 제공하며 공식 웹사이트에서는 OCR, 용어집 및 이중 언어 비교 기능을 소개합니다. 파일에서 직접 작업하려는 팀의 경우 이는 실제 샘플을 사용하여 평가할 가치가 있는 경로입니다. 업로드 권한이 있는 둔감화된 파일을 사용하시고, 이 글의 확인 항목을 사용하여 결과를 검토하시기 바랍니다. OmniDoc이 이 문서의 오픈 소스 라이브러리나 내부 알고리즘을 사용한다는 주장은 없으며 이 예가 제품 성능 테스트를 대체하지도 않습니다.

📊 핵심 비교

🎯 어떤 방법이 당신에게 적합합니까?

썸네일을 빠르게 생성해야 하는 경우

RGB 모드를 사용하고 알파를 끄고 페이지별로 렌더링하여 시간에 맞춰 Pixmap을 출시합니다.

투명한 배경 오버레이가 필요한 경우

더 높은 메모리 공간을 수용하고 렌더링하기 전에 최대치를 예측하고 필요한 경우 DPI를 낮추거나 일괄 처리합니다.

암호화되거나 복잡한 벡터 파일을 다루는 경우

자동화된 스크립트에 전적으로 의존하지 마십시오. 실패한 페이지에 대해 수동으로 판단하여 해당 페이지를 건너뛸지 아니면 특별히 처리할지 결정해야 합니다.

❓ 자주 묻는 질문(FAQ)

1. 수십 페이지를 처리한 후 시스템에 의해 스크립트가 종료되는 이유는 무엇입니까?

대부분의 경우 라이브러리 자체에 결함이 있는 것이 아니라 래스터화의 순간적인 메모리 사용량이 과소평가되어 루프에서 Pixmap이 제때 해제되지 않는 것입니다. 최고 값은 몇 초 내에 GB 수준을 초과할 수 있습니다.

2. 썸네일의 알파 채널을 꺼야 하는 이유는 무엇입니까?

Alpha는 투명한 배경 오버레이가 필요하지 않은 한 메모리만 추가합니다. 144 DPI의 A4를 예로 들면 단일 프레임이 6.0MB에서 8.0MB로 증가합니다.

3. 회전된 페이지가 변형되는 이유는 무엇인가요?

버퍼가 여전히 원래 너비와 높이를 기준으로 계산되는 경우 렌더링 결과가 잘리거나 늘어날 수 있습니다. 실제 회전된 직사각형은 픽셀 크기를 계산하기 전에 얻어야 합니다.

4. DPI 제한은 300이어야 합니까?

불확실한. 이 문서의 300 임계값은 업계 표준이 아닌 예제 임계값이며 실행 환경의 사용 가능한 메모리를 기반으로 설정해야 합니다.

5. 샘플 검사를 통과한 후 코드를 온라인에 올릴 수 있나요?

캔트. 코드가 실행될 수 있다고 해서 프로덕션에 사용할 수 있다는 의미는 아닙니다. 경계 조건은 승인 목록에 따라 실제이지만 둔감한 긴 문서에서 검토되어야 합니다.

📝 요약

코드를 작성하기 전에 리소스 예산을 명확하게 계산해야 합니다. 페이지별 렌더링, 적시 릴리스 및 매개변수 확인은 필수입니다. 자동화는 대부분의 리소스 제어 문제를 다룰 수 있지만 색상, 글꼴 및 복잡한 페이지는 여전히 수동 확인이 필요합니다.

지금 사용해 보세요: 원본 레이아웃을 유지하면서 번역을 시작하려면 문서를 업로드하세요.