Transformers documentation

Gemma 3

Transformers

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

이 모델은 2025-03-25에 HF papers에 게시되었으며, 2025-03-12에 Hugging Face Transformers에 기여되었습니다.

Gemma 3

Gemma 3는 사전 학습 및 지시 튜닝 변형이 제공되는 멀티모달 모델로, 1B, 13B, 27B 파라미터 규모로 사용할 수 있습니다. 아키텍처는 이전 Gemma 버전과 대부분 동일합니다. 주요 차이점은 전역 self-attention 레이어마다 5개의 로컬 슬라이딩 윈도우 self-attention 레이어가 교차 배치되는 구조, 128K 토큰의 더 긴 컨텍스트 길이에 대한 지원, 그리고 고해상도 이미지에서 정보가 손실되지 않도록 고해상도 이미지나 정사각형이 아닌 종횡비의 이미지를 “pan & scan”할 수 있는 SigLip 인코더입니다.

지시 튜닝 변형은 지식 증류와 강화 학습을 통해 후학습되었습니다.

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

오른쪽 사이드바의 Gemma 3 모델에 클릭하여 Gemma를 다양한 비전 및 언어 작업에 적용하는 방법에 대한 추가 예제를 확인하세요.

use_kernels=True를 from_pretrained()에 설정하여 Hub의 최적화 커널로 지원되는 레이어를 대체합니다. 자세한 내용은 커널 로딩을 참고하세요.

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

Pipeline

AutoModel

Quantization은 가중치를 더 낮은 정밀도로 표현하여 대규모 모델의 메모리 부담을 줄입니다. 사용 가능한 다른 양자화 백엔드에 대해서는 Quantization 개요를 참조하세요.

아래 예제는 torchao를 사용하여 가중치만 int4로 양자화합니다.

# pip install torchao
from transformers import AutoProcessor, Gemma3ForConditionalGeneration, TorchAoConfig


quantization_config = TorchAoConfig("int4_weight_only", group_size=128)
model = Gemma3ForConditionalGeneration.from_pretrained(
    "google/gemma-3-27b-it",
    device_map="auto",
    quantization_config=quantization_config
)
processor = AutoProcessor.from_pretrained(
    "google/gemma-3-27b-it",
    padding_side="left"
)

messages = [
    {
        "role": "system",
        "content": [
            {"type": "text", "text": "You are a helpful assistant."}
        ]
    },
    {
        "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)

output = model.generate(**inputs, max_new_tokens=50, cache_implementation="static")
print(processor.decode(output[0], skip_special_tokens=True))

AttentionMaskVisualizer를 사용하여 모델이 어떤 토큰에 주의를 기울일 수 있고, 어떤 토큰에는 기울일 수 없는지 더 잘 이해해 보세요.

from transformers.utils.attention_visualizer import AttentionMaskVisualizer


visualizer = AttentionMaskVisualizer("google/gemma-3-4b-it")
visualizer("<img>What is shown in this image?")

The input is a single word "Notes". 참고

이미지와 텍스트 입력 및 이미지 전용 입력에는 Gemma3ForConditionalGeneration를 사용합니다.

Gemma 3은 여러 입력 이미지를 지원하지만, 프로세서에 전달하기 전에 이미지가 올바르게 배치(batch)되었는지 확인하세요. 각 배치(batch)는 하나 이상의 이미지로 구성된 리스트여야 합니다.

url_cow = "https://media.istockphoto.com/id/1192867753/photo/cow-in-berchida-beach-siniscola.jpg?s=612x612&w=0&k=20&c=v0hjjniwsMNfJSuKWZuIn8pssmD5h5bSN1peBd1CmH4="
url_cat = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"

messages =[
    {
        "role": "system",
        "content": [
            {"type": "text", "text": "You are a helpful assistant."}
        ]
    },
    {
        "role": "user",
        "content": [
            {"type": "image", "url": url_cow},
            {"type": "image", "url": url_cat},
            {"type": "text", "text": "Which image is cuter?"},
        ]
    },
]

프로세서에 전달되는 텍스트에는 이미지가 삽입되어야 할 위치에 <start_of_image> 토큰이 있어야 합니다.
프로세서에는 채팅 메시지를 모델 입력으로 변환하기 위한 자체 apply_chat_template() 메서드가 있습니다.
기본적으로 이미지는 크롭되지 않으며, 모델에는 기본 이미지만 전달됩니다. 고해상도 이미지나 정사각형이 아닌 종횡비(aspect ratio)를 가진 이미지의 경우, 비전 인코더가 896x896의 고정 해상도를 사용하므로 아티팩트가 발생할 수 있습니다. 이러한 아티팩트를 방지하고 추론 시 성능을 개선하려면 do_pan_and_scan=True를 설정하여 이미지를 여러 개의 작은 패치로 크롭한 후, 이를 기본 이미지 임베딩과 연결(concatenate)하도록 하세요. 더 빠른 추론을 위해 pan and scan을 비활성화할 수도 있습니다.
```
inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    add_generation_prompt=True,
+   do_pan_and_scan=True,
    ).to(model.device)
```

텍스트 전용 모드로 학습된 Gemma-3 1B 체크포인트의 경우, AutoModelForCausalLM을 대신 사용하세요.

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained(
    "google/gemma-3-1b-pt",
)
model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-3-1b-pt",
    device_map="auto",
    attn_implementation="sdpa"
)
input_ids = tokenizer("Plants create energy through a process known as", return_tensors="pt").to(model.device)

output = model.generate(**input_ids, cache_implementation="static")
print(tokenizer.decode(output[0], skip_special_tokens=True))

Transformers

Gemma 3

The input is a single word "Notes". 참고

Gemma3ImageProcessor

클래스 transformers.Gemma3ImageProcessor

preprocess

Gemma3ImageProcessorPil

클래스 transformers.Gemma3ImageProcessorPil

preprocess

Gemma3Processor

클래스 transformers.Gemma3Processor

__call__

Gemma3TextConfig

클래스 transformers.Gemma3TextConfig

Gemma3Config

클래스 transformers.Gemma3Config

Gemma3TextModel

클래스 transformers.Gemma3TextModel

forward

Gemma3Model

class transformers.Gemma3Model

forward

get_image_features

get_placeholder_mask

Gemma3ForCausalLM

클래스 transformers.Gemma3ForCausalLM

forward

Gemma3ForConditionalGeneration

클래스 transformers.Gemma3ForConditionalGeneration

forward

get_image_features

Gemma3ForSequenceClassification

class transformers.Gemma3ForSequenceClassification

forward

Gemma3TextForSequenceClassification

class transformers.Gemma3TextForSequenceClassification

forward

call