Transformers documentation

MiniCPM-V 4.7

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-09-21에 Hugging Face Transformers에 기여되었습니다.

MiniCPM-V 4.7

MiniCPM-V는 OpenBMB에서 개발한 효율적인 멀티모달 대규모 언어 모델 시리즈입니다. MiniCPM-V 4.6와 마찬가지로, MiniCPM-V 4.7 아키텍처는 윈도우 어텐션 머저를 갖춘 SigLIP 비전 인코더와 Qwen3.5 언어 모델 백본을 결합하며, 4x 및 16x 시각 다운샘플링 모드를 모두 지원합니다.

4.6 버전 이후의 주요 추가 기능은 canvas M-RoPE입니다. 시각 토큰을 단일 1차원 시퀀스 순서로 번호를 매기는 대신, 모델은 모든 이미지를 2차원 캔버스에 배치하고 각 시각 토큰에 (temporal, height, width) 위치를 부여합니다. 이를 통해 동일한 이미지의 조각들은 공간적 관계를 유지하고, 비디오 프레임들은 시간적 순서를 유지합니다.

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

use_image_id를 프로세서에 전달하면 하나의 프롬프트에 포함된 여러 이미지에 번호를 매겨 텍스트가 각 이미지를 개별적으로 참조할 수 있습니다. 이 설정은 이미지에만 적용됩니다. 비디오는 여러 개의 참조 가능한 시각 요소가 아니라 프레임의 단일 시간적 시퀀스이며, 모델이 학습된 방식이 바로 이렇기 때문에 비디오 입력의 경우 이 설정은 무시됩니다.

사용 예시

Pipeline을 사용한 추론

from transformers import pipeline

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "image",
                "image": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/bee.jpg",
            },
            {"type": "text", "text": "Describe this image."},
        ],
    },
]

pipe = pipeline("image-text-to-text", model="openbmb/MiniCPM-V-4.7-1B")
outputs = pipe(text=messages, max_new_tokens=50, return_full_text=False)
outputs[0]["generated_text"]

단일 이미지에서 추론

from transformers import AutoProcessor, AutoModelForImageTextToText

model_checkpoint = "openbmb/MiniCPM-V-4.7-1B"
processor = AutoProcessor.from_pretrained(model_checkpoint)
model = AutoModelForImageTextToText.from_pretrained(model_checkpoint, device_map="auto")

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
            {"type": "text", "text": "Describe this image."},
        ],
    }
]

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

output = model.generate(**inputs, max_new_tokens=100)
decoded_output = processor.decode(output[0, inputs["input_ids"].shape[1]:], skip_special_tokens=True)
print(decoded_output)

다운샘플링 모드

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

16x (기본값): 더 공격적인 다운샘플링, 더 적은 시각 토큰, 더 빠른 추론.
4x: 다운샘플링이 적고 시각 토큰이 많아 세부 정보가 많은 작업에 더 적합합니다.

processor_kwargs와 model.generate에 downsample_mode를 전달하여 런타임에 다운샘플링 모드를 변경할 수 있습니다:

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=100, downsample_mode="4x")

생각 모드

모델은 채팅 템플릿의 enable_thinking으로 제어되는 사고(thinking) 모드를 지원합니다. 활성화되면 모델은 최종 답변을 제공하기 전에 내부 추론을 생성합니다:

inputs = processor.apply_chat_template(
    messages, add_generation_prompt=True, tokenize=True,
    return_dict=True, return_tensors="pt",
    enable_thinking=True,
).to(model.device, dtype=model.dtype)

output = model.generate(**inputs, max_new_tokens=1024)

생각(thinking)을 비활성화하려면(평가 기본값):

inputs = processor.apply_chat_template(
    messages, add_generation_prompt=True, tokenize=True,
    return_dict=True, return_tensors="pt",
    enable_thinking=False,
).to(model.device, dtype=model.dtype)

비디오 추론

MiniCPM-V 4.7은 비디오 이해를 지원합니다.

messages = [
    {
        "role": "user",
        "content": [
            {"type": "video", "video": "path/to/video.mp4"},
            {"type": "text", "text": "Describe what happens in this video."},
        ],
    }
]

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

output = model.generate(**inputs, max_new_tokens=200)
decoded_output = processor.decode(output[0, inputs["input_ids"].shape[1]:], skip_special_tokens=True)
print(decoded_output)

Transformers

MiniCPM-V 4.7

사용 예시

Pipeline을 사용한 추론

단일 이미지에서 추론

다운샘플링 모드

생각 모드

비디오 추론

MiniCPMV4_7Config

class transformers.MiniCPMV4_7Config

MiniCPMV4_7VisionConfig

class transformers.MiniCPMV4_7VisionConfig

MiniCPMV4_7VisionPreTrainedModel.

class transformers.MiniCPMV4_7VisionPreTrainedModel

forward

MiniCPMV4_7VisionModel

class transformers.MiniCPMV4_7VisionModel

forward

MiniCPMV4_7Model

class transformers.MiniCPMV4_7Model

forward

get_image_features

get_video_features

MiniCPMV4_7ForConditionalGeneration

클래스 transformers.MiniCPMV4_7ForConditionalGeneration

forward

get_image_features

get_video_features

MiniCPMV4_7Processor

클래스 transformers.MiniCPMV4_7Processor

__call__

call