# ShieldGemma 2

## Resumen

El modelo ShieldGemma 2 se propuso en un [informe técnico](https://huggingface.co/papers/2504.01081) de Google. ShieldGemma 2, construido sobre [Gemma 3](https://ai.google.dev/gemma/docs/core/model_card_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](https://huggingface.co/RyanMullins).

## 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.
- Puedes extender las políticas integradas de ShieldGemma con el argumento `custom_policies` del Processor. Si usas la misma clave que una de las políticas integradas, esa política se sobrescribirá con tu 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

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

### Clasificación frente a políticas personalizadas

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

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

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

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

**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íticas 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.

**Devuelve:**

Un `BatchFeature` que contiene `input_ids`, `pixel_values`, etc., donde cada Tensor tiene la forma `(len(images) * len(policies), )`, y el orden dentro del lote será img1_policy1, ... img1_policyN, ... imgM_policyN.

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 prompts específica. Este procesador genera un lote de dichos 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[[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)
```

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

**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 de 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 de truncated_normal_initializer para inicializar todas las matrices de pesos.

tie_word_embeddings (`bool`, *opcional*) : Indica 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](https://huggingface.co/google/shieldgemma-2-4b-it)

Los objetos de configuración heredan de [PreTrainedConfig](/docs/transformers/main/es/main_classes/configuration#transformers.PreTrainedConfig) y se pueden utilizar para controlar las salidas del modelo. Consulte la documentación de [PreTrainedConfig](/docs/transformers/main/es/main_classes/configuration#transformers.PreTrainedConfig) para obtener más información.

Ejemplo:

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

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

**Parámetros:**

config ([ShieldGemma2Config](/docs/transformers/main/es/model_doc/shieldgemma2#transformers.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()](/docs/transformers/main/es/main_classes/model#transformers.PreTrainedModel.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](/docs/transformers/main/es/main_classes/model#transformers.PreTrainedModel). Consulte 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](https://pytorch.org/docs/stable/nn.html#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[[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)
```

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

**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 mediante [AutoTokenizer](/docs/transformers/main/es/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/es/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) y [PreTrainedTokenizer.__call__()](/docs/transformers/main/es/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para obtener más detalles. [¿Qué son los IDs de entrada?](../glossary#input-ids)

pixel_values (`torch.Tensor` 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 usando `image_processor_class`. Consulte `image_processor_class.__call__` para obtener 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 la máscara seleccionados en `[0, 1]`:  - 1 para tokens que **no están enmascarados**, - 0 para tokens que **están enmascarados**.  [¿Qué son las máscaras de atención?](../glossary#attention-mask)

position_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices de las posiciones de los tokens de cada secuencia de entrada en las incrustaciones de posición. Seleccionados en el rango `[0, config.n_positions - 1]`.  [¿Qué son los IDs de posición?](../glossary#position-ids)

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 utilizar para acelerar la decodificación secuencial. Esto suele consistir en los `past_key_values` devueltos 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](/docs/transformers/main/es/internal/generation_utils#transformers.Cache) como entrada, consulte nuestra [guía de caché kv](https://huggingface.co/docs/transformers/en/kv_cache). Si no se pasan `past_key_values`, se inicializará [DynamicCache](/docs/transformers/main/es/internal/generation_utils#transformers.DynamicCache) de forma predeterminada.  El modelo devolverá el mismo formato de caché que se haya proporcionado como entrada.  Si se utilizan `past_key_values`, se espera que el usuario introduzca solo los `input_ids` no procesados (aquellos que no tienen sus estados de clave y valor previos dados 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 *oración A*, - 1 corresponde a un token de *oración B*.  [¿Qué son los IDs de tipo de token?](../glossary#token-type-ids)

inputs_embeds (`torch.Tensor` 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 imagen. 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 valores clave `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](/docs/transformers/main/es/main_classes/output#transformers.utils.ModelOutput) en lugar de una tupla simple.

logits_to_keep (`Union[int, torch.Tensor]`, *opcional*, valor predeterminado `0`) : Si es un `int`, se calculan los logits para los últimos `logits_to_keep` tokens. Si es `0`, se calculan los logits para todos los `input_ids` (caso especial). Solo se necesitan los logits del último token para la generación, y calcularlos únicamente 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).

**Devuelve:**

Una instancia de `ShieldGemma2ImageClassifierOutputWithNoAttention` que contiene los logits y las probabilidades asociadas con la predicción del modelo del token `Yes` o `No` como respuesta a ese prompt, capturados en las siguientes propiedades.

*   `logits` (`torch.Tensor` de forma `(batch_size, 2)`): La primera posición a lo largo de dim=1 corresponde a los logits del token `Yes` y la segunda posición a lo largo de dim=1 corresponde a los logits del token `No`.
*   `probabilities` (`torch.Tensor` de forma `(batch_size, 2)`): la primera posición a lo largo de dim=1 es la probabilidad de predecir el token `Yes` y la segunda posición a lo largo de dim=1 es la probabilidad de predecir el token `No`.

Los prompts de ShieldGemma se construyen de tal manera que predecir el token `Yes` significa que el contenido *viola* la política descrita. Si solo le interesa la condición de violación, use `violated = outputs.probabilities[:, 1]` para extraer esa porción de los tensores de salida.

Cuando se usa con `ShieldGemma2Processor`, `batch_size` será igual a `len(images) * len(policies)`, y el orden dentro del lote será img1_policy1, ... img1_policyN, ... imgM_policyN.

El método forward de [ShieldGemma2ForImageClassification](/docs/transformers/main/es/model_doc/shieldgemma2#transformers.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 preprocesamiento y posprocesamiento, mientras que la segunda los ignora silenciosamente.