Transformers documentation

ShieldGemma 2

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

Ce modèle a été publié dans les papiers HF le 2025-04-01 et contribué à Hugging Face Transformers le 2025-03-20.

ShieldGemma 2

Aperçu

Le modèle ShieldGemma 2 a été présenté dans un rapport technique par Google. ShieldGemma 2, construit sur Gemma 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.

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

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

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

classe 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'> )

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 les self.policy_definitions transmises au constructeur. Notez que les custom_policies partageant une clé avec self.policy_definitions remplaceront la description de la politique correspondante.
- 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 prompts seront générés pour chaque clé du dictionnaire conjoint.

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

ShieldGemma a été entraîné à classer 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 :

Créer une liste de conversations, une pour chaque paire <image, policy> ;
Convertir ces conversations en texte à l'aide de self.apply_chat_template() ; et
Encodage des conversations et des images à l'aide des mêmes techniques que Gemma3Processor.

ShieldGemma2Config

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

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, 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, 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, par défaut 0.02) — L'écart-type de la truncated_normal_initializer utilisé pour initialiser 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 permettant de 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

Les objets de configuration héritent de PreTrainedConfig et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de PreTrainedConfig pour plus d’informations.

Exemple :

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

classe transformers.ShieldGemma2ForImageClassification

< source >

( config: ShieldGemma2Config )

Paramètres

config (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() 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. 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, la taille des têtes, etc.)

Ce modèle est également une sous-classe de 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

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

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. Consultez PreTrainedTokenizer.encode() et PreTrainedTokenizer.call() pour plus de détails.

Qu'est-ce que les identifiants d'entrée ?
pixel_values (torch.FloatTensor de forme (batch_size, num_channels, image_size, image_size), facultatif) — Les tenseurs correspondant aux images d’entrée. Les valeurs de 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 masqués.
Qu'est-ce que les masques d'attention ?
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].
Qu'est-ce que les identifiants de position ?
past_key_values (~cache_utils.Cache, facultatif) — États cachés précalculés (clés et valeurs dans les blocs d'auto-attention et d'attention croisée) qui peuvent être utilisés pour accélérer le décodage séquentiel. Cela consiste généralement en la past_key_values retournée 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 est autorisée en entrée, consultez notre guide du cache kv. Si aucun past_key_values n'est transmis, DynamicCache sera initialisé par défaut.

Le modèle produira le même format de cache qui est 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 n’ont pas été 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 pour indiquer les première et deuxième parties des entrées. Les indices sont choisis dans [0, 1]:
- 0 correspond à un jeton sentence A,
- 1 correspond à un jeton sentence B.
Qu'est-ce que les identifiants de type de jeton ?
inputs_embeds (torch.FloatTensor 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 que 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 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. Consultez 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 sous les tenseurs retournés pour plus de détails.
return_dict (bool, facultatif) — Indique s'il faut retourner un 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 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 é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. Cela 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).

La méthode forward de 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.

Update on GitHub

←SAM3-LiteText SigLIP→