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

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

Эта модель была опубликована в HF papers 01.04.2025 и добавлена в Hugging Face Transformers 20.03.2025.

ShieldGemma 2

Обзор

Модель ShieldGemma 2 была представлена в техническом отчёте от Google. ShieldGemma 2, построенная на базе Gemma 3, — это модель с 4 миллиардами (4B) параметров, которая проверяет безопасность как синтетических, так и естественных изображений по ключевым категориям, помогая создавать надёжные наборы данных и модели. Благодаря добавлению этой модели в семейство Gemma исследователи и разработчики теперь могут легко минимизировать риск вредного контента в своих моделях в ключевых областях, определённых ниже:

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

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

Эта модель была предоставлена Ryan Mullins.

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

ShieldGemma 2 предоставляет Processor, который принимает на вход список images и необязательный список policies и формирует пакет промптов как произведение этих двух списков с использованием предоставленного шаблона чата.
Вы можете расширить встроенные политики ShieldGemma с помощью аргумента custom_policies для Processor. Использование того же ключа, что и у одной из встроенных политик, заменит её на ваше собственное определение.
ShieldGemma 2 не поддерживает функции обрезки изображений, используемые в Gemma 3.

Классификация по встроенным политикам

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)

Классификация по пользовательским политикам

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

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

Параметры

images — одно изображение или список изображений, которые нужно включить в пакет.
text — Не поддерживается.
videos — Не поддерживается.
audio — Не поддерживается.
kwargs — Необязательный словарь аргументов с ключевыми словами для настройки процессора. Возможные значения:
- custom_policies: Дополнительные определения политик, дополняющие self.policy_definitions, переданные в конструктор. Обратите внимание, что custom_policies, имеющие общий ключ с self.policy_definitions, переопределяют описание политики.
- policies: (Необязательно) список ключей из общего словаря self.policy_definitions | custom_policies, представляющих особый интерес для предоставленных изображений. Если список пуст или равен None, промпты будут сгенерированы для каждого ключа в общем словаре.

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

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

Создание списка диалогов, по одному для каждой пары <image, policy>;
Преобразование этих диалогов в текст с помощью self.apply_chat_template(); и
Кодирование диалогов и изображений с использованием тех же методов, что и в Gemma3Processor.

ShieldGemma2Config

класс 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 )

Параметры

text_config (Union[dict, ~configuration_utils.PreTrainedConfig], необязательный) — Объект конфигурации или словарь конфигурации текстового бэкбона.
vision_config (Union[dict, ~configuration_utils.PreTrainedConfig], необязательный) — Объект конфигурации или словарь конфигурации визуального бэкбона.
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) — Стандартное отклонение truncated_normal_initializer, используемое для инициализации всех матриц весов.
tie_word_embeddings (bool, необязательный) — Определяет, следует ли связывать векторные представления слов. Если не задано, по умолчанию используется значение text_config.tie_word_embeddings.

Это класс конфигурации для хранения настроек модели Shieldgemma2Model. Он используется для создания модели Shieldgemma2 в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации google/shieldgemma-2-4b-it

Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.

Пример:

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

< source >

( config: ShieldGemma2Config )

Параметры

config (ShieldGemma2Config) — Класс конфигурации модели, содержащий все параметры модели. Инициализация по файлу конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().

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

Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)

Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

forward

< source >

( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = 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.Tensor] = 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 )

Параметры

input_ids (torch.LongTensor формы (batch_size, sequence_length), , необязательный) — Индексы токенов входной последовательности в словаре. По умолчанию токены отсечки (padding) игнорируются.
Индексы можно получить с помощью AutoTokenizer. Подробности см. в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call().

Что такое входные идентификаторы?
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 для токенов, которые замаскированы.
Что такое маски внимания?
position_ids (torch.LongTensor формы (batch_size, sequence_length), , необязательный) — Индексы позиций токенов каждого входного последовательности в позиционных эмбеддингах. Выбираются из диапазона [0, config.n_positions - 1].
Что такое идентификаторы позиций?
past_key_values (~cache_utils.Cache, необязательный) — Предвычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это past_key_values , возвращённые моделью на предыдущем этапе декодирования, когда use_cache=True или config.use_cache=True.
В качестве входного параметра допускается только экземпляр Cache, см. наше руководство по кэшу KV. Если past_key_values не переданы, по умолчанию будет инициализирован 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 соответствует токену sentence A,
- 1 соответствует токену sentence B.
Что такое идентификаторы типов токенов?
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 вместо обычного кортежа.
logits_to_keep (Union[int, torch.Tensor], необязательный, по умолчанию 0) — Если передано значение типа int, вычисляет logits для последних logits_to_keep токенов. Если указано 0, logits вычисляются для всех input_ids (особый случай). Для генерации нужны logits только последнего токена, и вычисление их только для этого токена позволяет сэкономить память, что становится весьма значимым для длинных последовательностей или большого размера словаря. Если передано значение типа torch.Tensor, оно должно быть одномерным и соответствовать индексам, которые нужно сохранить в измерении длины последовательности. Это полезно при использовании упакованного формата тензоров (один размер для batch и длины последовательности).

Метод forward класса ShieldGemma2ForImageClassification переопределяет специальный метод __call__.

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

Update on GitHub

←SAM3-LiteText SigLIP→