# ShieldGemma 2

## Ikhtisar

Model ShieldGemma 2 diusulkan dalam [laporan teknis](https://huggingface.co/papers/2504.01081) oleh Google. ShieldGemma 2, yang dibangun di atas [Gemma 3](https://ai.google.dev/gemma/docs/core/model_card_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](https://huggingface.co/RyanMullins).

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

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

### Klasifikasi terhadap Kebijakan Kustom

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

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/shieldgemma2/processing_shieldgemma2.py#L60)

#### __call__[[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'>)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/shieldgemma2/processing_shieldgemma2.py#L84)

**Parameter:**

images : Satu gambar atau daftar gambar untuk 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 disediakan. Jika kosong atau None, prompt akan dihasilkan untuk setiap kunci dalam kamus gabungan.

**Mengembalikan:**

A `BatchFeature` yang berisi `input_ids`, `pixel_values`, dan sebagainya, di mana setiap Tensor memiliki bentuk `(len(images) * len(policies), )`, dan urutan dalam batch akan berupa img1_policy1, ... img1_policyN, ... imgM_policyN.

Membuat batch input dari gambar yang disediakan.

ShieldGemma dilatih untuk mengklasifikasikan konten gambar untuk 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[[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)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/shieldgemma2/configuration_shieldgemma2.py#L26)

**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*, default 256000) : Indeks token akhir gambar untuk membungkus prompt gambar.

image_token_index (`int`, *opsional*, defaultnya `262144`) : Indeks token gambar yang digunakan sebagai placeholder untuk gambar input.

initializer_range (`float`, *opsional*, defaultnya `0.02`) : Deviasi standar dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.

tie_word_embeddings (`bool`, *opsional*) : Apakah akan mengikat word embeddings. Bawaan ke nilai `text_config.tie_word_embeddings` jika tidak diatur.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari Shieldgemma2Model. Kelas ini digunakan untuk membuat instans model Shieldgemma2 sesuai dengan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari [google/shieldgemma-2-4b-it](https://huggingface.co/google/shieldgemma-2-4b-it)

Objek konfigurasi mewarisi dari [PreTrainedConfig](/docs/transformers/main/id/main_classes/configuration#transformers.PreTrainedConfig) dan dapat digunakan untuk mengontrol keluaran model. Baca dokumentasi dari [PreTrainedConfig](/docs/transformers/main/id/main_classes/configuration#transformers.PreTrainedConfig) untuk informasi lebih lanjut.

Contoh:

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

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/shieldgemma2/modeling_shieldgemma2.py#L44)

**Parameter:**

config ([ShieldGemma2Config](/docs/transformers/main/id/model_doc/shieldgemma2#transformers.ShieldGemma2Config)) : Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode [from_pretrained()](/docs/transformers/main/id/main_classes/model#transformers.PreTrainedModel.from_pretrained) untuk memuat bobot model.

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

Model ini mewarisi dari [PreTrainedModel](/docs/transformers/main/id/main_classes/model#transformers.PreTrainedModel). Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka ini untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran input embeddings, memangkas heads, dll.)

Model ini juga merupakan subclass dari [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#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[[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)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/shieldgemma2/modeling_shieldgemma2.py#L72)

**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](/docs/transformers/main/id/model_doc/auto#transformers.AutoTokenizer). Lihat [PreTrainedTokenizer.encode()](/docs/transformers/main/id/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) dan [PreTrainedTokenizer.__call__()](/docs/transformers/main/id/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) untuk detailnya. [Apa itu input IDs?](../glossary#input-ids)

pixel_values (`torch.Tensor` 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 pelaksanaan attention pada indeks token padding. Nilai mask dipilih dalam `[0, 1]`:  - 1 untuk token yang **tidak di-mask**, - 0 untuk token yang **di-mask**.  [Apa itu attention masks?](../glossary#attention-mask)

position_ids (`torch.LongTensor` dengan bentuk `(batch_size, sequence_length)`, *opsional*) : Indeks posisi token dari setiap urutan input dalam embedding posisi. Dipilih dalam rentang `[0, config.n_positions - 1]`.  [Apa itu position ID?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *opsional*) : Hidden-states yang telah 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](/docs/transformers/main/id/internal/generation_utils#transformers.Cache) yang diizinkan sebagai input, lihat [panduan kv cache](https://huggingface.co/docs/transformers/en/kv_cache) kami. Jika tidak ada `past_key_values` yang diteruskan, [DynamicCache](/docs/transformers/main/id/internal/generation_utils#transformers.DynamicCache) akan diinisialisasi secara default. Model akan mengoutput format cache yang sama dengan yang diberikan sebagai input. Jika `past_key_values` digunakan, pengguna diharapkan untuk hanya menginput `input_ids` yang belum diproses (yang tidak memiliki state past key value mereka 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 dalam `[0, 1]`:  - 0 sesuai dengan token *sentence A*, - 1 sesuai dengan token *sentence B*.  [Apa itu token type IDs?](../glossary#token-type-ids)

inputs_embeds (`torch.Tensor` dengan bentuk `(batch_size, sequence_length, hidden_size)`, *opsional*) : Secara opsional, alih-alih meneruskan `input_ids`, Anda dapat memilih untuk langsung meneruskan representasi tertanam. Ini berguna jika Anda ingin lebih banyak kendali atas cara mengonversi indeks `input_ids` menjadi vektor terkait daripada 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 diatur 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 perhatian dari semua lapisan perhatian. 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](/docs/transformers/main/id/main_classes/output#transformers.utils.ModelOutput) alih-alih tuple biasa.

logits_to_keep (`Union[int, torch.Tensor]`, *opsional*, defaultnya `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).

**Mengembalikan:**

Instans `ShieldGemma2ImageClassifierOutputWithNoAttention` yang berisi logits dan probabilitas yang terkait dengan prediksi model terhadap token `Yes` atau `No` sebagai respons terhadap prompt tersebut, yang tertangkap dalam properti berikut.

*   `logits` (`torch.Tensor` dengan bentuk `(batch_size, 2)`): Posisi pertama di sepanjang dim=1 adalah logits untuk token `Yes` dan posisi kedua di sepanjang dim=1 adalah logits untuk token `No`.
*   `probabilities` (`torch.Tensor` dengan bentuk `(batch_size, 2)`): Posisi pertama di sepanjang dim=1 adalah probabilitas memprediksi token `Yes` dan posisi kedua di sepanjang dim=1 adalah probabilitas memprediksi token `No`.

Prompt ShieldGemma disusun sedemikian rupa sehingga memprediksi token `Yes` berarti konten *melanggar* kebijakan yang dijelaskan. Jika Anda hanya tertarik pada kondisi pelanggaran, gunakan `violated = outputs.probabilities[:, 1]` untuk mengekstrak potongan tersebut dari tensor output.

Saat digunakan dengan `ShieldGemma2Processor`, nilai `batch_size` akan sama dengan `len(images) * len(policies)`, dan urutan di dalam batch akan berupa img1_policy1, ... img1_policyN, ... imgM_policyN.

Metode forward dari [ShieldGemma2ForImageClassification](/docs/transformers/main/id/model_doc/shieldgemma2#transformers.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.