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

نُشر هذا النموذج في أوراق HF في 2025-04-01 وسُهم به في Hugging Face Transformers في 2025-03-20.

FlashAttention SDPA

ShieldGemma 2

نظرة عامة

قُدِّم نموذج ShieldGemma 2 في تقرير تقني من Google. يُبنى ShieldGemma 2 على Gemma 3، وهو نموذج يحتوي على 4 مليارات (4B) من المعاملات، يفحص سلامة كلٍّ من الصور الاصطناعية والطبيعية مقابل فئات رئيسية لمساعدتك في بناء مجموعات بيانات ونماذج قوية. ومع إضافة هذا النموذج إلى عائلة نماذج Gemma، أصبح بإمكان الباحثين والمطورين الآن تقليل مخاطر المحتوى الضار في نماذجهم بسهولة عبر مجالات الضرر الرئيسية كما هو موضح أدناه:

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

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

تمت مساهمة هذا النموذج من قِبل Ryan Mullins.

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

  • يوفر ShieldGemma 2 معالجًا (Processor) يقبل قائمة من images وقائمة اختيارية من policies كمدخلات، ويبني دفعة من الأوامر (prompts) كجداء هاتين القائمتين باستخدام قالب المحادثة (chat template) المُقدَّم.
  • يمكنك توسيع السياسات المدمجة في ShieldGemma باستخدام معامل custom_policies الخاص بالمعالج (Processor). استخدام المفتاح نفسه لأحد السياسات المدمجة سيؤدي إلى استبدال تلك السياسة بتعريفك المخصص.
  • لا يدعم ShieldGemma 2 قدرات اقتصاص الصور المستخدمة في Gemma 3.

التصنيف مقابل السياسات المدمجة

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)

التصنيف مقابل السياسات المخصصة

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

< >

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

المعاملات

  • images — صورة واحدة أو قائمة من الصور لإدراجها في الدفعة.
  • text — غير مدعوم.
  • videos — غير مدعوم.
  • audio — غير مدعوم.
  • kwargs — قاموس اختياري لحجج الكلمات المفتاحية لضبط المعالج. تشمل القيم الممكنة:
    • custom_policies: تعريفات سياسات إضافية تُكمّل self.policy_definitions المُمرّرة إلى مُنشئ الكائن. لاحظ أن custom_policies التي تشترك في مفتاح مع self.policy_definitions ستُلغي وصف السياسة الأصلي.
    • policies: (اختياري) قائمة بمفاتيح من قاموس self.policy_definitions | custom_policies المشترك، وهي مفاتيح ذات اهتمام خاص للصور المُقدَّمة. إذا كانت القائمة فارغة أو None، فسيتم توليد الأوامر (prompts) لكل مفتاح في القاموس المشترك.

يولّد دفعة من المدخلات من الصور المُقدَّمة.

تم تدريب ShieldGemma على تصنيف محتوى الصور من حيث الامتثال للسياسات باستخدام بناء محدد للموجّهات. يولّد هذا المعالج دفعة من هذه الموجّهات من الصور المُقدَّمة من خلال:

  1. إنشاء قائمة بالمحادثات، محادثة واحدة لكل زوج <image, policy>؛
  2. تحويل هذه المحادثات إلى نص باستخدام self.apply_chat_template()؛
  3. ترميز المحادثات والصور باستخدام نفس التقنيات المستخدمة في Gemma3Processor.

ShieldGemma2Config

فئة 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 )

المعاملات

  • 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) المستخدم لتغليف موجه الصورة.
  • eoi_token_index (int، اختياري، القيمة الافتراضية 256000) — مؤشر رمز نهاية الصورة (end-of-image token index) المستخدم لتغليف موجه الصورة.
  • 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

ترث كائنات التهيئة من 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

فئة transformers.ShieldGemma2ForImageClassification

< >

( config: ShieldGemma2Config )

المعاملات

  • config (ShieldGemma2Config) — فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. لا يؤدي التهيئة باستخدام ملف الإعدادات إلى تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة from_pretrained() لتحميل أوزان النموذج.

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

يرث هذا النموذج من PreTrainedModel. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التحميل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضًا فئة فرعية من torch.nn.Module في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

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 )

المعاملات

  • input_ids (torch.LongTensor بشكل (batch_size, sequence_length), اختياري) — مؤشرات رموز تسلسل الإدخال في قاموس الكلمات. سيتم تجاهل الحشو افتراضيًا.

    يمكن الحصول على الفهارس باستخدام AutoTokenizer. راجع PreTrainedTokenizer.encode() و PreTrainedTokenizer.call() للتفاصيل.

    ما هي معرّفات الإدخال؟

  • 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 للرموز التي تم إخفاؤها.

    ما هي أقنعة الانتباه؟

  • position_ids (torch.LongTensor بشكل (batch_size, sequence_length), اختياري) — مؤشرات مواضع رموز كل تسلسل إدخال في تضمينات المواضع. يتم اختيارها ضمن النطاق [0, config.n_positions - 1].

    ما هي معرّفات المواقع؟

  • past_key_values (~cache_utils.Cache, اختياري) — حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكون هذا عادةً من past_key_values الذي يعيده النموذج في مرحلة سابقة من فك الترميز، عندما use_cache=True أو config.use_cache=True.

    يُسمح فقط بمرجع Cache كمدخل، راجع دليل ذاكرة kv لدينا. إذا لم يتم تمرير past_key_values، فسيتم تهيئة 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 يتوافق مع رمز sentence A،
    • 1 يتوافق مع رمز sentence B.

    ما هي معرّفات أنواع الرموز؟

  • inputs_embeds (torch.Tensor من الشكل (batch_size, sequence_length, hidden_size)، اختياري) — اختياريًا، بدلاً من تمرير input_ids، يمكنك اختيار تمرير تمثيل مضمّن مباشرة. وهذا مفيد إذا كنت ترغب في الحصول على مزيد من التحكم في كيفية تحويل فهارس input_ids إلى المتجهات المرتبطة بها، مقارنةً بمصفوفة البحث المضمّنة الداخلية للنموذج.
  • labels (torch.LongTensor of shape (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، اختياري) — ما إذا كان يجب إرجاع تensors الانتباه لجميع طبقات الانتباه أم لا. راجع attentions ضمن tensors المُرجعة لمزيد من التفاصيل.
  • output_hidden_states (bool، اختياري) — ما إذا كان يجب إرجاع حالات الطبقات المخفية لجميع الطبقات. راجع hidden_states ضمن الموترات المُرجعة للحصول على مزيد من التفاصيل.
  • return_dict (bool، اختياري) — ما إذا كان يجب إرجاع ModelOutput بدلاً من tuple عادي.
  • logits_to_keep (Union[int, torch.Tensor]، اختياري، القيمة الافتراضية 0) — إذا كان int، يتم حساب logits لآخر logits_to_keep رموز. إذا كانت القيمة 0، يتم حساب logits لجميع input_ids (حالة خاصة). لا يُحتاج إلى logits إلا للرمز الأخير في عملية التوليد، ويمكن أن يوفر حسابها لذلك الرمز وحده ذاكرة كبيرة، وهو أمر مهم بشكل ملحوظ للتسلسلات الطويلة أو حجم المفردات الكبير. إذا كان torch.Tensor، يجب أن يكون بعدًا واحدًا (1D) ويتوافق مع الفهارس التي يجب الاحتفاظ بها في بُعد طول التسلسل. يكون هذا مفيدًا عند استخدام تنسيق المصفوفات المعبأة (packed tensor format) (بعد واحد لكل من الدفعة وطول التسلسل).

تتجاوز طريقة ShieldGemma2ForImageClassification الخاصة بالتقديم (forward) الطريقة الخاصة __call__.

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

Update on GitHub

←SAM3-LiteText SigLIP→