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

Эта модель была добавлена в Hugging Face Transformers 2026-04-02.

Gemma4

Обзор

Gemma 4 — это мультимодальная модель, доступная в вариантах с предобучением и дообучением по инструкциям, с размерами параметров E2B, E4B, 31B и 26B-A4B (MoE). Модели Gemma 4 обеспечивают следующие возможности:

Рассуждения: Все модели в семействе разработаны как высокопроизводительные рассуждающие модели с настраиваемыми режимами размышления.
Расширенные мультимодальности: обработка текста, изображений с поддержкой переменного соотношения сторон и разрешения (во всех моделях), видео и аудио (нативно поддерживается в моделях E2B и E4B).
Увеличенное контекстное окно: у небольших моделей контекстное окно составляет 128K, а у остальных моделей — 256K.
Расширенные возможности кодирования и агентные функции: Достигает значительных улучшений в бенчмарках по кодированию, а также поддерживает встроенные вызовы функций, что обеспечивает работу высокопроизводительных автономных агентов.
Поддержка системного промпта: Gemma 4 вводит встроенную поддержку системной роли, что позволяет вести более структурированные и управляемые диалоги.

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

Модель Gemma4 Vision

Ключевое отличие от предыдущих релизов Gemma для задач компьютерного зрения — новый подход к обработке изображений разного размера с использованием фиксированного бюджета токенов. В отличие от многих моделей, которые вписывают любое изображение в фиксированный квадрат (например, 224×224), Gemma 4 сохраняет естественное соотношение сторон изображения, приводя его к нужному размеру. При этом необходимо соблюдать несколько ограничений:

Общее количество пикселей должно укладываться в бюджет патчей
Высота и ширина должны делиться нацело на 48 (= размер патча 16 × ядро пулинга 3)

Gemma 4 не применяет стандартную нормализацию по среднему/стандартному отклонению ImageNet, которую используют многие другие модели компьютерного зрения. Слой встраивания патчей самой модели выполняет финальное масштабирование внутри (сдвигая значения в диапазон [-1, 1]).

Количество «мягких токенов» (также называемых визуальными токенами), которые может сгенерировать процессор изображений, настраивается. Поддерживаемые варианты описаны ниже, а значением по умолчанию является 280 мягких токенов на изображение.

Мягкие токены	Патчи (до пулинга)	Прибл. область изображения
70	630	~161 тыс. пикселей
140	1,260	~323 тыс. пикселей
280	2,520	~645 тыс. пикселей
560	5,040	~1,3 млн пикселей
1,120	10,080	~2,6 млн пикселей

Для кодирования позиционной информации каждого патча в изображении Gemma 4 использует обучаемую таблицу 2D-позиционных эмбеддингов. Таблица позиций хранит до 10 240 позиций по каждой оси, что позволяет модели обрабатывать очень большие изображения. Каждая позиция представляет собой обучаемый вектор тех же размерностей, что и эмбеддинг патча. 2D RoPE, который использует Gemma 4, независимо вращает половину размерностей головы внимания для оси x и другую половину для оси y. Это позволяет модели понимать пространственные отношения, такие как «выше», «ниже», «слева» и «справа».

Встраивания по слоям (PLE)

Gemma 4 вводит систему Per-Layer Embeddings (PLE), которая подаёт дополнительный остаточный сигнал в каждый слой декодера, а не полагается исключительно на единую общую эмбеддинг на входе.

PLE объединяет два компонента, которые суммируются и масштабируются множителем 1/√2 перед подачей на каждый слой декодера:

Идентичность токенов (get_per_layer_inputs): выполняет поиск 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 (линейный слой), масштабирует на 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))

Вызов функций

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 Vision

Встраивания по слоям (PLE)

Примеры использования

Вызов функций

Аудио (только E2B и E4B)

Gemma4AudioConfig

класс transformers.Gemma4AudioConfig

Gemma4VisionConfig

класс transformers.Gemma4VisionConfig

Gemma4TextConfig

класс transformers.Gemma4TextConfig

Gemma4Config

класс transformers.Gemma4Config

Gemma4AudioFeatureExtractor

класс transformers.Gemma4AudioFeatureExtractor

__call__

Gemma4ImageProcessorPil

класс transformers.Gemma4ImageProcessorPil

preprocess

Gemma4ImageProcessor

класс transformers.Gemma4ImageProcessor

preprocess

Gemma4VideoProcessor

класс transformers.Gemma4VideoProcessor

preprocess

Gemma4Processor

класс transformers.Gemma4Processor

__call__

Gemma4PreTrainedModel

класс transformers.Gemma4PreTrainedModel

forward

Gemma4AudioModel

класс transformers.Gemma4AudioModel

forward

Gemma4VisionModel

класс transformers.Gemma4VisionModel

forward

Gemma4TextModel

класс transformers.Gemma4TextModel

forward

Gemma4ForCausalLM

класс transformers.Gemma4ForCausalLM

forward

Gemma4Model

класс transformers.Gemma4Model

forward

Gemma4ForConditionalGeneration

класс transformers.Gemma4ForConditionalGeneration

forward

call

call