# ShieldGemma 2

## Aperçu

Le modèle ShieldGemma 2 a été présenté dans un [rapport technique](https://huggingface.co/papers/2504.01081) par Google. ShieldGemma 2, construit sur [Gemma 3](https://ai.google.dev/gemma/docs/core/model_card_3), est un modèle de 4 milliards (4B) de paramètres qui vérifie la sécurité des images synthétiques et naturelles par rapport à des catégories clés, afin de vous aider à construire des jeux de données et des modèles robustes. Grâce à l'ajout de ce modèle à la famille Gemma, les chercheurs et les développeurs peuvent désormais minimiser facilement le risque de contenu nuisible dans leurs modèles dans les domaines de préjudice clés définis ci-dessous :

- Aucun contenu sexuellement explicite : l’image ne doit pas contenir de contenu représentant des actes sexuels explicites ou graphiques (par exemple, la pornographie, la nudité érotique, les représentations de viol ou d’agression sexuelle).
- Aucun contenu dangereux : l'image ne doit pas contenir de contenu facilitant ou encourageant des activités susceptibles de causer des dommages dans le monde réel (par exemple, la fabrication d'armes à feu et de dispositifs explosifs, la promotion du terrorisme, des instructions pour le suicide).
- Aucun contenu violent ou gore : l'image ne doit pas contenir de contenu représentant une violence choquante, sensationnaliste ou gratuite (par exemple, du sang et des blessures excessifs, une violence gratuite envers les animaux, des blessures extrêmes ou un moment de décès).

Nous recommandons d’utiliser ShieldGemma 2 comme filtre d’entrée pour les modèles de vision-langage, ou comme filtre de sortie pour les systèmes de génération d’images. Pour entraîner un modèle de sécurité d’images robuste, nous avons constitué des jeux de données d’entraînement composés d’images naturelles et synthétiques, et nous avons effectué un ajustement par instructions de Gemma 3 afin de démontrer de solides performances.

Ce modèle a été contribué par [Ryan Mullins](https://huggingface.co/RyanMullins).

## Exemple d'utilisation

- ShieldGemma 2 fournit un Processor qui accepte en entrée une liste de `images` et une liste facultative de `policies`, et construit un lot de prompts à partir du produit de ces deux listes en utilisant le modèle de conversation fourni.
- Vous pouvez étendre les politiques intégrées de ShieldGemma à l'aide de l'argument `custom_policies` du Processor. L'utilisation de la même clé que l'une des politiques intégrées remplace cette politique par votre définition personnalisée.
- ShieldGemma 2 ne prend pas en charge les fonctionnalités de recadrage d’images utilisées par Gemma 3.

### Classification par rapport aux politiques intégrées

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

### Classification par rapport à des politiques personnalisées

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

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

#### __appel__[[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'>)
```

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

**Paramètres :**

images : Une image unique ou une liste d'images à inclure dans le lot.

text : Non pris en charge.

videos : Non pris en charge.

audio : Non pris en charge.

kwargs : Dictionnaire facultatif d'arguments par mot-clé pour configurer le processeur. Les valeurs possibles incluent :  *   `custom_policies` : Définitions de politiques supplémentaires qui complètent `self.policy_definitions` passées au constructeur. Notez que les `custom_policies` partageant une clé avec `self.policy_definitions` remplaceront la description de la politique *   `policies` : (Facultatif) une liste de clés du dictionnaire conjoint `self.policy_definitions | custom_policies` d'un intérêt particulier pour les images fournies. S'il est vide ou None, des invites seront générées pour chaque clé du dictionnaire conjoint.

**Retourne :**

Un `BatchFeature` contenant `input_ids`, `pixel_values`, etc., où chaque Tensor a la forme `(len(images) * len(policies), )`, et l'ordre au sein du lot sera img1_policy1, ... img1_policyN, ... imgM_policyN.

Génère un lot d'entrées à partir des images fournies.

ShieldGemma a été entraîné à classifier le contenu des images en matière de conformité aux politiques à l’aide d’une construction de prompt spécifique. Ce processeur génère un lot de tels prompts à partir des images fournies en :

1.  Créer une liste de conversations, une pour chaque paire `<image, policy>` ;
2.  Convertir ces conversations en texte à l'aide de `self.apply_chat_template()` ; et
3.  Encodage des conversations et des images à l'aide des mêmes techniques que `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)
```

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

**Paramètres :**

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *facultatif*) : L'objet de configuration ou le dictionnaire du backbone de texte.

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *facultatif*) : L'objet de configuration ou le dictionnaire du backbone visuel.

mm_tokens_per_image (`int`, *facultatif*, valeur par défaut 256) : Le nombre de jetons par intégration d'image.

boi_token_index (`int`, *facultatif*, valeur par défaut 255999) : L'index du jeton de début d'image à utiliser pour encadrer le prompt d'image.

eoi_token_index (`int`, *facultatif*, valeur par défaut 256000) : L'index du jeton de fin d'image utilisé pour encadrer le prompt d'image.

image_token_index (`int`, *facultatif*, valeur par défaut `262144`) : L'index du jeton d'image utilisé comme espace réservé pour les images d'entrée.

initializer_range (`float`, *facultatif*, valeur par défaut `0.02`) : L'écart-type de la truncated_normal_initializer utilisé pour l'initialisation de toutes les matrices de poids.

tie_word_embeddings (`bool`, *facultatif*) : Indique s'il faut lier les embeddings de mots. Par défaut, prend la valeur de `text_config.tie_word_embeddings` si non défini.

Il s’agit de la classe de configuration destinée à stocker la configuration d’un Shieldgemma2Model. Elle est utilisée pour instancier un modèle Shieldgemma2 en fonction des arguments spécifiés, en définissant l’architecture du modèle. L’instanciation d’une configuration avec les valeurs par défaut produira une configuration similaire à celle de [google/shieldgemma-2-4b-it](https://huggingface.co/google/shieldgemma-2-4b-it)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/main/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/main/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

Exemple :

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

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

**Paramètres :**

config ([ShieldGemma2Config](/docs/transformers/main/fr/model_doc/shieldgemma2#transformers.ShieldGemma2Config)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/main/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Le modèle Shieldgemma2 avec une tête de classification d'images au sommet, par exemple pour ImageNet.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/main/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

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

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, pixel_values: typing.Optional[torch.Tensor] = 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.Tensor] = 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)
```

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

**Paramètres :**

input_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/main/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Que sont les identifiants d'entrée ?](../glossary#input-ids)

pixel_values (`torch.Tensor` de forme `(batch_size, num_channels, image_size, image_size)`, *facultatif*) : Les tenseurs correspondant aux images d'entrée. Les valeurs des pixels peuvent être obtenues à l'aide de `image_processor_class`. Voir `image_processor_class.__call__` pour plus de détails (`processor_class` utilise `image_processor_class` pour le traitement des images).

attention_mask (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans `[0, 1]` : - 1 pour les jetons qui ne sont **pas masqués**, - 0 pour les jetons qui sont **masqués**. [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask)

position_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des positions des jetons de chaque séquence d'entrée dans les embeddings de position. Sélectionnés dans l'intervalle `[0, config.n_positions - 1]`.  [Que sont les identifiants de position ?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *facultatif*) : États cachés précalculés (clés et valeurs dans les blocs d'auto-attention et dans les blocs d'attention croisée) qui peuvent être utilisés pour accélérer le décodage séquentiel. Il s'agit généralement des `past_key_values` renvoyés par le modèle à une étape antérieure du décodage, lorsque `use_cache=True` ou `config.use_cache=True`.  Seule une instance de [Cache](/docs/transformers/main/fr/internal/generation_utils#transformers.Cache) est autorisée en entrée, voir notre [guide sur le cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Si aucun `past_key_values` n'est transmis, [DynamicCache](/docs/transformers/main/fr/internal/generation_utils#transformers.DynamicCache) est initialisé par défaut.  Le modèle renverra le même format de cache que celui fourni en entrée.  Si `past_key_values` sont utilisés, l'utilisateur doit fournir uniquement les `input_ids` non traités (ceux pour lesquels les états de clés et de valeurs passées ne sont pas fournis à ce modèle) de forme `(batch_size, unprocessed_length)` au lieu de tous les `input_ids` de forme `(batch_size, sequence_length)`.

token_type_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices de jetons de segment indiquant les première et deuxième parties des entrées. Les indices sont sélectionnés dans `[0, 1]` : - 0 correspond à un jeton de *phrase A*, - 1 correspond à un jeton de *phrase B*. [Que sont les identifiants de type de jeton ?](../glossary#token-type-ids)

inputs_embeds (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Cela est utile si vous souhaitez un meilleur contrôle sur la manière de convertir les indices `input_ids` en vecteurs associés, par rapport à la matrice de recherche d'intégration interne du modèle.

labels (`torch.LongTensor` de forme `(batch_size,)`, *facultatif*) : Étiquettes pour le calcul de la perte de classification/régression d'image. Les indices doivent être dans `[0, ..., config.num_labels - 1]`. Si `config.num_labels == 1`, une perte de régression est calculée (perte du carré moyen). Si `config.num_labels > 1`, une perte de classification est calculée (entropie croisée).

use_cache (`bool`, *facultatif*) : Si défini sur `True`, les états clé-valeur de `past_key_values` sont renvoyés et peuvent être utilisés pour accélérer le décodage (voir `past_key_values`).

output_attentions (`bool`, *facultatif*) : Indique s'il faut ou non retourner les tenseurs d'attention de toutes les couches d'attention. Voir `attentions` sous les tenseurs retournés pour plus de détails.

output_hidden_states (`bool`, *facultatif*) : Indique s'il faut retourner les états cachés de toutes les couches. Voir `hidden_states` dans les tenseurs retournés pour plus de détails.

return_dict (`bool`, *facultatif*) : Indique s'il faut retourner un [ModelOutput](/docs/transformers/main/fr/main_classes/output#transformers.utils.ModelOutput) plutôt qu'un simple tuple.

logits_to_keep (`Union[int, torch.Tensor]`, *facultatif*, valeur par défaut `0`) : Si c'est un `int`, calcule les logits pour les `logits_to_keep` derniers jetons. Si c'est `0`, calcule les logits pour tous les `input_ids` (cas particulier). Seuls les logits du dernier jeton sont nécessaires pour la génération, et les calculer uniquement pour ce jeton peut faire économiser de la mémoire, ce qui devient assez significatif pour les séquences longues ou les tailles de vocabulaire importantes. Si c'est un `torch.Tensor`, il doit être 1D et correspondre aux indices à conserver dans la dimension de la longueur de la séquence. C'est utile lors de l'utilisation du format de tenseurs empilés (une seule dimension pour le lot et la longueur de la séquence).

**Retourne :**

Une instance de `ShieldGemma2ImageClassifierOutputWithNoAttention` contenant les logits et les probabilités associés à la prédiction du modèle du jeton `Yes` ou `No` en réponse à ce prompt, capturés dans les propriétés suivantes.

*   `logits` (`torch.Tensor` de forme `(batch_size, 2)`) : la première position le long de dim=1 correspond aux logits du jeton `Yes` et la deuxième position le long de dim=1 correspond aux logits du jeton `No`.
*   `probabilities` (`torch.Tensor` de forme `(batch_size, 2)`) : la première position le long de dim=1 est la probabilité de prédire le jeton `Yes` et la deuxième position le long de dim=1 est la probabilité de prédire le jeton `No`.

Les prompts ShieldGemma sont construits de manière à ce que la prédiction du jeton `Yes` signifie que le contenu *enfreint* la politique décrite. Si vous n'êtes intéressé que par la condition de violation, utilisez `violated = outputs.probabilities[:, 1]` pour extraire cette tranche des tenseurs de sortie.

Lorsqu’il est utilisé avec le `ShieldGemma2Processor`, la valeur de `batch_size` sera égale à `len(images) * len(policies)`, et l’ordre au sein du lot sera img1_policy1, ... img1_policyN, ... imgM_policyN.

La méthode forward de [ShieldGemma2ForImageClassification](/docs/transformers/main/fr/model_doc/shieldgemma2#transformers.ShieldGemma2ForImageClassification) redéfinit la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.