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

Ce modèle a été contribué à Hugging Face Transformers le 2026-04-02.

Gemma4

Aperçu

Gemma 4 est un modèle multimodal avec des variantes pré-entraînées et ajustées par instructions, disponible en tailles de paramètres E2B, E4B, 31B et 26B-A4B (MoE). Les modèles Gemma 4 offrent les capacités suivantes :

Raisonnement : tous les modèles de la famille sont conçus comme des raisonneurs très performants, avec des modes de réflexion configurables.
Multimodalités étendues : traite le texte, l'image avec prise en charge des rapports d'aspect et des résolutions variables (tous les modèles), la vidéo et l'audio (fonctionnalités natives des modèles E2B et E4B).
Fenêtre de contexte élargie : les petits modèles disposent d'une fenêtre de contexte de 128K, tandis que les autres modèles prennent en charge 256K.
Capacités de codage et d'agents renforcées : Obtient des améliorations notables sur les benchmarks de codage, tout en offrant un support intégré pour l'appel de fonctions, alimentant ainsi des agents autonomes hautement performants.
Prise en charge native des prompts système : Gemma 4 introduit un support intégré du rôle système, permettant des conversations plus structurées et contrôlables.

Vous pouvez trouver tous les points de contrôle originaux de Gemma 4 dans la version Gemma 4.

Modèle Gemma4 Vision

La principale différence par rapport aux versions précédentes de Gemma pour la vision est la nouvelle conception permettant de traiter des images de tailles différentes à l'aide d'un nombre de jetons à budget fixe. Contrairement à de nombreux modèles qui compressent chaque image dans un carré fixe (comme 224×224), Gemma 4 conserve le ratio d'aspect naturel de l'image tout en l'ajustant à la bonne taille. Il y a quelques contraintes à respecter :

Le nombre total de pixels doit tenir dans un budget de patches
La hauteur et la largeur doivent être divisibles par 48 (= taille du patch 16 × noyau de pooling 3)

Gemma 4 n’applique pas la normalisation moyenne/écart-type standard d’ImageNet utilisée par de nombreux autres modèles de vision. La couche d’incorporation de patch du modèle gère elle-même le mise à l’échelle finale en interne (décalant les valeurs vers l’intervalle [-1, 1]).

Le nombre de « soft tokens » (aussi appelés vision tokens) qu’un processeur d’images peut produire est configurable. Les options prises en charge sont décrites ci-dessous et la valeur par défaut est de 280 soft tokens par image.

Jetons doux	Patches (avant le pooling)	Surface approximative de l'image
70	630	~161K pixels
140	1,260	~323K pixels
280	2,520	~645K pixels
560	5,040	~1,3 M pixels
1,120	10,080	~2,6 M pixels

Pour encoder les informations positionnelles de chaque patch de l'image, Gemma 4 utilise une table d'embeddings de position 2D appris. La table de position stocke jusqu'à 10 240 positions par axe, ce qui permet au modèle de traiter des images très grandes. Chaque position est un vecteur appris de mêmes dimensions que l'embedding de patch. Le 2D RoPE utilisé par Gemma 4 fait tourner indépendamment la moitié des dimensions de la tête d'attention pour l'axe x et l'autre moitié pour l'axe y. Cela permet au modèle de comprendre les relations spatiales telles que « au-dessus », « en dessous », « à gauche de » et « à droite de ».

Embeddings par couche (PLE)

Gemma 4 introduit un système d'embeddings par couche (Per-Layer Embeddings, PLE) qui alimente chaque couche du décodeur avec un signal résiduel auxiliaire, plutôt que de s'appuyer uniquement sur un embedding unique partagé à l'entrée.

PLE combine deux composantes qui sont additionnées et mises à l'échelle par 1/√2 avant d'être transmises à chaque couche décodeur :

Identité des jetons (get_per_layer_inputs) : recherche input_ids dans embed_tokens_per_layer, un Gemma4TextScaledWordEmbedding qui multiplie par √(hidden_size_per_layer_input). La sortie empilée est redimensionnée de [batch, seq, num_hidden_layers * hidden_size_per_layer_input] à [batch, seq, num_hidden_layers, hidden_size_per_layer_input].
Prise en compte du contexte (project_per_layer_inputs) : projette inputs_embeds à travers per_layer_model_projection (une couche Linear), l'échelle par 1/√(hidden_size), le redimensionne en [batch, seq, num_layers, ple_dim] et le normalise avec per_layer_projection_norm (RMSNorm).

Lorsque les deux composants sont disponibles, l’entrée finale par couche est (token_identity + context_aware) * (1/√2). Pour les entrées multimodales où input_ids ne sont pas disponibles, seule la projection context-aware est utilisée.

Exemples d'utilisation

L'exemple ci-dessous montre comment générer du texte à partir d'une image avec Pipeline ou la 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))

Appel de fonction

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

Audio (E2B et E4B uniquement)

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

Aperçu

Modèle Gemma4 Vision

Embeddings par couche (PLE)

Exemples d'utilisation

Appel de fonction

Audio (E2B et E4B uniquement)

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étraiter

Gemma4ImageProcessor

classe transformers.Gemma4ImageProcessor

prétraiter

Gemma4VideoProcessor

classe transformers.Gemma4VideoProcessor

prétraiter

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