Transformers documentation

MiniCPM-OCR

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

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

نُشر هذا النموذج في أوراق HF في 16 سبتمبر 2025، وأُضيف إلى مكتبة Hugging Face Transformers في 26 أكتوبر 2026.

MiniCPM-OCR

MiniCPM-OCR هو نموذج لفهم المستندات من عائلة MiniCPM-V الذي طوّره OpenBMB. يحتفظ ببنية MiniCPM-V 4.6 — وهي مشفّر بصري SigLIP مع مُدمج انتباه نافذوي أمام نموذج لغوي Qwen3.5 — ويُخصّصه لقراءة الصور الكثيفة بالنص مثل الصفحات الممسوحة ضوئيًا، ولقطات الشاشة، والفواتير، والجداول.

تمت مساهمة هذا النموذج من قِبل 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 كلا وضعي التقليل البصري (visual downsampling) لعائلة MiniCPM-V:

4x (الافتراضي): تقليل نسبة التقليل، وزيادة عدد الرموز البصرية، وهو ما تتطلبه عمليات نسخ المستندات ولقطات الشاشة.
16x: نزع عينات أكثر عدوانية، ورموز بصرية أقل، واستدلال أسرع على الصور الطبيعية.

يجب تمرير الوضع إلى المعالج وإلى 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، ويُبقي الباقي بحجمه الأصلي؛ وفي أي مقطع، لا يستهلك عددًا من الرموز يتجاوز ما كان سيستهمله البلاط الأساسي. تُقاس ارتفاع الحروف وكثافتها باستخدام عتبة أوتسو تليها تحليل المكونات المتصلة، لذا يتطلب الأمر 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
# ...

تُعاد تصغير الصفحتين بشكل مستقل، لذا فإن تدرجاتهما (prompts) لها أطوال مختلفة. يجب طلب padding عبر processor_kwargs حتى يقوم apply_chat_template بتحويله إلى المعالج (processor)، ويقوم المعالج بتعبئة الجانب الأيسر حتى يستمر generate في الإنتاج من نهاية كل تدرج.

Transformers

MiniCPM-OCR

مثال على الاستخدام

MiniCPMOcrConfig

فئة transformers.MiniCPMOcrConfig

MiniCPMOcrVisionConfig

فئة transformers.MiniCPMOcrVisionConfig

MiniCPMOcrVisionPreTrainedModel

فئة transformers.MiniCPMOcrVisionPreTrainedModel

forward

MiniCPMOcrVisionModel

فئة transformers.MiniCPMOcrVisionModel

forward

MiniCPMOcrModel

فئة transformers.MiniCPMOcrModel

forward

get_image_features

get_video_features

MiniCPMOcrForConditionalGeneration

فئة transformers.MiniCPMOcrForConditionalGeneration

forward

get_image_features

get_video_features

MiniCPMOcrProcessor

فئة transformers.MiniCPMOcrProcessor

__call__

MiniCPMOcrImageProcessor

فئة transformers.MiniCPMOcrImageProcessor

preprocess

MiniCPMOcrVideoProcessor

فئة transformers.MiniCPMOcrVideoProcessor

preprocess

call