Transformers documentation

Gemma4

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

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-04-02에 Hugging Face Transformers에 기여되었습니다.

Gemma4

개요

Gemma 4는 사전 학습 및 지시 튜닝 변형이 제공되는 멀티모달 모델로, E2B, E4B, 31B, 26B-A4B(MoE) 파라미터 크기로 사용할 수 있습니다. Gemma 4 모델은 다음과 같은 기능을 제공합니다:

Reasoning: 해당 계열의 모든 모델은 설정 가능한 사고(thinking) 모드를 갖춘 고도의 추론 능력(reasoner)을 지닌 모델로 설계되었습니다.
Extended Multimodalities: 가변적인 종횡비와 해상도를 지원하는 텍스트, 이미지(모든 모델), 비디오, 오디오를 처리합니다(E2B 및 E4B 모델에 기본적으로 내장됨).
컨텍스트 윈도우 확장: 소형 모델은 128K 컨텍스트 윈도우를 제공하며, 다른 모델은 256K를 지원합니다.
향상된 코딩 및 에이전트 기능: 내장된 function-calling 지원과 함께 코딩 벤치마크에서 눈에 띄는 성능 향상을 달성하여, 고도로 자율적인 에이전트를 구동합니다.
네이티브 System Prompt 지원: Gemma 4는 system role에 대한 내장 지원을 도입하여 더 구조적이고 제어 가능한 대화를 가능하게 합니다.

모든 원본 Gemma 4 체크포인트는 Gemma 4 릴리스에서 찾을 수 있습니다.

Gemma4 비전 모델

이전 Gemma의 비전 모델과 가장 큰 차이점은 고정된 토큰 수 예산을 사용하여 크기가 서로 다른 이미지를 처리하도록 설계된 새로운 아키텍처입니다. 224×224와 같은 고정된 정사각형으로 모든 이미지를 압축하는 많은 모델들과 달리, Gemma 4는 이미지의 자연스러운 종횡비를 유지하면서 적절한 크기로 조정합니다. 다음 두 가지 제약 사항을 준수해야 합니다:

…
높이와 너비 모두 48(= 패치 크기 16 × 풀링 커널 3)로 나누어떨어져야 합니다

Gemma 4는 많은 다른 비전 모델에서 사용하는 표준 ImageNet 평균/표준편차 정규화를 적용하지 않습니다. 모델 자체의 패치 임베딩 레이어가 최종 스케일링을 내부적으로 처리합니다(값을 [-1, 1] 범위로 이동).

이미지 프로세서가 생성할 수 있는 “soft token”(즉, vision token)의 수는 설정 가능합니다. 지원되는 옵션은 아래에 나와 있으며, 기본값은 이미지당 280개의 soft token입니다.

소프트 토큰	패치(풀링 전)	대략적인 이미지 영역
70	630	약 161K 픽셀
140	1,260	약 323K 픽셀
280	2,520	약 645K 픽셀
560	5,040	약 130만 픽셀
1,120	10,080	약 260만 픽셀

이미지 내 각 패치에 대한 위치 정보를 인코딩하기 위해 Gemma 4는 학습된 2D 위치 임베딩 테이블을 사용합니다. 위치 테이블은 축당 최대 10,240개의 위치를 저장하므로 모델이 매우 큰 이미지를 처리할 수 있습니다. 각 위치는 패치 임베딩과 동일한 차원을 가진 학습된 벡터입니다. Gemma 4가 사용하는 2D RoPE는 주의 헤드 차원의 절반을 x축에 대해, 나머지 절반을 y축에 대해 독립적으로 회전시킵니다. 이를 통해 모델은 "위", "아래", "왼쪽", "오른쪽"과 같은 공간적 관계를 이해할 수 있습니다.

레이어별 임베딩(PLE)

Gemma 4는 입력에서 단일 공유 임베딩에만 의존하지 않고, 각 디코더 레이어에 보조 잔차 신호를 공급하는 Per-Layer Embeddings(PLE) 시스템을 도입했습니다.

PLE는 두 가지 구성 요소를 합산한 뒤 1/√2로 스케일링하여 각 decoder layer에 전달합니다:

Token-identity(get_per_layer_inputs): embed_tokens_per_layer에서 input_ids를 조회합니다. embed_tokens_per_layer는 Gemma4TextScaledWordEmbedding이며, √(hidden_size_per_layer_input)을 곱합니다. 패킹된 출력은 [batch, seq, num_hidden_layers * hidden_size_per_layer_input]에서 [batch, seq, num_hidden_layers, hidden_size_per_layer_input]으로 리사이즈됩니다.
컨텍스트 인식(project_per_layer_inputs): inputs_embeds를 per_layer_model_projection(Linear 레이어)를 통해 투영한 뒤 1/√(hidden_size)로 스케일링하고, [batch, seq, num_layers, ple_dim]으로 리사이즈한 다음 per_layer_projection_norm(RMSNorm)로 정규화합니다.

두 구성 요소가 모두 사용 가능한 경우, 최종 레이어별 입력은 (token_identity + context_aware) * (1/√2)입니다. input_ids가 사용 불가능한 멀티모달 입력의 경우, 컨텍스트 인식 투사만 사용됩니다.

사용 예시

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

from transformers import pipeline


pipeline = pipeline(
    task="image-text-to-text",
    model="google/gemma-4-E2B-it",
)
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">

from transformers import AutoModelForImageTextToText, AutoProcessor


model = AutoModelForImageTextToText.from_pretrained(
    "google/gemma-4-E2B-it",
    device_map="auto",
    attn_implementation="sdpa"
)
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, cache_implementation="static")
print(processor.decode(output[0][input_len:], skip_special_tokens=True))

Function calling

from transformers import AutoModelForCausalLM, AutoProcessor


WEATHER_TOOL = {
    "type": "function",
    "function": {
        "name": "get_n_day_weather_forecast",
        "description": "Get an N-day weather forecast",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                },
                "format": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "The temperature unit to use",
                },
                "num_days": {
                    "type": "integer",
                    "description": "The number of days to forecast",
                },
            },
            "required": ["location", "format", "num_days"],
        },
    },
}

messages = [
    {
        "role": "user",
        "content": "What's the weather like the next 3 days in San Francisco, CA (using F)?",
    },
]

model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-4-E2B-it",
    device_map="auto",
    attn_implementation="sdpa"
)
processor = AutoProcessor.from_pretrained(
    "google/gemma-4-E2B-it",
    padding_side="left"
)

text = processor.apply_chat_template(
    messages,
    tools=[WEATHER_TOOL],
    tokenize=False,
    add_generation_prompt=True,
)

inputs = processor(text=text, return_tensors="pt").to(model.device)
input_len = inputs["input_ids"].shape[-1]

outputs = model.generate(**inputs, max_new_tokens=200)
print(processor.decode(outputs[0][input_len:], skip_special_tokens=False))

오디오 (E2B 및 E4B 전용)

from transformers import AutoModelForMultimodalLM, AutoProcessor


messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Please transcribe the following audio:"},
            {
                "type": "audio",
                "url": "https://huggingface.co/datasets/eustlb/audio-samples/resolve/main/dude_where_is_my_car.wav",
            },
        ],
    }
]

model = AutoModelForMultimodalLM.from_pretrained(
    "google/gemma-4-E2B-it",
    device_map="auto",
    attn_implementation="sdpa"
)
processor = AutoProcessor.from_pretrained(
    "google/gemma-4-E2B-it",
    padding_side="left"
)

inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
    return_tensors="pt"
).to(model.device, dtype=model.dtype)

input_len = inputs["input_ids"].shape[-1]

outputs = model.generate(**inputs, max_new_tokens=200)
print(processor.decode(outputs[0][input_len:], skip_special_tokens=False))

Transformers

Gemma4

개요

Gemma4 비전 모델

레이어별 임베딩(PLE)

사용 예시

Function calling

오디오 (E2B 및 E4B 전용)

Gemma4AudioConfig

class transformers.Gemma4AudioConfig

Gemma4VisionConfig

class transformers.Gemma4VisionConfig

Gemma4TextConfig

클래스 transformers.Gemma4TextConfig

Gemma4Config

class transformers.Gemma4Config

Gemma4AudioFeatureExtractor

class transformers.Gemma4AudioFeatureExtractor

__call__

Gemma4ImageProcessorPil

class transformers.Gemma4ImageProcessorPil

preprocess

Gemma4ImageProcessor

클래스 transformers.Gemma4ImageProcessor

preprocess

Gemma4VideoProcessor

class transformers.Gemma4VideoProcessor

preprocess

Gemma4Processor

클래스 transformers.Gemma4Processor

__call__

Gemma4PreTrainedModel

클래스 transformers.Gemma4PreTrainedModel

forward

Gemma4AudioModel

클래스 transformers.Gemma4AudioModel

forward

Gemma4VisionModel

class transformers.Gemma4VisionModel

forward

Gemma4TextModel

class transformers.Gemma4TextModel

forward

Gemma4ForCausalLM

클래스 transformers.Gemma4ForCausalLM

forward

Gemma4Model

class transformers.Gemma4Model

forward

Gemma4ForConditionalGeneration

클래스 transformers.Gemma4ForConditionalGeneration

forward

call

call