# Gemma 4 Trợ lý Thống nhất

## Tổng quan

Gemma 4 Unified 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 Unified 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 mô hình Gemma 4 12B.

Để biết thêm thông tin, vui lòng xem [Gemma4 Assistant](./gemma4_assistant). Về mặt kiến trúc và khái niệm, chúng chia sẻ cùng một khái niệm và những điểm khác biệt so với mô hình cơ sở của chúng:

*   **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.

## 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/v5.23.0/vi/main_classes/pipelines#transformers.Pipeline) hoặc lớp [AutoModel](/docs/transformers/v5.23.0/vi/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)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified_assistant/configuration_gemma4_unified_assistant.py#L25)

**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à 3840) : Kích thước ẩn của mô hình thống nhất đích mà trợ lý này được huấn luyện với.

use_ordered_embeddings (`bool`, mặc định là `False`) : Nếu `True`, sử dụng bảng nhúng được sắp xếp tối ưu, cần sắp xếp lại.

num_centroids (`int`, mặc định là 2048) : Tổng số centroid cho bộ nhúng có mặt nạ dựa trên centroid.

centroid_intermediate_top_k (`int`, mặc định là 32) : Số lượng centroid hoạt động được chọn trong quá trình suy luận.

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 mô hình Gemma4 Unified Assistant. Nó được sử dụng để khởi tạo một mô hình Gemma4 Unified Assistant theo các đối số được chỉ định, xác định kiến trúc của 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ấu hình của [google/gemma-4-12b-it](https://huggingface.co/google/gemma-4-12b-it)

Các đối tượng cấu hình kế thừa từ [PreTrainedConfig](/docs/transformers/v5.23.0/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/v5.23.0/vi/main_classes/configuration#transformers.PreTrainedConfig) để biết thêm thông tin.

Ví dụ:

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

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified_assistant/modeling_gemma4_unified_assistant.py#L115)

**Tham số:**

config ([Gemma4UnifiedAssistantConfig](/docs/transformers/v5.23.0/vi/model_doc/gemma4_unified_assistant#transformers.Gemma4UnifiedAssistantConfig)) : 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/v5.23.0/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/v5.23.0/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.Gemma4UnifiedAssistantForCausalLM.create_attention_masks]]

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

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified_assistant/modeling_gemma4_unified_assistant.py#L211)

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

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified_assistant/modeling_gemma4_unified_assistant.py#L140)

**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/v5.23.0/vi/model_doc/auto#transformers.AutoTokenizer). Xem [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) và [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/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 [Gemma4UnifiedAssistantForCausalLM](/docs/transformers/v5.23.0/vi/model_doc/gemma4_unified_assistant#transformers.Gemma4UnifiedAssistantForCausalLM) 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, 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?"
```