Transformers documentation
MiniCPM-V 4.7
该模型于 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：模型不再将视觉标记沿单一的一维序列进行编号，而是将每张图片布局在一个二维画布上，并为每个视觉标记分配一个 (temporal, height, width) 位置，从而确保同一张图片的切片保持其空间关系，视频帧保持其时间顺序。
将
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（默认）：更激进的降采样，更少的视觉 token，更快的推理速度。
- 4x：下采样更少，视觉 token 更多，更适合细节丰富的任务。
您可以通过在 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 控制的思考模式。启用后，模型会在给出最终答案之前生成内部推理过程：
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)要禁用思考（评估时的默认设置）：
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)MiniCPMV4_7Config
class transformers.MiniCPMV4_7Config
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonetext_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneinsert_layer_id: int = 6image_size: int = 448image_token_id: int | None = Nonevideo_token_id: int | None = Nonetie_word_embeddings: bool = Falsedownsample_mode: str = '16x'merge_kernel_size: tuple[int, int] | list[int] = (2, 2)merger_times: int = 1image_start_id: int | None = Noneimage_end_id: int | None = Noneslice_start_id: int | None = Noneslice_end_id: int | None = Nonenewline_id: int | None = None )
参数
- text_config (
Union[dict, ~configuration_utils.PreTrainedConfig]，可选) — 文本骨干网络的配置对象或字典。 - vision_config (
Union[dict, ~configuration_utils.PreTrainedConfig]，可选) — 视觉骨干网络的配置对象或字典。 - insert_layer_id (
int，可选，默认为 6) — 应用窗口注意力合并器的视觉编码器层索引。 - image_size (
int，可选，默认为448) — 每张图片的尺寸（分辨率）。 - image_token_id (
int, 可选) — 用作输入图像占位符的图像 token 索引。 - video_token_id (
int, 可选) — 用作输入视频占位符的视频 token 索引。 - tie_word_embeddings (
bool，可选，默认为False) — 是否根据模型的tied_weights_keys映射来绑定权重嵌入。 - downsample_mode (
str，可选，默认为"16x") — 视觉 token 的下采样比例。"4x"会保留 4 倍数量的 token。 - merge_kernel_size (
tuple[int, int]，可选，默认为(2, 2)) — 用于在 Merger 中合并相邻视觉 patch 的卷积核大小(h, w)。 - merger_times (
int，可选，默认为 1) — Merger 中迭代合并轮次的数量。 - image_start_id (
int, 可选) — 图像起始标记（<image>）的 Token id。Canvas M-RoPE 将其固定在图像画布左上角外侧的 halo 位置。该值由转换脚本从 tokenizer 中解析并存储在config.json中；对于图像或视频输入，此项为必填。 - image_end_id (
int, 可选) — 图像结束标记的 Token id（</image>）。Canvas M-RoPE 会将其固定在图像画布的远角。该值由转换脚本从 tokenizer 中解析并存储在config.json中；对于图像或视频输入，此项为必填。 - slice_start_id (
int, 可选) — 切片起始标记（<slice>）的 Token id。Canvas M-RoPE 会将其固定在其所开启的切片的左上角。该值由转换脚本从分词器中解析，并存储在config.json中；对于图像或视频输入，此项为必填。 - slice_end_id (
int，可选) — 切片结束标记的 Token id（</slice>）。Canvas M-RoPE 会将其固定在其所关闭的切片的右下角。该值由转换脚本从分词器中解析，并存储在config.json中；对于图像或视频输入，此项为必填。 - newline_id (
int, 可选) — 用于分隔切片行的换行符（"\n"）的 Token id。Canvas M-RoPE 会将其固定在其结束行的右边缘稍外侧。该值由转换脚本从 tokenizer 中解析并存储在config.json中；对于图像或视频输入，此项为必填。
这是用于存储 MiniCPMV4_7Model 配置的类。它根据指定的参数实例化 Minicpmv4 7 模型，并定义模型架构。使用默认值实例化配置将得到与 openbmb/MiniCPM-V-4.7-1B 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
MiniCPMV4_7VisionConfig
class transformers.MiniCPMV4_7VisionConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 768intermediate_size: int = 3072num_hidden_layers: int = 12num_attention_heads: int = 12num_channels: int = 3image_size: int | list[int] | tuple[int, int] = 224patch_size: int | list[int] | tuple[int, int] = 16hidden_act: str = 'gelu_pytorch_tanh'layer_norm_eps: float = 1e-06attention_dropout: float | int = 0.0insert_layer_id: int = 6window_kernel_size: tuple[int, int] | list[int] = (2, 2) )
参数
- hidden_size (
int，可选，默认为768) — 隐藏表示的维度。 - intermediate_size (
int，可选，默认为3072) — MLP 表示的维度。 - num_hidden_layers (
int, 可选, 默认为12) — Transformer 解码器中的隐藏层数量。 - num_attention_heads (
int，可选，默认为12) — Transformer 解码器中每个注意力层的注意力头数量。 - num_channels (
int，可选，默认为3) — 输入通道的数量。 - image_size (
Union[int, list[int], tuple[int, int]]，可选，默认为224) — 每张图片的尺寸（分辨率）。 - patch_size (
Union[int, list[int], tuple[int, int]]，可选，默认为16) — 每个 patch 的大小（分辨率）。 - hidden_act (
str，可选，默认为gelu_pytorch_tanh) — 解码器中的非线性激活函数（函数或字符串）。例如，"gelu"、"relu"、"silu"等。 - layer_norm_eps (
float，可选，默认为1e-06) — 层归一化层所使用的 epsilon 值。 - attention_dropout (
Union[float, int]，可选，默认为0.0) — 注意力概率的 dropout 比率。 - insert_layer_id (
int，可选，默认为 6) — 应用窗口注意力合并器的视觉编码器层索引。 - window_kernel_size (
tuple[int, int]，可选，默认为(2, 2)) — 中间窗口注意力合并器的窗口大小(h, w)。
这是用于存储 MiniCPMV4_7Model 配置的类。它根据指定的参数实例化 Minicpmv4 7 模型，并定义模型架构。使用默认值实例化配置将得到与 openbmb/MiniCPM-V-4.7-1B 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
MiniCPMV4_7VisionPreTrainedModel.
class transformers.MiniCPMV4_7VisionPreTrainedModel
< source >( config: PreTrainedConfig*inputs**kwargs )
MiniCPMV4_7VisionModel
forward
< source >( pixel_valuestarget_sizes: typing.Optional[torch.IntTensor] = Noneuse_vit_merger: bool = True**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
参数
- pixel_values (`
of shape(batch_size, num_channels, image_size, image_size)`) — 与输入图像对应的张量。可以使用 MiniCPMV4_6ImageProcessor 获取像素值。有关详细信息，请参阅 MiniCPMV4_6ImageProcessor.call()（MiniCPMV4_7Processor 使用 MiniCPMV4_6ImageProcessor 处理图像）。 - target_sizes (
torch.IntTensor，形状为(batch_size, 2)，可选) — 用于计算位置嵌入的补丁网格大小(h, w)。 - use_vit_merger (
bool，可选，默认为True) — 是否在编码器之后应用 ViT 窗口注意力合并器。
返回值
BaseModelOutputWithPooling 或 tuple(torch.Tensor)
一个 BaseModelOutputWithPooling 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（MiniCPMV4_7Config）和输入。
MiniCPMV4_7VisionModel 的 forward 方法会重写 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor）— 模型最后一层输出的隐藏状态序列。pooler_output (
torch.Tensor，形状为(batch_size, hidden_size)) — 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后得到。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测（分类）目标进行训练。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
MiniCPMV4_7Model
class transformers.MiniCPMV4_7Model
< source >( config: MiniCPMV4_7Config )
参数
- config (MiniCPMV4_7Config) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
MiniCPMV4_7 模型由视觉主干网络和语言模型组成，不包含语言建模头。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Nonetarget_sizes: typing.Optional[torch.IntTensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Nonetarget_sizes_videos: typing.Optional[torch.IntTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: list[torch.Tensor] | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = Nonedownsample_mode: str | None = Nonemm_token_type_ids: typing.Optional[torch.IntTensor] = Nonemm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPast or tuple(torch.Tensor)
参数
- input_ids (
torch.LongTensor形状为(batch_size, sequence_length), ，可选) — 输入序列中各 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- pixel_values (
torch.Tensor, 可选) — 图像的像素值补丁，采用 NaViT 打包格式。 - target_sizes (
torch.IntTensor，可选) — 每张图片的高度和宽度（以 patch 为单位）。 - pixel_values_videos (
torch.Tensor, 可选) — 视频帧的像素值补丁，采用 NaViT 打包格式。 - target_sizes_videos (
torch.IntTensor, 可选) — 每个视频帧的高度和宽度（以 patch 为单位）。 - attention_mask (
torch.Tensor形状为(batch_size, sequence_length), ，可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自[0, 1]:- 1 表示未被屏蔽的 token，
- 对于被掩码的 token，值为 0。
- position_ids (
torch.LongTensor形状为(batch_size, sequence_length), 可选) — 输入序列中每个 token 在位置嵌入中的位置索引。取值范围为[0, config.n_positions - 1]. - past_key_values (
list[torch.Tensor], 可选) — 预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由past_key_values在解码的先前阶段返回，当use_cache=True或config.use_cache=True.仅允许将 Cache 实例作为输入，请参阅我们的 kv cache 指南。 如果未传入
past_key_values，则默认会初始化 DynamicCache。模型将输出与输入相同的缓存格式。
如果使用了
past_key_values，用户应仅输入未处理的input_ids（即未向该模型提供其过去键值状态的那些），其形状为(batch_size, unprocessed_length)，而不是形状为(batch_size, sequence_length)的全部input_ids。 - inputs_embeds（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor，可选） — 可选地，您可以选择直接传入嵌入表示，而不是传入input_ids。如果您希望对input_ids索引如何转换为相应向量拥有比模型内部嵌入查找矩阵更多的控制权，这将非常有用。 - use_cache (
bool，可选) — 如果设置为True，则会返回past_key_values键值状态，可用于加速解码（参见past_key_values）。 - downsample_mode (
str，可选) —"4x"保留 4 倍数量的视觉 token；默认值"16x"应用完全合并。 - mm_token_type_ids (
torch.IntTensor，形状为(batch_size, sequence_length)，可选) — 输入序列中匹配每种模态的 token 索引。例如文本 (0)、图像 (1)、视频 (2)。 可通过 AutoProcessor 获取多模态 token 类型 id。详情请参见 ProcessorMixin.call()。 - mm_encoder_outputs (
dict[str, ~modeling_outputs.BaseModelOutputWithPooling], 可选) — 一个字典，其中键为支持的模态，值为该模态的编码输出。每个编码输出是一个元组，由 (pooler_output、可选：last_hidden_states、可选：hidden_states、可选：attentions)pooler_output，形状为(batch_size, sequence_length, hidden_size)，可选) 组成，它是编码器融合到文本嵌入中的多模态特征序列。
返回值
BaseModelOutputWithPast 或 tuple(torch.Tensor)
一个 BaseModelOutputWithPast 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（MiniCPMV4_7Config）和输入。
MiniCPMV4_7Model 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor）— 模型最后一层输出的隐藏状态序列。如果使用了
past_key_values，则仅输出形状为(batch_size, 1, hidden_size)的序列的最后一个隐藏状态。past_key_values（
Cache，可选，在传入use_cache=True或config.use_cache=True时返回）—— 它是一个 Cache 实例。更多详情，请参阅我们的 kv cache 指南。包含预计算的隐藏状态（自注意力块中的键和值，以及如果
config.is_encoder_decoder=True则还包括交叉注意力块中的键和值），可用于（参见past_key_values输入）加速顺序解码。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
get_image_features
< source >( pixel_values: Tensortarget_sizes: IntTensordownsample_mode: str | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
参数
- pixel_values (
torch.Tensor，形状为(batch_size, num_channels, image_size, image_size)) — 与输入图像对应的张量。可以使用 MiniCPMV4_6ImageProcessor 获取像素值。有关详细信息，请参阅 MiniCPMV4_6ImageProcessor.call()（MiniCPMV4_7Processor 使用 MiniCPMV4_6ImageProcessor 来处理图像）。 - target_sizes（形状为
(num_images, 2)的torch.IntTensor）— 每张图片的高度和宽度（以 patch 为单位）。 - downsample_mode (
str, 可选) — 当设置为"4x"时，会跳过中间的vit_merger，从而使每张图像保留4×倍的视觉 token。默认的"16x"模式会应用完整的合并流程。
返回值
BaseModelOutputWithPooling 或 tuple(torch.Tensor)
一个 BaseModelOutputWithPooling 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（MiniCPMV4_7Config）和输入。
提取图像特征：视觉编码器，插入合并器，然后是 MLP 合并器。
last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor）— 模型最后一层输出的隐藏状态序列。pooler_output (
torch.Tensor，形状为(batch_size, hidden_size)) — 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后得到。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测（分类）目标进行训练。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
get_video_features
< source >( pixel_values_videos: Tensortarget_sizes_videos: IntTensordownsample_mode: str | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
参数
- pixel_values_videos (
torch.Tensor，形状为(1, channels, patch_size, seq_len)) — 所有视频帧的 NaViT 打包像素块。视频处理器将每一帧的块沿最后一个维度拼接为一个序列，其中 dim-0 = 1，与图像打包格式完全相同。 - target_sizes_videos（形状为
(num_patches, 2)的torch.IntTensor）— 每个视觉单元的高度和宽度（以 patch 为单位）。 - downsample_mode (
str, 可选) — 当设置为"4x"时，会跳过中间的vit_merger，使每帧保留4×倍的视觉 token。默认的"16x"模式会应用完整的合并流程。
返回值
BaseModelOutputWithPooling 或 tuple(torch.Tensor)
一个 BaseModelOutputWithPooling 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（MiniCPMV4_7Config）和输入。
提取视频特征：将帧重新打包为 NaViT 格式，然后使用视觉编码器 + 合并器。
last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor）— 模型最后一层输出的隐藏状态序列。pooler_output (
torch.Tensor，形状为(batch_size, hidden_size)) — 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后得到。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测（分类）目标进行训练。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
MiniCPMV4_7ForConditionalGeneration
class transformers.MiniCPMV4_7ForConditionalGeneration
< source >( config: MiniCPMV4_7Config )
参数
- config (MiniCPMV4_7Config) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
用于基于其他模态（例如图像-文本到文本生成）进行 token 生成的 Minicpmv4 7 模型。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Nonetarget_sizes: typing.Optional[torch.IntTensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Nonetarget_sizes_videos: typing.Optional[torch.IntTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: list[torch.Tensor] | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Nonedownsample_mode: str | None = Nonemm_token_type_ids: typing.Optional[torch.IntTensor] = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → CausalLMOutputWithPast or tuple(torch.Tensor)
参数
- input_ids (
torch.LongTensor形状为(batch_size, sequence_length), ，可选) — 输入序列中各 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- pixel_values (
torch.Tensor, 可选) — 图像的像素值补丁，采用 NaViT 打包格式。 - target_sizes (
torch.IntTensor，可选) — 每张图片的高度和宽度（以 patch 为单位）。 - pixel_values_videos (
torch.Tensor, 可选) — 视频帧的像素值补丁，采用 NaViT 打包格式。 - target_sizes_videos (
torch.IntTensor, 可选) — 每个视频帧的高度和宽度（以 patch 为单位）。 - attention_mask (
torch.Tensor形状为(batch_size, sequence_length), ，可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自[0, 1]:- 1 表示未被屏蔽的 token，
- 对于被掩码的 token，值为 0。
- position_ids (
torch.LongTensor形状为(batch_size, sequence_length), 可选) — 输入序列中每个 token 在位置嵌入中的位置索引。取值范围为[0, config.n_positions - 1]. - past_key_values (
list[torch.Tensor], 可选) — 预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由past_key_values在解码的先前阶段返回，当use_cache=True或config.use_cache=True.仅允许将 Cache 实例作为输入，请参阅我们的 kv cache 指南。 如果未传入
past_key_values，则默认会初始化 DynamicCache。模型将输出与输入相同的缓存格式。
如果使用了
past_key_values，用户应仅输入未处理的input_ids（即未向该模型提供其过去键值状态的那些），其形状为(batch_size, unprocessed_length)，而不是形状为(batch_size, sequence_length)的全部input_ids。 - inputs_embeds（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor，可选） — 可选地，您可以选择直接传入嵌入表示，而不是传入input_ids。如果您希望对input_ids索引如何转换为相应向量拥有比模型内部嵌入查找矩阵更多的控制权，这将非常有用。 - labels (
torch.LongTensor，形状为(batch_size, sequence_length)，可选) — 用于计算掩码语言建模损失的标签。索引值应在[0, ..., config.vocab_size]范围内，或为 -100（参见input_ids的文档字符串）。索引值设为-100的 token 将被忽略（即被掩码），损失仅针对标签位于[0, ..., config.vocab_size]范围内的 token 进行计算。 - use_cache (
bool，可选) — 如果设置为True，则会返回past_key_values键值状态，可用于加速解码（参见past_key_values）。 - downsample_mode (
str，可选) —"4x"保留 4 倍数量的视觉 token；默认值"16x"应用完全合并。 - mm_token_type_ids (
torch.IntTensor，形状为(batch_size, sequence_length)，可选) — 输入序列中匹配每种模态的 token 索引。例如文本 (0)、图像 (1)、视频 (2)。 可通过 AutoProcessor 获取多模态 token 类型 id。详情请参见 ProcessorMixin.call()。 - logits_to_keep (
Union[int, torch.Tensor], 可选，默认为0) — 如果为int，则计算最后logits_to_keep个 token 的 logits。如果为0，则计算所有input_ids的 logits（特殊情况）。生成过程只需要最后一个 token 的 logits，仅针对该 token 进行计算可以节省内存，对于长序列或大词汇量而言，这种节省相当显著。 如果为torch.Tensor，则必须是一维张量，对应于序列长度维度中需要保留的索引。 这在使用打包张量格式（将批次和序列长度合并为单一维度）时非常有用。 - mm_encoder_outputs (
dict[str, ~modeling_outputs.BaseModelOutputWithPooling], 可选) — 一个字典，其中键为支持的模态，值为该模态的编码输出。每个编码输出是一个元组，由 (pooler_output、可选：last_hidden_states、可选：hidden_states、可选：attentions)pooler_output，形状为(batch_size, sequence_length, hidden_size)，可选) 组成，它是编码器融合到文本嵌入中的多模态特征序列。
返回值
CausalLMOutputWithPast 或 tuple(torch.Tensor)
一个 CausalLMOutputWithPast 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（MiniCPMV4_7Config）和输入。
MiniCPMV4_7ForConditionalGeneration 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
loss (
torch.Tensor，形状为(1,)，可选，当提供labels时返回) — 语言建模损失（用于下一个 token 预测）。logits（形状为
(batch_size, sequence_length, config.vocab_size)的torch.Tensor）— 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。past_key_values（
Cache，可选，在传入use_cache=True或config.use_cache=True时返回）—— 它是一个 Cache 实例。更多详情，请参阅我们的 kv cache 指南。包含预计算的隐藏状态（自注意力块中的键和值），可用于（参见
past_key_values输入）加速顺序解码。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
示例：
>>> from PIL import Image
>>> from transformers import AutoProcessor, MiniCPMV4_7ForConditionalGeneration
>>> model = MiniCPMV4_7ForConditionalGeneration.from_pretrained("openbmb/MiniCPM-V-4.7-1B")
>>> processor = AutoProcessor.from_pretrained("openbmb/MiniCPM-V-4.7-1B")
>>> messages = [
... {
... "role": "user", "content": [
... {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
... {"type": "text", "text": "Where is the cat standing?"},
... ]
... },
... ]
>>> inputs = processor.apply_chat_template(
... messages,
... tokenize=True,
... return_dict=True,
... return_tensors="pt",
... add_generation_prompt=True
... )
>>> # Generate
>>> generate_ids = model.generate(**inputs)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True)[0]get_image_features
< source >( *args**kwargs ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
返回值
BaseModelOutputWithPooling 或 tuple(torch.Tensor)
一个 BaseModelOutputWithPooling 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（MiniCPMV4_7Config）和输入。
提取图像特征：视觉编码器，插入合并器，然后是 MLP 合并器。
last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor）— 模型最后一层输出的隐藏状态序列。pooler_output (
torch.Tensor，形状为(batch_size, hidden_size)) — 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后得到。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测（分类）目标进行训练。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
示例：
>>> from PIL import Image
>>> from transformers import AutoProcessor, MiniCPMV4_7ForConditionalGeneration
>>> model = MiniCPMV4_7ForConditionalGeneration.from_pretrained("openbmb/MiniCPM-V-4.7-1B")
>>> processor = AutoProcessor.from_pretrained("openbmb/MiniCPM-V-4.7-1B")
>>> messages = [
... {
... "role": "user", "content": [
... {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
... {"type": "text", "text": "Where is the cat standing?"},
... ]
... },
... ]
>>> inputs = processor.apply_chat_template(
... messages,
... tokenize=True,
... return_dict=True,
... return_tensors="pt",
... add_generation_prompt=True
... )
>>> # Generate
>>> generate_ids = model.generate(**inputs)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True)[0]get_video_features
< source >( *args**kwargs ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
返回值
BaseModelOutputWithPooling 或 tuple(torch.Tensor)
一个 BaseModelOutputWithPooling 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（MiniCPMV4_7Config）和输入。
提取视频特征：将帧重新打包为 NaViT 格式，然后使用视觉编码器 + 合并器。
last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor）— 模型最后一层输出的隐藏状态序列。pooler_output (
torch.Tensor，形状为(batch_size, hidden_size)) — 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后得到。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测（分类）目标进行训练。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
示例：
>>> from PIL import Image
>>> from transformers import AutoProcessor, MiniCPMV4_7ForConditionalGeneration
>>> model = MiniCPMV4_7ForConditionalGeneration.from_pretrained("openbmb/MiniCPM-V-4.7-1B")
>>> processor = AutoProcessor.from_pretrained("openbmb/MiniCPM-V-4.7-1B")
>>> messages = [
... {
... "role": "user", "content": [
... {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
... {"type": "text", "text": "Where is the cat standing?"},
... ]
... },
... ]
>>> inputs = processor.apply_chat_template(
... messages,
... tokenize=True,
... return_dict=True,
... return_tensors="pt",
... add_generation_prompt=True
... )
>>> # Generate
>>> generate_ids = model.generate(**inputs)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True)[0]MiniCPMV4_7Processor
class transformers.MiniCPMV4_7Processor
< source >( image_processor = Nonevideo_processor = Nonetokenizer = Nonechat_template = None**kwargs )
构建一个 MiniCPMV4_7Processor，它将图像处理器、视频处理器和分词器封装为单一处理器。
MiniCPMV4_7Processor 提供了 MiniCPMV4_6ImageProcessor、MiniCPMV4_6VideoProcessor 和 TokenizersBackend 的所有功能。有关更多信息，请参阅 ~MiniCPMV4_6ImageProcessor、~MiniCPMV4_6VideoProcessor 和 ~TokenizersBackend。
__call__
< source >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = None**kwargs: *<class 'transformers.models.minicpmv4_7.processing_minicpmv4_7.MiniCPMV4_7ProcessorKwargs'> )
参数
- images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], 可选) — 要预处理的图像。期望输入单张图像或一批图像，其像素值范围为 0 到 255。如果传入的图像像素值在 0 到 1 之间，请设置 do_rescale=False。
- text (Union[str, list[str], list[list[str]]], optional) — The sequence or batch of sequences to be encoded. Each sequence can be a string or a list of strings (pretokenized string). If you pass a pretokenized input, set is_split_into_words=True to avoid ambiguity with batched inputs.
- videos (Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]], optional) — 要预处理的视频。期望输入单个视频或一批视频，其像素值范围为 0 到 255。如果传入的像素值在 0 到 1 之间，请设置 do_rescale=False。
- return_mm_token_type_ids (bool, kwargs) — 是否返回多模态 token 类型 id，以指示多模态占位符 token 的位置。
- return_text_replacement_offsets (bool, kwargs) — 是否返回每个多模态占位符及其替换内容的字符偏移量。
- use_image_id (bool, kwargs, optional) —
是否在每个图像占位符前添加图像 ID 标签（
<image_id>N</image_id>）。如果未设置，则默认为图像处理器的 use_image_id。 - return_tensors (str 或 [~utils.TensorType], ，可选) —
如果设置，将返回特定框架的张量。可接受的值为：
- ‘pt’：返回 PyTorch torch.Tensor 对象。
- ‘np’：返回 NumPy np.ndarray 对象。
- **kwargs ([ProcessingKwargs], 可选) — 每种模态（文本、图像、视频、音频）的额外处理选项。模型特定参数已在上方列出；有关支持参数的完整列表，请参阅 TypedDict 类。