# Gemma 4 Unified Assistant

## Visão geral

O Gemma 4 Unified Assistant é um modelo pequeno, apenas de texto, que permite a decodificação especulativa para os modelos Gemma 4 Unified usando o método de Previsão de Múltiplos Tokens (MTP) e o gerador de candidatos associado. Modelos pré-treinados são fornecidos para as variantes IT do modelo Gemma 4 12B.

Para mais informações, consulte [Gemma4 Assistant](./gemma4_assistant). Arquitetural e conceitualmente, eles compartilham o mesmo conceito e as diferenças em relação ao seu modelo base:

*   **O modelo inteiro usa compartilhamento de KV**. Essa técnica, introduzida originalmente com o [Gemma 3n](./gemma3n), permite que o modelo reutilize o cache de KV preenchido pelo modelo de destino suportado pelo assistente, permitindo que o assistente pule completamente a fase de pre-fille e reduza consideravelmente o cálculo de atenção durante a passagem para frente.
*   **Os valores de `position_ids` são constantes**. Como o cache KV é compartilhado e o assistente não tem como atualizar o cache, ele prevê todos os tokens a partir do mesmo ID de posição.
*   **As entradas são a concatenação dos embeddings e dos hidden states**. Para se adaptar ao KV cache estático e a `position_ids`, o modelo recebe suas entradas como a concatenação do `embedding` e dos `hidden_states` do último token visto pelo modelo de destino e os projeta para o espaço do modelo assistente com uma transformação `nn.Linear`. A definição de último token visto muda ao longo do loop de decodificação assistida. Para o primeiro token rascunhado após o pre-fill, o último token visto será o último token do prompt. Para as etapas de rascunho subsequentes, o último token visto será o último token gerado pelo assistente (dentro de uma rodada de rascunho) ou o último token aceito pelo modelo de destino (entre as rodadas de rascunho).
*   **A cross-attention é usada para aproveitar ao máximo o contexto do modelo de destino**. A cross-attention permite que os estados de consulta gerados pelo assistente atendam aos valores do cache KV compartilhados pelo modelo de destino, permitindo que o assistente preveja com precisão mais tokens rascunhados por rodada de rascunho.

## Exemplos de uso

O exemplo abaixo demonstra como gerar texto com base em uma imagem usando [Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline) ou a classe [AutoModel](/docs/transformers/main/pt/model_doc/auto#transformers.AutoModel).

```py
import torch
from transformers import pipeline

pipeline = pipeline(
    task="image-text-to-text",
    model="google/gemma-4-12B-it",
    assistant_model="google/gemma-4-12B-it-assistant",
)
pipeline(
    images="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg",
    text="<|image|>\n\nWhat is shown in this image?"
)
```

```py
import torch
from transformers import AutoProcessor, AutoModelForImageTextToText

model = AutoModelForImageTextToText.from_pretrained(
    "google/gemma-4-12B-it",
    dtype=torch.bfloat16,
    device_map="auto",
)
assistant_model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-4-12B-it-assistant",
    dtype=torch.bfloat16,
    device_map="auto",
)

processor = AutoProcessor.from_pretrained(
    "google/gemma-4-12B-it",
    padding_side="left"
)
messages = [
    {
        "role": "user", "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
            {"type": "text", "text": "What is shown in this image?"},
        ]
    },
]
inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    add_generation_prompt=True,
).to(model.device)
input_len = inputs["input_ids"].shape[-1]

output = model.generate(**inputs, max_new_tokens=50, assistant_model=assistant_model)
print(processor.decode(output[0][input_len:], skip_special_tokens=True))
```

## Gemma4UnifiedAssistantConfig[[transformers.Gemma4UnifiedAssistantConfig]]

#### transformers.Gemma4UnifiedAssistantConfig[[transformers.Gemma4UnifiedAssistantConfig]]

```python
transformers.Gemma4UnifiedAssistantConfig(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: transformers.configuration_utils.PreTrainedConfig | dict[str, typing.Any] | None = None, backbone_hidden_size: int = 3840, use_ordered_embeddings: bool = False, num_centroids: int = 2048, centroid_intermediate_top_k: int = 32, tie_word_embeddings: bool = True)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/gemma4_unified_assistant/configuration_gemma4_unified_assistant.py#L25)

**Parâmetros:**

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

backbone_hidden_size (`int`, padrão 3840) : Tamanho oculto do modelo unificado de destino com o qual este assistente foi treinado.

use_ordered_embeddings (`bool`, padrão `False`) : Se `True`, usa uma tabela de incorporação com ordem otimizada que requer reordenação.

num_centroids (`int`, padrão 2048) : Número total de centróides para o incorporador mascarado baseado em centróides.

centroid_intermediate_top_k (`int`, padrão 32) : Número de centróides ativos selecionados durante a inferência.

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 Gemma4 Unified AssistantModel. Ela é usada para instanciar um modelo Gemma4 Unified Assistant 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 [google/gemma-4-12b-it](https://huggingface.co/google/gemma-4-12b-it)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/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/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

Exemplo:

```python
>>> from transformers import (
...     Gemma4UnifiedAssistantConfig,
...     Gemma4UnifiedAssistantForCausalLM,
...     Gemma4UnifiedTextConfig,
... )

>>> # Initializing a Gemma 4 Unified Text config for the assistant.
>>> text_config = Gemma4UnifiedTextConfig(...)

>>> # Initializing a Gemma 4 Unified Assistant config.
>>> configuration = Gemma4UnifiedAssistantConfig(text_config=text_config)

>>> # Initializing a model from the configuration.
>>> model = Gemma4UnifiedAssistantForCausalLM(configuration)

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

## Gemma4UnifiedAssistantForCausalLM[[transformers.Gemma4UnifiedAssistantForCausalLM]]

#### transformers.Gemma4UnifiedAssistantForCausalLM[[transformers.Gemma4UnifiedAssistantForCausalLM]]

```python
transformers.Gemma4UnifiedAssistantForCausalLM(config: Gemma4UnifiedAssistantConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/gemma4_unified_assistant/modeling_gemma4_unified_assistant.py#L115)

**Parâmetros:**

config ([Gemma4UnifiedAssistantConfig](/docs/transformers/main/pt/model_doc/gemma4_unified_assistant#transformers.Gemma4UnifiedAssistantConfig)) : 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()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

Um modelo para decodificação assistida baseada em previsão de múltiplos tokens com Gemma 4.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/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.

#### create_attention_masks[[transformers.Gemma4UnifiedAssistantForCausalLM.create_attention_masks]]

```python
create_attention_masks(inputs_embeds, attention_mask, shared_kv_states)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/gemma4_unified_assistant/modeling_gemma4_unified_assistant.py#L211)

Prepare as máscaras de atenção para o modelo assistido; o `shared_kv_states` atua como cache passado nesta instância.

Usamos máscaras bidirecionais para levar em conta a causalidade
- Não há diferença para o caso extremo de `q_len == 1`, pois ele atua como atenção completa, independentemente do contexto.
- A SWA interpreta a janela como prospectiva (futuro) quando `q_idx=1` e `kv>=1`
  - Alternamos de uma perspectiva futura para uma perspectiva passada ao inverter o eixo kv
  - Para levar em conta o padding invariante em relação à posição, também invertemos a máscara de atenção base antes da criação inicial

#### forward[[transformers.Gemma4UnifiedAssistantForCausalLM.forward]]

```python
forward(input_ids: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, attention_mask: dict[str, torch.Tensor] | None = None, shared_kv_states: dict[str, tuple[torch.Tensor, torch.Tensor]] | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/gemma4_unified_assistant/modeling_gemma4_unified_assistant.py#L140)

**Parâmetros:**

input_ids (`torch.Tensor` 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/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids)

inputs_embeds (`torch.Tensor` 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.

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)

attention_mask (`dict[str, 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)

shared_kv_states (`dict[str, torch.Tensor` de forma `(batch_size, 1, q_len, kv_len)`, *opcional*) : Um dicionário contendo os valores KV calculados para a última camada de cada `layer_type` neste modelo.

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`).

**Retorna:**

`tuple[torch.Tensor, torch.Tensor]`

O método forward de [Gemma4UnifiedAssistantForCausalLM](/docs/transformers/main/pt/model_doc/gemma4_unified_assistant#transformers.Gemma4UnifiedAssistantForCausalLM) 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.

Exemplo:

```python
>>> from transformers import AutoTokenizer, Gemma4UnifiedAssistantForCausalLM, Gemma4UnifiedForConditionalGeneration

>>> model = Gemma4UnifiedForConditionalGeneration.from_pretrained("google/gemma-4-e2b-it")
>>> assistant_model = Gemma4UnifiedAssistantForCausalLM.from_pretrained("google/gemma-4-e2b-it-assistant")
>>> tokenizer = AutoTokenizer.from_pretrained("google/gemma-4-e2b-it")

>>> prompt = "What is your favorite condiment?"
>>> inputs = tokenizer(prompt, return_tensors="pt")

>>> # Generate
>>> generate_ids = model.generate(inputs.input_ids, assistant_model=assistant_model, max_length=30)
>>> tokenizer.batch_decode(generate_ids, skip_special_tokens=True)[0]
"What is your favorite condiment?"
```