# ShieldGemma 2

## 概述

ShieldGemma 2 模型由 Google 在一篇[技术报告](https://huggingface.co/papers/2504.01081)中提出。ShieldGemma 2 基于[Gemma 3](https://ai.google.dev/gemma/docs/core/model_card_3)构建，是一个拥有 40 亿（4B）参数的模型，它针对关键类别检查合成图像和自然图像的安全性，以帮助您构建稳健的数据集和模型。随着该模型加入 Gemma 模型家族，研究人员和开发人员现在可以轻松地在以下定义的关键危害领域内，最大限度地降低模型中有害内容的风险：

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

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

该模型由 [Ryan Mullins](https://huggingface.co/RyanMullins) 贡献。

## 使用示例

- ShieldGemma 2 提供了一个 Processor，它接受一个 `images` 列表和一个可选的 `policies` 列表作为输入，并使用提供的聊天模板将这两个列表的笛卡尔积构造成一批提示。
- 您可以通过向 Processor 传入 `custom_policies` 参数来扩展 ShieldGemma 的内置策略。如果使用与某个内置策略相同的键，该策略将被您的自定义定义覆盖。
- 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/main/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/main/zh/model_doc/shieldgemma2#transformers.ShieldGemma2Processor) 提供了 [Gemma3ImageProcessor](/docs/transformers/main/zh/model_doc/gemma3#transformers.Gemma3ImageProcessor) 和 [GemmaTokenizer](/docs/transformers/main/zh/model_doc/gemma#transformers.GemmaTokenizer) 的所有功能。有关更多信息，请参阅 [~Gemma3ImageProcessor](/docs/transformers/main/zh/model_doc/gemma3#transformers.Gemma3ImageProcessor) 和 [~GemmaTokenizer](/docs/transformers/main/zh/model_doc/gemma#transformers.GemmaTokenizer)。

#### __调用__[[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/main/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*) : 是否返回多模态 token 类型 ID，以指示多模态占位符 token 的位置。

return_text_replacement_offsets (`bool`, *kwargs*) : 是否返回每个多模态占位符及其替换项的字符偏移量。

policies (`list[str]`, *kwargs*, *可选*) : 在联合字典 `self.policy_definitions | custom_policies` 中，针对所提供图像特别关注的键。如果为 `None`，将为联合字典中的每个键生成提示。

custom_policies (`dict[str, *kwargs*, str]`, *可选*) : 用于补充传入构造函数的 `self.policy_definitions` 的额外策略定义。请注意，与 `self.policy_definitions` 共享相同键的 `custom_policies` 将覆盖相应的策略描述。

return_tensors (`str` 或 [TensorType](/docs/transformers/main/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回特定框架的张量。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 NumPy `np.ndarray` 对象。

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/zh/main_classes/processors#transformers.ProcessingKwargs), *可选*) : 针对每种模态（文本、图像、视频、音频）的额外处理选项。模型特定参数已在上方列出；有关支持参数的完整列表，请参阅 TypedDict 类。

**返回值：**

包含 `input_ids`、`pixel_values` 等内容的 `BatchFeature`，其中每个 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/main/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)：每个图像嵌入的 token 数量。

boi_token_index (`int`, *可选*，默认为 255999)：用于包裹图像提示的图像起始标记索引。

eoi_token_index (`int`, *可选*，默认为 256000)：用于包裹图像提示的图像结束标记索引。

image_token_index (`int`, *可选*，默认为 `262144`)：用作输入图像占位符的图像 token 索引。

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/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/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/main/src/transformers/models/shieldgemma2/modeling_shieldgemma2.py#L44)

**参数：**

config ([ShieldGemma2Config](/docs/transformers/main/zh/model_doc/shieldgemma2#transformers.ShieldGemma2Config)) : 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

例如，在顶部添加图像分类头的 Shieldgemma2 模型，用于 ImageNet。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 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/main/src/transformers/models/shieldgemma2/modeling_shieldgemma2.py#L72)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../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)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/main/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

token_type_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于指示输入中第一和第二部分的段标记索引。索引选自 `[0, 1]`： - 0 对应 *句子 A* 的标记， - 1 对应 *句子 B* 的标记。 [什么是标记类型 ID？](../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/main/zh/main_classes/output#transformers.utils.ModelOutput) 而不是普通元组。

logits_to_keep (`Union[int, torch.Tensor]`，*可选*，默认为 `0`)：如果为 `int`，则计算最后 `logits_to_keep` 个 token 的 logits。如果为 `0`，则计算所有 `input_ids` 的 logits（特殊情况）。生成过程只需要最后一个 token 的 logits，仅针对该 token 进行计算可以节省内存，对于长序列或大词汇量而言，这种节省相当可观。如果为 `torch.Tensor`，则必须是一维张量，对应于序列长度维度中需要保留的索引。这在使用打包张量格式（将批次和序列长度合并为单一维度）时非常有用。

**返回值：**

一个 `ShieldGemma2ImageClassifierOutputWithNoAttention` 实例，包含模型预测 `Yes` 或 `No` 标记作为该提示词响应时相关的 logits 和概率，记录在以下属性中。

*   `logits`（形状为 `(batch_size, 2)` 的 `torch.Tensor`）：dim=1 上的第一个位置是 `Yes` 标记的 logits，dim=1 上的第二个位置是 `No` 标记的 logits。
*   `probabilities`（形状为 `(batch_size, 2)` 的 `torch.Tensor`）：dim=1 上的第一个位置是预测 `Yes` token 的概率，dim=1 上的第二个位置是预测 `No` token 的概率。

ShieldGemma 的提示词是这样构建的：预测 `Yes` 令牌表示内容*确实违反*了所描述的政策。如果您只关注违规条件，请使用 `violated = outputs.probabilities[:, 1]` 从输出张量中提取该切片。

当与 `ShieldGemma2Processor` 一起使用时，`batch_size` 将等于 `len(images) * len(policies)`，且批次内的顺序为 img1_policy1, ... img1_policyN, ... imgM_policyN。

[ShieldGemma2ForImageClassification](/docs/transformers/main/zh/model_doc/shieldgemma2#transformers.ShieldGemma2ForImageClassification) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。