# ShieldGemma 2

## 概要

ShieldGemma 2 モデルは、Google による[技術レポート](https://huggingface.co/papers/2504.01081)で提案されました。[Gemma 3](https://ai.google.dev/gemma/docs/core/model_card_3)を基盤とする ShieldGemma 2 は、40 億（4B）パラメータのモデルであり、合成画像と自然画像の両方について主要なカテゴリに対する安全性を確認することで、堅牢なデータセットやモデルの構築を支援します。Gemma モデルファミリーへのこの追加により、研究者や開発者は、以下で定義される主要な有害性領域において、モデル内の有害コンテンツのリスクを簡単に最小限に抑えることができます。

- 性的に露骨なコンテンツなし: 画像には、露骨または詳細な性的行為（例: ポルノ、エロティックな裸体、レイプや性的暴行の描写）を描くコンテンツを含んではなりません。
- 危険なコンテンツなし: 画像には、現実世界での危害を引き起こす可能性のある活動を助長または奨励するコンテンツ（例: 銃器や爆発物の製造、テロリズムの宣伝、自殺の手引き）を含んではなりません。
- 暴力・グロテスクなコンテンツの禁止: 画像には、衝撃的・センセーショナル・無意味な暴力（例: 過度な血やグロテスクな描写、動物に対する無意味な暴力、極端な負傷や死の瞬間）を描くコンテンツを含んではなりません。

ビジョン言語モデルの入力フィルタ、または画像生成システムの出力フィルタとして、ShieldGemma 2 の使用を推奨します。堅牢な画像安全性モデルを訓練するために、自然画像と合成画像からなる訓練データセットをキュレーションし、Gemma 3 を指示チューニングすることで、優れたパフォーマンスを実証しました。

このモデルは、[Ryan Mullins](https://huggingface.co/RyanMullins) によって提供されました。

## 使用例

- ShieldGemma 2 は、`images` のリストと任意の `policies` のリストを受け取り、提供されたチャットテンプレートを使用して、これら 2 つのリストの積からプロンプトのバッチを構築する Processor を提供します。
- Processor の `custom_policies` 引数を使用して、ShieldGemma の組み込みポリシーを拡張できます。組み込みポリシーと同じキーを使用すると、そのポリシーがカスタム定義で上書きされます。
- ShieldGemma 2 は、Gemma 3 で使用されている画像クロッピング機能をサポートしていません。

### 組み込みポリシーとの分類

```python
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)
```

### カスタムポリシーに対する分類

```python
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[[transformers.ShieldGemma2Processor]]

#### transformers.ShieldGemma2Processor[[transformers.ShieldGemma2Processor]]

```python
transformers.ShieldGemma2Processor(image_processor, tokenizer, chat_template = None, image_seq_length = 256, policy_definitions = None, **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/shieldgemma2/processing_shieldgemma2.py#L60)

#### __call__[[transformers.ShieldGemma2Processor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, text = None, **kwargs: *<class 'transformers.models.shieldgemma2.processing_shieldgemma2.ShieldGemma2ProcessorKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/shieldgemma2/processing_shieldgemma2.py#L84)

**パラメータ:**

images : バッチに含める単一の画像または画像のリスト。

text : 非対応。

videos : 非対応。

audio : 非対応。

kwargs : プロセッサを設定するためのキーワード引数の任意の辞書。可能な値には以下が含まれます: * `custom_policies`: コンストラクタに渡される`self.policy_definitions`を補完する追加のポリシー定義。`custom_policies`が`self.policy_definitions`とキーを共有する場合、ポリシーの説明を上書きします * `policies`: (任意) 提供された画像に対して特に興味がある、`self.policy_definitions | custom_policies`の結合辞書内のキーのリスト。空またはNoneの場合、結合辞書のすべてのキーに対してプロンプトが生成されます。

**戻り値:**

`BatchFeature` を含む。これは `input_ids`、`pixel_values` などを保持し、各 Tensor の形状は `(len(images) * len(policies), )` である。バッチ内の順序は img1_policy1、... img1_policyN、... imgM_policyN となる。

提供された画像から入力バッチを生成します。

ShieldGemmaは、特定のプロンプト構造を用いてポリシー遵守のための画像コンテンツ分類に学習されています。このプロセッサは、提供された画像から、次の方法でそのようなプロンプトのバッチを生成します。

1.  `<image, policy>`ペアごとに1つずつ、会話のリストを作成します;
2.  `self.apply_chat_template()` を使用してこれらの会話をテキストに変換し、
3.  `Gemma3Processor` と同じ手法を使用して、会話と画像をエンコードします。

## ShieldGemma2Config[[transformers.ShieldGemma2Config]]

#### transformers.ShieldGemma2Config[[transformers.ShieldGemma2Config]]

```python
transformers.ShieldGemma2Config(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, text_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, mm_tokens_per_image: int = 256, boi_token_index: int = 255999, eoi_token_index: int = 256000, image_token_index: int = 262144, initializer_range: float = 0.02, tie_word_embeddings: bool = False)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/shieldgemma2/configuration_shieldgemma2.py#L26)

**パラメータ:**

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *任意*) : テキストバックボーンの config オブジェクトまたは辞書。

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *任意*) : ビジョンバックボーンの config オブジェクトまたは辞書。

mm_tokens_per_image (`int`、*任意*、デフォルトは 256) : 1 つの画像埋め込みあたりのトークン数。

boi_token_index (`int`、*optional*、デフォルトは 255999) : 画像プロンプトをラップするための begin-of-image トークンのインデックスです。

eoi_token_index (`int`、*optional*、デフォルトは 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](https://huggingface.co/google/shieldgemma-2-4b-it) と同様の設定が得られます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) のドキュメントを参照してください。

例:

```python
>>> 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.config
```

## ShieldGemma2ForImageClassification[[transformers.ShieldGemma2ForImageClassification]]

#### transformers.ShieldGemma2ForImageClassification[[transformers.ShieldGemma2ForImageClassification]]

```python
transformers.ShieldGemma2ForImageClassification(config: ShieldGemma2Config)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/shieldgemma2/modeling_shieldgemma2.py#L44)

**パラメータ:**

config ([ShieldGemma2Config](/docs/transformers/main/ja/model_doc/shieldgemma2#transformers.ShieldGemma2Config)) : モデルのすべてのパラメータを含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを確認してください。

ImageNet などの用途で、画像分類ヘッドを上部に備えた Shieldgemma2 モデル。

このモデルは [PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel) を継承しています。ライブラリがすべてのモデルに対して実装している汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchの[torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)のサブクラスでもあります。通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

#### forward[[transformers.ShieldGemma2ForImageClassification.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, pixel_values: typing.Optional[torch.FloatTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, token_type_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.FloatTensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, return_dict: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/shieldgemma2/modeling_shieldgemma2.py#L72)

**パラメータ:**

input_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 語彙における入力シーケンスのトークンインデックスです。デフォルトでは、パディングは無視されます。インデックスは [AutoTokenizer](/docs/transformers/main/ja/model_doc/auto#transformers.AutoTokenizer) を使用して取得できます。詳細については、[PreTrainedTokenizer.encode()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) および [PreTrainedTokenizer.__call__()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) を参照してください。 [入力IDとは何ですか？](../glossary#input-ids)

pixel_values (`torch.FloatTensor`、shape `(batch_size, num_channels, image_size, image_size)`、*optional*) : 入力画像に対応するテンソルです。ピクセル値は `image_processor_class` を使用して取得できます。詳細は `image_processor_class.__call__` を参照してください（`processor_class` は画像の処理に `image_processor_class` を使用します）。

attention_mask (`torch.Tensor`、shape `(batch_size, sequence_length)`、*任意*) : padding トークンのインデックスに対する attention を回避するためのマスクです。マスクの値は `[0, 1]` から選択されます:  - **マスクされない**トークンは 1、- **マスクされる**トークンは 0。  [attention マスクとは?](../glossary#attention-mask)

position_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 各入力シーケンスのトークンが位置埋め込み内で占める位置のインデックスです。`[0, config.n_positions - 1]` の範囲から選択されます。 [位置 ID とは何か？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *任意*) : 逐次デコードを高速化するために使用できる、事前計算された hidden-states（self-attention ブロックおよび cross-attention ブロック内の key と value）です。通常、`use_cache=True` または `config.use_cache=True` の場合、モデルがデコードの以前の段階で返した `past_key_values` で構成されます。入力として許可されるのは [Cache](/docs/transformers/main/ja/internal/generation_utils#transformers.Cache) インスタンスのみです。[kv cache ガイド](https://huggingface.co/docs/transformers/en/kv_cache)を参照してください。`past_key_values` が渡されない場合、デフォルトで [DynamicCache](/docs/transformers/main/ja/internal/generation_utils#transformers.DynamicCache) が初期化されます。モデルは、入力として与えられたのと同じキャッシュ形式を出力します。`past_key_values` を使用する場合は、すべての `input_ids`（形状 `(batch_size, sequence_length)`）の代わりに、このモデルに過去の key value 状態が与えられていない未処理の `input_ids`（形状 `(batch_size, unprocessed_length)`）のみを入力する必要があります。

token_type_ids (`torch.LongTensor`、形状 `(batch_size, sequence_length)`、*任意*) : 入力の前半と後半を示すセグメントトークンインデックス。インデックスは `[0, 1]` から選択されます:  - 0 は *文 A* のトークンに対応します。 - 1 は *文 B* のトークンに対応します。  [トークンタイプIDとは何ですか？](../glossary#token-type-ids)

inputs_embeds (`torch.FloatTensor`、shape `(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` の場合は回帰損失（Mean-Square loss）が計算され、`config.num_labels > 1` の場合は分類損失（Cross-Entropy）が計算されます。

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](/docs/transformers/main/ja/main_classes/output#transformers.utils.ModelOutput) を返すかどうか。

logits_to_keep (`Union[int, torch.Tensor]`、*任意*、デフォルトは `0`) : `int` の場合、最後の `logits_to_keep` トークンについて logits を計算します。`0` の場合、すべての `input_ids` について logits を計算します（特殊ケース）。生成には最後のトークンの logits だけで十分であり、そのトークンのみについて計算することでメモリを節約できます。これは、長いシーケンスや大規模な語彙サイズの場合に特に顕著な効果があります。`torch.Tensor` の場合、シーケンス長次元で保持するインデックスに対応する 1 次元である必要があります。これは、パックされたテンソル形式（バッチとシーケンス長を単一の次元にまとめる形式）を使用する場合に有用です。

**戻り値:**

`ShieldGemma2ImageClassifierOutputWithNoAttention` のインスタンスで、そのプロンプトに対する応答として `Yes` または `No` トークンを予測するモデルに関連する logits および確率を、以下のプロパティに格納しています。

*   `logits` (`torch.Tensor`、shape `(batch_size, 2)`): dim=1 における最初の位置は`Yes`トークンの logits、2 番目の位置は`No`トークンの logits です。
*   `probabilities` (`torch.Tensor`、shape `(batch_size, 2)`): dim=1 方向の最初の位置は`Yes`トークンを予測する確率、dim=1 方向の2番目の位置は`No`トークンを予測する確率です。

ShieldGemmaのプロンプトは、`Yes`トークンを予測すると、そのコンテンツがポリシーに*違反している*ことを意味するように構築されています。違反条件のみに関心がある場合は、`violated = outputs.probabilities[:, 1]`を使用して、出力テンソルからそのスライスを抽出してください。

`ShieldGemma2Processor`と組み合わせて使用する場合、`batch_size`は`len(images) * len(policies)`に等しくなり、バッチ内の順序は img1_policy1, ... img1_policyN, ... imgM_policyN となります。

[ShieldGemma2ForImageClassification](/docs/transformers/main/ja/model_doc/shieldgemma2#transformers.ShieldGemma2ForImageClassification) の forward メソッドは、`__call__` という特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。