Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

이 모델은 2026-06-03에 Hugging Face Transformers에 기여되었습니다.

Gemma 4 통합 어시스턴트

개요

Gemma 4 Unified Assistant는 Multi-Token Prediction(MTP) 방법과 관련 후보 생성기를 사용하여 Gemma 4 Unified 모델의 speculative decoding을 지원하는 소형 텍스트 전용 모델입니다. Gemma 4 12B 모델의 IT 변형에 대한 사전 학습된 모델이 제공됩니다.

자세한 내용은 Gemma4 Assistant를 참고하세요. 아키텍처와 개념적으로, 기본 모델과의 공통점과 차이점이 동일합니다:

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

사용 예시

아래 예제는 Pipeline 또는 AutoModel 클래스를 사용하여 이미지 기반으로 텍스트를 생성하는 방법을 보여줍니다.

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

</hfoption> <hfoption id="AutoModel">

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

</hfoption>

Gemma4UnifiedAssistantConfig

class transformers.Gemma4UnifiedAssistantConfig

< source >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonetext_config: transformers.configuration_utils.PreTrainedConfig | dict[str, typing.Any] | None = Nonebackbone_hidden_size: int = 3840use_ordered_embeddings: bool = Falsenum_centroids: int = 2048centroid_intermediate_top_k: int = 32tie_word_embeddings: bool = True )

매개변수

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) — 추론 중에 선택되는 활성 centroid의 수입니다.
tie_word_embeddings (bool, 선택, 기본값 True) — 모델의 tied_weights_keys 매핑에 따라 가중치 임베딩을 묶을지 여부.

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

Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.

예:

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

< source >

( config: Gemma4UnifiedAssistantConfig )

매개변수

config (Gemma4UnifiedAssistantConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 연관된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.

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

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

이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.

create_attention_masks

< source >

( inputs_embedsattention_maskshared_kv_states )

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

인과성을 고려하기 위해 양방향 마스크를 사용합니다

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

forward

< source >

( input_ids: typing.Optional[torch.Tensor] = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: dict[str, torch.Tensor] | None = Noneshared_kv_states: dict[str, tuple[torch.Tensor, torch.Tensor]] | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> )

매개변수

input_ids (torch.Tensor 의 shape (batch_size, sequence_length), , 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.
AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.

입력 ID란 무엇인가요?
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란 무엇인가요?
attention_mask (dict[str, torch.Tensor] 형상 (batch_size, sequence_length), 선택 사항) — 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 하는 마스크. 선택된 마스크 값은 [0, 1]:
- 마스크되지 않은 토큰에 대해 1
- 마스크된 토큰에 대해 0
어텐션 마스크란 무엇인가요?
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 참조).

Gemma4UnifiedAssistantForCausalLM의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.

이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신 Module 인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.

예:

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

Update on GitHub

←Gemma 4 어시스턴트 Gemma3→