# ShieldGemma 2

## Обзор

Модель ShieldGemma 2 была представлена в [техническом отчёте](https://huggingface.co/papers/2504.01081) от Google. ShieldGemma 2, построенная на базе [Gemma 3](https://ai.google.dev/gemma/docs/core/model_card_3), — это модель с 4 миллиардами (4B) параметров, которая проверяет безопасность как синтетических, так и естественных изображений по ключевым категориям, помогая создавать надёжные наборы данных и модели. Благодаря добавлению этой модели в семейство Gemma исследователи и разработчики теперь могут легко минимизировать риск вредного контента в своих моделях в ключевых областях, определённых ниже:

- Отсутствие сексуально откровенного контента: изображение не должно содержать контента, изображающего откровенные или натуралистичные сексуальные действия (например, порнографию, эротическую наготу, изображения изнасилования или сексуального насилия).
- Отсутствие опасного контента: изображение не должно содержать контент, способствующий или поощряющий деятельность, которая может привести к реальному ущербу (например, изготовление огнестрельного оружия и взрывных устройств, пропаганда терроризма, инструкции по совершению суицида).
- Отсутствие насилия и сцен с кровью: изображение не должно содержать контента, изображающего шокирующее, сенсационное или беспричинное насилие (например, избыточное количество крови и сцен с кровью, беспричинное насилие над животными, тяжёлые увечья или момент смерти).

Мы рекомендуем использовать ShieldGemma 2 в качестве входного фильтра для мультимодальных моделей (vision language models) или в качестве выходного фильтра для систем генерации изображений. Для обучения надежной модели безопасности изображений мы подготовили обучающие наборы данных, состоящие из естественных и синтетических изображений, и провели instruction-tuning модели Gemma 3, что позволило продемонстрировать высокую эффективность.

Эта модель была предоставлена [Ryan Mullins](https://huggingface.co/RyanMullins).

## Пример использования

- ShieldGemma 2 предоставляет Processor, который принимает на вход список `images` и необязательный список `policies` и формирует пакет промптов как произведение этих двух списков с использованием предоставленного шаблона чата.
- Вы можете расширить встроенные политики ShieldGemma с помощью аргумента `custom_policies` для Processor. Использование того же ключа, что и у одной из встроенных политик, перезапишет её вашим собственным определением.
- 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/v5.23.0/src/transformers/models/shieldgemma2/processing_shieldgemma2.py#L70)

**Параметры:**

image_processor (`Gemma3ImageProcessor`) : процессор изображений является обязательным входным параметром.

tokenizer (`GemmaTokenizer`) : Токенизатор является обязательным входным параметром.

chat_template (`str`) : Шаблон Jinja для преобразования списков сообщений в чате в строку, готовую к токенизации.

image_seq_length (``, defaults to `256`) : The number of image tokens to be used for each image in the input. Added for backward compatibility but this should be set as a processor attribute in future models.

policy_definitions (`Mapping[str, str]`, *необязательный*) : Соответствие между именем политики и её текстовым описанием, используемым в качестве политик по умолчанию для классификации изображений. Описания политик включаются в текст промптов, генерируемых этим процессором. Как правило, этот параметр не задаётся, так как конфигурация процессора на Hugging Face Hub уже содержит базовые политики, на которых обучался ShieldGemma.

Создаёт ShieldGemma2Processor, который объединяет процессор изображений и токенизатор в единый процессор.

[ShieldGemma2Processor](/docs/transformers/v5.23.0/ru/model_doc/shieldgemma2#transformers.ShieldGemma2Processor) предоставляет все возможности [Gemma3ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/gemma3#transformers.Gemma3ImageProcessor) и [GemmaTokenizer](/docs/transformers/v5.23.0/ru/model_doc/gemma#transformers.GemmaTokenizer). Подробнее см. в [~Gemma3ImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/gemma3#transformers.Gemma3ImageProcessor) и [~GemmaTokenizer](/docs/transformers/v5.23.0/ru/model_doc/gemma#transformers.GemmaTokenizer).

#### __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/v5.23.0/src/transformers/models/shieldgemma2/processing_shieldgemma2.py#L109)

**Параметры:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *необязательный*) : Изображение для предварительной обработки. Ожидается одно изображение или пакет изображений со значениями пикселей в диапазоне от 0 до 255. Если передаются изображения со значениями пикселей в диапазоне от 0 до 1, установите `do_rescale=False`.

text (``) : The sequence or batch of sequences to be encoded. Each sequence can be a string or a list of strings (pretokenized string). If you pass a pretokenized input, set `is_split_into_words=True` to avoid ambiguity with batched inputs.

return_mm_token_type_ids (`bool`, *kwargs*) : Нужно ли возвращать идентификаторы типов мультимодальных токенов, указывающие на позиции мультимодальных плейсхолдер-токенов.

return_text_replacement_offsets (`bool`, *kwargs*) : Нужно ли возвращать смещения символов для каждого мультимодального плейсхолдера и его замены.

policies (`list[str]`, *kwargs*, *optional*) : Ключи в объединённом словаре `self.policy_definitions | custom_policies`, представляющие особый интерес для предоставленных изображений. Если `None`, промпты будут сгенерированы для каждого ключа в объединённом словаре.

custom_policies (`dict[str, *kwargs*, str]`, *необязательный*) : Дополнительные определения политик, дополняющие `self.policy_definitions`, переданные в конструктор. Обратите внимание, что `custom_policies`, имеющие общий ключ с `self.policy_definitions`, переопределяют описание политики.

return_tensors (`str` или [TensorType](/docs/transformers/v5.23.0/ru/internal/file_utils#transformers.TensorType), *optional*) : Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:  - `'pt'`: возвращает объекты `torch.Tensor` PyTorch. - `'np'`: возвращает объекты `np.ndarray` NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/v5.23.0/ru/main_classes/processors#transformers.ProcessingKwargs), *optional*) : Дополнительные параметры обработки для каждой модальности (текст, изображения, видео, аудио). Специфичные для модели параметры перечислены выше; полный список поддерживаемых аргументов см. в классе TypedDict.

**Возвращаемое значение:**

`BatchFeature`, содержащий `input_ids`, `pixel_values` и т. д., где каждый Tensor имеет форму `(len(images) * len(policies), )`, а порядок внутри батча будет следующим: img1_policy1, ... img1_policyN, ... imgM_policyN.

Создаёт пакет входных данных из предоставленных изображений.

ShieldGemma обучался классифицировать содержимое изображений на соответствие политикам с использованием специфической конструкции промпта. Этот процессор генерирует пакет таких промптов из предоставленных изображений, выполняя следующие действия:

1. Создание списка диалогов, по одному для каждой пары `<image, policy>`;
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/v5.23.0/src/transformers/models/shieldgemma2/configuration_shieldgemma2.py#L26)

**Параметры:**

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *необязательный*) : Объект конфигурации или словарь текстового бэкбона.

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *необязательный*) : Объект конфигурации или словарь для визуального бэкбона.

mm_tokens_per_image (`int`, *необязательный*, по умолчанию 256) : Количество токенов на вложение изображения.

boi_token_index (`int`, *optional*, по умолчанию 255999) : Индекс токена начала изображения, используемого для обрамления изображения-подсказки.

eoi_token_index (`int`, *optional*, по умолчанию 256000) : Индекс токена конца изображения, используемого для обрамления изображения-подсказки.

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/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/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/v5.23.0/src/transformers/models/shieldgemma2/modeling_shieldgemma2.py#L44)

**Параметры:**

config ([ShieldGemma2Config](/docs/transformers/v5.23.0/ru/model_doc/shieldgemma2#transformers.ShieldGemma2Config)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Shieldgemma2 с головкой для классификации изображений, например, для ImageNet.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

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

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/shieldgemma2/modeling_shieldgemma2.py#L72)

**Параметры:**

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы токенов входной последовательности в словаре. По умолчанию заполнение (padding) игнорируется. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__). [Что такое входные идентификаторы?](../glossary#input-ids)

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`, *необязательный*) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью `image_processor_class`. Подробности см. в `image_processor_class.__call__` (`processor_class` использует `image_processor_class` для обработки изображений).

attention_mask (`torch.Tensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

position_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы позиций токенов каждого входного последовательности в позиционных эмбеддингах. Выбираются из диапазона `[0, config.n_positions - 1]`.  [Что такое position IDs?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *необязательный*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `past_key_values`, возвращаемые моделью на предыдущем этапе декодирования, когда `use_cache=True` или `config.use_cache=True`. В качестве входного значения допускается только экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache), см. наше [руководство по kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Если `past_key_values` не переданы, по умолчанию будет инициализирован [DynamicCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.DynamicCache). Модель будет выводить тот же формат кэша, который был передан на вход. Если используются `past_key_values`, ожидается, что пользователь передаст только необработанные `input_ids` (те, для которых не заданы их прошлые состояния ключей и значений в этой модели) с формой `(batch_size, unprocessed_length)` вместо всех `input_ids` с формой `(batch_size, sequence_length)`.

token_type_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательный*) : Индексы токенов сегментов для указания первой и второй частей входных данных. Индексы выбираются из `[0, 1]`:  - 0 соответствует токену *предложения A*, - 1 соответствует токену *предложения B*.  [Что такое идентификаторы типов токенов?](../glossary#token-type-ids)

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `input_ids` можно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексы `input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

labels (`torch.LongTensor` формы `(batch_size,)`, *необязательный*) : Метки для вычисления потерь классификации/регрессии изображений. Индексы должны находиться в диапазоне `[0, ..., config.num_labels - 1]`. Если `config.num_labels == 1`, вычисляется потеря регрессии (среднеквадратичная потеря), если `config.num_labels > 1`, вычисляется потеря классификации (кросс-энтропия).

use_cache (`bool`, *необязательный*) : Если установлено в `True`, состояния ключей и значений `past_key_values` возвращаются и могут использоваться для ускорения декодирования (см. `past_key_values`).

output_attentions (`bool`, *необязательный*) : Нужно ли возвращать тензоры внимания всех слоев внимания. Подробнее см. `attentions` в разделе возвращаемых тензоров.

output_hidden_states (`bool`, *необязательный*) : Нужно ли возвращать скрытые состояния всех слоёв. Подробнее о `hidden_states` в разделе возвращаемых тензоров.

return_dict (`bool`, *необязательный*) : Нужно ли возвращать [ModelOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.utils.ModelOutput) вместо обычного кортежа.

logits_to_keep (`Union[int, torch.Tensor]`, *необязательный*, по умолчанию `0`) : Если передано значение типа `int`, вычисляются logits для последних `logits_to_keep` токенов. Если передано `0`, logits вычисляются для всех `input_ids` (специальный случай). Для генерации нужны logits только последнего токена, и вычисление их только для этого токена позволяет сэкономить память, что становится весьма значимым для длинных последовательностей или большого размера словаря. Если передано значение типа `torch.Tensor`, оно должно быть одномерным и соответствовать индексам, которые нужно сохранить в измерении длины последовательности. Это полезно при использовании упакованного формата тензоров (одно измерение для batch и длины последовательности).

**Возвращаемое значение:**

Экземпляр `ShieldGemma2ImageClassifierOutputWithNoAttention`, содержащий логиты и вероятности, связанные с предсказанием моделью токена `Yes` или `No` в качестве ответа на данный промпт, которые зафиксированы в следующих свойствах.

*   `logits` (`torch.Tensor` формы `(batch_size, 2)`): первое значение вдоль dim=1 — это logits для токена `Yes`, а второе значение вдоль dim=1 — это logits для токена `No`.
*   `probabilities` (`torch.Tensor` формы `(batch_size, 2)`): первая позиция вдоль dim=1 — вероятность предсказания токена `Yes`, вторая позиция вдоль dim=1 — вероятность предсказания токена `No`.

Промпты ShieldGemma построены таким образом, что предсказание токена `Yes` означает, что контент *нарушает* описанную политику. Если вас интересует только условие нарушения, используйте `violated = outputs.probabilities[:, 1]`, чтобы извлечь этот срез из выходных тензоров.

При использовании с `ShieldGemma2Processor` значение `batch_size` будет равно `len(images) * len(policies)`, а порядок элементов в батче будет следующим: img1_policy1, ... img1_policyN, ... imgM_policyN.

Метод forward класса [ShieldGemma2ForImageClassification](/docs/transformers/v5.23.0/ru/model_doc/shieldgemma2#transformers.ShieldGemma2ForImageClassification) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

