# Gemma 4 Assistant

## Ikhtisar

Gemma 4 Assistant adalah model kecil yang hanya mendukung teks, yang memungkinkan *speculative decoding* untuk model Gemma 4 menggunakan metode Multi-Token Prediction (MTP) dan generator kandidat terkait. Model pra-terlatih disediakan untuk varian IT dari model Gemma 4 E2B, E4B, 31B, dan 26B-A4B (MoE).

Secara arsitektur, Gemma 4 Assistant berbagi backbone [Gemma4TextModel](/docs/transformers/v5.23.0/id/model_doc/gemma4#transformers.Gemma4TextModel) yang sama dengan model Gemma 4 lainnya, tetapi berbeda dalam beberapa hal utama:

*   **Model secara keseluruhan menggunakan berbagi KV**. Teknik ini, yang awalnya diperkenalkan bersama [Gemma 3n](./gemma3n), memungkinkan model untuk menggunakan kembali KV cache yang diisi oleh model target yang didukung asisten, sehingga asisten dapat sepenuhnya melewati fase pre-fille dan secara signifikan mengurangi komputasi perhatian selama forward pass.
*   **Nilai `position_ids` bersifat konstan**. Karena KV cache dibagikan dan asisten tidak memiliki cara untuk memperbarui cache, asisten memprediksi semua token dari ID posisi yang sama.
*   **Input adalah konkatenasi dari embedding dan hidden states**. Untuk beradaptasi dengan KV cache statis dan `position_ids`, model menerima inputnya sebagai konkatenasi dari `embedding` dan `hidden_states` untuk token terakhir yang dilihat dari model target, lalu memproyeksikannya ke ruang model asisten dengan transformasi `nn.Linear`. Definisi token terakhir yang dilihat berubah sepanjang loop assisted decoding. Untuk token pertama yang dibuat setelah pre-fill, token terakhir yang dilihat akan menjadi token terakhir dari prompt. Untuk langkah pembuatan (drafting) berikutnya, token terakhir yang dilihat akan menjadi token terakhir yang dihasilkan oleh asisten (dalam satu putaran drafting) atau token terakhir yang diterima oleh model target (antara putaran drafting).
*   **Cross-attention digunakan untuk memaksimalkan konteks model target**. Cross-attention memungkinkan query states yang dihasilkan oleh asisten untuk memperhatikan nilai KV cache bersama dari model target, sehingga asisten dapat memprediksi lebih banyak token yang di-draft secara akurat per putaran drafting.

Anda dapat menemukan semua checkpoint asli Gemma 4 Assistant di bawah rilis [Gemma 4](https://huggingface.co/collections/google/gemma-4).

## Contoh penggunaan

Contoh di bawah ini menunjukkan cara menghasilkan teks berdasarkan gambar dengan [Pipeline](/docs/transformers/v5.23.0/id/main_classes/pipelines#transformers.Pipeline) atau kelas [AutoModel](/docs/transformers/v5.23.0/id/model_doc/auto#transformers.AutoModel).

```py
import torch
from transformers import pipeline

pipeline = pipeline(
    task="image-text-to-text",
    model="google/gemma-4-E2B-it",
    assistant_model="google/gemma-4-E2B-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-E2B-it",
    dtype=torch.bfloat16,
    device_map="auto",
)
assistant_model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-4-E2B-it-assistant",
    dtype=torch.bfloat16,
    device_map="auto",
)

processor = AutoProcessor.from_pretrained(
    "google/gemma-4-E2B-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))
```

## Gemma4AssistantConfig[[transformers.Gemma4AssistantConfig]]

#### transformers.Gemma4AssistantConfig[[transformers.Gemma4AssistantConfig]]

```python
transformers.Gemma4AssistantConfig(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 = 1536, use_ordered_embeddings: bool = False, num_centroids: int = 2048, centroid_intermediate_top_k: int = 32, tie_word_embeddings: bool = True)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_assistant/configuration_gemma4_assistant.py#L29)

**Parameter:**

text_config (`Union[~configuration_utils.PreTrainedConfig, dict[str, Any]]`, *opsional*) : Objek config atau dictionary dari text backbone.

backbone_hidden_size (`int`, defaultnya 1536) : Ukuran tersembunyi dari model target yang digunakan untuk melatih asisten ini.

use_ordered_embeddings (`bool`, defaultnya False) : Jika True, menggunakan tabel embedding yang diurutkan untuk kinerja optimal model asisten yang perlu diurutkan ulang agar selaras dengan model utama.

num_centroids (`int`, defaultnya 2048) : Jumlah total centroid.

centroid_intermediate_top_k (`int`, defaultnya 32) : Jumlah centroid aktif.

tie_word_embeddings (`bool`, *opsional*, defaultnya `True`) : Apakah mengikat embedding bobot sesuai dengan pemetaan `tied_weights_keys` model.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari Gemma4 AssistantModel. Kelas ini digunakan untuk menginstansiasi model Gemma4 Assistant sesuai dengan argumen yang ditentukan, yang mendefinisikan arsitektur model. Menginstansiasi konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari [google/gemma-4-e2b-it](https://huggingface.co/google/gemma-4-e2b-it)

Objek konfigurasi mewarisi dari [PreTrainedConfig](/docs/transformers/v5.23.0/id/main_classes/configuration#transformers.PreTrainedConfig) dan dapat digunakan untuk mengontrol keluaran model. Baca dokumentasi dari [PreTrainedConfig](/docs/transformers/v5.23.0/id/main_classes/configuration#transformers.PreTrainedConfig) untuk informasi lebih lanjut.

Contoh:

```python
>>> from transformers import (
>>>     Gemma4AssistantConfig,
>>>     Gemma4AssistantForCausalLM,
>>>     Gemma4TextConfig,
>>> )

>>> # Initializing a Gemma 4 Text config similar to google/gemma-4-e2b-it-assistant.
>>> text_config = Gemma4TextConfig(...)

>>> # Initializing a Gemma 4 Assistant config similar to google/gemma-4-e2b-it-assistant.
>>> configuration = Gemma4AssistantConfig(text_config)

>>> # Initializing a model from the google/gemma-4-e2b-it-assistant configuration.
>>> model = Gemma4AssistantForCausalLM(configuration)

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

## Gemma4AssistantForCausalLM[[transformers.Gemma4AssistantForCausalLM]]

#### transformers.Gemma4AssistantForCausalLM[[transformers.Gemma4AssistantForCausalLM]]

```python
transformers.Gemma4AssistantForCausalLM(config: Gemma4AssistantConfig)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_assistant/modeling_gemma4_assistant.py#L109)

**Parameter:**

config ([Gemma4AssistantConfig](/docs/transformers/v5.23.0/id/model_doc/gemma4_assistant#transformers.Gemma4AssistantConfig)) : Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode [from_pretrained()](/docs/transformers/v5.23.0/id/main_classes/model#transformers.PreTrainedModel.from_pretrained) untuk memuat bobot model.

Model untuk decoding terbantu berbasis prediksi multi-token dengan Gemma 4.

Model ini mewarisi dari [PreTrainedModel](/docs/transformers/v5.23.0/id/main_classes/model#transformers.PreTrainedModel). Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka ini untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran input embeddings, memangkas heads, dll.)

Model ini juga merupakan subclass dari [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.

#### create_attention_masks[[transformers.Gemma4AssistantForCausalLM.create_attention_masks]]

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

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_assistant/modeling_gemma4_assistant.py#L204)

Siapkan attention mask untuk model yang dibantu; `shared_kv_states` berfungsi sebagai cache masa lalu dalam kasus ini.

Kami menggunakan masker bidireksional untuk memperhitungkan kausalitas
- Tidak ada perbedaan untuk kasus tepi `q_len == 1` karena ia bertindak sebagai full attention apa pun kondisinya
- SWA menafsirkan jendela sebagai ke depan (masa depan) ketika `q_idx=1` dan `kv>=1`
  - Kami beralih dari perspektif masa depan ke perspektif masa lalu dengan membalik pada sumbu kv
  - Untuk mengakomodasi padding yang tidak bergantung pada posisi, kami juga membalik mask perhatian dasar sebelum pembuatan awal

#### forward[[transformers.Gemma4AssistantForCausalLM.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'>)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_assistant/modeling_gemma4_assistant.py#L133)

**Parameter:**

input_ids (`torch.Tensor` dengan bentuk `(batch_size, sequence_length)`, *opsional*) : Indeks token dari urutan input dalam kosakata. Padding akan diabaikan secara default. Indeks dapat diperoleh menggunakan [AutoTokenizer](/docs/transformers/v5.23.0/id/model_doc/auto#transformers.AutoTokenizer). Lihat [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/id/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) dan [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/id/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) untuk detailnya. [Apa itu input IDs?](../glossary#input-ids)

inputs_embeds (`torch.Tensor` dengan bentuk `(batch_size, sequence_length, hidden_size)`, *opsional*) : Secara opsional, alih-alih meneruskan `input_ids`, Anda dapat memilih untuk langsung meneruskan representasi tertanam. Ini berguna jika Anda ingin lebih banyak kendali atas cara mengonversi indeks `input_ids` menjadi vektor terkait daripada matriks pencarian penanaman internal model.

position_ids (`torch.LongTensor` dengan bentuk `(batch_size, sequence_length)`, *opsional*) : Indeks posisi token dari setiap urutan input dalam embedding posisi. Dipilih dalam rentang `[0, config.n_positions - 1]`.  [Apa itu position ID?](../glossary#position-ids)

attention_mask (`dict[str, torch.Tensor]` dengan bentuk `(batch_size, sequence_length)`, *opsional*) : Mask untuk menghindari pelaksanaan attention pada indeks token padding. Nilai mask dipilih dalam `[0, 1]`:  - 1 untuk token yang **tidak di-mask**, - 0 untuk token yang **di-mask**.  [Apa itu attention mask?](../glossary#attention-mask)

shared_kv_states (`dict[str, torch.Tensor` dengan bentuk `(batch_size, 1, q_len, kv_len)`, *opsional*) : Kamus yang berisi nilai KV yang dihitung untuk lapisan terakhir dari setiap `layer_type` dalam model ini.

use_cache (`bool`, *opsional*) : Jika diatur ke `True`, state kunci-nilai `past_key_values` akan dikembalikan dan dapat digunakan untuk mempercepat decoding (lihat `past_key_values`).

**Mengembalikan:**

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

Metode forward dari [Gemma4AssistantForCausalLM](/docs/transformers/v5.23.0/id/model_doc/gemma4_assistant#transformers.Gemma4AssistantForCausalLM) menimpa metode khusus `__call__`.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance `Module` setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

Contoh:

```python
>>> from transformers import AutoTokenizer, Gemma4AssistantForCausalLM, Gemma4ForCausalLM

>>> model = Gemma4ForCausalLM.from_pretrained("google/gemma-4-e2b-it")
>>> assistant_model = Gemma4AssistantForCausalLM.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?"
```

