Transformers documentation
ShieldGemma 2
このモデルは2025年4月1日にHF papersで公開され、2025年3月20日にHugging Face Transformersに貢献されました。
ShieldGemma 2
概要
ShieldGemma 2 モデルは、Google による技術レポートで提案されました。Gemma 3を基盤とする ShieldGemma 2 は、40 億（4B）パラメータのモデルであり、合成画像と自然画像の両方について主要なカテゴリに対する安全性を確認することで、堅牢なデータセットやモデルの構築を支援します。Gemma モデルファミリーへのこの追加により、研究者や開発者は、以下で定義される主要な有害性領域において、モデル内の有害コンテンツのリスクを簡単に最小限に抑えることができます。
- 性的に露骨なコンテンツなし: 画像には、露骨または詳細な性的行為（例: ポルノ、エロティックな裸体、レイプや性的暴行の描写）を描くコンテンツを含んではなりません。
- 危険なコンテンツなし: 画像には、現実世界での危害を引き起こす可能性のある活動を助長または奨励するコンテンツ（例: 銃器や爆発物の製造、テロリズムの宣伝、自殺の手引き）を含んではなりません。
- 暴力・グロテスクなコンテンツの禁止: 画像には、衝撃的・センセーショナル・無意味な暴力（例: 過度な血やグロテスクな描写、動物に対する無意味な暴力、極端な負傷や死の瞬間）を描くコンテンツを含んではなりません。
ビジョン言語モデルの入力フィルタ、または画像生成システムの出力フィルタとして、ShieldGemma 2 の使用を推奨します。堅牢な画像安全性モデルを訓練するために、自然画像と合成画像からなる訓練データセットをキュレーションし、Gemma 3 を指示チューニングすることで、優れたパフォーマンスを実証しました。
このモデルは、Ryan Mullins によって提供されました。
使用例
- ShieldGemma 2 は、
imagesのリストと任意のpoliciesのリストを受け取り、提供されたチャットテンプレートを使用して、これら 2 つのリストの積からプロンプトのバッチを構築する Processor を提供します。 - Processor の
custom_policies引数を使用することで、ShieldGemma の組み込みポリシーを拡張できます。組み込みポリシーと同じキーを使用すると、そのポリシーがカスタム定義で上書きされます。 - ShieldGemma 2 は、Gemma 3 で使用されている画像クロッピング機能をサポートしていません。
組み込みポリシーとの分類
import requests
from PIL import Image
from transformers import AutoProcessor, ShieldGemma2ForImageClassification
model_id = "google/shieldgemma-2-4b-it"
model = ShieldGemma2ForImageClassification.from_pretrained(model_id, device_map="auto")
processor = AutoProcessor.from_pretrained(model_id)
url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/bee.jpg"
image = Image.open(requests.get(url, stream=True).raw)
inputs = processor(images=[image], return_tensors="pt").to(model.device)
output = model(**inputs)
print(output.probabilities)カスタムポリシーに対する分類
import requests
from PIL import Image
from transformers import AutoProcessor, ShieldGemma2ForImageClassification
model_id = "google/shieldgemma-2-4b-it"
model = ShieldGemma2ForImageClassification.from_pretrained(model_id, device_map="auto")
processor = AutoProcessor.from_pretrained(model_id)
url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/bee.jpg"
image = Image.open(requests.get(url, stream=True).raw)
custom_policies = {
"key_a": "description_a",
"key_b": "description_b",
}
inputs = processor(
images=[image],
custom_policies=custom_policies,
policies=["dangerous", "key_a", "key_b"],
return_tensors="pt",
).to(model.device)
output = model(**inputs)
print(output.probabilities)ShieldGemma2Processor
class transformers.ShieldGemma2Processor
< source >( image_processortokenizerchat_template = Noneimage_seq_length = 256policy_definitions = None**kwargs )
__call__
< source >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext = None**kwargs: *<class 'transformers.models.shieldgemma2.processing_shieldgemma2.ShieldGemma2ProcessorKwargs'> )
パラメータ
- images — バッチに含める単一の画像または画像のリスト。
- text — 非対応です。
- videos — 未対応です。
- audio — 未対応。
- kwargs — プロセッサを設定するためのキーワード引数の任意の辞書です。可能な値には以下が含まれます:
custom_policies: コンストラクタに渡されるself.policy_definitionsを拡張する追加のポリシー定義です。custom_policiesがself.policy_definitionsとキーを共有する場合、ポリシーの説明を上書きします。policies: (任意) 提供された画像に対して特に興味のある、self.policy_definitions | custom_policiesの結合辞書内のキーのリストです。空または None の場合、結合辞書のすべてのキーに対してプロンプトが生成されます。
提供された画像から入力バッチを生成します。
ShieldGemma は、特定のプロンプト構造を用いて、ポリシー遵守のための画像コンテンツの分類を行うよう学習されています。 このプロセッサーは、提供された画像から、次の手順でそのようなプロンプトのバッチを生成します。
<image, policy>ペアごとに1つずつ、会話のリストを作成します;self.apply_chat_template()を使用してこれらの会話をテキストに変換し、Gemma3Processorと同じ手法を使用して、会話と画像をエンコードします。
ShieldGemma2Config
class transformers.ShieldGemma2Config
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonetext_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonemm_tokens_per_image: int = 256boi_token_index: int = 255999eoi_token_index: int = 256000image_token_index: int = 262144initializer_range: float = 0.02tie_word_embeddings: bool = False )
パラメータ
- text_config (
Union[dict, ~configuration_utils.PreTrainedConfig]、省略可) — テキストバックボーンの設定オブジェクトまたは辞書。 - vision_config (
Union[dict, ~configuration_utils.PreTrainedConfig]、任意) — ビジョンバックボーンの config オブジェクトまたは辞書です。 - mm_tokens_per_image (
int、任意、デフォルトは 256) — 画像埋め込みあたりのトークン数です。 - boi_token_index (
int、省略可能、デフォルトは 255999)— 画像プロンプトをラップするために使用する begin-of-image トークンのインデックスです。 - eoi_token_index (
int、省略可能、デフォルトは 256000) — 画像プロンプトをラップするために使用する end-of-image トークンのインデックスです。 - image_token_index (
int、任意、デフォルトは262144) — 入力画像のプレースホルダーとして使用される画像トークンのインデックスです。 - initializer_range (
float、任意、デフォルトは0.02) — すべての重み行列を初期化するための truncated_normal_initializer の標準偏差です。 - tie_word_embeddings (
bool, 任意) — ワード埋め込みをタイするかどうか。未設定の場合、text_config.tie_word_embeddingsの値がデフォルトとして使用されます。
これはShieldgemma2Modelの設定を保存するための設定クラスです。指定された引数に基づいてShieldgemma2モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、google/shieldgemma-2-4b-itと類似した設定が得られます。
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
例:
>>> from transformers import ShieldGemma2ForConditionalGeneration, ShieldGemma2Config, SiglipVisionConfig, ShieldGemma2TextConfig
>>> # Initializing a Siglip-like vision config
>>> vision_config = SiglipVisionConfig()
>>> # Initializing a ShieldGemma2 Text config
>>> text_config = ShieldGemma2TextConfig()
>>> # Initializing a ShieldGemma2 gemma-3-4b style configuration
>>> configuration = ShieldGemma2Config(vision_config, text_config)
>>> # Initializing a model from the gemma-3-4b style configuration
>>> model = ShieldGemma2TextConfig(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configShieldGemma2ForImageClassification
class transformers.ShieldGemma2ForImageClassification
< source >( config: ShieldGemma2Config )
パラメータ
- config (ShieldGemma2Config) — モデルのすべてのパラメータを含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連付けられた重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
ImageNet などの用途で、画像分類ヘッドを上部に備えた Shieldgemma2 モデル。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.FloatTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Nonetoken_type_ids: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.FloatTensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Noneoutput_attentions: bool | None = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0**kwargs )
パラメータ
- input_ids (
torch.LongTensorの形状(batch_size, sequence_length), 、省略可) — 語彙における入力シーケンスのトークンインデックスです。デフォルトではパディングは無視されます。インデックスはAutoTokenizerを使用して取得できます。詳細については、PreTrainedTokenizer.encode()およびPreTrainedTokenizer.call()を参照してください。
- pixel_values (
torch.FloatTensor、形状(batch_size, num_channels, image_size, image_size)、任意) — 入力画像に対応するテンソルです。ピクセル値はimage_processor_classを使用して取得できます。詳細はimage_processor_class.__call__を参照してください（processor_classは画像の処理にimage_processor_classを使用します）。 - attention_mask (
torch.Tensorの形状(batch_size, sequence_length), 、任意) — パディングトークンのインデックスに対するアテンションを回避するためのマスク。[0, 1]:- マスクされていないトークンに対して1
- マスクされたトークンに対しては 0 です。
- position_ids (
torch.LongTensorの形状(batch_size, sequence_length), 、任意) — 各入力シーケンスのトークンが位置埋め込み内で占める位置のインデックス。範囲[0, config.n_positions - 1]. - past_key_values (
~cache_utils.Cache, 省略可) — 逐次デコードを高速化するために使用できる、事前計算された隠れ状態(自己アテンションブロックおよびクロスアテンションブロックのキーとバリュー)。通常、これはデコードの以前の段階でモデルが返したpast_key_valuesであり、use_cache=Trueまたはconfig.use_cache=True.入力として許可されるのは Cache インスタンスのみです。kv cache ガイドを参照してください。
past_key_valuesが渡されない場合、デフォルトで DynamicCache が初期化されます。モデルは、入力として与えられたのと同じキャッシュ形式を出力します。
past_key_valuesを使用する場合、すべてのinput_ids（形状(batch_size, sequence_length)）ではなく、このモデルに過去のキー・バリュー状態が与えられていない未処理のinput_ids（形状(batch_size, unprocessed_length)）のみを入力することになります。 - token_type_ids (
torch.LongTensorの形状(batch_size, sequence_length), 、任意) — 入力テキストの第1部分と第2部分を区別するためのセグメントトークンインデックス。インデックスは[0, 1]:- 0 は sentence A トークンに対応します。
- 1 は sentence B トークンに対応します。
- inputs_embeds (
torch.FloatTensor、形状(batch_size, sequence_length, hidden_size)、任意) —input_idsを渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込みルックアップ行列よりも、input_idsのインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。 - labels (
torch.LongTensor、shape(batch_size,)、任意) — 画像分類/回帰の損失を計算するためのラベル。インデックスは[0, ..., config.num_labels - 1]の範囲である必要があります。config.num_labels == 1の場合は回帰損失(平均二乗誤差)が計算され、config.num_labels > 1の場合は分類損失(クロスエントロピー)が計算されます。 - use_cache (
bool、任意) —Trueに設定すると、past_key_valuesのキーバリュー状態が返され、デコーディングの高速化に利用できます（past_key_valuesを参照）。 - output_attentions (
bool, 省略可) — すべてのアテンション層のアテンションテンソルを返すかどうかを指定します。詳細は、返されるテンソルのattentionsを参照してください。 - output_hidden_states (
bool, 省略可) — すべての層の hidden states を返すかどうかを指定します。詳細は、返されるテンソルのhidden_statesを参照してください。 - return_dict (
bool, 任意) — プレーンなタプルではなく ModelOutput を返すかどうか。 - logits_to_keep (
Union[int, torch.Tensor]、省略可、デフォルトは0) —intの場合、最後のlogits_to_keepトークンについて logits を計算します。0の場合、すべてのinput_idsについて logits を計算します（特殊ケース）。生成には最後のトークンの logits だけで十分であり、そのトークンのみについて計算することでメモリを節約できます。これは、長いシーケンスや大規模な語彙サイズの場合に特に顕著な効果があります。torch.Tensorの場合、シーケンス長次元で保持するインデックスに対応する 1 次元テンソルである必要があります。これは、パックされたテンソル形式（バッチとシーケンス長を単一の次元にまとめた形式）を使用する場合に有用です。
ShieldGemma2ForImageClassification の forward メソッドは、__call__ という特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。