Hugging Face's logo

Transformers 文档

ShieldGemma 2

Hugging Face's logo
加入 Hugging Face 社区

并获取增强的文档体验

开始使用

ShieldGemma 2

概述

ShieldGemma 2 模型由 Google 在即将发布的技术报告中提出。ShieldGemma 2 构建于 Gemma 3 之上，是一个 40 亿（4B）参数模型，可针对关键类别检查合成图像和自然图像的安全性，以帮助您构建强大的数据集和模型。随着 Gemma 模型系列的这一新增功能，研究人员和开发人员现在可以轻松地最大限度地降低其模型中关键危害领域的有害内容风险，如下所述

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

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

此模型由 Ryan Mullins 贡献。

使用示例

  • ShieldGemma 2 提供了一个 Processor，它接受 images 列表和可选的 policies 列表作为输入，并使用提供的聊天模板构建这两个列表的乘积作为提示批次。
  • 您可以使用 Processor 的 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

< >

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

ShieldGemma2Config

class transformers.ShieldGemma2Config

< >

( 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, optional, defaults to 256) — 每个图像嵌入的令牌数量，默认为 256。
  • boi_token_index (int, optional, defaults to 255999) — 用于包裹图像提示的图像开始令牌索引，默认为 255999。
  • eoi_token_index (int, optional, defaults to 256000) — 用于包裹图像提示的图像结束令牌索引，默认为 256000。
  • image_token_index (int, optional, defaults to 262144) — 用于编码图像提示的图像令牌索引，默认为 262144。
  • initializer_range (float, optional, defaults to 0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差，默认为 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

< >

( config: ShieldGemma2Config )

forward

< >

( input_ids: LongTensor = None pixel_values: FloatTensor = None attention_mask: typing.Optional[torch.Tensor] = None position_ids: typing.Optional[torch.LongTensor] = None past_key_values: typing.Union[typing.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？

  • attention_mask (形状为 (batch_size, sequence_length) 的 torch.Tensor, optional) — 用于避免对填充令牌索引执行注意力的掩码。 在 [0, 1] 中选择的掩码值：

    • 1 表示未被掩盖的令牌，
    • 0 表示被掩盖的令牌。

    什么是注意力掩码？

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

    如果使用 past_key_values，则可以选择仅输入最后一个 input_ids（请参阅 past_key_values）。

    如果您想更改填充行为，则应阅读 modeling_opt._prepare_decoder_attention_mask 并根据您的需要进行修改。 有关默认策略的更多信息，请参见 论文 中的图 1。

    • 1 表示 head 未被掩盖，
    • 0 表示 head 被掩盖。
  • position_ids (形状为 (batch_size, sequence_length) 的 torch.LongTensor, optional) — 位置嵌入中每个输入序列令牌的位置索引。 在范围 [0, config.n_positions - 1] 中选择。

    什么是位置 ID？

  • past_key_values (Cache 或 tuple(tuple(torch.FloatTensor)), optional) — 预先计算的隐藏状态（自注意力模块和交叉注意力模块中的键和值），可用于加速顺序解码。 这通常包括模型在先前解码阶段返回的 past_key_values，当 use_cache=True 或 config.use_cache=True 时。

    允许两种格式：

    • Cache 实例，请参阅我们的 kv 缓存指南；
    • 长度为 config.n_layers 的 tuple(tuple(torch.FloatTensor)) 元组，每个元组具有 2 个形状为 (batch_size, num_heads, sequence_length, embed_size_per_head) 的张量）。 这也称为传统缓存格式。

    模型将输出与作为输入提供的缓存格式相同的格式。 如果未传递 past_key_values，则将返回传统缓存格式。

    如果使用 past_key_values，则用户可以选择仅输入最后一个 input_ids（那些没有将其过去键值状态提供给此模型的 input_ids），其形状为 (batch_size, 1)，而不是形状为 (batch_size, sequence_length) 的所有 input_ids。

  • inputs_embeds (形状为 (batch_size, sequence_length, hidden_size) 的 torch.FloatTensor, optional) — 可选地，您可以选择直接传递嵌入表示，而不是传递 input_ids。 如果您希望比模型的内部嵌入查找矩阵更好地控制如何将 input_ids 索引转换为关联的向量，这将非常有用。
  • use_cache (bool, optional) — 如果设置为 True，则返回 past_key_values 键值状态，并且可以用于加速解码（请参阅 past_key_values）。
  • output_attentions (bool, optional) — 是否返回所有注意力层的注意力张量。 有关更多详细信息，请参见返回张量下的 attentions。
  • output_hidden_states (bool, optional) — 是否返回所有层的隐藏状态。 有关更多详细信息，请参见返回张量下的 hidden_states。
  • return_dict (bool, optional) — 是否返回 ModelOutput 而不是普通元组。
  • cache_position (形状为 (sequence_length) 的 torch.LongTensor, optional) — 描述输入序列令牌在序列中位置的索引。 与 position_ids 相反，此张量不受填充的影响。 它用于在正确的位置更新缓存并推断完整的序列长度。

ShieldGemma2ForImageClassification 的 forward 方法，重写了 __call__ 特殊方法。

尽管前向传递的步骤需要在该函数内定义，但应该在之后调用 Module 实例，而不是调用此函数，因为前者负责处理预处理和后处理步骤，而后者会默默地忽略它们。

预测图像违反指定策略的二分类概率。

< > 在 GitHub 上更新

←Segment Anything SigLIP→