# Gemma 4 مساعد موحّد

## نظرة عامة

Gemma 4 Unified Assistant هو نموذج صغير مخصص للنص فقط، يتيح الترميز التخميني (speculative decoding) لنماذج Gemma 4 Unified باستخدام طريقة التنبؤ متعدد الرموز (MTP) ومولّد المرشحين المرتبط بها. تتوفر نماذج مُدرَّبة مسبقًا لتنويعات IT من نموذج Gemma 4 12B.

لمزيد من المعلومات، يرجى الاطلاع على [Gemma4 Assistant](./gemma4_assistant). من حيث البنية والمفهوم، يتشاركان في نفس المفهوم والاختلافات عن النموذج الأساسي الخاص بهما:

*   **يستخدم النموذج بأكمله مشاركة KV**. تتيح هذه التقنية، التي عُرضت لأول مرة مع [Gemma 3n](./gemma3n)، للنموذج إعادة استخدام ذاكرة KV المخزنة التي يملؤها النموذج المستهدف الذي يدعمه المساعد، مما يسمح للمساعد بتجاوز مرحلة التعبئة المسبقة بالكامل، ويقلل بشكل كبير من حساب الانتباه أثناء المرور الأمامي.
*   **قيم `position_ids` ثابتة**. نظرًا لأن ذاكرة KV مشتركة ولا يملك المساعد طريقة لتحديثها، فإن المساعد يتنبأ بجميع الرموز من معرّف الموضع نفسه.
*   **المدخلات هي دمج التضمينات وحالات الإخفاء**. للتكيف مع ذاكرة KV الثابتة و`position_ids`، يستقبل النموذج مدخلاته على شكل دمج `embedding` و`hidden_states` لآخر رمز شوهد من النموذج المستهدف، ثم يرميها إلى فضاء نموذج المساعد عبر تحويل `nn.Linear`. يتغير تعريف آخر رمز شوهد على مدار حلقة فك التشفير المساعد. بالنسبة للرمز الأول المُسود بعد التعبئة المسبقة، سيكون آخر رمز شوهد هو آخر رمز من الاستدعاء. أما في خطوات المسودة اللاحقة، فسيكون آخر رمز شوهد هو آخر رمز ولّده المساعد (ضمن جولة مسودة) أو آخر رمز قبله النموذج المستهدف (بين جولات المسودة).
*   **يُستخدم الانتباه المتقاطع (Cross-attention) لاستغلال سياق النموذج المستهدف بأفضل شكل**. يتيح الانتباه المتقاطع لحالات الاستعلام (query states) التي يولدها المساعد أن تنتبه إلى قيم ذاكرة KV المشتركة من النموذج المستهدف، مما يسمح للمساعد بالتنبؤ بدقة أكبر بعدد أكبر من الرموز المُسودة في كل جولة تدوير.

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

يُظهر المثال أدناه كيفية توليد النص بناءً على صورة باستخدام [Pipeline](/docs/transformers/main/ar/main_classes/pipelines#transformers.Pipeline) أو فئة [AutoModel](/docs/transformers/main/ar/model_doc/auto#transformers.AutoModel).

```py
import torch
from transformers import pipeline

pipeline = pipeline(
    task="image-text-to-text",
    model="google/gemma-4-12B-it",
    assistant_model="google/gemma-4-12B-it-assistant",
)
pipeline(
    images="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg",
    text="<|image|>\n\nWhat is shown in this image?"
)
```

```py
import torch
from transformers import AutoProcessor, AutoModelForImageTextToText

model = AutoModelForImageTextToText.from_pretrained(
    "google/gemma-4-12B-it",
    dtype=torch.bfloat16,
    device_map="auto",
)
assistant_model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-4-12B-it-assistant",
    dtype=torch.bfloat16,
    device_map="auto",
)

processor = AutoProcessor.from_pretrained(
    "google/gemma-4-12B-it",
    padding_side="left"
)
messages = [
    {
        "role": "user", "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
            {"type": "text", "text": "What is shown in this image?"},
        ]
    },
]
inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    add_generation_prompt=True,
).to(model.device)
input_len = inputs["input_ids"].shape[-1]

output = model.generate(**inputs, max_new_tokens=50, assistant_model=assistant_model)
print(processor.decode(output[0][input_len:], skip_special_tokens=True))
```

## Gemma4UnifiedAssistantConfig[[transformers.Gemma4UnifiedAssistantConfig]]

#### transformers.Gemma4UnifiedAssistantConfig[[transformers.Gemma4UnifiedAssistantConfig]]

```python
transformers.Gemma4UnifiedAssistantConfig(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: transformers.configuration_utils.PreTrainedConfig | dict[str, typing.Any] | None = None, backbone_hidden_size: int = 3840, use_ordered_embeddings: bool = False, num_centroids: int = 2048, centroid_intermediate_top_k: int = 32, tie_word_embeddings: bool = True)
```

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

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

text_config (`Union[~configuration_utils.PreTrainedConfig, dict[str, Any]]`, *اختياري*) : كائن الإعدادات أو قاموس العمود الفقري النصي.

backbone_hidden_size (`int`، القيمة الافتراضية 3840) : حجم الطبقة المخفية للنموذج الموحّد المستهدف الذي تم تدريب هذا المساعد باستخدامه.

use_ordered_embeddings (`bool`، القيمة الافتراضية `False`) : إذا كانت `True`، يتم استخدام جدول تضمين بترتيب مثالي يتطلب إعادة ترتيب.

num_centroids (`int`، القيمة الافتراضية 2048) : العدد الإجمالي للمراكز (centroids) لمُضمِّن الأقنعة القائم على المراكز.

centroid_intermediate_top_k (`int`، القيمة الافتراضية 32) : عدد مراكز التجميع النشطة التي يتم اختيارها أثناء الاستدلال.

tie_word_embeddings (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب ربط ترميزات الأوزان وفقاً لخريطة `tied_weights_keys` الخاصة بالنموذج.

هذه فئة الإعدادات المخزنة لإعدادات نموذج Gemma4 Unified AssistantModel. تُستخدم لاستحداث نموذج Gemma4 Unified Assistant وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ [google/gemma-4-12b-it](https://huggingface.co/google/gemma-4-12b-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 (
...     Gemma4UnifiedAssistantConfig,
...     Gemma4UnifiedAssistantForCausalLM,
...     Gemma4UnifiedTextConfig,
... )

>>> # Initializing a Gemma 4 Unified Text config for the assistant.
>>> text_config = Gemma4UnifiedTextConfig(...)

>>> # Initializing a Gemma 4 Unified Assistant config.
>>> configuration = Gemma4UnifiedAssistantConfig(text_config=text_config)

>>> # Initializing a model from the configuration.
>>> model = Gemma4UnifiedAssistantForCausalLM(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## Gemma4UnifiedAssistantForCausalLM[[transformers.Gemma4UnifiedAssistantForCausalLM]]

#### transformers.Gemma4UnifiedAssistantForCausalLM[[transformers.Gemma4UnifiedAssistantForCausalLM]]

```python
transformers.Gemma4UnifiedAssistantForCausalLM(config: Gemma4UnifiedAssistantConfig)
```

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

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

config ([Gemma4UnifiedAssistantConfig](/docs/transformers/main/ar/model_doc/gemma4_unified_assistant#transformers.Gemma4UnifiedAssistantConfig)) : فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. عند التهيئة باستخدام ملف إعدادات، لا يتم تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

نموذج لتفكيك مُساعَد مبني على التنبؤ متعدد الرموز مع Gemma 4.

يرث هذا النموذج من [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 لكل ما يتعلق بالاستخدام العام والسلوك.

#### create_attention_masks[[transformers.Gemma4UnifiedAssistantForCausalLM.create_attention_masks]]

```python
create_attention_masks(inputs_embeds, attention_mask, shared_kv_states)
```

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

جهّز أقنعة الانتباه للنموذج المُساعَد؛ حيث يعمل `shared_kv_states` كذاكرة مؤقتة سابقة في هذه الحالة.

نستخدم أقنعة ثنائية الاتجاه لمراعاة السببية
- لا يوجد فرق في الحالة الحدّية `q_len == 1` إذ تعمل كاهتمام كامل بغضّ النظر عن أي شيء
- يفسر SWA النافذة على أنها تنظر إلى الأمام (المستقبل) عندما يكون `q_idx=1` و`kv>=1`
  - ننتقل من منظور مستقبلي إلى منظور ماضٍ عن طريق قلب محور kv
  - لاستيعاب الحشو الذي لا يتأثر بالموضع، نقوم أيضًا بقلب قناع الانتباه الأساسي قبل الإنشاء الأولي

#### forward[[transformers.Gemma4UnifiedAssistantForCausalLM.forward]]

```python
forward(input_ids: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, attention_mask: dict[str, torch.Tensor] | None = None, shared_kv_states: dict[str, tuple[torch.Tensor, torch.Tensor]] | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

input_ids (`torch.Tensor` من الشكل `(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)

inputs_embeds (`torch.Tensor` من الشكل `(batch_size, sequence_length, hidden_size)`، *اختياري*) : بدلاً من تمرير `input_ids`، يمكنك اختيار تمرير تمثيل مضمّن مباشرةً. هذا مفيد إذا كنت ترغب في الحصول على مزيد من التحكم في كيفية تحويل فهارس `input_ids` إلى المتجهات المرتبطة بها، مقارنةً بمصفوفة البحث المضمّنة الداخلية للنموذج.

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

attention_mask (`dict[str, torch.Tensor]` من الشكل `(batch_size, sequence_length)`، *اختياري*) : قناع لتجنب تنفيذ الانتباه على فهارس رموز الحشو. قيم القناع المختارة في `[0, 1]`: - 1 للرموز التي **ليست مقنّعة**، - 0 للرموز التي **مقنّعة**. [ما هي أقنعة الانتباه؟](../glossary#attention-mask)

shared_kv_states (`dict[str, torch.Tensor` من الشكل `(batch_size, 1, q_len, kv_len)`، *اختياري*) : قاموس يحتوي على قيم KV المحسوبة للطبقة الأخيرة من كل `layer_type` في هذا النموذج.

use_cache (`bool`، *اختياري*) : إذا تم ضبطه على `True`، تُعاد حالات المفاتيح والقيم `past_key_values` ويمكن استخدامها لتسريع فك الترميز (انظر `past_key_values`).

**يعيد:**

`tuple[torch.Tensor, torch.Tensor]`

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

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

مثال:

```python
>>> from transformers import AutoTokenizer, Gemma4UnifiedAssistantForCausalLM, Gemma4UnifiedForConditionalGeneration

>>> model = Gemma4UnifiedForConditionalGeneration.from_pretrained("google/gemma-4-e2b-it")
>>> assistant_model = Gemma4UnifiedAssistantForCausalLM.from_pretrained("google/gemma-4-e2b-it-assistant")
>>> tokenizer = AutoTokenizer.from_pretrained("google/gemma-4-e2b-it")

>>> prompt = "What is your favorite condiment?"
>>> inputs = tokenizer(prompt, return_tensors="pt")

>>> # Generate
>>> generate_ids = model.generate(inputs.input_ids, assistant_model=assistant_model, max_length=30)
>>> tokenizer.batch_decode(generate_ids, skip_special_tokens=True)[0]
"What is your favorite condiment?"
```