Transformers documentation
VisionTextDualEncoder
该模型于 2021-11-15 在 HF papers 上发布，并于 2021-11-30 贡献至 Hugging Face Transformers。
VisionTextDualEncoder
概述
VisionTextDualEncoderModel 可用于初始化视觉-文本双编码器模型，其中视觉编码器可以是任意预训练的视觉自编码模型（例如 ViT、BEiT、DeiT），文本编码器可以是任意预训练的文本自编码模型（例如 RoBERTa、BERT）。在视觉编码器和文本编码器的顶部各添加了一个投影层，用于将输出嵌入投影到共享的潜在空间中。由于投影层采用随机初始化，因此应在下游任务上对该模型进行微调。该模型可用于通过类似 CLIP 的对比式图文训练来对齐视觉-文本嵌入，随后可用于零样本视觉任务，例如图像分类或检索。
在 LiT: Zero-Shot Transfer with Locked-image Text Tuning 中，展示了如何利用预训练（锁定/冻结）的图像和文本模型进行对比学习，从而在图像分类或检索等新的零样本视觉任务上取得显著提升。
VisionTextDualEncoderConfig
class transformers.VisionTextDualEncoderConfig
< 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: transformers.configuration_utils.PreTrainedConfig | dict | None = Nonevision_config: transformers.configuration_utils.PreTrainedConfig | dict | None = Noneprojection_dim: int = 512logit_scale_init_value: int | float = 2.6592 )
参数
- text_config (
Union[~configuration_utils.PreTrainedConfig, dict]，可选) — 文本骨干网络的配置对象或字典。 - vision_config (
Union[~configuration_utils.PreTrainedConfig, dict], 可选) — 视觉骨干网络的配置对象或字典。 - projection_dim (
int，可选，默认为512) — 文本和视觉投影层的维度。 - logit_scale_init_value (
Union[int, float]，可选，默认为2.6592) — logit_scale 参数的初始值。
这是用于存储视觉文本双编码器模型配置的类。它根据指定的参数实例化视觉文本双编码器模型，并定义模型架构。使用默认值实例化配置将生成与 None 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
示例：
>>> from transformers import ViTConfig, BertConfig, VisionTextDualEncoderConfig, VisionTextDualEncoderModel
>>> # Initializing a BERT and ViT configuration
>>> config_vision = ViTConfig()
>>> config_text = BertConfig()
>>> config = VisionTextDualEncoderConfig(vision_config=config_vision, text_config=config_text, projection_dim=512)
>>> # Initializing a BERT and ViT model (with random weights)
>>> model = VisionTextDualEncoderModel(config=config)
>>> # Accessing the model configuration
>>> config_vision = model.config.vision_config
>>> config_text = model.config.text_config
>>> # Saving the model, including its configuration
>>> model.save_pretrained("vit-bert")
>>> # loading model and config from pretrained folder
>>> vision_text_config = VisionTextDualEncoderConfig.from_pretrained("vit-bert")
>>> model = VisionTextDualEncoderModel.from_pretrained("vit-bert", config=vision_text_config)from_vision_text_configs
< source >( vision_config: PreTrainedConfigtext_config: PreTrainedConfig**kwargs ) → VisionTextDualEncoderConfig
配置对象的实例
根据文本模型配置和视觉模型配置，实例化一个 VisionTextDualEncoderConfig（或其派生类）。
VisionTextDualEncoderProcessor
class transformers.VisionTextDualEncoderProcessor
< source >( image_processor = Nonetokenizer = None**kwargs )
构建一个 VisionTextDualEncoderProcessor，它将图像处理器和分词器封装为单个处理器。
VisionTextDualEncoderProcessor 提供了 image_processor_class 和 tokenizer_class 的所有功能。有关更多信息，请参阅 ~image_processor_class 和 ~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_tensors (
str或 TensorType, 可选) — 如果设置，将返回特定框架的张量。可接受的值为：'pt'：返回 PyTorchtorch.Tensor对象。'np'：返回 NumPynp.ndarray对象。
- **kwargs (ProcessingKwargs，可选) — 每种模态（文本、图像、视频、音频）的额外处理选项。模型特定参数已在上方列出；有关支持参数的完整列表，请参阅 TypedDict 类。
VisionTextDualEncoderModel
class transformers.VisionTextDualEncoderModel
< source >( config: transformers.models.vision_text_dual_encoder.configuration_vision_text_dual_encoder.VisionTextDualEncoderConfig | None = Nonevision_model: transformers.modeling_utils.PreTrainedModel | None = Nonetext_model: transformers.modeling_utils.PreTrainedModel | None = None )
参数
- config (VisionTextDualEncoderConfig，可选) — 包含模型所有参数的模型配置类。使用配置文件进行初始化不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
- vision_model (
~modeling_utils.PreTrainedModel, 可选) — 要使用的视觉模型。 - text_model (
~modeling_utils.PreTrainedModel, 可选) — 要使用的文本模型。
输出原始隐藏状态、顶部未附加任何特定头部的裸视觉文本双编码器模型。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonereturn_loss: bool | None = Nonetoken_type_ids: typing.Optional[torch.LongTensor] = Noneoutput_attentions: bool | None = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = None**kwargs ) → CLIPOutput or tuple(torch.Tensor)
参数
- input_ids (
torch.LongTensor形状为(batch_size, sequence_length), ，可选) — 输入序列中各 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- pixel_values (
torch.Tensor，形状为(batch_size, num_channels, image_size, image_size)，可选) — 与输入图像对应的张量。可以使用image_processor_class获取像素值。有关详细信息，请参阅image_processor_class.__call__（VisionTextDualEncoderProcessor 使用image_processor_class处理图像）。 - 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]. - return_loss (
bool, 可选) — 是否返回对比损失。 - token_type_ids (
torch.LongTensor形状为(batch_size, sequence_length), ，可选) — 用于指示输入中第一和第二部分的片段 token 索引。索引取值范围为[0, 1]:- 0 对应 sentence A 标记，
- 1 对应于 sentence B 标记。
- output_attentions (
bool, 可选) — 是否返回所有注意力层的注意力张量。有关详细信息，请参阅返回张量中的attentions。 - output_hidden_states (
bool，可选) — 是否返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量中的hidden_states。 - return_dict (
bool, 可选) — 是否返回 ModelOutput 而不是普通元组。
返回值
CLIPOutput 或 tuple(torch.Tensor)
CLIPOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（VisionTextDualEncoderConfig）和输入。
VisionTextDualEncoderModel 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
- loss (
torch.Tensor，形状为(1,)，可选，当return_loss为True时返回) — 用于图像-文本相似度的对比损失。 - logits_per_image（形状为
(image_batch_size, text_batch_size)的torch.Tensor）—image_embeds与text_embeds之间的缩放点积分数。这表示图像-文本相似度分数。 - logits_per_text（形状为
(text_batch_size, image_batch_size)的torch.Tensor）—text_embeds与image_embeds之间的缩放点积分数。这表示文本-图像相似度分数。 - text_embeds（形状为
(batch_size, output_dim的torch.Tensor）—— 通过对 CLIPTextModel 的池化输出应用投影层获得的文本嵌入。 - image_embeds (
torch.Tensor，形状为(batch_size, output_dim) — 通过对 CLIPVisionModel 的池化输出应用投影层得到的图像嵌入。 - text_model_output (
~modeling_outputs.BaseModelOutputWithPooling，可选) — CLIPTextModel 的输出。 - vision_model_output（
~modeling_outputs.BaseModelOutputWithPooling，可选）— CLIPVisionModel 的输出。
示例：
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import (
... VisionTextDualEncoderModel,
... VisionTextDualEncoderProcessor,
... AutoImageProcessor,
... AutoTokenizer,
... )
>>> tokenizer = AutoTokenizer.from_pretrained("google-bert/bert-base-uncased")
>>> image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224")
>>> processor = VisionTextDualEncoderProcessor(image_processor, tokenizer)
>>> model = VisionTextDualEncoderModel.from_vision_text_pretrained(
... "google/vit-base-patch16-224", "google-bert/bert-base-uncased"
... )
>>> # contrastive training
>>> urls = [
... "http://images.cocodataset.org/val2017/000000039769.jpg",
... "https://farm3.staticflickr.com/2674/5850229113_4fe05d5265_z.jpg",
... ]
>>> with httpx.stream("GET", urls[0]) as response:
... image1 = Image.open(BytesIO(response.read()))
>>> with httpx.stream("GET", urls[1]) as response:
... image2 = Image.open(BytesIO(response.read()))
>>> images = [image1, image2]
>>> inputs = processor(
... text=["a photo of a cat", "a photo of a dog"], images=images, return_tensors="pt", padding=True
... )
>>> outputs = model(
... input_ids=inputs.input_ids,
... attention_mask=inputs.attention_mask,
... pixel_values=inputs.pixel_values,
... return_loss=True,
... )
>>> loss, logits_per_image = outputs.loss, outputs.logits_per_image # this is the image-text similarity score
>>> # save and load from pretrained
>>> model.save_pretrained("vit-bert")
>>> model = VisionTextDualEncoderModel.from_pretrained("vit-bert")
>>> # inference
>>> outputs = model(**inputs)
>>> logits_per_image = outputs.logits_per_image # this is the image-text similarity score
>>> probs = logits_per_image.softmax(dim=1) # we can take the softmax to get the label probabilitiesget_text_features
< source >( input_ids: Tensorattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.Tensor] = Nonetoken_type_ids: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
参数
- input_ids (
torch.Tensor形状为(batch_size, sequence_length)) — 输入序列中各 token 在词汇表中的索引。默认情况下，填充（padding）会被忽略。可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- attention_mask (
torch.Tensor形状为(batch_size, sequence_length), ，可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自[0, 1]:- 1 表示未被屏蔽的 token，
- 对于被掩码的 token，值为 0。
- position_ids (
torch.Tensor形状为(batch_size, sequence_length), 可选) — 输入序列中每个 token 在位置嵌入中的位置索引。取值范围为[0, config.n_positions - 1]. - token_type_ids (
torch.Tensor形状为(batch_size, sequence_length), ，可选) — 用于指示输入中第一和第二部分的片段标记索引。索引取自[0, 1]:- 0 对应 sentence A 标记，
- 1 对应于 sentence B 标记。
返回值
BaseModelOutputWithPooling 或 tuple(torch.Tensor)
一个 BaseModelOutputWithPooling 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（VisionTextDualEncoderConfig）和输入。
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 之后的权重，用于在自注意力头中计算加权平均值。
示例：
>>> import torch
>>> from transformers import VisionTextDualEncoderModel, AutoTokenizer
>>> model = VisionTextDualEncoderModel.from_pretrained("clip-italian/clip-italian")
>>> tokenizer = AutoTokenizer.from_pretrained("clip-italian/clip-italian")
>>> inputs = tokenizer(["una foto di un gatto", "una foto di un cane"], padding=True, return_tensors="pt")
>>> with torch.inference_mode():
... text_features = model.get_text_features(**inputs)get_image_features
< source >( pixel_values: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
参数
- pixel_values (
torch.Tensor，形状为(batch_size, num_channels, image_size, image_size)) — 对应输入图像的张量。像素值可通过image_processor_class获取。有关详细信息，请参阅image_processor_class.__call__（VisionTextDualEncoderProcessor 使用image_processor_class处理图像）。
返回值
BaseModelOutputWithPooling 或 tuple(torch.Tensor)
一个 BaseModelOutputWithPooling 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（VisionTextDualEncoderConfig）和输入。
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 之后的权重，用于在自注意力头中计算加权平均值。
示例：
>>> import torch
>>> from transformers import VisionTextDualEncoderModel, AutoImageProcessor
>>> from transformers.image_utils import load_image
>>> model = VisionTextDualEncoderModel.from_pretrained("clip-italian/clip-italian")
>>> image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224")
>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> image = load_image(url)
>>> inputs = image_processor(images=image, return_tensors="pt")
>>> with torch.inference_mode():
... image_features = model.get_image_features(**inputs)