# Assistant unifié Gemma 4

## Aperçu

Gemma 4 Unified Assistant est un petit modèle text-only qui permet le décodage spéculatif pour les modèles Gemma 4 Unified à l'aide de la méthode Multi-Token Prediction (MTP) et du générateur de candidats associé. Des modèles pré-entraînés sont fournis pour les variantes IT du modèle Gemma 4 12B.

Pour plus d'informations, veuillez consulter [Gemma4 Assistant](./gemma4_assistant). Sur le plan architectural et conceptuel, ils partagent le même concept et les mêmes différences par rapport à leur modèle de base :

*   **Le modèle entier utilise le partage de KV**. Cette technique, initialement introduite avec [Gemma 3n](./gemma3n), permet au modèle de réutiliser le cache KV rempli par le modèle cible pris en charge par l'assistant, ce qui permet à l'assistant de sauter entièrement la phase de pré-remplissage et de réduire considérablement le calcul d'attention lors du passage avant.
*   **La valeur de `position_ids` est constante**. Comme le cache KV est partagé et que l'assistant ne dispose d'aucun moyen de mettre à jour le cache, il prédit tous les jetons à partir du même identifiant de position.
*   **Les entrées sont la concaténation des embeddings et des états cachés**. Pour s'adapter à la cache KV statique et à `position_ids`, le modèle reçoit ses entrées sous forme de la concaténation de l'`embedding` et des `hidden_states` du dernier jeton vu par le modèle cible, puis les projette dans l'espace du modèle assistant à l'aide d'une transformation `nn.Linear`. La définition du dernier jeton vu évolue au fil de la boucle de décodage assisté. Pour le premier jeton rédigé après la pré-remplissage, le dernier jeton vu sera le dernier jeton du prompt. Pour les étapes de rédaction suivantes, le dernier jeton vu sera le dernier jeton généré par l'assistant (au sein d'un cycle de rédaction) ou le dernier jeton accepté par le modèle cible (entre les cycles de rédaction).
*   **L'attention croisée est utilisée pour tirer le meilleur parti du contexte du modèle cible**. L'attention croisée permet aux états de requête générés par l'assistant de prendre en compte les valeurs du cache KV partagé du modèle cible, ce qui permet à l'assistant de prédire avec précision davantage de jetons rédigés par tour de rédaction.

## Exemples d'utilisation

L'exemple ci-dessous montre comment générer du texte à partir d'une image avec [Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.Pipeline) ou la classe [AutoModel](/docs/transformers/main/fr/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)
```

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

**Paramètres :**

text_config (`Union[~configuration_utils.PreTrainedConfig, dict[str, Any]]`, *facultatif*) : L'objet de configuration ou le dictionnaire du backbone de texte.

backbone_hidden_size (`int`, par défaut 3840) : Taille cachée du modèle unifié cible avec lequel cet assistant a été entraîné.

use_ordered_embeddings (`bool`, par défaut `False`) : Si `True`, utilise une table d'embeddings ordonnée de manière optimale qui nécessite un réordonnancement.

num_centroids (`int`, par défaut 2048) : Nombre total de centroïdes pour l'encodeur masqué basé sur les centroïdes.

centroid_intermediate_top_k (`int`, par défaut 32) : Nombre de centroïdes actifs sélectionnés lors de l'inférence.

tie_word_embeddings (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut lier les embeddings de poids selon la correspondance `tied_weights_keys` du modèle.

Il s'agit de la classe de configuration destinée à stocker la configuration d'un modèle Gemma4 Unified Assistant. Elle est utilisée pour instancier un modèle Gemma4 Unified Assistant en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de [google/gemma-4-12b-it](https://huggingface.co/google/gemma-4-12b-it)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/main/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/main/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

Exemple :

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

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

**Paramètres :**

config ([Gemma4UnifiedAssistantConfig](/docs/transformers/main/fr/model_doc/gemma4_unified_assistant#transformers.Gemma4UnifiedAssistantConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/main/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Un modèle pour le décodage assisté basé sur la prédiction multi-jetons avec Gemma 4.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/main/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

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

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

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

Préparez les masques d'attention pour le modèle assisté ; dans ce cas, `shared_kv_states` agit comme cache passé.

Nous utilisons des masques bidirectionnels pour prendre en compte la causalité
- Il n'y a aucune différence pour le cas limite `q_len == 1`, car il se comporte comme une attention complète dans tous les cas.
- SWA interprète la fenêtre comme prospective (future) lorsque `q_idx=1` et `kv>=1`
  - Nous passons d'une perspective future à une perspective passée en inversant sur l'axe kv
  - Pour prendre en compte le padding invariant par rapport à la position, nous inversons également le masque d'attention de base avant sa création initiale

#### 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'>)
```

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

**Paramètres :**

input_ids (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/main/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Que sont les identifiants d'entrée ?](../glossary#input-ids)

inputs_embeds (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Cela est utile si vous souhaitez un meilleur contrôle sur la manière de convertir les indices `input_ids` en vecteurs associés, par rapport à la matrice de recherche d'intégration interne du modèle.

position_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des positions des jetons de chaque séquence d'entrée dans les embeddings de position. Sélectionnés dans l'intervalle `[0, config.n_positions - 1]`.  [Que sont les identifiants de position ?](../glossary#position-ids)

attention_mask (`dict[str, torch.Tensor]` de forme `(batch_size, sequence_length)`, *facultatif*) : Masque pour éviter d’appliquer l’attention aux indices des jetons de bourrage. Les valeurs du masque sont comprises dans `[0, 1]` : - 1 pour les jetons **non masqués**, - 0 pour les jetons **masqués**. [Qu’est-ce qu’un masque d’attention ?](../glossary#attention-mask)

shared_kv_states (`dict[str, torch.Tensor` de forme `(batch_size, 1, q_len, kv_len)`, *facultatif*) : Un dictionnaire contenant les valeurs KV calculées pour la dernière couche de chaque `layer_type` de ce modèle.

use_cache (`bool`, *facultatif*) : Si défini sur `True`, les états clé-valeur de `past_key_values` sont renvoyés et peuvent être utilisés pour accélérer le décodage (voir `past_key_values`).

**Retourne :**

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

La méthode forward de [Gemma4UnifiedAssistantForCausalLM](/docs/transformers/main/fr/model_doc/gemma4_unified_assistant#transformers.Gemma4UnifiedAssistantForCausalLM) redéfinit la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

Exemple :

```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?"
```