Transformers documentation

MiniCPM-OCR

Transformers

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

이 모델은 2025-09-16에 HF papers에 게시되었으며, 2026-10-26에 Hugging Face Transformers에 기여되었습니다.

MiniCPM-OCR

MiniCPM-OCR는 OpenBMB에서 개발한 MiniCPM-V 계열의 문서 이해 모델입니다. MiniCPM-V 4.6 아키텍처, 즉 Qwen3.5 언어 모델 앞에 window-attention merger가 결합된 SigLIP 비전 인코더를 유지하면서, 스캔 페이지, 스크린샷, 영수증, 표와 같이 텍스트가 밀집된 이미지를 읽는 데 특화되어 있습니다.

이 모델은 OpenBMB에서 기여했습니다. 원본 코드는 여기에서 찾을 수 있습니다.

사용 예시

Pipeline을 사용한 추론

단일 이미지에서 추론

다운샘플링 모드

작은 이미지 리사이징

배치 추론

from transformers import pipeline

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "image",
                "image": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/ocr_receipt.jpeg",
            },
            {"type": "text", "text": "Transcribe all the text in this document."},
        ],
    },
]

pipe = pipeline("image-text-to-text", model="openbmb/MiniCPM-OCR-1.0")
outputs = pipe(text=messages, max_new_tokens=256, return_full_text=False)
print(outputs[0]["generated_text"])
#
#
# Document No : TD01167104
# Date : 25/12/2018 8:13:39 PM
# Cashier : MANIS
# Member :
# CASH BILL
# CODE/DESC PRICE Disc AMOUNT
# QTY RM RM
# 9556939040118 KF MODELLING CLAY KIDDY FISH
# 1 PC * 9.00 0.00 9.00
# Total : 9.00
# Rounding Adjustment : 0.00
# Round-d Total (RM) : 9.00

MiniCPM-OCR은 MiniCPM-V 계열의 두 가지 시각적 다운샘플링 모드를 모두 지원합니다:

4x (기본값): 다운샘플링이 적고 시각 토큰이 많아 문서 및 스크린샷 전사 작업에 적합합니다.
16x: 더 공격적인 다운샘플링, 더 적은 시각 토큰, 자연 이미지에서 더 빠른 추론.

mode는 비전 타워가 생성할 것으로 예상되는 시각적 플레이스홀더를 카운트하는 프로세서와 model.generate에 함께 전달되어야 합니다:

from transformers import AutoModelForImageTextToText, AutoProcessor

model_id = "openbmb/MiniCPM-OCR-1.0"
processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForImageTextToText.from_pretrained(model_id, device_map="auto")

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/ocr_suggestion_form.jpg"},
            {"type": "text", "text": "Convert this page to markdown."},
        ],
    }
]

inputs = processor.apply_chat_template(
    messages, add_generation_prompt=True, tokenize=True,
    return_dict=True, return_tensors="pt",
    processor_kwargs={"downsample_mode": "4x"},
).to(model.device, dtype=model.dtype)

output = model.generate(**inputs, max_new_tokens=512, downsample_mode="4x")
print((inputs["input_ids"] == model.config.image_token_id).sum().item())
# 1260 visual tokens; the same page in `"16x"` mode is 315 instead

호출마다 지정하는 downsample_mode는 해당 호출에만 적용되며 프로세서 자체는 변경되지 않으므로, 동일한 프로세서로 두 가지 모드를 동시에 처리할 수 있습니다. apply_chat_template를 통해 호출하는 대신 프로세서를 직접 호출하는 경우, 일반 키워드 인수로 전달하세요:

inputs = processor(images=[image], text=[text], return_tensors="pt", downsample_mode="4x")

대신 특정 모드를 기본값으로 설정하려면 프로세서 로드 시점에 설정합니다:

processor = AutoProcessor.from_pretrained("openbmb/MiniCPM-OCR-1.0", downsample_mode="4x")

슬라이싱할 수 없을 정도로 작은 이미지는 기본적으로 scale_resolution으로 업스케일링되며, 이는 공개된 체크포인트가 학습될 때 사용된 설정입니다. 스크린샷이나 크롭 이미지는 네이티브 해상도를 유지하는 것이 글리프가 흐려지는 업스케일링보다 나은 경우가 많으므로, small_image_upsize는 두 옵션 중 하나를 선택합니다:

"always" (기본값): scale_resolution으로 업스케일링합니다.
"never": 패치 그리드에만 정렬된 채로 원본 해상도를 유지합니다.
"adaptive": 글리프의 크기와 밀도를 기준으로 이미지 및 슬라이스별로 결정합니다.

from transformers import AutoProcessor
from transformers.image_utils import load_image

url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/ocr_receipt.jpeg"
image = load_image(url).resize((224, 224))

processor = AutoProcessor.from_pretrained("openbmb/MiniCPM-OCR-1.0")
messages = [{"role": "user", "content": [{"type": "image"}, {"type": "text", "text": "Read the text."}]}]
text = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)

print(processor(images=[image], text=[text], return_tensors="pt")["target_sizes"].tolist())
# [[32, 32]] -- upscaled to `scale_resolution`

processor = AutoProcessor.from_pretrained("openbmb/MiniCPM-OCR-1.0", small_image_upsize="never")
print(processor(images=[image], text=[text], return_tensors="pt")["target_sizes"].tolist())
# [[16, 16]] -- 224 / 14 patches per side, no upscaling

"adaptive"는 작은 고밀도 텍스트를 scale_resolution로 업스케일링하고, 6272픽셀 미만인 이미지는 84로 처리하며, 나머지는 원본 해상도를 유지합니다. 슬라이스에서는 베이스라인 타일보다 더 많은 토큰을 사용하지 않습니다. 글리프 높이와 밀도는 Otsu 임계값을 적용한 후 연결 요소 분석을 통해 측정하므로, OpenCV가 필요하며 없으면 다른 규칙으로 조용히 폴백하는 대신 예외를 발생시킵니다.

processor = AutoProcessor.from_pretrained("openbmb/MiniCPM-OCR-1.0", small_image_upsize="adaptive")
print(processor(images=[image], text=[text], return_tensors="pt")["target_sizes"].tolist())
# [[32, 32]] -- dense text detected, so this one is upscaled anyway

downsample_mode와 마찬가지로, 호출별로 오버라이드할 수 있으며, 이를 통해 프로세서를 다시 로드하지 않고 224x224 영수증을 원래 해상도로 유지할 수 있습니다:

inputs = processor(images=[image], text=[text], return_tensors="pt", small_image_upsize="never")
print(inputs["target_sizes"].tolist())
# [[16, 16]] -- 224 / 14 patches per side, no upscaling

from transformers import AutoModelForImageTextToText, AutoProcessor

model_id = "openbmb/MiniCPM-OCR-1.0"
processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForImageTextToText.from_pretrained(model_id, device_map="auto")

messages = [
    [
        {
            "role": "user",
            "content": [
                {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/ocr_receipt.jpeg"},
                {"type": "text", "text": "Transcribe all the text in this document."},
            ],
        }
    ],
    [
        {
            "role": "user",
            "content": [
                {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/ocr_suggestion_form.jpg"},
                {"type": "text", "text": "Transcribe all the text in this document."},
            ],
        }
    ],
]

inputs = processor.apply_chat_template(
    messages, add_generation_prompt=True, tokenize=True,
    return_dict=True, return_tensors="pt",
    processor_kwargs={"padding": True},
).to(model.device, dtype=model.dtype)

output = model.generate(**inputs, max_new_tokens=256)
decoded_outputs = processor.batch_decode(output[:, inputs["input_ids"].shape[1]:], skip_special_tokens=True)
print(decoded_outputs[0])
# Document No : TD01167104
# Date : 25/12/2018 8:13:39 PM
# Cashier : MANIS
# ...
print(decoded_outputs[1])
# R&D QUALITY IMPROVEMENT
# SUGGESTION/SOLUTION FORM
#
# Name/Phone Ext.: M. Hamann P. Harper P. Martinez Date: 9/3/92
# Supervisor/Manager: J. S. Wigand R&D Group: Licensee
# ...

두 페이지는 독립적으로 리사이즈되므로 프롬프트 길이가 서로 다릅니다. apply_chat_template가 프로세서로 전달하려면 padding을 processor_kwargs를 통해 요청해야 하며, 프로세서는 왼쪽으로 패딩하여 generate가 각 프롬프트의 끝에서 계속 생성되도록 합니다.

Transformers

MiniCPM-OCR

사용 예시

MiniCPMOcrConfig

class transformers.MiniCPMOcrConfig

MiniCPMOcrVisionConfig

class transformers.MiniCPMOcrVisionConfig

MiniCPMOcrVisionPreTrainedModel

class transformers.MiniCPMOcrVisionPreTrainedModel

forward

MiniCPMOcrVisionModel

class transformers.MiniCPMOcrVisionModel

forward

MiniCPMOcrModel

class transformers.MiniCPMOcrModel

forward

get_image_features

get_video_features

MiniCPMOcrForConditionalGeneration

class transformers.MiniCPMOcrForConditionalGeneration

forward

get_image_features

get_video_features

MiniCPMOcrProcessor

클래스 transformers.MiniCPMOcrProcessor

__call__

MiniCPMOcrImageProcessor

class transformers.MiniCPMOcrImageProcessor

preprocess

MiniCPMOcrVideoProcessor

클래스 transformers.MiniCPMOcrVideoProcessor

preprocess

call