# Gemma 4 Trợ lý

## Tổng quan

Gemma 4 Assistant là một mô hình nhỏ, chỉ xử lý văn bản, cho phép giải mã suy đoán (speculative decoding) cho các mô hình Gemma 4 bằng phương pháp Dự đoán Nhiều Token (Multi-Token Prediction - MTP) và bộ sinh ứng viên liên quan. Các mô hình được huấn luyện trước được cung cấp cho các biến thể IT của các mô hình Gemma 4 E2B, E4B, 31B và 26B-A4B (MoE).

Về mặt kiến trúc, Gemma 4 Assistant chia sẻ cùng backbone [Gemma4TextModel](/docs/transformers/main/vi/model_doc/gemma4#transformers.Gemma4TextModel) với các mô hình Gemma 4 khác, nhưng khác biệt ở một số điểm chính:

*   **Toàn bộ mô hình sử dụng chia sẻ KV**. Kỹ thuật này, ban đầu được giới thiệu cùng với [Gemma 3n](./gemma3n), cho phép mô hình tái sử dụng bộ nhớ đệm KV đã được nạp bởi mô hình đích mà trợ lý hỗ trợ, nhờ đó trợ lý có thể bỏ qua hoàn toàn giai đoạn pre-fille và giảm đáng kể lượng tính toán attention trong quá trình truyền thẳng.
*   **Giá trị của `position_ids` là hằng số**. Vì bộ nhớ đệm KV được dùng chung và trợ lý không có cách nào để cập nhật bộ nhớ đệm, trợ lý dự đoán tất cả các token từ cùng một ID vị trí.
*   **Inputs là phép nối (concatenation) của embeddings và hidden states**. Để thích ứng với static KV cache và `position_ids`, model nhận inputs dưới dạng phép nối của `embedding` và `hidden_states` của token cuối cùng được nhìn thấy từ target model, sau đó chiếu chúng vào không gian của assistant model bằng phép biến đổi `nn.Linear`. Định nghĩa của token cuối cùng được nhìn thấy thay đổi trong suốt vòng lặp assisted decoding. Đối với token đầu tiên được draft sau pre-fill, token cuối cùng được nhìn thấy sẽ là token cuối cùng từ prompt. Đối với các bước draft tiếp theo, token cuối cùng được nhìn thấy sẽ là token cuối cùng do assistant tạo ra (trong một vòng draft) hoặc token cuối cùng được target model chấp nhận (giữa các vòng draft).
*   **Cross-attention được sử dụng để khai thác tối đa ngữ cảnh của mô hình đích**. Cross-attention cho phép các trạng thái query do trợ lý tạo ra chú ý đến các giá trị KV cache chung từ mô hình đích, giúp trợ lý dự đoán chính xác hơn số lượng token được phác thảo trong mỗi vòng phác thảo.

Bạn có thể tìm thấy tất cả các checkpoint gốc của Gemma 4 Assistant dưới bản phát hành [Gemma 4](https://huggingface.co/collections/google/gemma-4).

## Ví dụ sử dụng

Ví dụ dưới đây minh họa cách tạo văn bản dựa trên hình ảnh bằng [Pipeline](/docs/transformers/main/vi/main_classes/pipelines#transformers.Pipeline) hoặc lớp [AutoModel](/docs/transformers/main/vi/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)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/gemma4_assistant/configuration_gemma4_assistant.py#L29)

**Tham số:**

text_config (`Union[~configuration_utils.PreTrainedConfig, dict[str, Any]]`, *tùy chọn*) : Đối tượng config hoặc từ điển của text backbone.

backbone_hidden_size (`int`, mặc định là 1536) : Kích thước ẩn của mô hình đích mà trợ lý này được huấn luyện với.

use_ordered_embeddings (`bool`, mặc định là False) : Nếu là True, sử dụng bảng nhúng được sắp xếp để đạt hiệu suất tối ưu cho mô hình trợ lý, cần được sắp xếp lại để khớp với mô hình chính.

num_centroids (`int`, mặc định là 2048) : Tổng số tâm cụm.

centroid_intermediate_top_k (`int`, mặc định là 32) : Số lượng tâm cụm (centroids) đang hoạt động.

tie_word_embeddings (`bool`, *tùy chọn*, mặc định là `True`) : Có nên gắn kết các nhúng trọng số theo ánh xạ `tied_weights_keys` của mô hình hay không.

Đây là lớp cấu hình để lưu trữ cấu hình của một Gemma4 AssistantModel. Nó được sử dụng để khởi tạo một mô hình Gemma4 Assistant theo các đối số được chỉ định, xác định kiến trúc mô hình. Khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như của [google/gemma-4-e2b-it](https://huggingface.co/google/gemma-4-e2b-it)

Các đối tượng cấu hình kế thừa từ [PreTrainedConfig](/docs/transformers/main/vi/main_classes/configuration#transformers.PreTrainedConfig) và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ [PreTrainedConfig](/docs/transformers/main/vi/main_classes/configuration#transformers.PreTrainedConfig) để biết thêm thông tin.

Ví dụ:

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/gemma4_assistant/modeling_gemma4_assistant.py#L109)

**Tham số:**

config ([Gemma4AssistantConfig](/docs/transformers/main/vi/model_doc/gemma4_assistant#transformers.Gemma4AssistantConfig)) : Lớp cấu hình mô hình chứa tất cả các tham số của mô hình. Khởi tạo bằng tệp cấu hình sẽ không tải trọng số liên quan đến mô hình, chỉ tải cấu hình. Xem phương thức [from_pretrained()](/docs/transformers/main/vi/main_classes/model#transformers.PreTrainedModel.from_pretrained) để tải trọng số mô hình.

Một mô hình cho giải mã hỗ trợ dựa trên dự đoán đa token với Gemma 4.

Mô hình này kế thừa từ [PreTrainedModel](/docs/transformers/main/vi/main_classes/model#transformers.PreTrainedModel). Xem tài liệu của lớp cha để biết các phương thức chung mà thư viện triển khai cho tất cả các mô hình của nó (chẳng hạn như tải xuống hoặc lưu trữ, thay đổi kích thước các nhúng đầu vào, cắt tỉa các đầu ra, v.v.)

Mô hình này cũng là một lớp con của [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) trong PyTorch. Hãy sử dụng nó như một Module PyTorch thông thường và tham khảo tài liệu PyTorch cho mọi vấn đề liên quan đến cách sử dụng và hành vi chung.

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

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/gemma4_assistant/modeling_gemma4_assistant.py#L204)

Chuẩn bị các attention mask cho mô hình được hỗ trợ; `shared_kv_states` đóng vai trò là bộ nhớ đệm quá khứ trong trường hợp này.

Chúng tôi sử dụng các mặt nạ hai chiều để tính đến tính nhân quả
- Không có sự khác biệt cho trường hợp biên `q_len == 1` vì nó hoạt động như chú ý đầy đủ trong mọi trường hợp
- SWA hiểu cửa sổ là nhìn về phía trước (tương lai) khi `q_idx=1` và `kv>=1`
  - Chúng ta chuyển từ góc nhìn tương lai sang góc nhìn quá khứ bằng cách lật theo trục kv
  - Để xử lý padding không phụ thuộc vào vị trí, chúng ta cũng đảo ngược mặt nạ chú ý cơ bản trước khi tạo ban đầu

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/gemma4_assistant/modeling_gemma4_assistant.py#L133)

**Tham số:**

input_ids (`torch.Tensor` có hình dạng `(batch_size, sequence_length)`, *tùy chọn*) : Chỉ số của các token trong chuỗi đầu vào theo từ vựng. Mặc định, các token đệm (padding) sẽ bị bỏ qua. Có thể lấy chỉ số bằng cách sử dụng [AutoTokenizer](/docs/transformers/main/vi/model_doc/auto#transformers.AutoTokenizer). Xem [PreTrainedTokenizer.encode()](/docs/transformers/main/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) và [PreTrainedTokenizer.__call__()](/docs/transformers/main/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) để biết thêm chi tiết. [ID đầu vào là gì?](../glossary#input-ids)

inputs_embeds (`torch.Tensor` có hình dạng `(batch_size, sequence_length, hidden_size)`, *tùy chọn*) : Tùy chọn, thay vì truyền `input_ids`, bạn có thể chọn cách truyền trực tiếp một biểu diễn nhúng. Điều này hữu ích nếu bạn muốn kiểm soát nhiều hơn cách chuyển đổi các chỉ số `input_ids` thành các vector liên quan so với ma trận tra cứu nhúng nội bộ của mô hình.

position_ids (`torch.LongTensor` có hình dạng `(batch_size, sequence_length)`, *tùy chọn*) : Chỉ số của vị trí các token trong mỗi chuỗi đầu vào trong các embedding vị trí. Được chọn trong khoảng `[0, config.n_positions - 1]`.  [Position IDs là gì?](../glossary#position-ids)

attention_mask (`dict[str, torch.Tensor]` có shape `(batch_size, sequence_length)`, *tùy chọn*) : Mặt nạ để tránh thực hiện chú ý trên các chỉ số token đệm. Các giá trị mặt nạ được chọn trong `[0, 1]`:  - 1 cho các token **không bị che**, - 0 cho các token **bị che**.  [Mặt nạ chú ý là gì?](../glossary#attention-mask)

shared_kv_states (`dict[str, torch.Tensor` có hình dạng `(batch_size, 1, q_len, kv_len)`, *tùy chọn*) : Một từ điển chứa các giá trị KV đã tính cho lớp cuối cùng của mỗi `layer_type` trong mô hình này.

use_cache (`bool`, *tùy chọn*) : Nếu được đặt thành `True`, các trạng thái khóa và giá trị `past_key_values` sẽ được trả về và có thể được sử dụng để tăng tốc quá trình giải mã (xem `past_key_values`).

**Trả về:**

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

Phương thức forward của [Gemma4AssistantForCausalLM](/docs/transformers/main/vi/model_doc/gemma4_assistant#transformers.Gemma4AssistantForCausalLM) ghi đè lên phương thức đặc biệt `__call__`.

Mặc dù công thức cho bước truyền tiến cần được định nghĩa bên trong hàm này, bạn nên gọi instance của `Module` sau đó thay vì gọi hàm này, vì instance `Module` sẽ đảm nhận việc thực hiện các bước tiền xử lý và hậu xử lý, trong khi hàm này sẽ bỏ qua chúng một cách im lặng.

Ví dụ:

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