# Gemma 4 통합 어시스턴트

## 개요

Gemma 4 Unified Assistant는 Multi-Token Prediction(MTP) 방식과 관련 후보 생성기를 사용하여 Gemma 4 Unified 모델에 대한 추측적 디코딩을 활성화하는 소형 텍스트 전용 모델입니다. Gemma 4 12B 모델의 IT 변형에 대해 사전 학습된 모델이 제공됩니다.

자세한 내용은 [Gemma4 Assistant](./gemma4_assistant)를 참고하세요. 아키텍처 및 개념적으로, 기본 모델과의 동일한 개념과 차이점을 공유합니다:

*   **모델 전체가 KV 공유를 사용합니다**. [Gemma 3n](./gemma3n)에서 처음 도입된 이 기법은 어시스턴트가 지원하는 대상 모델이 채운 KV 캐시를 재사용할 수 있게 하여, 어시스턴트가 pre-fille 단계를 완전히 건너뛰고 forward pass 중 attention 연산을 크게 줄일 수 있습니다.
*   **`position_ids` 값은 일정합니다.** KV 캐시가 공유되고 어시스턴트가 캐시를 업데이트할 방법이 없으므로, 어시스턴트는 동일한 위치 ID에서 모든 토큰을 예측합니다.
*   **입력은 임베딩과 히든 상태의 연결(concatenation)입니다**. 정적 KV 캐시와 `position_ids`에 적응하기 위해, 모델은 타깃 모델에서 마지막으로 확인된 토큰의 `embedding`과 `hidden_states`를 연결하여 입력으로 받아들이고, `nn.Linear` 변환을 통해 어시스턴트 모델 공간으로 투영합니다. assisted decoding 루프 내에서 마지막 확인된 토큰의 정의는 계속 변합니다. pre-fill 이후에 초안으로 작성되는 첫 번째 토큰의 경우, 마지막 확인된 토큰은 프롬프트의 마지막 토큰입니다. 이후의 초안 작성 단계에서는, 마지막 확인된 토큰은 어시스턴트가 생성한 마지막 토큰(초안 작성 라운드 내)이거나 타깃 모델이 수락한 마지막 토큰(초안 작성 라운드 사이)입니다.
*   **Cross-attention은 대상 모델의 컨텍스트를 최대한 활용하기 위해 사용됩니다.** Cross-attention을 통해 어시스턴트가 생성한 query 상태가 대상 모델의 공유 KV cache 값에 attend할 수 있어, 어시스턴트가 드래프팅 라운드마다 더 많은 drafted tokens을 정확하게 예측할 수 있습니다.

## 사용 예시

아래 예제는 [Pipeline](/docs/transformers/main/ko/main_classes/pipelines#transformers.Pipeline) 또는 [AutoModel](/docs/transformers/main/ko/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)
```

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

**매개변수:**

text_config (`Union[~configuration_utils.PreTrainedConfig, dict[str, Any]]`, *선택*) : 텍스트 백본의 config 객체 또는 사전입니다.

backbone_hidden_size (`int`, 기본값 3840) : 이 어시스턴트가 학습된 대상 통합 모델의 숨겨진 크기(hidden size)입니다.

use_ordered_embeddings (`bool`, 기본값은 `False`) : `True`인 경우, 재정렬이 필요한 최적 순서 임베딩 테이블을 사용합니다.

num_centroids (`int`, 기본값 2048) : centroid 기반 masked embedder의 총 centroid 수입니다.

centroid_intermediate_top_k (`int`, 기본값 32) : 추론 중에 선택되는 활성 센트로이드의 수입니다.

tie_word_embeddings (`bool`, *선택 사항*, 기본값 `True`) : 모델의 `tied_weights_keys` 매핑에 따라 가중치 임베딩을 묶을지 여부.

이것은 Gemma4 Unified AssistantModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Gemma4 Unified Assistant 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [google/gemma-4-12b-it](https://huggingface.co/google/gemma-4-12b-it)의 구성과 유사한 구성이 생성됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

예:

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

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

**매개변수:**

config ([Gemma4UnifiedAssistantConfig](/docs/transformers/main/ko/model_doc/gemma4_unified_assistant#transformers.Gemma4UnifiedAssistantConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

Gemma 4를 위한 멀티 토큰 예측 기반 보조 디코딩 모델입니다.

이 모델은 [PreTrainedModel](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

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

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

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

보조 모델의 attention masks를 준비합니다. 이 경우 `shared_kv_states`가 past cache 역할을 합니다.

인과성을 고려하기 위해 양방향 마스크를 사용합니다
- `q_len == 1`인 경계 사례의 경우, 어떤 경우든 전체 어텐션으로 동작하므로 차이가 없습니다.
- `q_idx=1`이고 `kv>=1`인 경우, SWA는 해당 윈도우를 미래 방향(앞으로 보는)으로 해석합니다.
  - kv 축을 뒤집어 미래 관점에서 과거 관점으로 전환합니다
  - 위치 불변 패딩을 처리하기 위해, 초기 생성 전에 기본 attention mask를 반전시킵니다

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

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

**매개변수:**

input_ids (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/main/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

position_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 각 입력 시퀀스의 토큰 위치 인덱스입니다. `[0, config.n_positions - 1]` 범위에서 선택됩니다. [위치 ID란 무엇인가요?](../glossary#position-ids)

attention_mask (`dict[str, torch.Tensor]`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 어텐션을 수행하지 않도록 하는 마스크. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [어텐션 마스크란?](../glossary#attention-mask)

shared_kv_states (`dict[str, torch.Tensor`, shape `(batch_size, 1, q_len, kv_len)`, *선택 사항*) : 이 모델의 각 `layer_type`의 마지막 레이어에 대해 계산된 KV 값을 포함하는 사전.

use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `past_key_values` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`past_key_values` 참조).

**반환값:**

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

[Gemma4UnifiedAssistantForCausalLM](/docs/transformers/main/ko/model_doc/gemma4_unified_assistant#transformers.Gemma4UnifiedAssistantForCausalLM)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

예:

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