# LFM3-VL

## Visão geral

LFM3-VL é a família de modelos de visão-linguagem construída sobre o [LFM3](./lfm3) pela [Liquid AI](https://liquid.ai/). Ele aceita imagens e vídeos em sua resolução nativa, juntamente com texto.

## Arquitetura

LFM3-VL consiste em um codificador de visão, um projetor e um modelo de linguagem LFM3. O codificador de visão é, em si, um híbrido Liquid: um linear patchifier seguido por camadas de convolução 2D depthwise com gate e camadas de atenção grouped-query bidirecional com embeddings rotativos 2D sobre a grade de patches de cada quadro. As imagens são divididas em patches de 16x16 com o pré-processamento de resolução dinâmica do Qwen2-VL, enquanto os vídeos, adicionalmente, emparelham quadros consecutivos e prefixam cada quadro com seu timestamp. O projetor mescla cada bloco 2x2 de recursos de patch em um único token de linguagem com uma camada de normalização e um MLP de duas camadas.

## Exemplo

O exemplo a seguir mostra como gerar uma resposta usando a classe `AutoModelForImageTextToText`.

```python
from transformers import AutoModelForImageTextToText, AutoProcessor

# Load model and processor
model_id = "LiquidAI/LFM3-VL-2B"
model = AutoModelForImageTextToText.from_pretrained(model_id, device_map="auto")
processor = AutoProcessor.from_pretrained(model_id)

# Load image and create conversation
conversation = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": "https://www.ilankelman.org/stopsigns/australia.jpg"},
            {"type": "text", "text": "What is in this image?"},
        ],
    },
]

# Generate answer
inputs = processor.apply_chat_template(
    conversation,
    add_generation_prompt=True,
    return_tensors="pt",
    return_dict=True,
    tokenize=True,
).to(model.device, model.dtype)

outputs = model.generate(**inputs, max_new_tokens=64)
processor.batch_decode(outputs, skip_special_tokens=True)[0]
```

## Lfm3VlProcessor[[transformers.Lfm3VlProcessor]]

#### transformers.Lfm3VlProcessor[[transformers.Lfm3VlProcessor]]

```python
transformers.Lfm3VlProcessor(image_processor = None, tokenizer = None, video_processor = None, chat_template = None, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/lfm3_vl/processing_lfm3_vl.py#L30)

**Parâmetros:**

image_processor (`Qwen2VLImageProcessor`) : O processador de imagem é uma entrada obrigatória.

tokenizer (`tokenizer_class`) : O tokenizer é uma entrada obrigatória.

video_processor (`Qwen3VLVideoProcessor`) : O processador de vídeo é uma entrada obrigatória.

chat_template (`str`) : Um modelo Jinja para converter listas de mensagens em um chat em uma string tokenizável.

Constrói um Lfm3VlProcessor que encapsula um processador de imagem, um tokenizador e um processador de vídeo em um único processador.

[Lfm3VlProcessor](/docs/transformers/v5.23.0/pt/model_doc/lfm3_vl#transformers.Lfm3VlProcessor) oferece todas as funcionalidades de [Qwen2VLImageProcessor](/docs/transformers/v5.23.0/pt/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor), `tokenizer_class` e [Qwen3VLVideoProcessor](/docs/transformers/v5.23.0/pt/model_doc/qwen3_vl#transformers.Qwen3VLVideoProcessor). Consulte [~Qwen2VLImageProcessor](/docs/transformers/v5.23.0/pt/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor), `~tokenizer_class` e [~Qwen3VLVideoProcessor](/docs/transformers/v5.23.0/pt/model_doc/qwen3_vl#transformers.Qwen3VLVideoProcessor) para mais informações.

#### post_process_image_text_to_text[[transformers.Lfm3VlProcessor.post_process_image_text_to_text]]

```python
post_process_image_text_to_text(generated_outputs, skip_special_tokens = True, clean_up_tokenization_spaces = False, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/lfm3_vl/processing_lfm3_vl.py#L140)

**Parâmetros:**

generated_outputs (`torch.Tensor` ou `np.ndarray`) : A saída da função `generate` do modelo. A saída deve ser um tensor com a forma `(batch_size, sequence_length)` ou `(sequence_length,)`.

skip_special_tokens (`bool`, *opcional*, padrão `True`) : Indica se os tokens especiais devem ser removidos na saída. Argumento passado para o método `batch_decode` do tokenizer.

clean_up_tokenization_spaces (`bool`, *opcional*, padrão `False`) : Indica se os espaços de tokenização devem ser limpos ou não. Argumento passado para o método `batch_decode` do tokenizer.

- ****kwargs** : Argumentos adicionais a serem passados para o `batch_decode method` do tokenizer.

**Retorna:** `list[str]`

O texto decodificado.

Pós-processe a saída do modelo para decodificar o texto.

## Lfm3VlConfig[[transformers.Lfm3VlConfig]]

#### transformers.Lfm3VlConfig[[transformers.Lfm3VlConfig]]

```python
transformers.Lfm3VlConfig(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, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, text_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, image_token_id: int = 125030, video_token_id: int = 125029, vision_start_token_id: int = 125009, vision_end_token_id: int = 125010, projector_hidden_act: str = 'gelu', projector_hidden_size: int = 4096, projector_bias: bool = True, tie_word_embeddings: bool = True)
```

[Origem](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/lfm3_vl/configuration_lfm3_vl.py#L63)

**Parâmetros:**

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : O objeto de configuração ou dicionário do backbone de visão.

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : O objeto de configuração ou dicionário do backbone de texto.

image_token_id (`int`, *opcional*, padrão `125030`) : O índice do token de imagem usado como marcador para as imagens de entrada.

video_token_id (`int`, *opcional*, padrão `125029`) : O índice do token de vídeo usado como marcador para vídeos de entrada.

vision_start_token_id (`int`, *opcional*, padrão `125009`) : ID do token que marca o início de um segmento visual na sequência de entrada multimodal.

vision_end_token_id (`int`, *opcional*, padrão `125010`) : ID do token que marca o fim de um segmento visual na sequência de entrada multimodal.

projector_hidden_act (`str`, *opcional*, padrão `gelu`) : A função de ativação usada pelo projetor multimodal.

projector_hidden_size (`int`, *opcional*, padrão `4096`) : Dimensionalidade das camadas de projeção de texto e visão.

projector_bias (`bool`, *opcional*, padrão `True`) : Se deve usar viés no projetor multimodal.

tie_word_embeddings (`bool`, *opcional*, padrão `True`) : Se deve vincular as embeddings de pesos de acordo com o mapeamento `tied_weights_keys` do modelo.

Esta é a classe de configuração para armazenar a configuração de um Lfm3VlModel. Ela é usada para instanciar um modelo Lfm3 Vl 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 [LiquidAI/LFM3-VL-2B](https://huggingface.co/LiquidAI/LFM3-VL-2B)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/v5.23.0/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/v5.23.0/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

## Lfm3VlVisionConfig[[transformers.Lfm3VlVisionConfig]]

#### transformers.Lfm3VlVisionConfig[[transformers.Lfm3VlVisionConfig]]

```python
transformers.Lfm3VlVisionConfig(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 = 2560, in_channels: int = 3, patch_size: int | list[int] | tuple[int, int] = 16, spatial_merge_size: int = 2, temporal_patch_size: int | list[int] | tuple[int, int] = 2, initializer_range: float = 0.02, rope_parameters: dict | None = None, num_hidden_layers: int = 14, num_attention_heads: int = 16, num_key_value_heads: int = 8, layer_types: list[str] | None = None, conv_kernel_size: int = 3, norm_eps: float = 1e-05)
```

[Origem](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/lfm3_vl/configuration_lfm3_vl.py#L29)

**Parâmetros:**

hidden_size (`int`, *opcional*, padrão `1024`) : Dimensão das representações ocultas.

intermediate_size (`int`, *opcional*, padrão `2560`) : Dimensão das representações do MLP.

in_channels (`int`, *opcional*, padrão `3`) : O número de canais de entrada.

patch_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, padrão `16`) : O tamanho (resolução) de cada patch.

spatial_merge_size (`int`, *opcional*, padrão `2`) : O tamanho da janela de mesclagem espacial usada para reduzir o número de tokens visuais mesclando patches vizinhos.

temporal_patch_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, padrão `2`) : Tamanho do patch temporal usado no embedding de patch 3D para entradas de vídeo.

initializer_range (`float`, *opcional*, padrão `0.02`) : O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

rope_parameters (`dict`, *opcional*) : Dicionário contendo os parâmetros de configuração para os embeddings RoPE. O dicionário deve conter um valor para `rope_theta` e, opcionalmente, parâmetros usados para escalonamento, caso você queira usar RoPE com `max_position_embeddings` maiores.

num_hidden_layers (`int`, *opcional*, padrão `14`) : Número de camadas ocultas no decodificador do Transformer.

num_attention_heads (`int`, *opcional*, padrão `16`) : Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.

num_key_value_heads (`int`, *opcional*, padrão `8`) : Este é o número de cabeças de key_value que devem ser usadas para implementar Grouped Query Attention. Se `num_key_value_heads=num_attention_heads`, o modelo usará Multi Head Attention (MHA); se `num_key_value_heads=1`, o modelo usará Multi Query Attention (MQA); caso contrário, será usado GQA. Ao converter um checkpoint multi-head para um checkpoint GQA, cada cabeça de chave e valor do grupo deve ser construída pela média (meanpooling) de todas as cabeças originais dentro desse grupo. Para mais detalhes, consulte [este artigo](https://huggingface.co/papers/2305.13245). Se não for especificado, o valor padrão será `num_attention_heads`.

layer_types (`list[str]`, *opcional*) : Uma lista que mapeia explicitamente cada índice de camada com seu tipo de camada. Se não for fornecida, será gerada automaticamente com base nos valores de config.

conv_kernel_size (`int`, *opcional*, padrão 3) : Tamanho do kernel da convolução depthwise sobre a grade de patches de cada quadro.

norm_eps (`float`, *opcional*, padrão `1e-05`) : O epsilon usado pelas camadas de normalização de camada.

Esta é a classe de configuração para armazenar a configuração de um Lfm3VlModel. Ela é usada para instanciar um modelo Lfm3 Vl 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 [LiquidAI/LFM3-VL-2B](https://huggingface.co/LiquidAI/LFM3-VL-2B)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/v5.23.0/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/v5.23.0/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

## Lfm3VlVisionModel[[transformers.Lfm3VlVisionModel]]

#### transformers.Lfm3VlVisionModel[[transformers.Lfm3VlVisionModel]]

```python
transformers.Lfm3VlVisionModel(config: Lfm3VlVisionConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/lfm3_vl/modeling_lfm3_vl.py#L398)

**Parâmetros:**

config ([Lfm3VlVisionConfig](/docs/transformers/v5.23.0/pt/model_doc/lfm3_vl#transformers.Lfm3VlVisionConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. Inicializar com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/v5.23.0/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O codificador de visão do LFM3-VL: uma pilha de camadas de convolução com gate e de atenção bidirecional sobre os patches de cada imagem ou quadro de vídeo, incorporados por um incorporamento linear de patches.

Este modelo herda de [PreTrainedModel](/docs/transformers/v5.23.0/pt/main_classes/model#transformers.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](https://pytorch.org/docs/stable/nn.html#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 e comportamento gerais.

#### forward[[transformers.Lfm3VlVisionModel.forward]]

```python
forward(pixel_values: Tensor, grid_thw: Tensor, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/lfm3_vl/modeling_lfm3_vl.py#L424)

**Parâmetros:**

pixel_values (`torch.Tensor` de forma `(num_patches, in_channels * temporal_patch_size * patch_size**2)`) : Os patches achatados de cada imagem ou vídeo, agrupados por bloco de mesclagem.

grid_thw (`torch.LongTensor` de forma `(num_images_or_videos, 3)`) : As dimensões temporal, de altura e de largura da grade de patches de cada imagem ou vídeo.

**Retorna:** [BaseModelOutputWithPooling](/docs/transformers/v5.23.0/pt/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) ou `tuple(torch.Tensor)`

Um [BaseModelOutputWithPooling](/docs/transformers/v5.23.0/pt/main_classes/output#transformers.modeling_outputs.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 ([Lfm3VlConfig](/docs/transformers/v5.23.0/pt/model_doc/lfm3_vl#transformers.Lfm3VlConfig)) e das entradas.

O método forward do [Lfm3VlVisionModel](/docs/transformers/v5.23.0/pt/model_doc/lfm3_vl#transformers.Lfm3VlVisionModel) 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 `Module` em 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.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do modelo.
- **pooler_output** (`torch.Tensor` de forma `(batch_size, hidden_size)`) -- Estado oculto da última camada do primeiro token da sequência (token de classificação) após processamento adicional pelas camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para modelos da família BERT, isso retorna o token de classificação após o processamento por 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 quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a 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 quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a 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 nas cabeças de autoatenção.

## Lfm3VlModel[[transformers.Lfm3VlModel]]

#### transformers.Lfm3VlModel[[transformers.Lfm3VlModel]]

```python
transformers.Lfm3VlModel(config: Lfm3VlConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/lfm3_vl/modeling_lfm3_vl.py#L521)

**Parâmetros:**

config ([Lfm3VlConfig](/docs/transformers/v5.23.0/pt/model_doc/lfm3_vl#transformers.Lfm3VlConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. Inicializar com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/v5.23.0/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo Lfm3 Vl puro, que gera estados ocultos brutos sem nenhum head específico no topo.

Este modelo herda de [PreTrainedModel](/docs/transformers/v5.23.0/pt/main_classes/model#transformers.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](https://pytorch.org/docs/stable/nn.html#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 e comportamento gerais.

#### forward[[transformers.Lfm3VlModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.FloatTensor] = None, pixel_values: typing.Optional[torch.FloatTensor] = None, image_grid_thw: typing.Optional[torch.LongTensor] = None, pixel_values_videos: typing.Optional[torch.FloatTensor] = None, video_grid_thw: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/lfm3_vl/modeling_lfm3_vl.py#L602)

**Parâmetros:**

input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Í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](/docs/transformers/v5.23.0/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids)

attention_mask (`torch.Tensor` de 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**.  [O que são máscaras de atenção?](../glossary#attention-mask)

position_ids (`torch.LongTensor` de 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]`.  [O que são IDs de posição?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`.  Apenas uma instância de [Cache](/docs/transformers/v5.23.0/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/v5.23.0/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão.  O modelo sairá no mesmo formato de cache que foi fornecido como entrada.  Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`.

inputs_embeds (`torch.FloatTensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo.

pixel_values (`torch.FloatTensor` de forma `(batch_size, num_channels, image_size, image_size)`, *opcional*) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [Qwen2VLImageProcessor](/docs/transformers/v5.23.0/pt/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor). Veja [Qwen2VLImageProcessor.__call__()](/docs/transformers/v5.23.0/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes ([Lfm3VlProcessor](/docs/transformers/v5.23.0/pt/model_doc/lfm3_vl#transformers.Lfm3VlProcessor) usa [Qwen2VLImageProcessor](/docs/transformers/v5.23.0/pt/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor) para processar imagens).

image_grid_thw (`torch.LongTensor` de forma `(num_images, 3)`, *opcional*) : O tempo, a altura e a largura da forma dos recursos de cada imagem no LLM.

pixel_values_videos (`torch.FloatTensor` de forma `(batch_size, num_frames, num_channels, frame_size, frame_size)`, *opcional*) : Os tensores correspondentes ao vídeo de entrada. Os valores de pixels para vídeos podem ser obtidos usando [Qwen3VLVideoProcessor](/docs/transformers/v5.23.0/pt/model_doc/qwen3_vl#transformers.Qwen3VLVideoProcessor). Veja [Qwen3VLVideoProcessor.__call__()](/docs/transformers/v5.23.0/pt/model_doc/molmo2#transformers.Molmo2VideoProcessor.__call__) para detalhes ([Lfm3VlProcessor](/docs/transformers/v5.23.0/pt/model_doc/lfm3_vl#transformers.Lfm3VlProcessor) usa [Qwen3VLVideoProcessor](/docs/transformers/v5.23.0/pt/model_doc/qwen3_vl#transformers.Qwen3VLVideoProcessor) para processar vídeos).

video_grid_thw (`torch.LongTensor` de forma `(num_videos, 3)`, *opcional*) : O valor temporal, a altura e a largura da forma dos recursos de cada vídeo no LLM.

use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`).

mm_encoder_outputs (`dict[str, ~modeling_outputs.BaseModelOutputWithPooling]`, *opcional*) : Dicionário em que as chaves são as modalidades suportadas e os valores são as saídas codificadas para essa modalidade. Cada saída codificada é uma tupla que consiste em (`pooler_output`, *opcional*: `last_hidden_states`, *opcional*: `hidden_states`, *opcional*: `attentions`) `pooler_output` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) é uma sequência de recursos multimodais do codificador mesclados em incorporações de texto.

**Retorna:** `Lfm3VlModelOutputWithPast` ou `tuple(torch.Tensor)`

Um `Lfm3VlModelOutputWithPast` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) compreendendo vários elementos dependendo da configuração ([Lfm3VlConfig](/docs/transformers/v5.23.0/pt/model_doc/lfm3_vl#transformers.Lfm3VlConfig)) e das entradas.

O método forward do [Lfm3VlModel](/docs/transformers/v5.23.0/pt/model_doc/lfm3_vl#transformers.Lfm3VlModel) 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 `Module` em 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.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do modelo.

  Se `past_key_values` for usado, apenas o último hidden-state das sequências, com forma `(batch_size, 1, hidden_size)`, é retornado.
- **past_key_values** (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- Trata-se de uma instância de [Cache](/docs/transformers/v5.23.0/pt/internal/generation_utils#transformers.Cache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Contém estados ocultos pré-computados (chaves e valores nos blocos de autoatenção e, opcionalmente, se `config.is_encoder_decoder=True`, nos blocos de atenção cruzada) que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a 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 quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a 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 nas cabeças de autoatenção.
- **image_pooler_output** (`torch.FloatTensor`, *opcional*) -- Um `torch.FloatTensor` de tamanho `(num_image_tokens, hidden_size)`. Recursos de imagem produzidos pelo codificador de visão e projetados para o tamanho oculto do modelo de linguagem.
- **video_pooler_output** (`torch.FloatTensor`, *opcional*) -- Um `torch.FloatTensor` de tamanho `(num_video_tokens, hidden_size)`. Recursos de vídeo produzidos pelo codificador de visão e projetados para o tamanho oculto do modelo de linguagem.

## Lfm3VlForConditionalGeneration[[transformers.Lfm3VlForConditionalGeneration]]

#### transformers.Lfm3VlForConditionalGeneration[[transformers.Lfm3VlForConditionalGeneration]]

```python
transformers.Lfm3VlForConditionalGeneration(config: Lfm3VlConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/lfm3_vl/modeling_lfm3_vl.py#L682)

**Parâmetros:**

config ([Lfm3VlConfig](/docs/transformers/v5.23.0/pt/model_doc/lfm3_vl#transformers.Lfm3VlConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. Inicializar com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/v5.23.0/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo LFM3_VL, que consiste em um backbone de visão e um modelo de linguagem.

Este modelo herda de [PreTrainedModel](/docs/transformers/v5.23.0/pt/main_classes/model#transformers.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](https://pytorch.org/docs/stable/nn.html#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 e comportamento gerais.

#### forward[[transformers.Lfm3VlForConditionalGeneration.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.FloatTensor] = None, pixel_values: typing.Optional[torch.FloatTensor] = None, image_grid_thw: typing.Optional[torch.LongTensor] = None, pixel_values_videos: typing.Optional[torch.FloatTensor] = None, video_grid_thw: typing.Optional[torch.LongTensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/lfm3_vl/modeling_lfm3_vl.py#L723)

**Parâmetros:**

input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Í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](/docs/transformers/v5.23.0/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids)

attention_mask (`torch.Tensor` de 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**.  [O que são máscaras de atenção?](../glossary#attention-mask)

position_ids (`torch.LongTensor` de 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]`.  [O que são IDs de posição?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`.  Apenas uma instância de [Cache](/docs/transformers/v5.23.0/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/v5.23.0/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão.  O modelo sairá no mesmo formato de cache que foi fornecido como entrada.  Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`.

inputs_embeds (`torch.FloatTensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo.

pixel_values (`torch.FloatTensor` de forma `(batch_size, num_channels, image_size, image_size)`, *opcional*) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [Qwen2VLImageProcessor](/docs/transformers/v5.23.0/pt/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor). Veja [Qwen2VLImageProcessor.__call__()](/docs/transformers/v5.23.0/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes ([Lfm3VlProcessor](/docs/transformers/v5.23.0/pt/model_doc/lfm3_vl#transformers.Lfm3VlProcessor) usa [Qwen2VLImageProcessor](/docs/transformers/v5.23.0/pt/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor) para processar imagens).

image_grid_thw (`torch.LongTensor` de forma `(num_images, 3)`, *opcional*) : O tempo, a altura e a largura da forma dos recursos de cada imagem no LLM.

pixel_values_videos (`torch.FloatTensor` de forma `(batch_size, num_frames, num_channels, frame_size, frame_size)`, *opcional*) : Os tensores correspondentes ao vídeo de entrada. Os valores de pixels para vídeos podem ser obtidos usando [Qwen3VLVideoProcessor](/docs/transformers/v5.23.0/pt/model_doc/qwen3_vl#transformers.Qwen3VLVideoProcessor). Veja [Qwen3VLVideoProcessor.__call__()](/docs/transformers/v5.23.0/pt/model_doc/molmo2#transformers.Molmo2VideoProcessor.__call__) para detalhes ([Lfm3VlProcessor](/docs/transformers/v5.23.0/pt/model_doc/lfm3_vl#transformers.Lfm3VlProcessor) usa [Qwen3VLVideoProcessor](/docs/transformers/v5.23.0/pt/model_doc/qwen3_vl#transformers.Qwen3VLVideoProcessor) para processar vídeos).

video_grid_thw (`torch.LongTensor` de forma `(num_videos, 3)`, *opcional*) : O valor temporal, a altura e a largura da forma dos recursos de cada vídeo no LLM.

labels (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Rótulos para calcular a perda de modelagem de linguagem mascarada. Os índices devem estar em `[0, ..., config.vocab_size]` ou ser -100 (veja a docstring de `input_ids`). Tokens com índices definidos como `-100` são ignorados (mascarados); a perda é calculada apenas para os tokens com rótulos em `[0, ..., config.vocab_size]`.

use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`).

logits_to_keep (`Union[int, torch.Tensor]`, *opcional*, padrão `0`) : Se for um `int`, calcula os logits para os últimos `logits_to_keep` tokens. Se for `0`, calcula os logits para todos os `input_ids` (caso especial). Apenas os logits do último token são necessários para a geração, e calculá-los apenas para esse token pode economizar memória, o que se torna bastante significativo para sequências longas ou tamanho de vocabulário grande. Se for um `torch.Tensor`, deve ser 1D, correspondendo aos índices a serem mantidos na dimensão de comprimento da sequência. Isso é útil ao usar o formato de tensor empacotado (uma única dimensão para lote e comprimento da sequência).

mm_encoder_outputs (`dict[str, ~modeling_outputs.BaseModelOutputWithPooling]`, *opcional*) : Dicionário em que as chaves são as modalidades suportadas e os valores são as saídas codificadas para essa modalidade. Cada saída codificada é uma tupla que consiste em (`pooler_output`, *opcional*: `last_hidden_states`, *opcional*: `hidden_states`, *opcional*: `attentions`) `pooler_output` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) é uma sequência de recursos multimodais do codificador mesclados em incorporações de texto.

**Retorna:** `Lfm3VlCausalLMOutputWithPast` ou `tuple(torch.Tensor)`

Um `Lfm3VlCausalLMOutputWithPast` 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 ([Lfm3VlConfig](/docs/transformers/v5.23.0/pt/model_doc/lfm3_vl#transformers.Lfm3VlConfig)) e das entradas.

O método forward de [Lfm3VlForConditionalGeneration](/docs/transformers/v5.23.0/pt/model_doc/lfm3_vl#transformers.Lfm3VlForConditionalGeneration) sobrescreve 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 `Module` em 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.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de modelagem de linguagem (para previsão do próximo token).
- **logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.vocab_size)`) -- Pontuações de previsão da cabeça de modelagem de linguagem (pontuações para cada token do vocabulário antes do SoftMax).
- **past_key_values** (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- Trata-se de uma instância de [Cache](/docs/transformers/v5.23.0/pt/internal/generation_utils#transformers.Cache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Contém estados ocultos pré-computados (chaves e valores nos blocos de autoatenção) que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a 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 quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a 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 nas cabeças de autoatenção.
- **image_pooler_output** (`torch.FloatTensor`, *opcional*) -- Um `torch.FloatTensor` de tamanho `(num_image_tokens, hidden_size)`. Recursos de imagem produzidos pelo codificador de visão e projetados para o tamanho oculto do modelo de linguagem.
- **video_pooler_output** (`torch.FloatTensor`, *opcional*) -- Um `torch.FloatTensor` de tamanho `(num_video_tokens, hidden_size)`. Recursos de vídeo produzidos pelo codificador de visão e projetados para o tamanho oculto do modelo de linguagem.

Exemplo:

```python
>>> from transformers import AutoProcessor, AutoModelForImageTextToText

>>> model = AutoModelForImageTextToText.from_pretrained("LiquidAI/LFM3-VL-2B")
>>> processor = AutoProcessor.from_pretrained("LiquidAI/LFM3-VL-2B")

>>> conversation = [
...     {
...         "role": "user",
...         "content": [
...             {"type": "image", "url": "https://www.ilankelman.org/stopsigns/australia.jpg"},
...             {"type": "text", "text": "What is in this image?"},
...         ],
...     },
... ]

>>> inputs = processor.apply_chat_template(
...     conversation, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt"
... ).to(model.device, model.dtype)

>>> outputs = model.generate(**inputs, max_new_tokens=45)
>>> processor.batch_decode(outputs, skip_special_tokens=True)[0]
```

