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.2).

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

Mô hình này được công bố trên HF papers vào ngày 16-09-2025 và được đóng góp cho Hugging Face Transformers vào ngày 26-10-2026.

MiniCPM-OCR

MiniCPM-OCR là một mô hình hiểu tài liệu thuộc dòng MiniCPM-V do OpenBMB phát triển. Nó giữ nguyên kiến trúc MiniCPM-V 4.6 — một bộ mã hóa thị giác SigLIP với bộ hợp nhất chú ý cửa sổ đặt trước mô hình ngôn ngữ Qwen3.5 — và được chuyên biệt hóa để đọc các hình ảnh chứa nhiều văn bản như trang quét, ảnh chụp màn hình, hóa đơn và bảng biểu.

Mô hình này được đóng góp bởi OpenBMB. Mã nguồn gốc có thể được tìm thấy tại đây.

Ví dụ sử dụng

Suy luận với Pipeline

Suy luận trên một hình ảnh

Chế độ giảm mẫu

Đổi kích thước ảnh nhỏ

Suy luận theo lô

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 hỗ trợ cả hai chế độ giảm mẫu hình ảnh của dòng MiniCPM-V:

4x (mặc định): Ít hạ mẫu hơn, nhiều token thị giác hơn, đây là điều cần thiết cho việc chuyển đổi văn bản từ tài liệu và ảnh chụp màn hình.
16x: Giảm mẫu (downsampling) mạnh hơn, ít token thị giác hơn, suy luận nhanh hơn trên các hình ảnh tự nhiên.

Chế độ phải được truyền cho bộ xử lý và cho model.generate cùng lúc, vì bộ xử lý đếm các vị trí giữ chỗ hình ảnh mà tháp thị giác được kỳ vọng sẽ tạo ra:

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

Mỗi lần gọi downsample_mode chỉ áp dụng cho lần gọi đó và không làm thay đổi bộ xử lý, do đó cùng một bộ xử lý có thể phục vụ cả hai chế độ đồng thời. Khi gọi bộ xử lý trực tiếp thay vì thông qua apply_chat_template, hãy truyền nó như một đối số từ khóa thông thường:

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

Để đặt một chế độ làm mặc định, hãy thiết lập nó khi nạp bộ xử lý:

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

Các hình ảnh quá nhỏ để được cắt sẽ được phóng to lên scale_resolution theo mặc định, đây là cài đặt mà checkpoint đã phát hành được huấn luyện với. Ảnh chụp màn hình và ảnh cắt thường nên giữ ở độ phân giải gốc, vì việc phóng to chỉ làm mờ các ký tự, do đó small_image_upsize cho phép chọn giữa hai phương án:

"always" (mặc định): phóng to chúng lên scale_resolution.
"never": giữ chúng ở độ phân giải gốc, chỉ căn chỉnh theo lưới patch.
"adaptive": quyết định theo từng hình ảnh và từng lát cắt, dựa trên kích thước và mật độ của glyph.

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" phóng to văn bản đặc nhỏ lên scale_resolution, các ảnh dưới 6272 pixel lên 84, và giữ nguyên độ phân giải gốc cho phần còn lại; trên một lát cắt, nó không bao giờ tiêu tốn nhiều token hơn so với ô chuẩn. Chiều cao và mật độ của ký tự được đo bằng ngưỡng Otsu kết hợp với phân tích thành phần liên thông, do đó nó yêu cầu OpenCV và sẽ gây lỗi nếu thiếu thư viện này, thay vì âm thầm chuyển sang một quy tắc khác.

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

Tương tự như downsample_mode, tham số này cũng có thể được ghi đè cho từng lần gọi, giúp giữ nguyên độ phân giải gốc 224x224 của phiếu biên nhận mà không cần nạp lại bộ xử lý:

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
# ...

Hai trang được thay đổi kích thước độc lập, nên prompt của chúng có độ dài khác nhau. padding phải được yêu cầu thông qua processor_kwargs để apply_chat_template chuyển tiếp nó đến processor, và processor sẽ đệm ở phía bên trái để generate tiếp tục tạo ra từ cuối mỗi prompt.

Transformers

MiniCPM-OCR

Ví dụ sử dụng

MiniCPMOcrConfig

lớp transformers.MiniCPMOcrConfig

MiniCPMOcrVisionConfig

lớp transformers.MiniCPMOcrVisionConfig

MiniCPMOcrVisionPreTrainedModel

lớp transformers.MiniCPMOcrVisionPreTrainedModel

forward

MiniCPMOcrVisionModel

lớp transformers.MiniCPMOcrVisionModel

forward

MiniCPMOcrModel

lớp transformers.MiniCPMOcrModel

forward

get_image_features

get_video_features

MiniCPMOcrForConditionalGeneration

lớp transformers.MiniCPMOcrForConditionalGeneration

forward

get_image_features

get_video_features

MiniCPMOcrProcessor

lớp transformers.MiniCPMOcrProcessor

__call__

MiniCPMOcrImageProcessor

lớp transformers.MiniCPMOcrImageProcessor

preprocess

MiniCPMOcrVideoProcessor

lớp transformers.MiniCPMOcrVideoProcessor

preprocess

call