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年3月25日にHF papersで公開され、2025年3月12日にHugging Face Transformersに貢献されました。

Gemma 3

Gemma 3は、事前学習済みと指示チューニング済みのバリアントが用意されているマルチモーダルモデルで、1B、13B、27Bのパラメータサイズが利用可能です。アーキテクチャは以前のGemmaバージョンとほぼ同じです。主な違いは、グローバルな自己注意レイヤーごとに5つのローカルスライディングウィンドウ自己注意レイヤーを交互に配置していること、128Kトークンというより長いコンテキスト長をサポートしていること、そしてSigLipエンコーダーによって高解像度画像を「パン＆スキャン」でき、高解像度画像や正方形でないアスペクト比の画像における情報の消失を防げることです。

指示チューニング済みバリアントは、知識蒸留と強化学習を用いてポストトレーニングされました。

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

Gemma をさまざまなビジョンおよび言語タスクに適用する方法の例については、右側のサイドバーにある Gemma 3 モデルをクリックしてください。

use_kernels=True を from_pretrained() に設定すると、対応するレイヤーが Hub からの最適化されたカーネルに置き換えられます。詳細はカーネルの読み込みを参照してください。

以下の例では、PipelineまたはAutoModelクラスを使用して、画像に基づいてテキストを生成する方法を示しています。

パイプライン

AutoModel

Quantization は、重みを低精度で表現することで、大規模モデルのメモリ負荷を軽減します。利用可能な Quantization バックエンドの詳細については、Quantization の概要を参照してください。

以下の例では、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 を使用して、モデルが注意できるトークンと注意できないトークンをより深く理解してください。

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 は複数の入力画像をサポートしていますが、プロセッサに渡す前に画像が正しくバッチ化されていることを確認してください。各バッチは、1 つ以上の画像のリストである必要があります。

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

preprocess

Gemma3ImageProcessorPil

クラス transformers.Gemma3ImageProcessorPil

preprocess

Gemma3Processor

class transformers.Gemma3Processor

__call__

Gemma3TextConfig

クラス transformers.Gemma3TextConfig

Gemma3Config

クラス transformers.Gemma3Config

Gemma3TextModel

クラス transformers.Gemma3TextModel

forward

Gemma3Model

class transformers.Gemma3Model

forward

get_image_features

get_placeholder_mask

Gemma3ForCausalLM

クラス transformers.Gemma3ForCausalLM

forward

Gemma3ForConditionalGeneration

クラス transformers.Gemma3ForConditionalGeneration

forward

get_image_features

Gemma3ForSequenceClassification

class transformers.Gemma3ForSequenceClassification

forward

Gemma3TextForSequenceClassification

class transformers.Gemma3TextForSequenceClassification

forward

call