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

and get access to the augmented documentation experience

to get started

Model ini dipublikasikan di HF papers pada 2025-04-01 dan disumbangkan ke Hugging Face Transformers pada 2025-03-20.

FlashAttention SDPA

ShieldGemma 2

Ikhtisar

Model ShieldGemma 2 diusulkan dalam laporan teknis oleh Google. ShieldGemma 2, yang dibangun di atas Gemma 3, adalah model dengan 4 miliar (4B) parameter yang memeriksa keamanan gambar sintetis maupun alami terhadap kategori utama untuk membantu Anda membangun dataset dan model yang robust. Dengan penambahan ini ke dalam keluarga model Gemma, peneliti dan pengembang kini dapat dengan mudah meminimalkan risiko konten berbahaya dalam model mereka di berbagai area bahaya utama yang didefinisikan di bawah ini:

  • Konten yang Tidak Bersifat Seksual Eksplisit: Gambar tidak boleh memuat konten yang menggambarkan tindakan seksual yang eksplisit atau grafis (misalnya, pornografi, ketelanjangan erotis, penggambaran pemerkosaan atau pelecehan seksual).
  • Tidak Ada Konten Berbahaya: Gambar tidak boleh memuat konten yang memfasilitasi atau mendorong aktivitas yang dapat menyebabkan bahaya di dunia nyata (misalnya, pembuatan senjata api dan perangkat peledak, promosi terorisme, instruksi bunuh diri).
  • Konten Kekerasan/Gore: Gambar tidak boleh memuat konten yang menggambarkan kekerasan yang mengejutkan, sensasional, atau berlebihan (misalnya, darah dan gore yang berlebihan, kekerasan yang tidak perlu terhadap hewan, cedera ekstrem, atau momen kematian).

Kami merekomendasikan penggunaan ShieldGemma 2 sebagai filter input untuk vision language models, atau sebagai filter output untuk sistem generasi gambar. Untuk melatih model keamanan gambar yang robust, kami mengkurasi dataset pelatihan berupa gambar alami dan sintetis, serta melakukan instruction-tuning pada Gemma 3 untuk menunjukkan kinerja yang kuat.

Model ini disumbangkan oleh Ryan Mullins.

Contoh Penggunaan

  • ShieldGemma 2 menyediakan Processor yang menerima daftar images dan daftar opsional policies sebagai input, lalu membangun batch prompt sebagai hasil perkalian dari kedua daftar tersebut menggunakan chat template yang disediakan.
  • Anda dapat memperluas kebijakan bawaan ShieldGemma dengan argumen custom_policies pada Processor. Menggunakan kunci yang sama dengan salah satu kebijakan bawaan akan menimpa kebijakan tersebut dengan definisi kustom Anda.
  • ShieldGemma 2 tidak mendukung fitur pemotongan gambar yang digunakan oleh Gemma 3.

Klasifikasi terhadap Kebijakan Bawaan

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)

Klasifikasi terhadap Kebijakan Kustom

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

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

Parameter

  • images — Satu gambar atau daftar gambar yang akan disertakan dalam batch.
  • text — Tidak didukung.
  • videos — Tidak didukung.
  • audio — Tidak didukung.
  • kwargs — Kamus opsional berisi argumen kata kunci untuk mengonfigurasi prosesor. Nilai yang mungkin termasuk:
    • custom_policies: Definisi kebijakan tambahan yang melengkapi self.policy_definitions yang diteruskan ke konstruktor. Perhatikan bahwa custom_policies yang berbagi kunci dengan self.policy_definitions akan menimpa deskripsi kebijakan
    • policies: (Opsional) daftar kunci dalam kamus gabungan self.policy_definitions | custom_policies yang menjadi perhatian khusus untuk gambar yang diberikan. Jika kosong atau None, prompt akan dibuat untuk setiap kunci dalam kamus gabungan.

Membuat batch input dari gambar yang disediakan.

ShieldGemma dilatih untuk mengklasifikasikan konten gambar guna kepatuhan kebijakan menggunakan konstruksi prompt tertentu. Prosesor ini menghasilkan batch prompt semacam itu dari gambar yang diberikan dengan cara:

  1. Membuat daftar percakapan, satu untuk setiap pasangan <image, policy>;
  2. Mengonversi percakapan-percakapan ini menjadi teks menggunakan self.apply_chat_template(); dan
  3. Mengode percakapan dan gambar menggunakan teknik yang sama seperti Gemma3Processor.

ShieldGemma2Config

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

Parameter

  • text_config (Union[dict, ~configuration_utils.PreTrainedConfig], opsional) — Objek config atau dictionary dari text backbone.
  • vision_config (Union[dict, ~configuration_utils.PreTrainedConfig], opsional) — Objek config atau dictionary dari vision backbone.
  • mm_tokens_per_image (int, opsional, default 256) — Jumlah token per embedding gambar.
  • boi_token_index (int, opsional, defaultnya 255999) — Indeks token awal gambar untuk membungkus prompt gambar.
  • eoi_token_index (int, opsional, defaultnya 256000) — Indeks token end-of-image untuk membungkus prompt gambar.
  • image_token_index (int, opsional, default 262144) — Indeks token gambar yang digunakan sebagai placeholder untuk gambar input.
  • initializer_range (float, opsional, defaultnya 0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.
  • tie_word_embeddings (bool, opsional) — Apakah akan mengikat (tie) word embeddings. Nilainya secara default mengikuti text_config.tie_word_embeddings jika tidak disetel.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari Shieldgemma2Model. Kelas ini digunakan untuk membuat instans model Shieldgemma2 berdasarkan argumen yang ditentukan, sehingga mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari google/shieldgemma-2-4b-it

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

Contoh:

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

kelas transformers.ShieldGemma2ForImageClassification

< >

( config: ShieldGemma2Config )

Parameter

  • config (ShieldGemma2Config) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya saja. Lihat metode from_pretrained() untuk memuat bobot model.

Model Shieldgemma2 dengan kepala klasifikasi gambar di atasnya, misalnya untuk ImageNet.

Model ini mewarisi dari PreTrainedModel. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran embedding input, memangkas kepala, dll.)

Model ini juga merupakan subclass dari torch.nn.Module PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.

forward

< >

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

Parameter

  • input_ids (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Indeks token dari urutan input dalam kosakata. Padding akan diabaikan secara default.

    Indeks dapat diperoleh menggunakan AutoTokenizer. Lihat PreTrainedTokenizer.encode() dan PreTrainedTokenizer.call() untuk detailnya.

    Apa itu input ID?

  • pixel_values (torch.FloatTensor dengan bentuk (batch_size, num_channels, image_size, image_size), opsional) — Tensor yang sesuai dengan gambar input. Nilai piksel dapat diperoleh menggunakan image_processor_class. Lihat image_processor_class.__call__ untuk detailnya (processor_class menggunakan image_processor_class untuk memproses gambar).
  • attention_mask (torch.Tensor dengan bentuk (batch_size, sequence_length), opsional) — Mask untuk menghindari eksekusi attention pada indeks token padding. Nilai mask dipilih dari [0, 1]:
    • 1 untuk token yang tidak dimasker,
    • 0 untuk token yang dimasker.

    Apa itu attention mask?

  • position_ids (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Indeks posisi token dari setiap urutan input dalam position embeddings. Dipilih dalam rentang [0, config.n_positions - 1].

    Apa itu ID posisi?

  • past_key_values (~cache_utils.Cache, opsional) — Hidden-states yang sudah dihitung sebelumnya (key dan values di blok self-attention dan di blok cross-attention) yang dapat digunakan untuk mempercepat decoding berurutan. Ini biasanya terdiri dari past_key_values yang dikembalikan oleh model pada tahap decoding sebelumnya, ketika use_cache=True atau config.use_cache=True.

    Hanya instance Cache yang diizinkan sebagai input, lihat panduan kv cache kami. Jika tidak ada past_key_values yang diteruskan, DynamicCache akan diinisialisasi secara default.

    Model akan menghasilkan format cache yang sama dengan yang diberikan sebagai input.

    Jika past_key_values digunakan, pengguna diharapkan hanya memasukkan input_ids yang belum diproses (yang tidak memiliki state past key value yang diberikan ke model ini) dengan bentuk (batch_size, unprocessed_length) alih-alih semua input_ids dengan bentuk (batch_size, sequence_length).

  • token_type_ids (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Indeks token segmen untuk menunjukkan bagian pertama dan kedua dari input. Indeks dipilih dari [0, 1]:
    • 0 sesuai dengan token sentence A,
    • 1 sesuai dengan token sentence B.

    Apa itu token type ID?

  • inputs_embeds (torch.FloatTensor dengan bentuk (batch_size, sequence_length, hidden_size), opsional) — Secara opsional, alih-alih meneruskan input_ids, Anda dapat memilih untuk langsung meneruskan representasi tertanam. Hal ini berguna jika Anda ingin memiliki kendali lebih atas cara mengonversi indeks input_ids menjadi vektor terkait, dibandingkan dengan matriks pencarian penanaman internal model.
  • labels (torch.LongTensor dengan bentuk (batch_size,), opsional) — Label untuk menghitung loss klasifikasi/regresi gambar. Indeks harus berada dalam [0, ..., config.num_labels - 1]. Jika config.num_labels == 1, loss regresi dihitung (Mean-Square loss). Jika config.num_labels > 1, loss klasifikasi dihitung (Cross-Entropy).
  • use_cache (bool, opsional) — Jika diset ke True, state kunci-nilai past_key_values akan dikembalikan dan dapat digunakan untuk mempercepat decoding (lihat past_key_values).
  • output_attentions (bool, opsional) — Apakah akan mengembalikan tensor attentions dari semua lapisan attention. Lihat attentions di bawah tensor yang dikembalikan untuk detail lebih lanjut.
  • output_hidden_states (bool, opsional) — Apakah akan mengembalikan hidden states dari semua lapisan. Lihat hidden_states di bawah tensor yang dikembalikan untuk detail lebih lanjut.
  • return_dict (bool, opsional) — Apakah akan mengembalikan ModelOutput alih-alih tuple biasa.
  • logits_to_keep (Union[int, torch.Tensor], opsional, default 0) — Jika berupa int, hitung logits untuk logits_to_keep token terakhir. Jika 0, hitung logits untuk semua input_ids (kasus khusus). Hanya logits token terakhir yang diperlukan untuk generasi, dan menghitungnya hanya untuk token tersebut dapat menghemat memori, yang menjadi cukup signifikan untuk urutan panjang atau ukuran kosakata besar. Jika berupa torch.Tensor, harus 1D yang sesuai dengan indeks yang akan dipertahankan pada dimensi panjang urutan. Ini berguna saat menggunakan format tensor terpadu (satu dimensi untuk batch dan panjang urutan).

Metode forward dari ShieldGemma2ForImageClassification menimpa metode khusus __call__.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

Update on GitHub

←SAM3-LiteText SigLIP→