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.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é publié dans HF papers le 2025-03-25 et contribué à Hugging Face Transformers le 2025-03-12.

Gemma 3

Gemma 3 est un modèle multimodal avec des variantes pré-entraînées et ajustées par instructions, disponible en 1B, 13B et 27B paramètres. L’architecture est globalement identique à celle des versions précédentes de Gemma. Les principales différences sont l’alternance de 5 couches d’auto-attention locale à fenêtre glissante pour chaque couche d’auto-attention globale, la prise en charge d’une longueur de contexte plus longue de 128K jetons, et un encodeur SigLip capable de « pan & scan » les images haute résolution pour empêcher la disparition d’informations dans les images haute résolution ou les images dont le ratio d’aspect n’est pas carré.

La variante ajustée par instructions a été entraînée ultérieurement à l'aide de la distillation de connaissances et de l'apprentissage par renforcement.

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

Cliquez sur les modèles Gemma 3 dans la barre latérale droite pour plus d’exemples sur la façon d’appliquer Gemma à différentes tâches de vision et de langage.

Définissez use_kernels=True dans from_pretrained() pour remplacer les couches prises en charge par des noyaux optimisés du Hub. Consultez Chargement des noyaux pour en savoir plus.

L'exemple ci-dessous montre comment générer du texte à partir d'une image avec Pipeline ou la classe AutoModel.

Pipeline

AutoModel

La quantification réduit la charge mémoire des grands modèles en représentant les poids avec une précision inférieure. Reportez-vous à l'aperçu de la Quantization pour plus d'informations sur les backends de quantification disponibles.

L'exemple ci-dessous utilise torchao pour quantiser uniquement les poids en 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))

Utilisez le AttentionMaskVisualizer pour mieux comprendre les jetons auxquels le modèle peut ou non prêter attention.

from transformers.utils.attention_visualizer import AttentionMaskVisualizer


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

Notes

Utilisez Gemma3ForConditionalGeneration pour les entrées image et texte ainsi que les entrées image uniquement.

Gemma 3 prend en charge plusieurs images en entrée, mais assurez-vous que les images sont correctement groupées par lots avant de les transmettre au processeur. Chaque lot doit être une liste d'une ou plusieurs images.

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?"},
        ]
    },
]

Le texte transmis au processeur doit contenir le jeton <start_of_image> à l'endroit où une image doit être insérée.
Le processeur dispose de sa propre méthode apply_chat_template() pour convertir les messages de chat en entrées du modèle.
Par défaut, les images ne sont pas recadrées et seule l'image de base est transmise au modèle. Dans le cas d'images haute résolution ou d'images dont le ratio d'aspect n'est pas carré, des artefacts peuvent apparaître car l'encodeur visuel utilise une résolution fixe de 896x896. Pour éviter ces artefacts et améliorer les performances lors de l'inférence, définissez do_pan_and_scan=True afin de découper l'image en plusieurs patches plus petits et de les concaténer avec l'embedding de l'image de base. Vous pouvez désactiver pan and scan pour une inférence plus rapide.
```
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)
```

Pour le point de contrôle Gemma-3 1B entraîné en mode texte uniquement, utilisez AutoModelForCausalLM à la place.

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

Notes

Gemma3ImageProcessor

classe transformers.Gemma3ImageProcessor

prétraiter

Gemma3ImageProcessorPil

classe transformers.Gemma3ImageProcessorPil

prétraiter

Gemma3Processor

classe transformers.Gemma3Processor

__call__

Gemma3TextConfig

classe transformers.Gemma3TextConfig

Gemma3Config

classe transformers.Gemma3Config

Gemma3TextModel

classe transformers.Gemma3TextModel

forward

Gemma3Model

classe transformers.Gemma3Model

forward

get_image_features

get_placeholder_mask

Gemma3ForCausalLM

classe transformers.Gemma3ForCausalLM

forward

Gemma3ForConditionalGeneration

classe transformers.Gemma3ForConditionalGeneration

forward

get_image_features

Gemma3ForSequenceClassification

classe transformers.Gemma3ForSequenceClassification

forward

Gemma3TextForSequenceClassification

classe transformers.Gemma3TextForSequenceClassification

forward

call