# KOSMOS-2

## 概述

KOSMOS-2 模型由 Zhiliang Peng、Wenhui Wang、Li Dong、Yaru Hao、Shaohan Huang、Shuming Ma 和 Furu Wei 在 [Kosmos-2: Grounding Multimodal Large Language Models to the World](https://huggingface.co/papers/2306.14824) 中提出。

KOSMOS-2 是一个基于 Transformer 的因果语言模型，使用基于有依据的图像-文本对的 Web 规模数据集 [GRIT](https://huggingface.co/datasets/zzliang/GRIT) 通过下一个词预测任务进行训练。数据集中边界框的空间坐标被转换为位置标记序列，并附加到其对应的实体文本片段之后（例如，`a snowman` 后跟 `<patch_index_0044><patch_index_0863>`）。该数据格式类似于“超链接”，将图像中的对象区域与其在相应说明中的文本片段连接起来。

该论文的摘要如下：

*我们推出了 Kosmos-2，一种多模态大语言模型（MLLM），使其具备感知对象描述（例如边界框）并将文本定位到视觉世界的新能力。具体而言，我们将指代表达表示为 Markdown 中的链接，即 [text span](bounding boxes)，其中对象描述是位置标记的序列。结合多模态语料库，我们构建了大规模的定位图像-文本对数据（称为 GrIT）来训练该模型。除了 MLLM 的现有能力（例如感知通用模态、遵循指令和执行上下文学习）之外，Kosmos-2 还将定位能力整合到下游应用中。我们在广泛的任务上评估了 Kosmos-2，包括 (i) 多模态定位，如指代表达理解和短语定位，(ii) 多模态指代，如指代表达生成，(iii) 感知-语言任务，以及 (iv) 语言理解和生成。这项工作为具身智能（Embodiment AI）的发展奠定了基础，并揭示了语言、多模态感知、动作和世界模型的大融合，这是迈向通用人工智能的关键一步。代码和预训练模型可在 https://aka.ms/kosmos-2 获取。*

<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/kosmos_2_overview.jpg"
alt="drawing" width="600"/>

 KOSMOS-2 可处理的任务概览。摘自原始论文。

## 示例

```python
import requests
from PIL import Image

from transformers import AutoProcessor, Kosmos2ForConditionalGeneration

model = Kosmos2ForConditionalGeneration.from_pretrained("microsoft/kosmos-2-patch14-224", device_map="auto")
processor = AutoProcessor.from_pretrained("microsoft/kosmos-2-patch14-224")

url = "https://huggingface.co/microsoft/kosmos-2-patch14-224/resolve/main/snowman.jpg"
image = Image.open(requests.get(url, stream=True).raw)

prompt = "<grounding> An image of"

inputs = processor(text=prompt, images=image, return_tensors="pt").to(model.device)

generated_ids = model.generate(
    pixel_values=inputs["pixel_values"],
    input_ids=inputs["input_ids"],
    attention_mask=inputs["attention_mask"],
    image_embeds=None,
    image_embeds_position_mask=inputs["image_embeds_position_mask"],
    use_cache=True,
    max_new_tokens=64,
)
generated_text = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
processed_text = processor.post_process_generation(generated_text, cleanup_and_extract=False)
processed_text
'<grounding> An image of<phrase> a snowman</phrase><object><patch_index_0044><patch_index_0863></object> warming himself by<phrase> a fire</phrase><object><patch_index_0005><patch_index_0911></object>.'

caption, entities = processor.post_process_generation(generated_text)
caption
'An image of a snowman warming himself by a fire.'

entities
[('a snowman', (12, 21), [(0.390625, 0.046875, 0.984375, 0.828125)]), ('a fire', (41, 47), [(0.171875, 0.015625, 0.484375, 0.890625)])]
```

该模型由 [Yih-Dar SHIEH](https://huggingface.co/ydshieh) 贡献。原始代码可在[此处](https://github.com/microsoft/unilm/tree/master/kosmos-2)找到。

## Kosmos2Config[[transformers.Kosmos2Config]]

#### transformers.Kosmos2Config[[transformers.Kosmos2Config]]

```python
transformers.Kosmos2Config(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, text_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, latent_query_num: int = 64, tie_word_embeddings: bool = True)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/kosmos2/configuration_kosmos2.py#L81)

**参数：**

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`，*可选*)：文本骨干网络的配置对象或字典。

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`，*可选*)：视觉骨干网络的配置对象或字典。

latent_query_num (`int`, *可选*，默认为 64)：用于表示文本解码器组件中图像特征的潜在查询 token 数量。

tie_word_embeddings (`bool`，*可选*，默认为 `True`)：是否根据模型的 `tied_weights_keys` 映射来绑定权重嵌入。

这是用于存储 Kosmos2Model 配置的类。它根据指定的参数实例化 Kosmos2 模型，并定义模型架构。使用默认值实例化配置将得到与 [microsoft/kosmos-2-patch14-224](https://huggingface.co/microsoft/kosmos-2-patch14-224) 类似的配置

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

示例：

```python
>>> from transformers import Kosmos2Config, Kosmos2Model

>>> # Initializing a Kosmos-2 kosmos-2-patch14-224 style configuration
>>> configuration = Kosmos2Config()

>>> # Initializing a model (with random weights) from the kosmos-2-patch14-224 style configuration
>>> model = Kosmos2Model(configuration)

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

## Kosmos2TextConfig[[transformers.Kosmos2TextConfig]]

#### transformers.Kosmos2TextConfig[[transformers.Kosmos2TextConfig]]

```python
transformers.Kosmos2TextConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vocab_size: int = 65037, max_position_embeddings: int = 2048, embed_dim: int = 2048, layers: int = 24, ffn_dim: int = 8192, attention_heads: int = 32, activation_function: str = 'gelu', dropout: float | int = 0.1, attention_dropout: float | int = 0.1, activation_dropout: float | int = 0.0, layerdrop: float | int = 0.0, layer_norm_eps: float = 1e-05, init_std: float = 0.02, scale_embedding: bool = True, use_cache: bool = True, tie_word_embeddings: bool = True, pad_token_id: int | None = 1, bos_token_id: int | None = 0, eos_token_id: int | list[int] | None = 2, add_cross_attention: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/kosmos2/configuration_kosmos2.py#L27)

**参数：**

vocab_size (`int`，*可选*，默认为 `65037`)：模型的词汇表大小。定义了 `input_ids` 可以表示的不同 token 数量。

max_position_embeddings (`int`，*可选*，默认值为 `2048`)：该模型可能使用的最大序列长度。

embed_dim (`int`，*可选*，默认为 `2048`)：嵌入和隐藏状态的维度。

layers (`int`，*可选*，默认为 `24`)：Transformer 解码器中的隐藏层数。

ffn_dim (`int`，*可选*，默认为 `8192`)：MLP 表示的维度。

attention_heads (`int`，*可选*，默认为 `32`)：Transformer 解码器中每个注意力层的注意力头数量。

activation_function (`str`，*可选*，默认为 `gelu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。

dropout (`Union[float, int]`，*可选*，默认为 `0.1`)：所有 dropout 层的比率。

attention_dropout (`Union[float, int]`，*可选*，默认值为 `0.1`)：注意力概率的 dropout 比率。

activation_dropout (`Union[float, int]`，*可选*，默认值为 `0.0`)：全连接层内部激活值的 dropout 比率。

layerdrop (`Union[float, int]`，*可选*，默认为 `0.0`)：LayerDrop 概率。有关更多详细信息，请参阅 [LayerDrop 论文](see https://huggingface.co/papers/1909.11556)。

layer_norm_eps (`float`，*可选*，默认为 `1e-05`)：层归一化层所使用的 epsilon。

init_std (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

scale_embedding (`bool`, *可选*, 默认为 `True`) : 是否通过将嵌入除以 sqrt(d_model) 来对其进行缩放。

use_cache (`bool`，*可选*，默认为 `True`)：模型是否应返回最后的键/值注意力（并非所有模型都使用）。仅当 `config.is_decoder=True` 或模型为仅解码器生成模型时相关。

tie_word_embeddings (`bool`，*可选*，默认为 `True`)：是否根据模型的 `tied_weights_keys` 映射来绑定权重嵌入。

pad_token_id (`int`，*可选*，默认为 `1`)：词表中用于填充的 token id。

bos_token_id (`int`，*可选*，默认为 `0`)：词汇表中用于表示流开始的 token id。

eos_token_id (`Union[int, list[int]]`，*可选*，默认为 `2`)：词汇表中用于表示流结束（end-of-stream）的 token id。

add_cross_attention (`bool`，*可选*，默认为 `False`)：是否应在模型中添加交叉注意力层。

这是用于存储 Kosmos2Model 配置的类。它根据指定的参数实例化 Kosmos2 模型，并定义模型架构。使用默认值实例化配置将得到与 [microsoft/kosmos-2-patch14-224](https://huggingface.co/microsoft/kosmos-2-patch14-224) 类似的配置

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

## Kosmos2VisionConfig[[transformers.Kosmos2VisionConfig]]

#### transformers.Kosmos2VisionConfig[[transformers.Kosmos2VisionConfig]]

```python
transformers.Kosmos2VisionConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 1024, intermediate_size: int = 4096, num_hidden_layers: int = 24, num_attention_heads: int = 16, num_channels: int = 3, image_size: int | list[int] | tuple[int, int] = 224, patch_size: int | list[int] | tuple[int, int] = 14, hidden_act: str = 'quick_gelu', layer_norm_eps: float = 1e-05, attention_dropout: float | int = 0.0, initializer_range: float = 0.02, initializer_factor: float = 1.0)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/kosmos2/configuration_kosmos2.py#L61)

**参数：**

hidden_size (`int`，*可选*，默认为 `1024`)：隐藏表示的维度。

intermediate_size (`int`，*可选*，默认为 `4096`)：MLP 表示的维度。

num_hidden_layers (`int`，*可选*，默认为 `24`)：Transformer 解码器中的隐藏层数。

num_attention_heads (`int`，*可选*，默认为 `16`)：Transformer 解码器中每个注意力层的注意力头数量。

num_channels (`int`，*可选*，默认为 `3`)：输入通道数。

image_size (`Union[int, list[int], tuple[int, int]]`，*可选*，默认为 `224`)：每张图片的尺寸（分辨率）。

patch_size (`Union[int, list[int], tuple[int, int]]`，*可选*，默认为 `14`)：每个 patch 的大小（分辨率）。

hidden_act (`str`，*可选*，默认为 `quick_gelu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。

layer_norm_eps (`float`，*可选*，默认为 `1e-05`)：层归一化层所使用的 epsilon。

attention_dropout (`Union[float, int]`，*可选*，默认值为 `0.0`)：注意力概率的 dropout 比率。

initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

initializer_factor (`float`, *可选*，默认为 `1.0`)：用于初始化所有权重矩阵的系数（应保持为 1，内部用于初始化测试）。

这是用于存储 Kosmos2Model 配置的类。它根据指定的参数实例化 Kosmos2 模型，并定义模型架构。使用默认值实例化配置将得到与 [microsoft/kosmos-2-patch14-224](https://huggingface.co/microsoft/kosmos-2-patch14-224) 类似的配置

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

## Kosmos2Processor[[transformers.Kosmos2Processor]]

#### transformers.Kosmos2Processor[[transformers.Kosmos2Processor]]

```python
transformers.Kosmos2Processor(image_processor, tokenizer, num_patch_index_tokens = 1024, *kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/kosmos2/processing_kosmos2.py#L94)

**参数：**

image_processor (`image_processor_class`)：图像处理器是必需的输入。

tokenizer (`tokenizer_class`)：分词器是必需的输入。

num_patch_index_tokens (`int`，*可选*，默认为 1024)：表示补丁索引的 token 数量。

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

[Kosmos2Processor](/docs/transformers/v5.23.0/zh/model_doc/kosmos-2#transformers.Kosmos2Processor) 提供了 `image_processor_class` 和 `tokenizer_class` 的所有功能。有关更多信息，请参阅 `~image_processor_class` 和 `~tokenizer_class`。

#### __调用__[[transformers.Kosmos2Processor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, text: str | list[str] = None, bboxes: list[tuple | None | list[tuple | None | list[tuple | None | list[tuple | None]]]] | None = None, **kwargs: *<class 'transformers.models.kosmos2.processing_kosmos2.Kosmos2ProcessorKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/kosmos2/processing_kosmos2.py#L154)

**参数：**

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]]`，*可选*)：要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果传入预分词输入，请设置 `is_split_into_words=True` 以避免与批量输入产生歧义。

bboxes (`Union[list[tuple[int]], list[tuple[float]], list[list[tuple[int]]], list[list[tuple[float]]]]`, *可选*) : 与 `texts` 关联的边界框。

add_eos_token (`bool`, *kwargs*, *可选*) : 已弃用，请改用 `Kosmos2ProcessorKwargs.add_eos_token`。当 `add_special_tokens=True` 时，是否在编码中包含 `EOS` token id。

bboxes (`Union[list[tuple[int]], *kwargs*, list[tuple[float]], list[list[tuple[int]]], list[list[tuple[float]]]]`，*可选*)：已弃用，请改为直接将其作为 `bboxes` 传递给 [Kosmos2Processor.__call__()](/docs/transformers/v5.23.0/zh/model_doc/kosmos-2#transformers.Kosmos2Processor.__call__)。与 `texts` 关联的边界框。

num_image_tokens (`int`, *kwargs*, *可选*) : 已弃用，请改用 `Kosmos2ProcessorKwargs.num_image_tokens`。用于标记占位符以存储图像信息的（连续）位置数量。此值应与您使用的 `Kosmos2Config` 实例中的 `latent_query_num` 相同。

first_image_token_id (`int`, *kwargs*, *可选*) : 已弃用，请改用 `Kosmos2ProcessorKwargs.first_image_token_id`。用于子序列中预留存储图像信息的首个位置的 token id。如果未设置，则默认为 `self.tokenizer.unk_token_id + 1`。

return_mm_token_type_ids (`bool`, *kwargs*) : 是否返回多模态 token 类型 ID，以指示多模态占位符 token 的位置。

return_text_replacement_offsets (`bool`, *kwargs*) : 是否返回每个多模态占位符及其替换项的字符偏移量。

num_image_tokens (`int`, *kwargs*, *可选*，默认值为 64) : 用于标记存储图像信息占位符的（连续）位置数量。此值应与您正在使用的 `Kosmos2Config` 实例中的 `latent_query_num` 相同。

first_image_token_id (`int`, *kwargs*, *可选*) : 用于子序列中预留存储图像信息的首个位置的 token id。如果未设置，则默认为 `self.tokenizer.unk_token_id + 1`。

add_eos_token (`bool`, *kwargs*, *可选*，默认为 `False`) : 当 `add_special_tokens=True` 时，编码中是否包含 `EOS` token id。

return_tensors (`str` 或 [TensorType](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回特定框架的张量。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 NumPy `np.ndarray` 对象。

- ****kwargs** ([ProcessingKwargs](/docs/transformers/v5.23.0/zh/main_classes/processors#transformers.ProcessingKwargs), *可选*) : 针对每种模态（文本、图像、视频、音频）的额外处理选项。模型特定参数已在上方列出；有关支持参数的完整列表，请参阅 TypedDict 类。

**返回：** `~image_processing_base.BatchFeature`

- **data** (`dict`) -- 由 __call__ 方法返回的列表/数组/张量字典（例如 'pixel_values'）。
- **tensor_type** (`Union[None, str, TensorType]`，*可选*) -- 您可以在此处指定 tensor_type，以便在初始化时将 PyTorch/Numpy 张量中的整数列表进行转换。

## Kosmos2Model[[transformers.Kosmos2Model]]

#### transformers.Kosmos2Model[[transformers.Kosmos2Model]]

```python
transformers.Kosmos2Model(config: Kosmos2Config)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/kosmos2/modeling_kosmos2.py#L1352)

**参数：**

config ([Kosmos2Config](/docs/transformers/v5.23.0/zh/model_doc/kosmos-2#transformers.Kosmos2Config))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

用于生成文本和图像特征的 KOSMOS-2 模型。该模型由视觉编码器和语言模型组成。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.Kosmos2Model.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, input_ids: typing.Optional[torch.Tensor] = None, image_embeds_position_mask: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, image_embeds: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, interpolate_pos_encoding: bool = False, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/kosmos2/modeling_kosmos2.py#L1404)

**参数：**

pixel_values (`torch.Tensor`，形状为 `(batch_size, num_channels, image_size, image_size)`，*可选*) : 与输入图像对应的张量。可以使用 `image_processor_class` 获取像素值。有关详细信息，请参阅 `image_processor_class.__call__`（`processor_class` 使用 `image_processor_class` 处理图像）。

input_ids (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中各个 token 在词汇表中的索引。默认情况下，填充（padding）会被忽略。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取这些索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

image_embeds_position_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于指示序列中插入图像特征位置的掩码。掩码值选自 `[0, 1]`： - 1 表示放置图像特征的位置， - 0 表示非图像特征的位置（即文本标记）。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

image_embeds (`torch.Tensor`，形状为 `(batch_size, latent_query_num, hidden_size)`，*可选*)：`Kosmos2ImageToTextProjection` 输出的隐藏状态序列。

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

position_ids （`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*）：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

use_cache (`bool`，*可选*)：如果设置为 `True`，则会返回 `past_key_values` 键值状态，可用于加速解码（参见 `past_key_values`）。

interpolate_pos_encoding (`bool`，*可选*，默认为 `False`)：是否对预训练的位置编码进行插值。

**返回：** `Kosmos2ModelOutput` 或 `tuple(torch.Tensor)`

`Kosmos2ModelOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[Kosmos2Config](/docs/transformers/v5.23.0/zh/model_doc/kosmos-2#transformers.Kosmos2Config)）和输入。

[Kosmos2Model](/docs/transformers/v5.23.0/zh/model_doc/kosmos-2#transformers.Kosmos2Model) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`，*可选*）-- 模型最后一层输出的隐藏状态序列。
- **past_key_values** (`~cache_utils.Cache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回) -- 它是一个 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/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_embeds**（形状为 `(batch_size, latent_query_num, hidden_size)` 的 `torch.Tensor`，*可选*）-- `Kosmos2ImageToTextProjection` 输出的隐藏状态序列。
- **projection_attentions** (`tuple(torch.Tensor)`，*可选*) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  由 `Kosmos2ImageToTextProjection` 给出的注意力权重，经过注意力 softmax 后，用于在自注意力头中计算加权平均值。
- **vision_model_output**（`BaseModelOutputWithPooling`，*可选*）—— `Kosmos2VisionModel` 的输出。

示例：

```python
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import AutoProcessor, Kosmos2Model

>>> model = Kosmos2Model.from_pretrained("microsoft/kosmos-2-patch14-224")
>>> processor = AutoProcessor.from_pretrained("microsoft/kosmos-2-patch14-224")

>>> url = "https://huggingface.co/microsoft/kosmos-2-patch14-224/resolve/main/snowman.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read()))

>>> text = (
...     "<grounding> An image of<phrase> a snowman</phrase><object><patch_index_0044><patch_index_0863>"
...     "</object> warming himself by<phrase> a fire</phrase><object><patch_index_0005><patch_index_0911>"
...     "</object>"
... )

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

>>> last_hidden_state = model(
...     pixel_values=inputs["pixel_values"],
...     input_ids=inputs["input_ids"],
...     attention_mask=inputs["attention_mask"],
...     image_embeds_position_mask=inputs["image_embeds_position_mask"],
... ).last_hidden_state
>>> list(last_hidden_state.shape)
[1, 91, 2048]
```

#### get_image_features[[transformers.Kosmos2Model.get_image_features]]

```python
get_image_features(pixel_values: Tensor, interpolate_pos_encoding: bool | None = False, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/kosmos2/modeling_kosmos2.py#L1372)

**参数：**

pixel_values (`torch.Tensor`，形状为 `(batch_size, num_channels, image_size, image_size)`)：与输入图像对应的张量。可以使用 `image_processor_class` 获取像素值。有关详细信息，请参阅 `image_processor_class.__call__`（`processor_class` 使用 `image_processor_class` 处理图像）。

interpolate_pos_encoding (`bool`，*可选*，默认为 `False`)：是否对预训练的位置编码进行插值。

**返回：** `BaseModelOutputWithProjectionAttentions` 或 `tuple(torch.Tensor)`

`BaseModelOutputWithProjectionAttentions` 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[Kosmos2Config](/docs/transformers/v5.23.0/zh/model_doc/kosmos-2#transformers.Kosmos2Config)）和输入。

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。
- **pooler_output**（形状为 `(batch_size, hidden_size)` 的 `torch.Tensor`）-- 序列中第一个 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 后的注意力权重，用于在自注意力头中计算加权平均值。
- **projection_attentions** (`tuple(torch.Tensor)`) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  由 `Kosmos2ImageToTextProjection` 给出的注意力权重，经过注意力 softmax 后，用于在自注意力头中计算加权平均值。

## Kosmos2ForConditionalGeneration[[transformers.Kosmos2ForConditionalGeneration]]

#### transformers.Kosmos2ForConditionalGeneration[[transformers.Kosmos2ForConditionalGeneration]]

```python
transformers.Kosmos2ForConditionalGeneration(config: Kosmos2Config)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/kosmos2/modeling_kosmos2.py#L1503)

**参数：**

config ([Kosmos2Config](/docs/transformers/v5.23.0/zh/model_doc/kosmos-2#transformers.Kosmos2Config))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

KOSMOS-2 模型，用于根据图像生成文本和边界框。该模型由视觉编码器和语言模型组成。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.Kosmos2ForConditionalGeneration.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, input_ids: typing.Optional[torch.Tensor] = None, image_embeds_position_mask: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, image_embeds: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/kosmos2/modeling_kosmos2.py#L1531)

**参数：**

pixel_values (`torch.Tensor`，形状为 `(batch_size, num_channels, image_size, image_size)`，*可选*) : 与输入图像对应的张量。可以使用 `image_processor_class` 获取像素值。有关详细信息，请参阅 `image_processor_class.__call__`（`processor_class` 使用 `image_processor_class` 处理图像）。

input_ids (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中各个 token 在词汇表中的索引。默认情况下，填充（padding）会被忽略。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取这些索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

image_embeds_position_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于指示序列中插入图像特征位置的掩码。掩码值选自 `[0, 1]`： - 1 表示放置图像特征的位置， - 0 表示非图像特征的位置（即文本标记）。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

image_embeds (`torch.Tensor`，形状为 `(batch_size, latent_query_num, hidden_size)`，*可选*)：`Kosmos2ImageToTextProjection` 输出的隐藏状态序列。

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

position_ids （`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*）：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

labels (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于计算从左到右的语言建模损失（下一个词预测）的标签。索引应在 `[-100, 0, ..., config.vocab_size]` 范围内（参见 `input_ids` 的文档字符串）。索引设置为 `-100` 的标记将被忽略（被掩码），损失仅针对标签在 `[0, ..., config.vocab_size]` 范围内的标记进行计算。

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`，则必须是一维张量，对应于序列长度维度中需要保留的索引。这在使用打包张量格式（将批次和序列长度合并为单一维度）时非常有用。

**返回：** `Kosmos2ForConditionalGenerationModelOutput` 或 `tuple(torch.Tensor)`

`Kosmos2ForConditionalGenerationModelOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[Kosmos2Config](/docs/transformers/v5.23.0/zh/model_doc/kosmos-2#transformers.Kosmos2Config)）和输入。

[Kosmos2ForConditionalGeneration](/docs/transformers/v5.23.0/zh/model_doc/kosmos-2#transformers.Kosmos2ForConditionalGeneration) 的 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](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/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_embeds**（形状为 `(batch_size, latent_query_num, hidden_size)` 的 `torch.Tensor`，*可选*）-- `Kosmos2ImageToTextProjection` 输出的隐藏状态序列。
- **projection_attentions** (`tuple(torch.Tensor)`，*可选*) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  由 `Kosmos2ImageToTextProjection` 给出的注意力权重，经过注意力 softmax 后，用于在自注意力头中计算加权平均值。
- **vision_model_output**（`BaseModelOutputWithPooling`，*可选*）—— `Kosmos2VisionModel` 的输出。

示例：

```python
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import AutoProcessor, Kosmos2ForConditionalGeneration

>>> model = Kosmos2ForConditionalGeneration.from_pretrained("microsoft/kosmos-2-patch14-224")
>>> processor = AutoProcessor.from_pretrained("microsoft/kosmos-2-patch14-224")

>>> url = "https://huggingface.co/microsoft/kosmos-2-patch14-224/resolve/main/snowman.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read()))

>>> prompt = "<grounding> An image of"

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

>>> generated_ids = model.generate(
...     pixel_values=inputs["pixel_values"],
...     input_ids=inputs["input_ids"],
...     attention_mask=inputs["attention_mask"],
...     image_embeds=None,
...     image_embeds_position_mask=inputs["image_embeds_position_mask"],
...     use_cache=True,
...     max_new_tokens=64,
... )
>>> generated_text = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
>>> processed_text = processor.post_process_generation(generated_text, cleanup_and_extract=False)
>>> processed_text
'<grounding> An image of<phrase> a snowman</phrase><object><patch_index_0044><patch_index_0863></object> warming himself by<phrase> a fire</phrase><object><patch_index_0005><patch_index_0911></object>.'

>>> caption, entities = processor.post_process_generation(generated_text)
>>> caption
'An image of a snowman warming himself by a fire.'

>>> entities
[('a snowman', (12, 21), [(0.390625, 0.046875, 0.984375, 0.828125)]), ('a fire', (41, 47), [(0.171875, 0.015625, 0.484375, 0.890625)])]
```

