# ShieldGemma 2

## نظرة عامة

قُدِّم نموذج ShieldGemma 2 في [تقرير تقني](https://huggingface.co/papers/2504.01081) من Google. يُبنى ShieldGemma 2 على [Gemma 3](https://ai.google.dev/gemma/docs/core/model_card_3)، وهو نموذج يحتوي على 4 مليارات (4B) من المعاملات، يفحص سلامة كلٍّ من الصور الاصطناعية والطبيعية مقابل فئات رئيسية لمساعدتك في بناء مجموعات بيانات ونماذج قوية. ومع إضافة هذا النموذج إلى عائلة نماذج Gemma، أصبح بإمكان الباحثين والمطورين الآن تقليل مخاطر المحتوى الضار في نماذجهم بسهولة عبر مجالات الضرر الرئيسية كما هو موضح أدناه:

- لا يُسمح بمحتوى جنسي صريح: يجب ألا يحتوي الصورة على محتوى يصوّر أفعالاً جنسية صريحة أو بذيئة (مثل: الإباحية، العُري الإباحي، تصوير الاغتصاب أو الاعتداء الجنسي).
- لا توجد محتويات خطيرة: يجب ألا تحتوي الصورة على محتوى يسهّل أو يشجّع على أنشطة قد تسبب ضرراً في العالم الحقيقي (مثل: تصنيع الأسلحة النارية والأجهزة المتفجرة، الترويج للإرهاب، تعليمات الانتحار).
- لا يُسمح بمحتوى عنيف أو دموي: يجب ألا يحتوي الصورة على محتوى يصوّر عنفاً صادماً أو مثيراً للجدل أو عنفاً مفرطاً بلا مبرر (مثل: كميات كبيرة من الدم والجروح، أو عنف مفرط ضد الحيوانات، أو إصابات بالغة أو لحظة الوفاة).

نوصي باستخدام ShieldGemma 2 كمرشّح للمدخلات لنماذج اللغة البصرية، أو كمرشّح للمخرجات لأنظمة توليد الصور. ولتدريب نموذج أمان صور قوي، قمنا بتجهيز مجموعات بيانات تدريبية من الصور الطبيعية والاصطناعية، وضبطنا Gemma 3 بالتعليمات لتُظهر أداءً قوياً.

تمت مساهمة هذا النموذج من قِبل [Ryan Mullins](https://huggingface.co/RyanMullins).

## مثال على الاستخدام

- يوفر ShieldGemma 2 معالجًا (Processor) يقبل قائمة من `images` وقائمة اختيارية من `policies` كمدخلات، ويبني دفعة من الأوامر (prompts) كجداء هاتين القائمتين باستخدام قالب المحادثة (chat template) المُقدَّم.
- يمكنك توسيع السياسات المدمجة في ShieldGemma باستخدام الحجة `custom_policies` الخاصة بالمعالج (Processor). استخدام المفتاح نفسه كأحد السياسات المدمجة سيؤدي إلى تجاوز تلك السياسة بتعريفك المخصص.
- لا يدعم 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#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'>)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/shieldgemma2/processing_shieldgemma2.py#L84)

**المعاملات:**

images : صورة واحدة أو قائمة بالصور لإدراجها في الدفعة.

text : غير مدعوم.

videos : غير مدعوم.

audio : غير مدعوم.

kwargs : قاموس اختياري لحجج الكلمات المفتاحية لتكوين المعالج. تشمل القيم الممكنة: * `custom_policies`: تعريفات سياسات إضافية تكمل `self.policy_definitions` المُمررة إلى منشئ الكائن. لاحظ أن `custom_policies` التي تشترك في مفتاح مع `self.policy_definitions` ستُلغي وصف السياسة * `policies`: (اختياري) قائمة بمفاتيح في قاموس `self.policy_definitions | custom_policies` المشترك ذات اهتمام خاص للصور المُقدمة. إذا كانت فارغة أو None، فسيتم توليد الأوامر لكل مفتاح في القاموس المشترك.

**يعيد:**

A `BatchFeature` containing `input_ids`, `pixel_values`, etc. where each Tensor is of shape `(len(images) * len(policies), )`, and the order within the batch will be 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) : عدد الرموز لكل تضمين صورة.

boi_token_index (`int`، *اختياري*، القيمة الافتراضية 255999) : فهرس رمز بداية الصورة (begin-of-image token) المستخدم لتغليف موجه الصورة.

eoi_token_index (`int`، *اختياري*، القيمة الافتراضية 256000) : فهرس رمز نهاية الصورة (end-of-image token) المستخدم لتغليف موجه الصورة.

image_token_index (`int`، *اختياري*، القيمة الافتراضية `262144`) : فهرس رمز الصورة المستخدم كحقل محجوز للصور المدخلة.

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/ar/main_classes/configuration#transformers.PreTrainedConfig) ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ [PreTrainedConfig](/docs/transformers/main/ar/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/ar/model_doc/shieldgemma2#transformers.ShieldGemma2Config)) : فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. عند التهيئة باستخدام ملف إعدادات، لا يتم تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

نموذج Shieldgemma2 مع رأس تصنيف الصور في الأعلى، على سبيل المثال لـ ImageNet.

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التنزيل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضاً فئة فرعية من [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق 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)`، *اختياري*) : فهارس رموز تسلسل الإدخال في قاموس الكلمات. سيتم تجاهل الحشو افتراضيًا. يمكن الحصول على الفهارس باستخدام [AutoTokenizer](/docs/transformers/main/ar/model_doc/auto#transformers.AutoTokenizer). راجع [PreTrainedTokenizer.encode()](/docs/transformers/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) و [PreTrainedTokenizer.__call__()](/docs/transformers/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) للتفاصيل. [ما هي معرّفات الإدخال؟](../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)`، *اختياري*) : قناع لتجنب تنفيذ الانتباه على فهارس رموز الحشو. قيم القناع المختارة من `[0, 1]`: - 1 للرموز التي **ليست مقنّعة**، - 0 للرموز التي **مقنّعة**.  [ما هي أقنعة الانتباه؟](../glossary#attention-mask)

position_ids (`torch.LongTensor` من الشكل `(batch_size, sequence_length)`، *اختياري*) : فهارس مواضع رموز كل تسلسل إدخال في تضمينات المواضع. يتم اختيارها من النطاق `[0, config.n_positions - 1]`.  [ما هي معرّفات المواضع؟](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`، *اختياري*) : حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكوّن هذا عادةً من `past_key_values` التي يعيدها النموذج في مرحلة سابقة من فك الترميز، عندما يكون `use_cache=True` أو `config.use_cache=True`. يُسمح فقط بتمرير كائن [Cache](/docs/transformers/main/ar/internal/generation_utils#transformers.Cache) كمدخل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache). إذا لم يتم تمرير `past_key_values`، فسيتم تهيئة [DynamicCache](/docs/transformers/main/ar/internal/generation_utils#transformers.DynamicCache) افتراضيًا. سيُخرج النموذج نفس تنسيق الذاكرة المؤقتة المُدخل. إذا تم استخدام `past_key_values`، يُتوقع من المستخدم إدخال `input_ids` غير المعالجة فقط (تلك التي لم تُعطَ حالات مفاتيح وقيم سابقة لها في هذا النموذج) بأبعاد `(batch_size, unprocessed_length)` بدلاً من جميع `input_ids` بأبعاد `(batch_size, sequence_length)`.

token_type_ids (`torch.LongTensor` من الشكل `(batch_size, sequence_length)`، *اختياري*) : فهارس رموز المقاطع لتحديد الجزء الأول والثاني من المدخلات. يتم اختيار الفهارس من `[0, 1]`: - 0 يقابل رمز *الجملة أ*، - 1 يقابل رمز *الجملة ب*. [ما هي معرّفات أنواع الرموز؟](../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/ar/main_classes/output#transformers.utils.ModelOutput) بدلاً من tuple عادي.

logits_to_keep (`Union[int, torch.Tensor]`، *اختياري*، القيمة الافتراضية `0`) : إذا كان `int`، يتم حساب القيم اللوجستية (logits) لآخر `logits_to_keep` رموز. إذا كانت `0`، يتم حساب القيم اللوجستية لجميع `input_ids` (حالة خاصة). لا تكون قيم اللوجستيات للرمز الأخير فقط ضرورية للتوليد، ويمكن أن يوفر حسابها لذلك الرمز وحده ذاكرة، وهو ما يصبح ذا أهمية كبيرة للترتيبات الطويلة أو لحجم المفردات الكبير. إذا كان `torch.Tensor`، يجب أن يكون بعدًا واحدًا (1D) ويتوافق مع الفهارس التي يجب الاحتفاظ بها في بُعد طول الترتيب. وهذا مفيد عند استخدام تنسيق المصفوفات المعبأة (packed tensor format) (بعد واحد لكل من الدفعة وطول الترتيب).

**يعيد:**

مثال من `ShieldGemma2ImageClassifierOutputWithNoAttention` يحتوي على القيم الاحتمالية (logits) والاحتمالات المرتبطة بتنبؤ النموذج برمز `Yes` أو `No` كاستجابة لذلك الموجه، كما هو موثق في الخصائص التالية.

*   `logits` (`torch.Tensor` من الشكل `(batch_size, 2)`): الموضع الأول على طول dim=1 هو قيم `Yes` للمرجّحات، والموضع الثاني على طول dim=1 هو قيم `No` للمرجّحات.
*   `probabilities` (`torch.Tensor` من الشكل `(batch_size, 2)`): الموضع الأول على طول dim=1 هو احتمال التنبؤ برموز `Yes` والموضع الثاني على طول dim=1 هو احتمال التنبؤ برموز `No`.

تُبنى موجهات ShieldGemma بحيث يعني التنبؤ برمز `Yes` أن المحتوى *يخالف* السياسة كما هو موصوف. إذا كنت مهتمًا فقط بحالة المخالفة، فاستخدم `violated = outputs.probabilities[:, 1]` لاستخراج تلك الشريحة من المصفوفات الناتجة.

عند الاستخدام مع `ShieldGemma2Processor`، ستكون قيمة `batch_size` مساوية لـ `len(images) * len(policies)`، وسيكون الترتيب داخل الدفعة على النحو التالي: img1_policy1، ... img1_policyN، ... imgM_policyN.

تتجاوز طريقة [ShieldGemma2ForImageClassification](/docs/transformers/main/ar/model_doc/shieldgemma2#transformers.ShieldGemma2ForImageClassification) الخاصة بالتقديم (forward) الطريقة الخاصة `__call__`.

على الرغم من أنه يجب تعريف وصفة المرور الأمامي داخل هذه الدالة، إلا أنه ينبغي استدعاء كائن `Module` بدلاً من هذه الدالة، لأن الكائن يتولى تنفيذ خطوات المعالجة المسبقة والمعالجة اللاحقة، بينما تتجاهل الدالة هذه الخطوات بصمت.