Transformers documentation

Granite4Vision

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

该模型于 2026-05-05 贡献至 Hugging Face Transformers。

Granite4Vision

Granite Vision 4.1 是 IBM Research 推出的一款视觉语言模型，专为面向企业级文档的数据提取而设计。它擅长图表提取（Chart2CSV、Chart2Summary、Chart2Code）、表格提取（JSON、HTML、OTSL）以及语义键值对提取。

该模型基于 LLaVA-NeXT，并引入了多项架构创新：

SigLIP2 视觉编码器（google/siglip2-so400m-patch16-384）：图像被切分为 384x384 的块。
窗口 Q-Former 投影器：通过 4x4 补丁窗口上的窗口交叉注意力，将视觉特征压缩 4 倍，映射为 2x2 个 token。
DeepStack Feature Injection 包含 8 个视觉到 LLM 的注入点：
- LayerDeepstack：将来自 4 个视觉编码器深度的特征投影到不同的早期 LLM 层中。
- SpatialDeepstack：将最深层的视觉特征划分为 4 个空间组，并注入到后续的 LLM 层中。
语言模型：Granite 4.1（4B 参数），在所有自注意力层和 MLP 层上应用 LoRA 适配器（秩 256）。

该模型以 LoRA 适配器的形式交付，叠加在基础 LLM 之上，使单一部署即可同时支持多模态和纯文本工作负载。总参数量约为 4B。

该模型由 IBM Granite Vision Team 贡献。

使用技巧

在批量生成期间设置 padding_side="left" 以获得更准确的结果。

processor.tokenizer.padding_side = "left"

该模型支持用于文档提取的专用任务标签：<chart2csv>、<chart2summary>、<chart2code>、<tables_html>、<tables_otsl>、<tables_json>。请将它们作为文本提示与文档图像一起传入。
对于键值对提取，请提供一个 JSON 模式来描述要提取的字段。模型将返回符合该模式的结构化 JSON。

以下示例演示了如何使用 Pipeline 或 AutoModel 类基于图像生成文本。

Pipeline

AutoModel

量化通过以较低精度表示权重来降低大模型的内存负担。有关更多可用的量化后端，请参阅量化概述。

下面的示例使用 bitsandbytes 仅将权重量化为 int4。

import torch
from transformers import AutoProcessor, AutoModelForImageTextToText, BitsAndBytesConfig

quant_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.float16,
    bnb_4bit_quant_type="nf4",
)

model_id = "ibm-granite/granite-vision-4.1-4b"
processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForImageTextToText.from_pretrained(
    model_id, quantization_config=quant_config, device_map="auto"
)

conversation = [
    {
        "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(
    conversation,
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
).to(model.device)

output = model.generate(**inputs, max_new_tokens=100)
print(processor.decode(output[0], skip_special_tokens=True))

Granite4VisionConfig

class transformers.Granite4VisionConfig

< 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 = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonetext_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneimage_token_index: int = 32000vision_feature_select_strategy: typing.Literal['default', 'full'] = 'default'vision_feature_layer: int | list[int] = -2tie_word_embeddings: bool = Falseimage_grid_pinpoints: list | None = Noneimage_seq_length: int = 576downsample_rate: str | None = Nonedeepstack_layer_map: list | None = Nonespatial_vision_layer: int = -1spatial_target_layers: list | None = Noneprojector_dropout: float = 0.1qformer_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None )

参数

vision_config (Union[dict, ~configuration_utils.PreTrainedConfig]，可选) — 视觉骨干网络的配置对象或字典。
text_config (Union[dict, ~configuration_utils.PreTrainedConfig]，可选) — 文本骨干网络的配置对象或字典。
image_token_index (int，可选，默认为 32000) — 用作输入图像占位符的图像 token 索引。
vision_feature_select_strategy (Literal[default, full]，可选，默认为 default) — 用于从视觉主干网络中选择视觉特征的特征选择策略。
vision_feature_layer (Union[int, list[int]]，可选，默认为 -2) — 用于选择视觉特征的层索引。如果提供了多个索引，则会将对应索引处的视觉特征拼接起来，以构成视觉特征。
tie_word_embeddings (bool，可选，默认为 False) — 是否根据模型的 tied_weights_keys 映射来绑定权重嵌入。
image_grid_pinpoints (list，可选) — 用于处理高分辨率图像的可用分辨率列表。列表中的每个元素应为 (height, width) 形式的元组或列表。
image_seq_length (int，可选，默认为 576) — 单个图像嵌入的序列长度。
downsample_rate (str, 可选) — Window Q-Former 投影器的分数下采样率，例如 "1/4" 或 "3/8"。分子为查询窗口边长，分母为键窗口边长。
deepstack_layer_map (list, 可选) — [vision_layer_idx, llm_layer_idx] 对的列表。在前向传播过程中，每个视觉编码器层的特征会被投影并注入到对应的 LLM 解码器层。
spatial_vision_layer (int，可选，默认为 -1) — 用于空间采样的视觉编码器层索引。
spatial_target_layers (list，可选，默认为 [12, 15, 18, 21]) — 用于 4 个空间偏移组的 LLM 目标层。
projector_dropout (float，可选，默认为 0.1) — Window Q-Former 投影器中的 Dropout 概率。
qformer_config (dict 或 Blip2QFormerConfig，可选) — Window Q-Former 投影器的配置。如果为 None，则默认值由 vision_config.hidden_size 推导得出。

这是用于存储 Granite4VisionModel 配置的类。它根据指定的参数实例化 Granite4 Vision 模型，并定义模型架构。使用默认值实例化配置将得到与 llava-hf/llava-v1.6-mistral-7b-hf 类似的配置。

配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。

Granite4VisionTextConfig

class transformers.Granite4VisionTextConfig

< 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 = Nonevocab_size: int = 32000hidden_size: int = 4096intermediate_size: int = 11008num_hidden_layers: int = 32num_attention_heads: int = 32num_key_value_heads: int | None = Nonehidden_act: str = 'silu'max_position_embeddings: int = 2048initializer_range: float = 0.02rms_norm_eps: float = 1e-06use_cache: bool = Truepad_token_id: int | None = Nonebos_token_id: int | None = 1eos_token_id: int | list[int] | None = 2tie_word_embeddings: bool = Falserope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = Noneattention_bias: bool = Falseattention_dropout: float | int = 0.0mlp_bias: bool = Falseembedding_multiplier: float | int = 1.0logits_scaling: float | int = 1.0residual_multiplier: float | int = 1.0attention_multiplier: float | int = 1.0 )

参数

vocab_size (int，可选，默认为 32000) — 模型的词汇表大小。定义了 input_ids 可以表示的不同 token 数量。
hidden_size (int，可选，默认为 4096) — 隐藏表示的维度。
intermediate_size (int，可选，默认为 11008) — MLP 表示的维度。
num_hidden_layers (int，可选，默认为 32) — Transformer 解码器中的隐藏层数量。
num_attention_heads (int，可选，默认为 32) — Transformer 解码器中每个注意力层的注意力头数量。
num_key_value_heads (int, 可选) — 这是用于实现 Grouped Query Attention 的 key_value 头数。如果 num_key_value_heads=num_attention_heads，模型将使用 Multi Head Attention (MHA)；如果 num_key_value_heads=1，模型将使用 Multi Query Attention (MQA)；否则使用 GQA。在将多头检查点转换为 GQA 检查点时，每个组的 key 和 value 头应通过对该组内所有原始头进行平均池化来构建。更多详情请参阅这篇论文。如果未指定，则默认为 num_attention_heads。
hidden_act (str，可选，默认为 silu) — 解码器中的非线性激活函数（函数或字符串）。例如，"gelu"、 "relu"、"silu" 等。
max_position_embeddings (int，可选，默认为 2048) — 该模型可能使用的最大序列长度。
initializer_range (float，可选，默认为 0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。
rms_norm_eps (float，可选，默认为 1e-06) — RMS 归一化层使用的 epsilon 值。
use_cache (bool，可选，默认为 True) — 模型是否应返回最后一次键/值注意力（并非所有模型都使用）。仅当 config.is_decoder=True 或模型为仅解码器生成式模型时相关。
pad_token_id (int, 可选) — 词表中用于填充的 token id。
bos_token_id (int，可选，默认为 1) — 词汇表中用于表示流起始的 token id。
eos_token_id (Union[int, list[int]]，可选，默认为 2) — 词汇表中用于表示流结束（end-of-stream）的 token id。
tie_word_embeddings (bool，可选，默认为 False) — 是否根据模型的 tied_weights_keys 映射来绑定权重嵌入。
rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], 可选) — 包含 RoPE 嵌入配置参数的字典。该字典应包含 rope_theta 的值，并且如果希望使用 RoPE 处理更长的 max_position_embeddings，则可选地包含用于缩放的参数。
attention_bias (bool，可选，默认为 False) — 在自注意力机制中，是否在 query、key、value 和 output 投影层中使用偏置。
attention_dropout (Union[float, int]，可选，默认为 0.0) — 注意力概率的 dropout 比率。
mlp_bias (bool，可选，默认为 False) — 是否在 MLP 层的 up_proj、down_proj 和 gate_proj 层中使用偏置。
embedding_multiplier (Union[float, int]，可选，默认为 1.0) — 应用于词嵌入的缩放因子。用于根据隐藏层大小对嵌入进行缩放。
logits_scaling (Union[float, int]，可选，默认为 1.0) — 在计算概率分布之前，应用于输出 logits 的缩放因子。
residual_multiplier (Union[float, int]，可选，默认为 1.0) — 应用于残差连接的缩放因子。
attention_multiplier (Union[float, int]，可选，默认为 1.0) — 应用于注意力权重的缩放因子。

这是用于存储 Granite4VisionModel 配置的类。它根据指定的参数实例化 Granite4 Vision 模型，并定义模型架构。使用默认值实例化配置，将得到与 ibm-granite4_vision_text/granite4_vision_text-3.0-8b-base 类似的配置。

配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。

>>> from transformers import Granite4VisionTextModel, Granite4VisionTextConfig

>>> # Initializing a Granite4VisionText granite4_vision_text-3b style configuration
>>> configuration = Granite4VisionTextConfig()

>>> # Initializing a model from the granite4_vision_text-7b style configuration
>>> model = Granite4VisionTextModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

Granite4VisionProcessor

class transformers.Granite4VisionProcessor

< source >

( image_processor = Nonetokenizer = Nonepatch_size = Nonevision_feature_select_strategy = Nonechat_template = Noneimage_token = '<image>'num_additional_image_tokens = 0downsample_rate = None**kwargs )

参数

image_processor (LlavaNextImageProcessor) — 图像处理器是必需的输入。
tokenizer (tokenizer_class) — 分词器是必需的输入。
patch_size (int, 可选) — 视觉塔的 patch 大小。
vision_feature_select_strategy (str, 可选) — 用于从视觉主干网络中选择视觉特征的特征选择策略。应与模型配置中的设置保持一致。
chat_template (str) — 一个 Jinja 模板，用于将聊天中的消息列表转换为可分词的字符串。
image_token (str，可选，默认为 "<image>") — 用于表示图像位置的专用标记。
num_additional_image_tokens (int，可选，默认为 0) — 添加到图像嵌入中的额外 token 数量，例如 CLS（+1）。
downsample_rate (str, 可选) — 分数下采样率（例如 "1/4"），用于在计算填充/截断所需的 token 数量时调整图像 token 的数量。

构建一个 Granite4VisionProcessor，它将图像处理器和分词器封装为单一处理器。

Granite4VisionProcessor 提供了 LlavaNextImageProcessor 和 tokenizer_class 的所有功能。有关更多信息，请参阅 ~LlavaNextImageProcessor 和 ~tokenizer_class。

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] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )

参数

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]]]，可选) — 要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果传入预分词输入，请设置 is_split_into_words=True，以避免与批量输入产生歧义。
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]]], 可选) — 要预处理的视频。期望输入单个视频或一批视频，其像素值范围为 0 到 255。如果传入的像素值在 0 到 1 之间，请设置 do_rescale=False。
audio (Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]], 可选) — 要准备处理的音频或音频批次。每个音频可以是 NumPy 数组或 PyTorch 张量。如果为 NumPy 数组/PyTorch 张量，每个音频的形状应为 (C, T)，其中 C 为通道数，T 为音频的采样长度。
return_mm_token_type_ids (bool, kwargs) — 是否返回多模态 token 类型 id，用于指示多模态占位符 token 的位置。
return_text_replacement_offsets (bool, kwargs) — 是否返回每个多模态占位符及其替换内容的字符偏移量。
return_tensors (str 或 TensorType, 可选) — 如果设置，将返回特定框架的张量。可接受的值为：
- 'pt'：返回 PyTorch torch.Tensor 对象。
- 'np'：返回 NumPy np.ndarray 对象。
**kwargs (ProcessingKwargs，可选) — 每种模态（文本、图像、视频、音频）的额外处理选项。模型特定参数已在上方列出；有关支持参数的完整列表，请参阅 TypedDict 类。

Granite4VisionModel

class transformers.Granite4VisionModel

< source >

( config: Granite4VisionConfig )

参数

config (Granite4VisionConfig) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

Llava-Next 模型由视觉骨干网络和语言模型组成，不包含语言建模头。

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

forward

< source >

( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Noneimage_sizes: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonevision_feature_layer: int | list[int] | None = Nonevision_feature_select_strategy: str | None = Noneuse_cache: bool | None = Nonemm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Granite4VisionModelOutputWithPast or tuple(torch.Tensor)

参数

input_ids (torch.LongTensor 形状为 (batch_size, sequence_length), ，可选) — 输入序列中各 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。
可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。

什么是输入 ID？
pixel_values (torch.Tensor，形状为 (batch_size, num_channels, image_size, image_size)，可选) — 与输入图像对应的张量。可以使用 LlavaNextImageProcessor 获取像素值。有关详细信息，请参阅 LlavaNextImageProcessor.call()（Granite4VisionProcessor 使用 LlavaNextImageProcessor 处理图像）。
image_sizes (torch.LongTensor，形状为 (batch_size, 2)，可选) — 批次中各图像的尺寸，每张图像表示为 (height, width)。
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].
什么是位置 ID？
past_key_values (~cache_utils.Cache, 可选) — 预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由 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 索引如何转换为相应向量拥有比模型内部嵌入查找矩阵更多的控制权，这将非常有用。
vision_feature_layer (Union[int, list[int]], 可选) — 用于选择视觉特征的层索引。如果提供了多个索引，则会将对应索引的视觉特征拼接起来，以形成视觉特征。
vision_feature_select_strategy (str, 可选，默认为 "default") — 用于从视觉主干网络中选择视觉特征的特征选择策略。可以是 "default" 或 "full" 之一。如果为 "default"，则会从视觉特征中移除 CLS token。如果为 "full"，则使用完整的视觉特征。
use_cache (bool，可选) — 如果设置为 True，则会返回 past_key_values 键值状态，可用于加速解码（参见 past_key_values）。
mm_encoder_outputs (dict[str, ~modeling_outputs.BaseModelOutputWithPooling], 可选) — 一个字典，其中键为支持的模态，值为该模态的编码输出。每个编码输出是一个元组，由 (pooler_output、可选：last_hidden_states、可选：hidden_states、可选：attentions) pooler_output，形状为 (batch_size, sequence_length, hidden_size)，可选) 组成，它是编码器融合到文本嵌入中的多模态特征序列。

返回值

Granite4VisionModelOutputWithPast 或 tuple(torch.Tensor)

Granite4VisionModelOutputWithPast 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（Granite4VisionConfig）和输入。

Granite4VisionModel 的 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 之后的权重，用于在自注意力头中计算加权平均值。
image_hidden_states (torch.Tensor，形状为 (batch_size, num_images, sequence_length, hidden_size)，可选) — 由视觉编码器生成并在投影最后一个隐藏状态后得到的模型图像隐藏状态。
deepstack_features (list[tuple[int, list[torch.Tensor]]], 可选) — 由 deepstack 和空间投影器生成的 (llm_layer_idx, packed_features) 对列表。每个条目对应一个 LLM 解码器层；packed_features 是一个按图像划分的张量列表，每个张量的形状为 (num_image_tokens, hidden_size)。

get_image_features

< source >

( pixel_values: Tensorimage_sizes: Tensorvision_feature_layer: int | list[int] | None = Nonevision_feature_select_strategy: str | None = None**kwargs ) → Granite4VisionImageFeaturesOutput or tuple(torch.Tensor)

参数

pixel_values (torch.Tensor，形状为 (batch_size, num_patches, channels, height, width)) — 与输入图像对应的张量。
image_sizes（形状为 (num_images, 2) 的 torch.Tensor）— 每张图片的实际尺寸（H, W）。
vision_feature_layer (Union[int, list[int]], 可选) — 用于选择视觉特征的层索引。如果提供了多个索引，则会将对应索引的视觉特征拼接起来，以形成视觉特征。
image_sizes (torch.Tensor，形状为 (batch_size, 2)) — 批次中各图像的尺寸，每张图像对应 (height, width)。
vision_feature_layer (Union[int, list[int]], 可选) — 用于选择视觉特征的层索引。如果提供了多个索引，则会将对应索引的视觉特征拼接起来，以形成视觉特征。
vision_feature_select_strategy (str, 可选) — 用于从视觉主干网络中选择视觉特征的特征选择策略。可以是 "default" 或 "full"

返回值

Granite4VisionImageFeaturesOutput 或 tuple(torch.Tensor)

Granite4VisionImageFeaturesOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（Granite4VisionConfig）和输入。

从视觉塔获取图像的最后隐藏状态，并应用多模态投影。

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 之后的权重，用于在自注意力头中计算加权平均值。
deepstack_features (list[tuple[int, list[torch.Tensor]]], 可选) — 由 deepstack 和空间投影器生成的 (llm_layer_idx, packed_features) 对列表。每个条目对应一个 LLM 解码器层；packed_features 是一个按图像划分的张量列表，每个张量的形状为 (num_image_tokens, hidden_size)。

get_placeholder_mask

< source >

( input_ids: LongTensorinputs_embeds: Tensorimage_features: Tensor )

从 input_ids 或 inputs_embeds 中获取多模态占位符掩码，并检查占位符 token 的数量是否等于多模态特征的长度。如果长度不一致，则会引发错误。

pack_image_features

< source >

( image_featuresimage_sizesvision_feature_select_strategyimage_newline = None )

将每个 image_feature 重塑、去除填充，然后打包成一个包含所有视觉向量的单一 image_features 张量。

重写父类方法，将 downsample_rate 应用于高度/宽度的计算。

Granite4VisionTextModel

class transformers.Granite4VisionTextModel

< source >

( config: Granite4VisionTextConfig )

参数

config (Granite4VisionTextConfig) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

未添加任何特定头部的裸 Granite4 Vision Text Model，直接输出原始隐藏状态。

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

forward

< source >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = Nonevision_mask: typing.Optional[torch.BoolTensor] = Nonedeepstack_features: dict[int, torch.Tensor] | 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()。

什么是输入 ID？
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].
什么是位置 ID？
past_key_values (~cache_utils.Cache, 可选) — 预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由 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）。
vision_mask（形状为 (batch_size, sequence_length, hidden_size) 的 torch.BoolTensor，可选） — 用于标记图像 token 位置的布尔掩码。当提供 deepstack_features 时，此参数为必填项。
deepstack_features (dict[int, torch.Tensor], 可选) — 从 LLM 层索引到形状为 (num_image_tokens, hidden_size) 的投影视觉特征的映射。这些特征会在对应的解码器层之前，被添加到隐藏状态中图像 token 所在的位置。

返回值

BaseModelOutputWithPast 或 tuple(torch.Tensor)

一个 BaseModelOutputWithPast 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（Granite4VisionConfig）和输入。

Granite4VisionTextModel 的 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 之后的权重，用于在自注意力头中计算加权平均值。

Granite4VisionForConditionalGeneration

class transformers.Granite4VisionForConditionalGeneration

< source >

( config: Granite4VisionConfig )

参数

config (Granite4VisionConfig) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

由视觉骨干网络和语言模型组成的 LLAVA-NeXT 模型。

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

forward

< source >

( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Noneimage_sizes: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonevision_feature_layer: int | list[int] | None = Nonevision_feature_select_strategy: str | None = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = 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'> ) → Granite4VisionCausalLMOutputWithPast or tuple(torch.Tensor)

参数

input_ids (torch.LongTensor 形状为 (batch_size, sequence_length), ，可选) — 输入序列中各 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。
可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。

什么是输入 ID？
pixel_values (torch.Tensor，形状为 (batch_size, num_channels, image_size, image_size)，可选) — 与输入图像对应的张量。可以使用 LlavaNextImageProcessor 获取像素值。有关详细信息，请参阅 LlavaNextImageProcessor.call()（Granite4VisionProcessor 使用 LlavaNextImageProcessor 处理图像）。
image_sizes (torch.LongTensor，形状为 (batch_size, 2)，可选) — 批次中各图像的尺寸，每张图像表示为 (height, width)。
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].
什么是位置 ID？
past_key_values (~cache_utils.Cache, 可选) — 预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由 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 索引如何转换为相应向量拥有比模型内部嵌入查找矩阵更多的控制权，这将非常有用。
vision_feature_layer (Union[int, list[int]], 可选) — 用于选择视觉特征的层索引。如果提供了多个索引，则会将对应索引的视觉特征拼接起来，以形成视觉特征。
vision_feature_select_strategy (str, 可选，默认为 "default") — 用于从视觉主干网络中选择视觉特征的特征选择策略。可以是 "default" 或 "full" 之一。如果为 "default"，则会从视觉特征中移除 CLS token。如果为 "full"，则使用完整的视觉特征。
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）。
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)，可选) 组成，它是编码器融合到文本嵌入中的多模态特征序列。

返回值

Granite4VisionCausalLMOutputWithPast 或 tuple(torch.Tensor)

Granite4VisionCausalLMOutputWithPast 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（Granite4VisionConfig）和输入。

Granite4VisionForConditionalGeneration 的 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_utils.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 之后的权重，用于在自注意力头中计算加权平均值。
image_hidden_states (torch.Tensor，形状为 (batch_size, num_images, sequence_length, hidden_size)，可选) — 由视觉编码器生成并在投影最后一个隐藏状态后得到的模型图像隐藏状态。
deepstack_features (list[tuple[int, list[torch.Tensor]]], 可选) — 由 deepstack 和空间投影器生成的 (llm_layer_idx, packed_features) 对列表。每个条目对应一个 LLM 解码器层；packed_features 是一个按图像划分的张量列表，每个张量的形状为 (num_image_tokens, hidden_size)。

示例：

>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import AutoProcessor, Granite4VisionForConditionalGeneration

>>> model = Granite4VisionForConditionalGeneration.from_pretrained("llava-hf/llava-v1.6-mistral-7b-hf")
>>> processor = AutoProcessor.from_pretrained("llava-hf/llava-v1.6-mistral-7b-hf")

>>> prompt = "[INST] <image>\nWhat is shown in this image? [/INST]"
>>> url = "https://www.ilankelman.org/stopsigns/australia.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read()))

>>> inputs = processor(images=image, text=prompt, return_tensors="pt")

>>> # Generate
>>> generate_ids = model.generate(**inputs, max_length=30)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
"[INST]  \nWhat is shown in this image? [/INST] The image appears to be a radar chart, which is a type of multi-dimensional plot (...)"

get_image_features

< source >

( pixel_values: Tensorimage_sizes: Tensorvision_feature_layer: int | list[int] | None = Nonevision_feature_select_strategy: str | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)

参数

pixel_values (torch.Tensor，形状为 (batch_size, num_patches, channels, height, width)) — 与输入图像对应的张量。
image_sizes（形状为 (num_images, 2) 的 torch.Tensor）— 每张图片的实际尺寸（H, W）。
vision_feature_layer (Union[int, list[int]], 可选) — 用于选择视觉特征的层索引。如果提供了多个索引，则会将对应索引的视觉特征拼接起来，以形成视觉特征。
image_sizes (torch.Tensor，形状为 (batch_size, 2)) — 批次中各图像的尺寸，每张图像对应 (height, width)。
vision_feature_layer (Union[int, list[int]], 可选) — 用于选择视觉特征的层索引。如果提供了多个索引，则会将对应索引的视觉特征拼接起来，以形成视觉特征。
vision_feature_select_strategy (str, 可选) — 用于从视觉主干网络中选择视觉特征的特征选择策略。可以是 "default" 或 "full"

返回值

BaseModelOutputWithPooling 或 tuple(torch.Tensor)

一个 BaseModelOutputWithPooling 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（Granite4VisionConfig）和输入。

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, Granite4VisionForConditionalGeneration

>>> model = Granite4VisionForConditionalGeneration.from_pretrained("llava-hf/llava-v1.6-mistral-7b-hf")
>>> processor = AutoProcessor.from_pretrained("llava-hf/llava-v1.6-mistral-7b-hf")

>>> 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]

Update on GitHub

←GOT-OCR2 GraniteDocling→