Transformers documentation
VisionTextDualEncoder
Este modelo foi publicado no HF papers em 2021-11-15 e contribuído para o Hugging Face Transformers em 2021-11-30.
VisionTextDualEncoder
Visão geral
O VisionTextDualEncoderModel pode ser usado para inicializar um modelo de codificador dual de visão-texto com qualquer modelo pré-treinado de auto-encoding de visão como codificador de visão (por exemplo ViT, BEiT, DeiT) e qualquer modelo pré-treinado de auto-encoding de texto como codificador de texto (por exemplo RoBERTa, BERT). Duas camadas de projeção são adicionadas acima dos codificadores de visão e de texto para projetar os embeddings de saída para um espaço latente compartilhado. As camadas de projeção são inicializadas aleatoriamente, portanto, o modelo deve ser ajustado em uma tarefa de nível inferior. Este modelo pode ser usado para alinhar os embeddings de visão-texto usando treinamento contrastivo de imagem-texto semelhante ao CLIP e, em seguida, pode ser usado para tarefas de visão zero-shot, como classificação de imagens ou recuperação.
Em LiT: Zero-Shot Transfer with Locked-image Text Tuning, é demonstrado como o aproveitamento de modelos de imagem e texto pré-treinados (travados/congelados) para aprendizado contrastivo resulta em melhorias significativas em novas tarefas de visão zero-shot, como classificação de imagens ou recuperação.
VisionTextDualEncoderConfig
classe 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 )
Parâmetros
- text_config (
Union[~configuration_utils.PreTrainedConfig, dict], opcional) — O objeto de configuração ou dicionário do backbone de texto. - vision_config (
Union[~configuration_utils.PreTrainedConfig, dict], opcional) — O objeto de configuração ou dicionário do backbone de visão. - projection_dim (
int, opcional, padrão512) — Dimensão das camadas de projeção de texto e visão. - logit_scale_init_value (
Union[int, float], opcional, padrão2.6592) — O valor inicial do parâmetro logit_scale.
Esta é a classe de configuração para armazenar a configuração de um modelo Vision Text Dual Encoder. Ela é usada para instanciar um modelo Vision Text Dual Encoder de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do None
Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.
Exemplos:
>>> 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
Retorna
Uma instância de um objeto de configuração
Instancie um VisionTextDualEncoderConfig (ou uma classe derivada) a partir da configuração do modelo de texto e da configuração do modelo de visão.
VisionTextDualEncoderProcessor
classe transformers.VisionTextDualEncoderProcessor
< source >( image_processor = Nonetokenizer = None**kwargs )
Constrói um VisionTextDualEncoderProcessor que encapsula um processador de imagem e um tokenizer em um único processador.
VisionTextDualEncoderProcessor oferece todas as funcionalidades de image_processor_class e tokenizer_class. Consulte ~image_processor_class e ~tokenizer_class para mais informações.
__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'> )
Parâmetros
- images (
Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], opcional) — Imagem a ser pré-processada. Espera uma única imagem ou um lote de imagens com valores de pixel variando de 0 a 255. Se passar imagens com valores de pixel entre 0 e 1, definado_rescale=False. - text (
Union[str, list[str], list[list[str]]], opcional) — A sequência ou lote de sequências a ser codificada. Cada sequência pode ser uma string ou uma lista de strings (string pré-tokenizada). Se você passar uma entrada pré-tokenizada, definais_split_into_words=Truepara evitar ambiguidade com entradas em lote. - 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]]], opcional) — Vídeo a ser pré-processado. Espera um único vídeo ou um lote de vídeos com valores de pixel variando de 0 a 255. Se passar vídeos com valores de pixel entre 0 e 1, definado_rescale=False. - audio (
Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]], opcional) — O áudio ou lote de áudios a ser preparado. Cada áudio pode ser um array NumPy ou um tensor PyTorch. No caso de um array NumPy/tensor PyTorch, cada áudio deve ter a forma (C, T), onde C é o número de canais e T é o comprimento de amostras do áudio. - return_tensors (
strou TensorType, opcional) — Se definido, retornará tensors de um framework específico. Os valores aceitos são:'pt': Retorna objetostorch.Tensordo PyTorch.'np': Retorna objetosnp.ndarraydo NumPy.
- **kwargs (ProcessingKwargs, opcional) — Opções de processamento adicionais para cada modalidade (texto, imagens, vídeos, áudio). Os parâmetros específicos do modelo estão listados acima; consulte a classe TypedDict para a lista completa de argumentos suportados.
VisionTextDualEncoderModel
classe 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 )
Parâmetros
- config (VisionTextDualEncoderConfig, opcional) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.
- vision_model (
~modeling_utils.PreTrainedModel, opcional) — O modelo de visão a ser utilizado. - text_model (
~modeling_utils.PreTrainedModel, opcional) — O modelo de texto a ser usado.
O modelo Vision Text Dual Encoder puro, que produz estados ocultos brutos sem nenhum head específico no topo.
Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)
Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.
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)
Parâmetros
- input_ids (
torch.LongTensorde forma(batch_size, sequence_length), opcional) — Índices dos tokens da sequência de entrada no vocabulário. O padding será ignorado por padrão.Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.
- pixel_values (
torch.Tensorde forma(batch_size, num_channels, image_size, image_size), opcional) — Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usandoimage_processor_class. Consulteimage_processor_class.__call__para mais detalhes (VisionTextDualEncoderProcessor usaimage_processor_classpara processar as imagens). - attention_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em[0, 1]:- 1 para tokens que não estão mascarados,
- 0 para tokens que estão mascarados.
- position_ids (
torch.LongTensorde forma(batch_size, sequence_length), opcional) — Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo[0, config.n_positions - 1]. - return_loss (
bool, opcional) — Se deve ou não retornar a perda contrastiva. - token_type_ids (
torch.LongTensorde forma(batch_size, sequence_length), opcional) — Índices de tokens de segmento para indicar as primeiras e segundas partes das entradas. Os índices são selecionados em[0, 1]:- 0 corresponde a um token de sentence A,
- 1 corresponde a um token de sentence B.
- output_attentions (
bool, opcional) — Indica se os tensores de atenção de todas as camadas de atenção devem ser retornados. Consulteattentionsnos tensores retornados para mais detalhes. - output_hidden_states (
bool, opcional) — Indica se as hidden states de todas as camadas devem ser retornadas. Consultehidden_statesem tensors retornados para mais detalhes. - return_dict (
bool, opcional) — Indica se deve retornar um ModelOutput em vez de uma tupla simples.
Retorna
CLIPOutput ou tuple(torch.Tensor)
Uma CLIPOutput ou uma tupla de
torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários
elementos, dependendo da configuração (VisionTextDualEncoderConfig) e das entradas.
O método forward do VisionTextDualEncoderModel substitui o método especial __call__.
Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de
Moduleem seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.
- loss (
torch.Tensorde forma(1,), opcional, retornado quandoreturn_losséTrue) — Perda contrastiva para similaridade entre imagem e texto. - logits_per_image (
torch.Tensorde forma(image_batch_size, text_batch_size)) — As pontuações de produto escalar escalonado entreimage_embedsetext_embeds. Isso representa as pontuações de similaridade entre imagem e texto. - logits_per_text (
torch.Tensorde forma(text_batch_size, image_batch_size)) — As pontuações de produto escalar escalonado entretext_embedseimage_embeds. Isso representa as pontuações de similaridade texto-imagem. - text_embeds (
torch.Tensorde forma(batch_size, output_dim) — Os embeddings de texto obtidos aplicando a camada de projeção à saída agregada do CLIPTextModel. - image_embeds (
torch.Tensorde forma(batch_size, output_dim) — Os embeddings de imagem obtidos aplicando a camada de projeção à saída agregada do CLIPVisionModel. - text_model_output (
~modeling_outputs.BaseModelOutputWithPooling, opcional) — A saída do CLIPTextModel. - vision_model_output (
~modeling_outputs.BaseModelOutputWithPooling, opcional) — A saída do CLIPVisionModel.
Exemplos:
>>> 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)
Parâmetros
- input_ids (
torch.Tensorde formato(batch_size, sequence_length)) — Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão.Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.
- attention_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em[0, 1]:- 1 para tokens que não estão mascarados,
- 0 para tokens que estão mascarados.
- position_ids (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo[0, config.n_positions - 1]. - token_type_ids (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Índices de tokens de segmento para indicar as primeiras e segundas partes das entradas. Os índices são selecionados em[0, 1]:- 0 corresponde a um token de sentence A,
- 1 corresponde a um token de sentence B.
Retorna
BaseModelOutputWithPooling ou tuple(torch.Tensor)
Um BaseModelOutputWithPooling ou uma tupla de
torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False), contendo vários
elementos dependendo da configuração (VisionTextDualEncoderConfig) e das entradas.
last_hidden_state (
torch.Tensorde forma(batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.pooler_output (
torch.Tensorde forma(batch_size, hidden_size)) — Estado oculto da última camada do primeiro token da sequência (token de classificação) após processamento adicional através das camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para a família de modelos BERT, isso retorna o token de classificação após o processamento através de uma camada linear e uma função de ativação tanh. Os pesos da camada linear são treinados a partir do objetivo de previsão da próxima frase (classificação) durante o pré-treinamento.hidden_states (
tuple(torch.Tensor), opcional, retornado quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.Tensor(um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma(batch_size, sequence_length, hidden_size).Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
attentions (
tuple(torch.Tensor), opcional, retornado quandooutput_attentions=Trueé passado ou quandoconfig.output_attentions=True) — Tupla detorch.Tensor(um para cada camada) com forma(batch_size, num_heads, sequence_length, sequence_length).Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.
Exemplos:
>>> 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)
Parâmetros
- pixel_values (
torch.Tensorde forma(batch_size, num_channels, image_size, image_size)) — Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usandoimage_processor_class. Consulteimage_processor_class.__call__para mais detalhes (VisionTextDualEncoderProcessor usaimage_processor_classpara processar as imagens).
Retorna
BaseModelOutputWithPooling ou tuple(torch.Tensor)
Um BaseModelOutputWithPooling ou uma tupla de
torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários
elementos, dependendo da configuração (VisionTextDualEncoderConfig) e das entradas.
last_hidden_state (
torch.Tensorde forma(batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.pooler_output (
torch.Tensorde forma(batch_size, hidden_size)) — Estado oculto da última camada do primeiro token da sequência (token de classificação) após processamento adicional através das camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para a família de modelos BERT, isso retorna o token de classificação após o processamento através de uma camada linear e uma função de ativação tanh. Os pesos da camada linear são treinados a partir do objetivo de previsão da próxima frase (classificação) durante o pré-treinamento.hidden_states (
tuple(torch.Tensor), opcional, retornado quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.Tensor(um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma(batch_size, sequence_length, hidden_size).Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
attentions (
tuple(torch.Tensor), opcional, retornado quandooutput_attentions=Trueé passado ou quandoconfig.output_attentions=True) — Tupla detorch.Tensor(um para cada camada) com forma(batch_size, num_heads, sequence_length, sequence_length).Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.
Exemplos:
>>> 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)