Hugging Face's logo

Transformers documentation

ShieldGemma 2

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).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Bu model, 2025-04-01 tarihinde HF papers'ta yayımlandı ve 2025-03-20 tarihinde Hugging Face Transformers'a katkıda bulunuldu.

FlashAttention SDPA

ShieldGemma 2

Genel Bakış

ShieldGemma 2 modeli, Google tarafından hazırlanan bir teknik raporda tanıtılmıştır. Gemma 3 üzerine inşa edilen ShieldGemma 2, 4 milyar (4B) parametreli bir modeldir; sentetik ve doğal görsellerin güvenliğini ana kategorilere göre kontrol ederek sağlam veri setleri ve modeller oluşturmanıza yardımcı olur. Gemma model ailesine bu eklemeyi yapan Google, araştırmacıların ve geliştiricilerin aşağıda tanımlanan ana zarar alanlarında modellerindeki zararlı içerik riskini kolayca en aza indirmesini sağlar:

  • Cinsel açıdan açık içerik yok: Görsel, açık veya detaylı cinsel eylemleri (ör. pornografi, erotik çıplaklık, tecavüz veya cinsel saldırı tasvirleri) betimleyen içerikler içermemelidir.
  • Tehlikeli İçerik Yok: Görsel, gerçek dünyada zarar verebilecek faaliyetleri kolaylaştıran veya teşvik eden içerikler (ör. ateşli silah ve patlayıcı cihaz yapımı, terörizmin propagandası, intihar talimatları) içermemelidir.
  • Şiddet/Kanlı İçerik Yok: Görsel, şok edici, abartılı veya gereksiz şiddet tasvir eden içerikler içermemelidir (ör. aşırı kan ve ceset, hayvanlara karşı gereksiz şiddet, aşırı yaralanma veya ölüm anı).

Görsel dil modellerinde girdi filtresi olarak veya görüntü üretim sistemlerinde çıktı filtresi olarak ShieldGemma 2 kullanmanızı öneririz. Sağlam bir görüntü güvenliği modeli eğitmek için doğal ve sentetik görüntülerden oluşan eğitim veri kümeleri derledik ve güçlü bir performans sergilemek üzere Gemma 3'ü talimatla ayarladık.

Bu model Ryan Mullins tarafından katkıda bulunmuştur.

Kullanım Örneği

  • ShieldGemma 2, girdi olarak images listesini ve isteğe bağlı policies listesini kabul eden bir Processor sağlar ve bu iki listenin çarpımı olarak, sağlanan sohbet şablonunu kullanarak bir istem partisi oluşturur.
  • ShieldGemma’nın yerleşik politikalarını, Processor’a custom_policies argümanını kullanarak genişletebilirsiniz. Yerleşik politikalardan birinin anahtarını kullanmak, o politikayı özel tanımınızla değiştirir.
  • ShieldGemma 2, Gemma 3 tarafından kullanılan görüntü kırpma özelliklerini desteklemez.

Yerleşik Politiklere Karşı Sınıflandırma

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)

Özel Politikalar Karşısında Sınıflandırma

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

sınıf transformers.ShieldGemma2Processor

< >

( image_processortokenizerchat_template = Noneimage_seq_length = 256policy_definitions = None**kwargs )

__call__

< >

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

Parametreler

  • images — Partiye dahil edilecek tek bir görüntü veya görüntü listesi.
  • text — Desteklenmiyor.
  • videos — Desteklenmiyor.
  • audio — Desteklenmiyor.
  • kwargs — İşleyiciyi yapılandırmak için isteğe bağlı bir anahtar kelime argümanı sözlüğü. Olası değerler şunları içerir:
    • custom_policies: Yapıcıya geçirilen self.policy_definitions'i genişleten ek politika tanımları. custom_policies'in, self.policy_definitions ile aynı anahtarı paylaşanları, politika tanımını geçersiz kılar.
    • policies: (İsteğe bağlı) sağlanan görüntüler için özel ilgi gösterilen, self.policy_definitions | custom_policies birleşik sözlüğündeki anahtarların listesi. Boş veya None ise, birleşik sözlükteki her anahtar için istemler oluşturulur.

Sağlanan görüntülerden bir girdi grubu oluşturur.

ShieldGemma, belirli bir istem yapısı kullanarak politika uyumluluğu için görsel içeriği sınıflandırmak üzere eğitilmiştir. Bu işlemci, sağlanan görsellerden bu tür istemlerin bir toplu kümesini şu şekilde oluşturur:

  1. Her <image, policy> çifti için bir tane olmak üzere konuşmalar listesi oluşturma;
  2. Bu konuşmaları self.apply_chat_template() kullanarak metne dönüştürülür; ve
  3. Konuşmaları ve görüntüleri Gemma3Processor ile aynı teknikleri kullanarak kodlama.

ShieldGemma2Config

sınıf transformers.ShieldGemma2Config

< >

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

Parametreler

  • text_config (Union[dict, ~configuration_utils.PreTrainedConfig], isteğe bağlı) — Metin omurgasının yapılandırma nesnesi veya sözlüğü.
  • vision_config (Union[dict, ~configuration_utils.PreTrainedConfig], isteğe bağlı) — Görüntü omurgasının yapılandırma nesnesi veya sözlüğü.
  • mm_tokens_per_image (int, isteğe bağlı, varsayılan 256) — Görsel gömme başına token sayısı.
  • boi_token_index (int, isteğe bağlı, varsayılan 255999) — Görsel istemi sarmak için kullanılan başlangıç-görsel (begin-of-image) belirteç dizini.
  • eoi_token_index (int, isteğe bağlı, varsayılan 256000) — Görsel istemi sarmak için kullanılan görsel sonu (end-of-image) token indeksi.
  • image_token_index (int, isteğe bağlı, varsayılan 262144) — Girdi görselleri için yer tutucu olarak kullanılan görsel jeton indeksi.
  • initializer_range (float, isteğe bağlı, varsayılan 0.02) — Tüm ağırlık matrislerini başlatmak için kullanılan truncated_normal_initializer'ın standart sapması.
  • tie_word_embeddings (bool, isteğe bağlı) — Kelime gömme (embedding) bağlamasının yapılıp yapılmayacağını belirtir. Ayarlanmazsa, text_config.tie_word_embeddings değeri kullanılır.

Bu, bir Shieldgemma2Model yapılandırmasını depolamak için kullanılan yapılandırma sınıfıdır. Belirtilen argümanlara göre bir Shieldgemma2 modelinin örneklenmesinde, model mimarisini tanımlamak için kullanılır. Varsayılan değerlerle bir yapılandırma örneklendiğinde, google/shieldgemma-2-4b-it modelinin yapılandırmasına benzer bir yapılandırma elde edilir.

Yapılandırma nesneleri PreTrainedConfig sınıfından devralır ve model çıktılarını kontrol etmek için kullanılabilir. Daha fazla bilgi için PreTrainedConfig belgesini okuyun.

Örnek:

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

sınıf transformers.ShieldGemma2ForImageClassification

< >

( config: ShieldGemma2Config )

Parametreler

  • config (ShieldGemma2Config) — Modelin tüm parametrelerini içeren model yapılandırma sınıfı. Bir yapılandırma dosyasıyla başlatmak, modelle ilişkili ağırlıkları yüklemez, yalnızca yapılandırmayı yükler. Model ağırlıklarını yüklemek için from_pretrained() yöntemine bakın.

Örneğin ImageNet için üstünde bir görüntü sınıflandırma başlığı bulunan Shieldgemma2 Modeli.

Bu model PreTrainedModel sınıfından devralır. Kütüphanenin tüm modelleri için uyguladığı genel yöntemler (indirme veya kaydetme, giriş gömme boyutlarını yeniden boyutlandırma, başları budama vb.) için üst sınıf belgelendirmesine bakın.

Bu model aynı zamanda bir PyTorch torch.nn.Module alt sınıfıdır. Bunu standart bir PyTorch Module olarak kullanın ve genel kullanım ve davranışla ilgili tüm konular için PyTorch dokümantasyonuna başvurun.

forward

< >

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

Parametreler

  • input_ids (torch.LongTensor şeklinde (batch_size, sequence_length), isteğe bağlı) — Sözlükteki girdi dizisi belirteçlerinin (token) indeksleri. Varsayılan olarak dolgu (padding) yok sayılır.

    Dizinler AutoTokenizer kullanılarak elde edilebilir. Ayrıntılar için PreTrainedTokenizer.encode() ve PreTrainedTokenizer.call() konularına bakın.

    Girdi kimlikleri nelerdir?

  • pixel_values (torch.Tensor, şekli (batch_size, num_channels, image_size, image_size), isteğe bağlı) — Girdi görüntülerine karşılık gelen tensörler. Piksel değerleri image_processor_class kullanılarak elde edilebilir. Ayrıntılar için image_processor_class.__call__ bölümüne bakın (processor_class, görüntü işleme için image_processor_class kullanır).
  • attention_mask (torch.Tensor şeklinde (batch_size, sequence_length), isteğe bağlı) — Doldurma (padding) token indekslerinde dikkat (attention) işlemi yapmaktan kaçınmak için kullanılan maske. Seçilen maske değerleri [0, 1]:
    • 1, maskelenmemiş jetonlar için,
    • maskelenmiş jetonlar için 0.

    Dikkat maskeleri nedir?

  • position_ids (torch.LongTensor şeklinde (batch_size, sequence_length), isteğe bağlı) — Girdi dizilerindeki her token'ın konum gömme (position embedding) içindeki konum indeksleri. Seçim aralığı [0, config.n_positions - 1].

    Pozisyon kimlikleri nedir?

  • past_key_values (~cache_utils.Cache, isteğe bağlı) — Sıralı çözümlemeyi hızlandırmak için kullanılabilen önceden hesaplanmış gizli durumlar (self-attention ve cross-attention bloklarındaki anahtar ve değerler). Bu genellikle past_key_values değerinin, çözümlemenin önceki bir aşamasında model tarafından döndürülen use_cache=True veya config.use_cache=True.

    Girdi olarak yalnızca Cache örneği kabul edilir, kv cache kılavuzumuza bakın. past_key_values geçirilmezse, varsayılan olarak DynamicCache başlatılır.

    Model, girdi olarak verilen aynı önbellek biçimini çıktı olarak üretecektir.

    past_key_values kullanılıyorsa, kullanıcının tüm input_ids (şekli (batch_size, sequence_length)) yerine, bu modele geçmiş anahtar değer durumları verilmemiş olan, işlenmemiş input_ids (şekli (batch_size, unprocessed_length)) girmesi beklenir.

  • token_type_ids (torch.LongTensor şeklinde (batch_size, sequence_length), isteğe bağlı) — Girdilerin ilk ve ikinci bölümlerini belirtmek için segment token dizinleri. Dizinler [0, 1]:
    • 0, sentence A belirteci ile eşleşir,
    • 1, sentence B belirteçlerine karşılık gelir.

    Token type ID'leri nelerdir?

  • inputs_embeds (torch.Tensor, şekli (batch_size, sequence_length, hidden_size), isteğe bağlı) — İsteğe bağlı olarak, input_ids yerine gömülü bir temsil doğrudan geçmeyi tercih edebilirsiniz. Bu, input_ids dizinlerini ilgili vektörlere dönüştürme biçimi üzerinde modelin dahili gömme arama matrisinden daha fazla kontrol sahibi olmak istiyorsanız faydalıdır.
  • labels (torch.LongTensor, şekli (batch_size,), isteğe bağlı) — Görüntü sınıflandırma/geri dönüşüm kaybını hesaplamak için etiketler. Endeksler [0, ..., config.num_labels - 1] aralığında olmalıdır. config.num_labels == 1 ise bir geri dönüşüm kaybı (Ortalama Kare kaybı) hesaplanır, config.num_labels > 1 ise bir sınıflandırma kaybı (Çapraz Entropi) hesaplanır.
  • use_cache (bool, isteğe bağlı) — True olarak ayarlanırsa, past_key_values anahtar değer durumları döndürülür ve çözümlemeyi hızlandırmak için kullanılabilir (bkz. past_key_values).
  • output_attentions (bool, isteğe bağlı) — Tüm dikkat katmanlarının dikkat tensörlerinin döndürülüp döndürülmeyeceğini belirtir. Daha fazla ayrıntı için döndürülen tensörler altındaki attentions bölümüne bakın.
  • output_hidden_states (bool, isteğe bağlı) — Tüm katmanların gizli durumlarının (hidden states) döndürülüp döndürülmeyeceğini belirtir. Daha fazla ayrıntı için döndürülen tensörler altındaki hidden_states bölümüne bakın.
  • return_dict (bool, isteğe bağlı) — Düz bir tuple yerine ModelOutput döndürülecek mi?
  • logits_to_keep (Union[int, torch.Tensor], isteğe bağlı, varsayılan 0) — int ise, son logits_to_keep token için logits hesaplanır. 0 ise, tüm input_ids için logits hesaplanır (özel durum). Üretim için yalnızca son token logits'leri gereklidir ve bunların yalnızca o token için hesaplanması bellek tasarrufu sağlar; bu, uzun diziler veya büyük sözlük boyutu için oldukça önemli hale gelir. torch.Tensor ise, dizi uzunluğu boyutundaki korunacak indekslere karşılık gelen 1B olmalıdır. Bu, paketlenmiş tensor biçimini (batch ve dizi uzunluğu için tek boyut) kullanırken faydalıdır.

ShieldGemma2ForImageClassification forward metodu, __call__ özel metodunu geçersiz kılar.

İleri geçiş tarifi bu fonksiyon içinde tanımlanmalı olsa da, sonrasında bunun yerine Module örneğini çağırmak gerekir; çünkü önceki, ön ve son işleme adımlarını çalıştırmaktan sorumluyken ikincisi bunları sessizce yok sayar.

Update on GitHub

←SAM3-LiteText SigLIP→