Hugging Face's logo

Transformers documentation

ShieldGemma 2

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).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Este modelo se publicó en HF papers el 2025-04-01 y se contribuyó a Hugging Face Transformers el 2025-03-20.

FlashAttention SDPA

ShieldGemma 2

Resumen

El modelo ShieldGemma 2 se propuso en un informe técnico de Google. ShieldGemma 2, construido sobre Gemma 3, es un modelo de 4 mil millones (4B) de parámetros que verifica la seguridad de imágenes tanto sintéticas como naturales frente a categorías clave para ayudarte a construir conjuntos de datos y modelos robustos. Con esta adición a la familia de modelos Gemma, los investigadores y desarrolladores ahora pueden minimizar fácilmente el riesgo de contenido dañino en sus modelos en las principales áreas de daño, definidas a continuación:

  • Contenido sexualmente explícito: La imagen no debe contener contenido que represente actos sexuales explícitos o gráficos (p. ej., pornografía, desnudez erótica, representaciones de violación o agresión sexual).
  • Contenido no peligroso: La imagen no debe contener contenido que facilite o anime actividades que puedan causar daños en el mundo real (p. ej., fabricación de armas de fuego y dispositivos explosivos, promoción del terrorismo, instrucciones para el suicidio).
  • Contenido sin violencia/sangriento: La imagen no debe contener contenido que represente violencia impactante, sensacionalista o gratuita (p. ej., sangre y vísceras excesivas, violencia gratuita contra animales, lesiones extremas o momento de la muerte).

Recomendamos usar ShieldGemma 2 como filtro de entrada para modelos de visión y lenguaje, o como filtro de salida de sistemas de generación de imágenes. Para entrenar un modelo de seguridad de imágenes robusto, curamos conjuntos de datos de entrenamiento de imágenes naturales y sintéticas y ajustamos Gemma 3 con instrucciones para demostrar un rendimiento sólido.

Este modelo fue aportado por Ryan Mullins.

Ejemplo de uso

  • ShieldGemma 2 proporciona un Processor que acepta una lista de images y una lista opcional de policies como entrada, y construye un lote de prompts como el producto de estas dos listas utilizando la plantilla de chat proporcionada.
  • Puede extender las políticas integradas de ShieldGemma con el argumento custom_policies del Processor. Si utiliza la misma clave que una de las políticas integradas, esa política se sobrescribirá con su definición personalizada.
  • ShieldGemma 2 no admite las funciones de recorte de imágenes utilizadas por Gemma 3.

Clasificación frente a políticas integradas

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)

Clasificación frente a políticas personalizadas

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

clase transformers.ShieldGemma2Processor

< >

( image_processortokenizerchat_template = Noneimage_seq_length = 256policy_definitions = None**kwargs )

__call__

< >

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

Parámetros

  • images — Una sola imagen o una lista de imágenes para incluir en el lote.
  • text — No compatible.
  • videos — No compatible.
  • audio — No compatible.
  • kwargs — Un diccionario opcional de argumentos de palabra clave para configurar el procesador. Los valores posibles incluyen:
    • custom_policies: Definiciones de política adicionales que complementan las self.policy_definitions pasadas al constructor. Tenga en cuenta que las custom_policies que comparten una clave con self.policy_definitions reemplazarán la descripción de la política.
    • policies: (Opcional) una lista de claves del diccionario conjunto self.policy_definitions | custom_policies de interés específico para las imágenes proporcionadas. Si está vacío o es None, se generarán prompts para cada clave del diccionario conjunto.

Genera un lote de entradas a partir de las imágenes proporcionadas.

ShieldGemma se entrenó para clasificar el contenido de imágenes en función del cumplimiento de políticas, utilizando una construcción de prompt específica. Este procesador genera un lote de estos prompts a partir de las imágenes proporcionadas mediante:

  1. Crear una lista de conversaciones, una para cada par <image, policy>;
  2. Convertir estas conversaciones a texto usando self.apply_chat_template(); y
  3. Codificación de las conversaciones y las imágenes utilizando las mismas técnicas que Gemma3Processor.

ShieldGemma2Config

clase transformers.ShieldGemma2Config

< >

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

Parámetros

  • text_config (Union[dict, ~configuration_utils.PreTrainedConfig], opcional) — El objeto de configuración o el diccionario del backbone de texto.
  • vision_config (Union[dict, ~configuration_utils.PreTrainedConfig], opcional) — El objeto de configuración o el diccionario del backbone de visión.
  • mm_tokens_per_image (int, opcional, valor predeterminado 256) — El número de tokens por incrustación de imagen.
  • boi_token_index (int, opcional, valor predeterminado 255999) — El índice del token de inicio de imagen para envolver el prompt de imagen.
  • eoi_token_index (int, opcional, valor predeterminado 256000) — El índice del token de fin de imagen para envolver el prompt de imagen.
  • image_token_index (int, opcional, valor predeterminado 262144) — El índice del token de imagen utilizado como marcador de posición para las imágenes de entrada.
  • initializer_range (float, opcional, valor predeterminado 0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos.
  • tie_word_embeddings (bool, opcional) — Si se deben vincular las incrustaciones de palabras. Si no se establece, el valor predeterminado es el de text_config.tie_word_embeddings.

Esta es la clase de configuración para almacenar la configuración de un Shieldgemma2Model. Se utiliza para instanciar un modelo Shieldgemma2 según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de google/shieldgemma-2-4b-it

Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.

Ejemplo:

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

clase transformers.ShieldGemma2ForImageClassification

< >

( config: ShieldGemma2Config )

Parámetros

  • config (ShieldGemma2Config) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.

El modelo Shieldgemma2 con una cabeza de clasificación de imágenes en la parte superior, por ejemplo, para ImageNet.

Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).

Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.

forward

< >

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

Parámetros

  • input_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices de los tokens de la secuencia de entrada en el vocabulario. El relleno se ignorará de forma predeterminada.

    Los índices se pueden obtener usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() y PreTrainedTokenizer.call() para más detalles.

    ¿Qué son los IDs de entrada?

  • pixel_values (torch.FloatTensor de forma (batch_size, num_channels, image_size, image_size), opcional) — Los tensores correspondientes a las imágenes de entrada. Los valores de píxeles se pueden obtener utilizando image_processor_class. Consulte image_processor_class.__call__ para más detalles (processor_class utiliza image_processor_class para procesar las imágenes).
  • attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en los índices de tokens de relleno. Valores de máscara seleccionados en [0, 1]:
    • 1 para los tokens que no están enmascarados,
    • 0 para los tokens que están enmascarados.

    ¿Qué son las máscaras de atención?

  • position_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices de las posiciones de los tokens de cada secuencia de entrada en los embeddings de posición. Seleccionados en el rango [0, config.n_positions - 1].

    ¿Qué son los IDs de posición?

  • past_key_values (~cache_utils.Cache, opcional) — Estados ocultos precalculados (claves y valores en los bloques de autoatención y en los bloques de atención cruzada) que se pueden usar para acelerar la decodificación secuencial. Esto generalmente consiste en la past_key_values devuelta por el modelo en una etapa anterior de la decodificación, cuando use_cache=True o config.use_cache=True.

    Solo se permite una instancia de Cache como entrada, consulte nuestra guía de caché kv. Si no se pasan past_key_values, DynamicCache se inicializará de forma predeterminada.

    El modelo generará el mismo formato de caché que se proporciona como entrada.

    Si se utilizan past_key_values, se espera que el usuario introduzca únicamente los input_ids no procesados (aquellos que no tienen sus estados de clave y valor pasados proporcionados a este modelo) con forma (batch_size, unprocessed_length) en lugar de todos los input_ids con forma (batch_size, sequence_length).

  • token_type_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices de tokens de segmento para indicar las primeras y segundas partes de las entradas. Los índices se seleccionan en [0, 1]:
    • 0 corresponde a un token de sentence A,
    • 1 corresponde a un token de sentence B.

    ¿Qué son los IDs de tipo de token?

  • inputs_embeds (torch.FloatTensor de forma (batch_size, sequence_length, hidden_size), opcional) — Opcionalmente, en lugar de pasar input_ids, puedes elegir pasar directamente una representación incrustada. Esto es útil si deseas tener más control sobre cómo convertir los índices de input_ids en los vectores asociados que en la matriz de búsqueda de incrustaciones interna del modelo.
  • labels (torch.LongTensor de forma (batch_size,), opcional) — Etiquetas para calcular la pérdida de clasificación/regresión de imágenes. Los índices deben estar en [0, ..., config.num_labels - 1]. Si config.num_labels == 1 se calcula una pérdida de regresión (pérdida de error cuadrático medio), si config.num_labels > 1 se calcula una pérdida de clasificación (entropía cruzada).
  • use_cache (bool, opcional) — Si se establece en True, se devuelven los estados de clave-valor de past_key_values y pueden usarse para acelerar la decodificación (ver past_key_values).
  • output_attentions (bool, opcional) — Indica si se deben devolver los tensores de atención de todas las capas de atención. Consulte attentions en los tensores devueltos para obtener más detalles.
  • output_hidden_states (bool, opcional) — Indica si se deben devolver los estados ocultos de todas las capas. Consulte hidden_states en los tensores devueltos para obtener más detalles.
  • return_dict (bool, opcional) — Indica si se debe devolver un ModelOutput en lugar de una tupla simple.
  • logits_to_keep (Union[int, torch.Tensor], opcional, valor predeterminado 0) — Si es un int, calcula los logits para los últimos logits_to_keep tokens. Si es 0, calcula los logits para todos los input_ids (caso especial). Solo se necesitan los logits del último token para la generación, y calcularlos solo para ese token puede ahorrar memoria, lo cual se vuelve bastante significativo para secuencias largas o un tamaño de vocabulario grande. Si es un torch.Tensor, debe ser de 1D y corresponder a los índices a conservar en la dimensión de longitud de secuencia. Esto es útil al usar el formato de tensor empaquetado (una sola dimensión para el lote y la longitud de secuencia).

El método forward de ShieldGemma2ForImageClassification sobrescribe el método especial __call__.

Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de Module después en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.

Update on GitHub

←SAM3-LiteText SigLIP→