Transformers documentation

Gemma 3

Transformers

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

该模型于 2025-03-25 在 HF papers 上发布，并于 2025-03-12 贡献至 Hugging Face Transformers。

Gemma 3

Gemma 3 是一个多模态模型，提供预训练和指令微调版本，参数量分别为 1B、13B 和 27B。其架构与之前的 Gemma 版本基本相同。主要区别在于：每 5 层局部滑动窗口自注意力层后交替使用一层全局自注意力层；支持更长的 128K token 上下文长度；以及一个 SigLip 编码器，能够对高分辨率图像进行“平移与扫描”（pan & scan），以防止高分辨率图像或非正方形宽高比图像中的信息丢失。

经过指令微调的变体通过知识蒸馏和强化学习进行了后训练。

您可以在 Gemma 3 发布中找到所有原始的 Gemma 3 检查点。

点击右侧边栏中的 Gemma 3 模型，以查看更多将 Gemma 应用于不同视觉和语言任务的示例。

在 from_pretrained() 中设置 use_kernels=True，即可用 Hub 上的优化内核替换受支持的层。有关详细信息，请参阅加载内核。

以下示例演示了如何使用 Pipeline 或 AutoModel 类基于图像生成文本。

Pipeline

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 可以更直观地了解模型能够和不能关注哪些 token。

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

class transformers.Gemma3ImageProcessor

预处理

Gemma3ImageProcessorPil

class transformers.Gemma3ImageProcessorPil

预处理

Gemma3Processor

class transformers.Gemma3Processor

__call__

Gemma3TextConfig

class transformers.Gemma3TextConfig

Gemma3Config

class transformers.Gemma3Config

Gemma3TextModel

class transformers.Gemma3TextModel

forward

Gemma3Model

class transformers.Gemma3Model

forward

get_image_features

get_placeholder_mask

Gemma3ForCausalLM

class transformers.Gemma3ForCausalLM

forward

Gemma3ForConditionalGeneration

类 transformers.Gemma3ForConditionalGeneration

forward

get_image_features

Gemma3ForSequenceClassification

class transformers.Gemma3ForSequenceClassification

forward

Gemma3TextForSequenceClassification

class transformers.Gemma3TextForSequenceClassification

forward

call