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

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

该模型于 2026-04-02 贡献至 Hugging Face Transformers。

Gemma4

概述

Gemma 4 是一个多模态模型，提供预训练和指令微调版本，参数规模包括 E2B、E4B、31B 和 26B-A4B（MoE）。Gemma 4 模型提供以下功能：

推理：该系列中的所有模型均被设计为具备强大推理能力的模型，并支持可配置的思考模式。
扩展多模态：支持处理文本、具有可变宽高比和分辨率的图像（所有模型均支持）、视频以及音频（E2B 和 E4B 模型原生支持）。
上下文窗口扩展：小型模型的上下文窗口为 128K，而其他模型支持 256K。
增强的编码与智能体能力：在编码基准测试中取得了显著的提升，同时内置了函数调用支持，从而驱动了能力强大的自主智能体。
原生系统提示词支持：Gemma 4 引入了对 system 角色的内置支持，从而实现更结构化、更可控的对话。

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

Gemma4 视觉模型

与之前发布的 Gemma 视觉模型相比，关键区别在于采用了新的设计，使用固定数量的 token 预算来处理不同尺寸的图像。与许多将每张图像压缩为固定正方形（例如 224×224）的模型不同，Gemma 4 在调整图像至合适尺寸的同时，保留了图像的自然宽高比。需要遵循以下几项约束：

总像素数必须控制在补丁预算范围内
高度和宽度都必须能被 48（= 补丁大小 16 × 池化核 3）整除

Gemma 4 不会应用许多其他视觉模型所使用的标准 ImageNet 均值/标准差归一化。该模型自身的 patch embedding 层会在内部处理最终的缩放（将数值转换到 [-1, 1] 范围内）。

图像处理器可生成的“软标记”（即视觉标记）数量是可配置的。下方列出了支持的选项，默认值为每张图像 280 个软标记。

软标记	补丁（池化前）	近似图像面积
70	630	~161K 像素
140	1,260	~323K 像素
280	2,520	约 645K 像素
560	5,040	约 130 万像素
1,120	10,080	约 260 万像素

为了对图像中每个 patch 的位置信息进行编码，Gemma 4 使用了一个学习得到的 2D 位置嵌入表。该位置表在每个轴上最多存储 10,240 个位置，从而使模型能够处理非常大的图像。每个位置都是一个与 patch 嵌入维度相同的学习向量。Gemma 4 使用的 2D RoPE 独立地对注意力头维度的一半进行 x 轴旋转，对另一半进行 y 轴旋转。这使得模型能够理解诸如“上方”、“下方”、“左侧”和“右侧”等空间关系。

逐层嵌入（PLE）

Gemma 4 引入了逐层嵌入（Per-Layer Embeddings，PLE）系统，该系统向每个解码器层输入一个辅助残差信号，而不仅仅依赖输入端的单一共享嵌入。

PLE 将两个组件相加，并在输入每个解码器层之前乘以 1/√2 进行缩放：

Token-identity（get_per_layer_inputs）：在 embed_tokens_per_layer 中查找 input_ids，该层是一个 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（一个 Linear 层）进行投影，乘以 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 视觉模型

逐层嵌入（PLE）

使用示例

函数调用

音频（仅限 E2B 和 E4B）

Gemma4AudioConfig

class transformers.Gemma4AudioConfig

Gemma4VisionConfig

class transformers.Gemma4VisionConfig

Gemma4TextConfig

class transformers.Gemma4TextConfig

Gemma4Config

class transformers.Gemma4Config

Gemma4AudioFeatureExtractor

class transformers.Gemma4AudioFeatureExtractor

__call__

Gemma4ImageProcessorPil

class transformers.Gemma4ImageProcessorPil

预处理

Gemma4ImageProcessor

class transformers.Gemma4ImageProcessor

预处理

Gemma4VideoProcessor

class transformers.Gemma4VideoProcessor

预处理

Gemma4Processor

class transformers.Gemma4Processor

__call__

Gemma4PreTrainedModel

class transformers.Gemma4PreTrainedModel

forward

Gemma4AudioModel

class transformers.Gemma4AudioModel

forward

Gemma4VisionModel

class transformers.Gemma4VisionModel

forward

Gemma4TextModel

class transformers.Gemma4TextModel

forward

Gemma4ForCausalLM

class transformers.Gemma4ForCausalLM

forward

Gemma4Model

class transformers.Gemma4Model

forward

Gemma4ForConditionalGeneration

类 transformers.Gemma4ForConditionalGeneration

forward

call

call