ShieldGemma 2

概述

ShieldGemma 2 模型由 Google 在一份技术报告中提出。ShieldGemma 2 基于 Gemma 3 构建，是一个拥有 40 亿（4B）参数的模型，可以根据关键类别检查合成图像和自然图像的安全性，以帮助您构建强大的数据集和模型。通过将此模型添加到 Gemma 模型系列，研究人员和开发人员现在可以轻松地将模型中有害内容的风险降至最低，具体定义如下：

无露骨色情内容：图像不得包含描绘露骨或图形化性行为的内容（例如，色情、色情裸露、描绘强奸或性侵犯）。
无危险内容：图像不得包含促使或鼓励可能造成现实世界伤害的活动的内容（例如，制造枪支和爆炸装置、宣扬恐怖主义、自杀说明）。
无暴力/血腥内容：图像不得包含描绘令人震惊、耸人听闻或无谓暴力的内容（例如，过度血腥、对动物的无谓暴力、极端伤害或死亡瞬间）。

我们建议将 ShieldGemma 2 用作视觉语言模型的输入过滤器，或图像生成系统的输出过滤器。为了训练一个强大的图像安全模型，我们策划了自然图像和合成图像的训练数据集，并对 Gemma 3 进行了指令微调，以展示强大的性能。

该模型由Ryan Mullins贡献。

使用示例

ShieldGemma 2 提供了一个处理器 (Processor)，它接受一个 images 列表和一个可选的 policies 列表作为输入，并使用提供的聊天模板将这两个列表的乘积构建成一批提示。
您可以通过处理器的 custom_policies 参数扩展 ShieldGemma 的内置策略。使用与内置策略相同的键将用您的自定义定义覆盖该策略。
ShieldGemma 2 不支持 Gemma 3 使用的图像裁剪功能。

基于内置策略的分类

from PIL import Image
import requests
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)

基于自定义策略的分类

from PIL import Image
import requests
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": "descrition_a",
    "key_b": "descrition_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

class transformers.ShieldGemma2Processor

< source >

( image_processor tokenizer chat_template = None image_seq_length = 256 policy_definitions = None **kwargs )

ShieldGemma2Config

class transformers.ShieldGemma2Config

< source >

( text_config = None vision_config = 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 **kwargs )

参数

text_config (Union[ShieldGemma2TextConfig, dict], 可选) — 文本骨干的配置对象。
vision_config (Union[AutoConfig, dict], 可选) — 自定义视觉配置或字典。
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) — 用于初始化所有权重矩阵的截断正态初始化器的标准差。

这是存储 ShieldGemma2ForImageClassification 配置的配置类。它用于根据指定参数实例化 ShieldGemma2ForImageClassification，定义模型架构。使用默认值实例化配置将产生与 shieldgemma-2-4b-it 相似的配置。

例如：google/gemma-3-4b

配置对象继承自 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

class transformers.ShieldGemma2ForImageClassification

< source >

( config: ShieldGemma2Config )

参数

config (ShieldGemma2Config) — 包含模型所有参数的模型配置类。使用配置文件初始化不会加载与模型相关的权重，只加载配置。请查看 from_pretrained() 方法以加载模型权重。

Shieldgemma2 模型，其顶部带有一个图像分类头，例如用于 ImageNet。

此模型继承自 PreTrainedModel。请查看超类文档，了解库为其所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、修剪头部等）。

此模型也是 PyTorch torch.nn.Module 子类。将其作为常规 PyTorch 模块使用，并参考 PyTorch 文档以了解与一般用法和行为相关的所有事项。

forward

< source >

( input_ids: typing.Optional[torch.LongTensor] = None pixel_values: typing.Optional[torch.FloatTensor] = None attention_mask: typing.Optional[torch.Tensor] = None position_ids: typing.Optional[torch.LongTensor] = None past_key_values: typing.Union[list[torch.FloatTensor], transformers.cache_utils.Cache, NoneType] = None token_type_ids: typing.Optional[torch.LongTensor] = None cache_position: typing.Optional[torch.LongTensor] = None inputs_embeds: typing.Optional[torch.FloatTensor] = None labels: typing.Optional[torch.LongTensor] = None use_cache: typing.Optional[bool] = None output_attentions: typing.Optional[bool] = None output_hidden_states: typing.Optional[bool] = None return_dict: typing.Optional[bool] = None logits_to_keep: typing.Union[int, torch.Tensor] = 0 **lm_kwargs )

参数

input_ids (形状为 (batch_size, sequence_length) 的 torch.LongTensor，可选) — 词汇表中输入序列标记的索引。默认情况下将忽略填充。

可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。

什么是输入 ID？
pixel_values (形状为 (batch_size, num_channels, image_size, image_size) 的 torch.FloatTensor，可选) — 对应于输入图像的张量。像素值可以使用 {image_processor_class} 获取。有关详细信息，请参阅 {image_processor_class}.__call__（{processor_class} 使用 {image_processor_class} 处理图像）。
attention_mask (形状为 (batch_size, sequence_length) 的 torch.Tensor，可选) — 遮罩，用于避免对填充标记索引执行注意力。遮罩值选择在 [0, 1] 之间：
- 1 表示**未被遮罩**的标记，
- 0 表示**被遮罩**的标记。
什么是注意力遮罩？
position_ids (形状为 (batch_size, sequence_length) 的 torch.LongTensor，可选) — 每个输入序列标记在位置嵌入中的位置索引。选择范围为 [0, config.n_positions - 1]。

什么是位置 ID？
past_key_values (Union[list[torch.FloatTensor], ~cache_utils.Cache, NoneType]) — 预先计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常包括模型在解码前期返回的 past_key_values，当 use_cache=True 或 config.use_cache=True 时。

允许两种格式：
- Cache 实例，请参阅我们的 kv cache 指南；
- 长度为 config.n_layers 的 tuple(torch.FloatTensor) 元组，每个元组包含 2 个形状为 (batch_size, num_heads, sequence_length, embed_size_per_head) 的张量。这也称为传统缓存格式。
模型将输出与输入相同的缓存格式。如果未传入 past_key_values，则将返回传统缓存格式。

如果使用 past_key_values，用户可以选择仅输入最后一个 input_ids（那些没有将其过去键值状态提供给此模型的）形状为 (batch_size, 1)，而不是所有 input_ids 形状为 (batch_size, sequence_length)。
token_type_ids (形状为 (batch_size, sequence_length) 的 torch.LongTensor，可选) — 分段标记索引，指示输入的第一个和第二个部分。索引选择在 [0, 1] 之间：
- 0 对应于**句子 A** 标记，
- 1 对应于**句子 B** 标记。
什么是标记类型 ID？
cache_position (形状为 (sequence_length) 的 torch.LongTensor，可选) — 描绘输入序列标记在序列中位置的索引。与 position_ids 不同，此张量不受填充影响。它用于在正确位置更新缓存并推断完整的序列长度。
inputs_embeds (形状为 (batch_size, sequence_length, hidden_size) 的 torch.FloatTensor，可选) — 可选地，您可以直接传入嵌入表示，而不是传入 input_ids。如果您想对如何将 input_ids 索引转换为关联向量有比模型内部嵌入查找矩阵更多的控制权，这将很有用。
labels (形状为 (batch_size, sequence_length) 的 torch.LongTensor，可选) — 用于计算遮罩语言建模损失的标签。索引应为 [0, ..., config.vocab_size] 或 -100 (请参阅 input_ids 文档字符串)。索引设置为 -100 的标记将被忽略（遮罩），损失仅针对标签在 [0, ..., config.vocab_size] 中的标记计算。
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_to_keep 个标记的逻辑值。如果是 0，则计算所有 input_ids 的逻辑值（特殊情况）。生成时只需要最后一个标记的逻辑值，仅计算该标记可以节省内存，这对于长序列或大词汇量非常重要。如果是 torch.Tensor，则必须是对应于序列长度维度中要保留的索引的一维张量。这在使用打包张量格式（批次和序列长度的单维度）时很有用。

ShieldGemma2ForImageClassification 的 forward 方法，覆盖了 __call__ 特殊方法。

尽管前向传播的配方需要在此函数中定义，但应在此之后调用 Module 实例，因为前者负责运行预处理和后处理步骤，而后者则默默地忽略它们。

示例

>>> from transformers import AutoImageProcessor, ShieldGemma2ForImageClassification
>>> import torch
>>> from datasets import load_dataset

>>> dataset = load_dataset("huggingface/cats-image")
>>> image = dataset["test"]["image"][0]

>>> image_processor = AutoImageProcessor.from_pretrained("google/gemma-3-4b")
>>> model = ShieldGemma2ForImageClassification.from_pretrained("google/gemma-3-4b")

>>> inputs = image_processor(image, return_tensors="pt")

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> # model predicts one of the 1000 ImageNet classes
>>> predicted_label = logits.argmax(-1).item()
>>> print(model.config.id2label[predicted_label])
...

< > 在 GitHub 上更新

Transformers

ShieldGemma 2

概述

使用示例

基于内置策略的分类

基于自定义策略的分类

ShieldGemma2Processor

class transformers.ShieldGemma2Processor

ShieldGemma2Config

class transformers.ShieldGemma2Config

ShieldGemma2ForImageClassification

class transformers.ShieldGemma2ForImageClassification

forward