Transformers documentation

Gemma 3

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

Эта модель была опубликована в HF papers 25.03.2025 и добавлена в Hugging Face Transformers 12.03.2025.

Gemma 3

Gemma 3 — это мультимодальная модель, доступная в вариантах с предобучением и с обучением по инструкциям, с числом параметров 1B, 13B и 27B. Архитектура в целом совпадает с предыдущими версиями Gemma. Ключевые отличия: чередование пяти локальных слоев self-attention со скользящим окном на каждый глобальный слой self-attention, поддержка более длинного контекста в 128K токенов, а также энкодер SigLip, который может «pan & scan» изображения высокого разрешения, чтобы предотвратить потерю информации на изображениях с высоким разрешением или с неквадратным соотношением сторон.

Инструктивно настроенная версия была дообучена с использованием дистилляции знаний и обучения с подкреплением.

Все исходные контрольные точки Gemma 3 можно найти в релизе Gemma 3.

Нажмите на модели Gemma 3 в боковой панели справа, чтобы увидеть дополнительные примеры применения Gemma к различным задачам в области зрения и языка.

Установите use_kernels=True в from_pretrained(), чтобы заменить поддерживаемые слои на оптимизированные ядра из Hub. Подробнее см. в разделе Загрузка ядер.

Приведённый ниже пример показывает, как генерировать текст на основе изображения с помощью Pipeline или класса AutoModel.

Пайплайн

AutoModel

Квантование снижает нагрузку на память при работе с большими моделями, представляя веса в пониженной точности. Подробнее о доступных бэкендах квантования см. в обзоре Квантование.

Приведённый ниже пример использует 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?")

Примечания

Используйте Gemma3ForConditionalGeneration для входных данных, содержащих изображения и текст, а также для входных данных, содержащих только изображения.

Gemma 3 поддерживает несколько входных изображений, но убедитесь, что изображения правильно сгруппированы в батчи перед передачей в процессор. Каждый батч должен представлять собой список из одного или нескольких изображений.

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() для преобразования сообщений чата во входные данные модели.
По умолчанию изображения не обрезаются, и в модель передаётся только базовое изображение. В случае изображений высокого разрешения или с неквадратным соотношением сторон могут возникать артефакты, поскольку визуальный энкодер использует фиксированное разрешение 896x896. Чтобы предотвратить эти артефакты и улучшить производительность при инференсе, установите do_pan_and_scan=True, чтобы разрезать изображение на несколько меньших патчей и скатенировать их с эмбеддингом базового изображения. Вы можете отключить 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

Примечания

Gemma3ImageProcessor

класс transformers.Gemma3ImageProcessor

preprocess

Gemma3ImageProcessorPil

класс transformers.Gemma3ImageProcessorPil

preprocess

Gemma3Processor

класс transformers.Gemma3Processor

__call__

Gemma3TextConfig

класс transformers.Gemma3TextConfig

Gemma3Config

класс transformers.Gemma3Config

Gemma3TextModel

класс transformers.Gemma3TextModel

forward

Gemma3Model

класс transformers.Gemma3Model

forward

get_image_features

get_placeholder_mask

Gemma3ForCausalLM

класс transformers.Gemma3ForCausalLM

forward

Gemma3ForConditionalGeneration

класс transformers.Gemma3ForConditionalGeneration

forward

get_image_features

Gemma3ForSequenceClassification

класс transformers.Gemma3ForSequenceClassification

forward

Gemma3TextForSequenceClassification

класс transformers.Gemma3TextForSequenceClassification

forward

call