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

Este modelo foi contribuído para o Hugging Face Transformers em 2026-04-02.

Gemma4

Visão geral

Gemma 4 é um modelo multimodal com variantes pré-treinadas e ajustadas por instruções, disponível nos tamanhos de parâmetros E2B, E4B, 31B e 26B-A4B (MoE). Os modelos Gemma 4 oferecem as seguintes capacidades:

Raciocínio: Todos os modelos da família são projetados como raciocinadores altamente capazes, com modos de raciocínio configuráveis.
Multimodalidades estendidas: processa texto, imagem com suporte a proporção de aspecto e resolução variáveis (todos os modelos), vídeo e áudio (recursos nativos nos modelos E2B e E4B).
Janela de contexto ampliada: os modelos pequenos possuem uma janela de contexto de 128K, enquanto os outros modelos suportam 256K.
Capacidades aprimoradas de codificação e agentes: alcança melhorias notáveis em benchmarks de codificação, além de oferecer suporte nativo a chamadas de funções, impulsionando agentes autônomos altamente capazes.
Suporte nativo a System Prompt: o Gemma 4 introduz suporte integrado ao papel de sistema, permitindo conversas mais estruturadas e controláveis.

Você pode encontrar todos os checkpoints originais do Gemma 4 na liberação Gemma 4.

Modelo Gemma4 Vision

A principal diferença em relação às versões anteriores do Gemma para visão é o novo design para processar imagens de tamanhos diferentes usando um número fixo de tokens. Diferentemente de muitos modelos que comprimem cada imagem em um quadrado fixo (como 224×224), o Gemma 4 preserva a proporção natural da imagem ao mesmo tempo que a redimensiona adequadamente. Há alguns limites a serem observados:

O número total de pixels deve caber dentro de um orçamento de patches
Tanto a altura quanto a largura devem ser divisíveis por 48 (= tamanho do patch 16 × kernel de pooling 3)

O Gemma 4 não aplica a normalização de média/desvio padrão padrão do ImageNet que muitos outros modelos de visão utilizam. A própria camada de incorporação de patches do modelo trata do escalonamento final internamente (deslocando os valores para o intervalo [-1, 1]).

O número de “soft tokens” (também chamados de tokens de visão) que um processador de imagem pode gerar é configurável. As opções suportadas estão descritas abaixo e o padrão é 280 soft tokens por imagem.

Tokens Suaves	Patches (antes do pooling)	Área Aprox. da Imagem
70	630	~161 mil pixels
140	1,260	~323 mil pixels
280	2,520	~645 mil pixels
560	5,040	~1,3M pixels
1,120	10,080	~2,6M pixels

Para codificar as informações posicionais de cada patch na imagem, o Gemma 4 utiliza uma tabela de embeddings de posição 2D aprendida. A tabela de posições armazena até 10.240 posições por eixo, o que permite que o modelo processe imagens muito grandes. Cada posição é um vetor aprendido com as mesmas dimensões do embedding do patch. O 2D RoPE, que o Gemma 4 utiliza, gira independentemente metade das dimensões da cabeça de atenção para o eixo x e a outra metade para o eixo y. Isso permite que o modelo compreenda relações espaciais como “acima”, “abaixo”, “à esquerda de” e “à direita de”.

Incorporações por Camada (PLE)

Gemma 4 introduz um sistema de Per-Layer Embeddings (PLE) que fornece um sinal residual auxiliar para cada camada do decodificador, em vez de depender exclusivamente de uma única incorporação compartilhada na entrada.

O PLE combina dois componentes que são somados e escalados por 1/√2 antes de serem enviados para cada camada do decodificador:

Identidade de token (get_per_layer_inputs): consulta input_ids em embed_tokens_per_layer, um Gemma4TextScaledWordEmbedding que multiplica por √(hidden_size_per_layer_input). A saída empacotada é redimensionada de [batch, seq, num_hidden_layers * hidden_size_per_layer_input] para [batch, seq, num_hidden_layers, hidden_size_per_layer_input].
Contextual (project_per_layer_inputs): projeta inputs_embeds por meio de per_layer_model_projection (uma camada Linear), escala por 1/√(hidden_size), redimensiona para [batch, seq, num_layers, ple_dim] e normaliza com per_layer_projection_norm (RMSNorm).

Quando ambos os componentes estão disponíveis, a entrada final por camada é (token_identity + context_aware) * (1/√2). Para entradas multimodais em que input_ids não estão disponíveis, apenas a projeção consciente do contexto é utilizada.

Exemplos de uso

O exemplo abaixo demonstra como gerar texto com base em uma imagem usando Pipeline ou a classe 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))

Chamada de função

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

Áudio (somente E2B e 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

Visão geral

Modelo Gemma4 Vision

Incorporações por Camada (PLE)

Exemplos de uso

Chamada de função

Áudio (somente E2B e E4B)

Gemma4AudioConfig

classe transformers.Gemma4AudioConfig

Gemma4VisionConfig

classe transformers.Gemma4VisionConfig

Gemma4TextConfig

classe transformers.Gemma4TextConfig

Gemma4Config

classe transformers.Gemma4Config

Gemma4AudioFeatureExtractor

classe transformers.Gemma4AudioFeatureExtractor

__call__

Gemma4ImageProcessorPil

classe transformers.Gemma4ImageProcessorPil

pré-processamento

Gemma4ImageProcessor

classe transformers.Gemma4ImageProcessor

pré-processamento

Gemma4VideoProcessor

classe transformers.Gemma4VideoProcessor

pré-processamento

Gemma4Processor

classe transformers.Gemma4Processor

__call__

Gemma4PreTrainedModel

classe transformers.Gemma4PreTrainedModel

forward

Gemma4AudioModel

classe transformers.Gemma4AudioModel

forward

Gemma4VisionModel

classe transformers.Gemma4VisionModel

forward

Gemma4TextModel

classe transformers.Gemma4TextModel

forward

Gemma4ForCausalLM

classe transformers.Gemma4ForCausalLM

forward

Gemma4Model

classe transformers.Gemma4Model

forward

Gemma4ForConditionalGeneration

classe transformers.Gemma4ForConditionalGeneration

forward

call

call