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

このモデルは2026年4月2日にHugging Face Transformersに貢献されました。

Gemma4

概要

Gemma 4 は、事前学習済みと指示チューニング済みのバリアントが用意されているマルチモーダルモデルで、E2B、E4B、31B、26B-A4B (MoE) のパラメータサイズが利用可能です。Gemma 4 モデルは、以下の機能を提供します。

推論: このファミリーのすべてのモデルは、設定可能な思考モードを備えた、高度な推論能力を持つ推論者として設計されています。
拡張マルチモーダル性: テキスト、可変のアスペクト比と解像度をサポートする画像（すべてのモデル）、動画、および音声（E2BおよびE4Bモデルでネイティブ対応）を処理します。
コンテキストウィンドウの拡大: 小型モデルは128Kのコンテキストウィンドウを備えており、その他のモデルは256Kに対応しています。
コーディングおよびエージェント機能の強化: 組み込みの関数呼び出しサポートにより、コーディングベンチマークで顕著な改善を実現し、高度な自律エージェントを駆動します。
ネイティブなシステムプロンプトのサポート: Gemma 4では、システムロールの組み込みサポートが導入され、より構造化され、制御可能な対話が可能になりました。

Gemma 4リリースの下に、すべてのオリジナルの Gemma 4 チェックポイントを見つけることができます。

Gemma4 Vision モデル

ビジョン機能において、以前の Gemma リリースとの主な違いは、固定のトークン数を使用して異なるサイズの画像を処理する新しい設計です。多くのモデルがすべての画像を固定の正方形（224×224 など）に圧縮するのに対し、Gemma 4 は画像の自然なアスペクト比を維持したまま、適切なサイズに調整します。以下のいくつかの制約を遵守する必要があります。

総ピクセル数はパッチ予算の範囲内に収まる必要があります
高さも幅も、48（= パッチサイズ 16 × プーリングカーネル 3）で割り切れる必要があります。

Gemma 4 は、他の多くのビジョンモデルで使用されている標準的な ImageNet の平均/標準偏差による正規化を適用しません。モデル自身のパッチ埋め込み層が最終的なスケーリングを内部で処理します（値を [-1, 1] の範囲にシフトします）。

画像プロセッサが生成できる「ソフトトークン」（別名: ビジョントークン）の数は設定可能です。サポートされているオプションは以下に示されており、デフォルト値は1画像あたり280ソフトトークンです。

ソフトトークン	パッチ(プーリング前)	おおよその画像領域
70	630	約161Kピクセル
140	1,260	約323Kピクセル
280	2,520	約645Kピクセル
560	5,040	約130万ピクセル
1,120	10,080	約260万ピクセル

画像内の各パッチの位置情報をエンコードするために、Gemma 4 は学習された 2D 位置埋め込みテーブルを使用します。位置テーブルは軸ごとに最大 10,240 個の位置を保存でき、これによりモデルは非常に大きな画像を処理できます。各位置は、パッチ埋め込みと同じ次元を持つ学習ベクトルです。Gemma 4 が使用する 2D RoPE は、アテンションヘッドの次元の半分を x 軸用に、残りの半分を y 軸用に独立して回転させます。これにより、モデルは「上」「下」「左側」「右側」のような空間的な関係を理解できます。

レイヤー別埋め込み（PLE）

Gemma 4 は、入力部の単一の共有埋め込みにのみ依存するのではなく、各デコーダ層に補助的な残差シグナルを供給する Per-Layer Embeddings (PLE) システムを導入しています。

PLEは、2つのコンポーネントを合計し、1/√2でスケーリングしてから、各デコーダ層に渡すという構成です。

Token-identity（get_per_layer_inputs）: embed_tokens_per_layer（√(hidden_size_per_layer_input) を乗算する Gemma4TextScaledWordEmbedding）で input_ids を参照します。パッキングされた出力は、[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))

Function calling

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 Vision モデル

レイヤー別埋め込み（PLE）

使用例

Function calling

オーディオ（E2BおよびE4Bのみ）

Gemma4AudioConfig

class transformers.Gemma4AudioConfig

Gemma4VisionConfig

クラス transformers.Gemma4VisionConfig

Gemma4TextConfig

クラス transformers.Gemma4TextConfig

Gemma4Config

クラス transformers.Gemma4Config

Gemma4AudioFeatureExtractor

クラス transformers.Gemma4AudioFeatureExtractor

__call__

Gemma4ImageProcessorPil

クラス transformers.Gemma4ImageProcessorPil

preprocess

Gemma4ImageProcessor

class transformers.Gemma4ImageProcessor

preprocess

Gemma4VideoProcessor

class transformers.Gemma4VideoProcessor

preprocess

Gemma4Processor

class transformers.Gemma4Processor

__call__

Gemma4PreTrainedModel

class transformers.Gemma4PreTrainedModel

forward

Gemma4AudioModel

class transformers.Gemma4AudioModel

forward

Gemma4VisionModel

class transformers.Gemma4VisionModel

forward

Gemma4TextModel

クラス transformers.Gemma4TextModel

forward

Gemma4ForCausalLM

クラス transformers.Gemma4ForCausalLM

forward

Gemma4Model

class transformers.Gemma4Model

forward

Gemma4ForConditionalGeneration

クラス transformers.Gemma4ForConditionalGeneration

forward

call

call