# Laguna

Laguna هي عائلة نماذج اللغة من نوع مزيج الخبراء (mixture-of-experts) الخاصة بـ Poolside. الفروق المحددة في Laguna مقارنةً بنموذج Transformer قياسي من نوع SwiGLU MoE هي:

- **عدد الرؤوس لكل طبقة** عبر `num_attention_heads_per_layer` — يمكن أن تمتلك طبقات المُفكِّك المختلفة أعدادًا مختلفة من رؤوس الاستعلام مع مشاركة نفس شكل ذاكرة KV.
- **موجِّه Sigmoid MoE مع موازنة حمولة خالية من الخسارة المساعدة** ([arXiv:248.15664](https://huggingface.co/papers/2408.15664)) وقصّ اختياري ناعم للقيم اللوجستية (`moe_router_logit_softcapping`) — درجات الموجِّه هي سيجمويد عنصر-بعنصر للقيم اللوجستية البوابة بالإضافة إلى انحياز متعلَّم لكل خبير (`e_score_correction_bias`) يُضاف فقط عند وقت الاختيار.

## الاستخدام

```python
from transformers import pipeline

pipe = pipeline(
    "text-generation",
    model="poolside/Laguna-XS.2",
    dtype="auto",
    device_map="auto",
)
print(pipe("The capital of France is", max_new_tokens=20, do_sample=False)[0]["generated_text"])
```

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "poolside/Laguna-XS.2"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    dtype=torch.bfloat16,
    device_map="auto",
)

prompt = "The capital of France is"
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
generated = model.generate(**inputs, max_new_tokens=20, do_sample=False)
print(tokenizer.decode(generated[0], skip_special_tokens=True))
```

## ملاحظات

- **واجهات خلفية الانتباه.** يتم دعم SDPA (الافتراضي) وFlashAttention-2 وflex attention. يُطبَّق بواب الانتباه خارج استدعاء النواة، وبالتالي يعمل مع جميع الواجهات الخلفية.
- **`num_attention_heads_per_layer`.** عند تقديمه، يجب أن يساوي طوله `num_hidden_layers`. ويجب أن يكون كل عنصر قابلاً للقسمة على `num_key_value_heads`.
- **`layer_types`.** إذا تُرك غير مُعيَّن، يكون الافتراضي `["full_attention"] * num_hidden_layers`. لتفعيل الانتباه النافذي المنزلق، مرّر قائمة من قيم `"full_attention"` / `"sliding_attention"`.
- **`mlp_layer_types`.** نوع طبقة MLP لكل طبقة، القيم `"dense"` أو `"sparse"`. يجب أن يكون الطول مساوياً لـ `num_hidden_layers`. القيمة الافتراضية هي `["dense"] + ["sparse"] * (num_hidden_layers - 1)` (الطبقة الأولى dense والباقي MoE) إذا لم يتم ضبطها.
- لا يُدعم **`moe_apply_router_weight_on_input=True`** حاليًا مع نواة الخبراء المدمجة (`grouped_mm_experts_forward`)؛ يرمي `validate_architecture` استثناءً عند بناء التهيئة. اضبطه على `False` (القيمة الافتراضية).

## LagunaConfig[[transformers.LagunaConfig]]

#### transformers.LagunaConfig[[transformers.LagunaConfig]]

```python
transformers.LagunaConfig(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, vocab_size: int = 100352, hidden_size: int = 2048, intermediate_size: int = 8192, num_hidden_layers: int = 40, num_attention_heads: int = 48, num_key_value_heads: int = 8, hidden_act: str = 'silu', max_position_embeddings: int = 131072, initializer_range: float = 0.02, rms_norm_eps: float = 1e-06, use_cache: bool = True, tie_word_embeddings: bool = False, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None, sliding_window: int = 512, attention_dropout: float | int = 0.0, moe_intermediate_size: int = 512, shared_expert_intermediate_size: int = 512, num_experts_per_tok: int = 8, num_experts: int = 256, output_router_logits: bool = False, router_aux_loss_coef: float = 0.001, layer_types: list[str] | None = None, pad_token_id: int | None = None, bos_token_id: int | None = None, eos_token_id: int | list[int] | None = None, head_dim: int = 128, attention_bias: bool = False, gating: bool | str = True, num_attention_heads_per_layer: list[int] | None = None, mlp_layer_types: list[str] | None = None, moe_routed_scaling_factor: float = 1.0, moe_apply_router_weight_on_input: bool = False, moe_router_logit_softcapping: float = 0.0)
```

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

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

vocab_size (*int*، *اختياري*، القيمة الافتراضية *100352*) : حجم مفردات النموذج. يحدد عدد الرموز المختلفة التي يمكن تمثيلها بواسطة *input_ids*.

hidden_size (*int*، *optional*، القيمة الافتراضية *2048*) : بُعد التمثيلات المخفية.

intermediate_size (*int*، *optional*، القيمة الافتراضية *8192*) : بُعد تمثيلات MLP.

num_hidden_layers (*int*، *optional*، القيمة الافتراضية *40*) : عدد الطبقات المخفية في مُفكِّك Transformer.

num_attention_heads (*int*، *optional*، القيمة الافتراضية *48*) : عدد رؤوس الانتباه لكل طبقة انتباه في مُفكِّك Transformer.

num_key_value_heads (*int*، *optional*، القيمة الافتراضية *8*) : هذا هو عدد رؤوس key_value التي يجب استخدامها لتنفيذ Grouped Query Attention. إذا كان *num_key_value_heads=num_attention_heads*، فسيستخدم النموذج Multi Head Attention (MHA)، وإذا كان *num_key_value_heads=1* فسيستخدم النموذج Multi Query Attention (MQA)، وإلا فسيتم استخدام GQA. عند تحويل نقطة تحقق متعددة الرؤوس إلى نقطة تحقق GQA، يجب بناء كل مجموعة من رؤوس key و value عن طريق meanpooling جميع الرؤوس الأصلية داخل تلك المجموعة. لمزيد من التفاصيل، راجع [هذا الورق](https://huggingface.co/papers/2305.13245). إذا لم يتم تحديد ذلك، فسيكون الافتراضي *num_attention_heads*.

hidden_act (*str*، *اختياري*، القيمة الافتراضية *silu*) : دالة التنشيط غير الخطية (دالة أو نص) في المُفكِّك. على سبيل المثال، *"gelu"*، *"relu"*، *"silu"*، وما إلى ذلك.

max_position_embeddings (*int*، *اختياري*، القيمة الافتراضية *131072*) : الحد الأقصى لطول التسلسل الذي قد يُستخدم به هذا النموذج على الإطلاق.

initializer_range (*float*، *optional*، القيمة الافتراضية *0.02*) : الانحراف المعياري لـ truncated_normal_initializer المستخدم لتجميع جميع مصفوفات الأوزان.

rms_norm_eps (*float*، *optional*، القيمة الافتراضية *1e-06*) : قيمة الإيبسلون المستخدمة في طبقات تطبيع rms.

use_cache (*bool*, *optional*, defaults to *True*) : Whether or not the model should return the last key/values attentions (not used by all models). Only relevant if *config.is_decoder=True* or when the model is a decoder-only generative model.

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

rope_parameters (*Union[~modeling_rope_utils.RopeParameters, dict]*، *اختياري*) : قاموس يحتوي على معاملات التهيئة الخاصة بتضمينات RoPE. يجب أن يحتوي القاموس على قيمة لـ *rope_theta*، وبشكل اختياري معاملات تُستخدم للتوسيع في حال رغبتك في استخدام RoPE مع *max_position_embeddings* أطول.

sliding_window (*int*، *اختياري*، القيمة الافتراضية *512*) : حجم نافذة الانتباه النافذة المنزلقة. إذا كانت *None*، فلا تُطبَّق نافذة منزلقة.

attention_dropout (*Union[float, int]*، *اختياري*، القيمة الافتراضية *0.0*) : نسبة الإسقاط (dropout) لاحتمالات الانتباه.

moe_intermediate_size (*int*، *optional*، القيمة الافتراضية *512*) : الحجم الوسيط لشبكات MLP الخاصة بالخبراء الموجَّهين.

shared_expert_intermediate_size (*int*، *optional*، القيمة الافتراضية *512*) : الحجم الوسيط لشبكات MLP الخاصة بالخبراء المشتركين.

num_experts_per_tok (*int*، *اختياري*، القيمة الافتراضية *8*) : عدد الخبراء الذين يُوجَّه إليهم كل رمز. هذه هي قيمة top-k الخاصة بتوجيه اختيار الرموز.

num_experts (*int*، *اختياري*، القيمة الافتراضية *256*) : عدد الخبراء الموجَّهين في طبقات MoE.

output_router_logits (*bool*، *اختياري*، القيمة الافتراضية *False*) : ما إذا كان يجب على النموذج إرجاع قيم التوجيه (router logits). تمكين هذا الخيار سيتيح أيضًا للنموذج إخراج الخسارة المساعدة، بما في ذلك خسارة موازنة الحمل وخسارة توجيه z.

router_aux_loss_coef (*float*، *optional*، القيمة الافتراضية *0.001*) : معامل خسارة موازنة الحمل المساعدة. يُستخدم لعقابلة عدم تساوي توجيه الخبراء في نماذج MoE.

layer_types (*list[str]*، *اختياري*) : قائمة تُقرن بشكل صريح كل فهرس طبقة بنوعها. إذا لم تُقدَّم، فسيتم توليدها تلقائيًا بناءً على قيم الإعداد.

pad_token_id (*int*, *اختياري*) : معرّف الرمز المستخدم للتعبئة في المفردات.

bos_token_id (*int*، *اختياري*) : معرّف الرمز المستخدم لبدء البث في المفردات.

eos_token_id (*Union[int, list[int]]*، *اختياري*) : معرّف الرمز المستخدم لنهاية البث في المفردات.

head_dim (*int*، *optional*، القيمة الافتراضية *128*) : بُعد رأس الانتباه. إذا كانت القيمة None، فستكون القيمة الافتراضية هي hidden_size // num_attention_heads

attention_bias (*bool*، *اختياري*، القيمة الافتراضية *False*) : ما إذا كان سيتم استخدام انحياز في طبقات الإسقاط للاستعلام والمفتاح والقيمة والمخرجات أثناء الانتباه الذاتي.

gating (*bool* أو *str*، *اختياري*، القيمة الافتراضية *True*) : حُسن تقسيم بوابة Softplus. `True` أو `"per-head"` يطبّق بوابة واحدة لكل رأس، مع بثّها عبر `head_dim`؛ بينما `"per-element"` يطبّق بوابة واحدة لكل قناة `(head, head_dim)`.

num_attention_heads_per_layer (*list[int]*، *اختياري*) : تجاوز لكل طبقة لـ `num_attention_heads`. يجب أن تكون الطول مساويًا لـ `num_hidden_layers`.

mlp_layer_types (*list[str]*، *اختياري*) : نوع MLP لكل طبقة — `"dense"` أو `"sparse"`. يجب أن يكون الطول مساويًا لـ `num_hidden_layers`. الافتراضي هو أن تكون الطبقة الأولى `"dense"` والباقي `"sparse"`.

moe_routed_scaling_factor (*float*، *optional*، القيمة الافتراضية 1.0) : قيمة عددية تُطبَّق على مخرجات الخبير الموجَّه قبل دمجها مع مخرجات الخبير المشترك.

moe_apply_router_weight_on_input (*bool*، *اختياري*، القيمة الافتراضية *False*) : ما إذا كان سيتم تطبيق أوزان الموجّه على مدخل MoE بدلاً من المخرج. غير مدعوم في transformers بعد؛ سيؤدي `True` إلى رفع `NotImplementedError` حاليًا.

moe_router_logit_softcapping (*float*, *optional*, الافتراضي 0.0) : معامل التوسيع عند تطبيق tanh softcapping على logits الخاصة بـ logits موجّه MoE.

هذه فئة الإعدادات المخزنة لإعدادات نموذج LagunaModel. تُستخدم لاستحداث نموذج Laguna وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ [poolside/laguna-XS.2](https://huggingface.co/poolside/laguna-XS.2)

ترث كائنات التهيئة من [*PreTrainedConfig*] ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ [*PreTrainedConfig*] لمزيد من المعلومات.

مثال:

```python
>>> from transformers import LagunaModel, LagunaConfig

>>> configuration = LagunaConfig()
>>> model = LagunaModel(configuration)
>>> configuration = model.config
```

#### validate_architecture[[transformers.LagunaConfig.validate_architecture]]

```python
validate_architecture()
```

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

جزء من التحقق المدعوم بواسطة `@strict`.

## LagunaModel[[transformers.LagunaModel]]

#### transformers.LagunaModel[[transformers.LagunaModel]]

```python
transformers.LagunaModel(config: LagunaConfig)
```

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

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

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

نموذج Laguna العاري الذي يُخرج حالات مخفية خام دون أي رأس محدد في الأعلى.

يرث هذا النموذج من [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.LagunaModel.forward]]

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

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

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

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)

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

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

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

**يعيد:** `MoeModelOutputWithPast` أو `tuple(torch.Tensor)`

`MoeModelOutputWithPast` أو مجموعة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتمادًا على الإعدادات ([LagunaConfig](/docs/transformers/main/ar/model_doc/laguna#transformers.LagunaConfig)) والمدخلات.

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

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

- **last_hidden_state** (`torch.Tensor` من الشكل `(batch_size, sequence_length, hidden_size)`) -- تسلسل من حالات الإخفاء (hidden-states) عند مخرج الطبقة الأخيرة من النموذج.
- **past_key_values** (`Cache`، *اختياري*، يُعاد عند تمرير `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).

  تحتوي على حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي، وفي كتل الانتباه المتقاطع اختياريًا إذا كان `config.is_encoder_decoder=True`) يمكن استخدامها (انظر مدخل `past_key_values`) لتسريع فك الترميز التسلسلي.
- **hidden_states** (`tuple(torch.Tensor)`، *اختياري*، يُعاد عند تمرير `output_hidden_states=True` أو عند تعيين `config.output_hidden_states=True`) -- مجموعة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل طبقة) بأبعاد `(batch_size, sequence_length, hidden_size)`.

  حالات النموذج المخفية عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي الاختيارية.
- **attentions** (`tuple(torch.Tensor)`، *اختياري*، يُعاد عند تمرير `output_attentions=True` أو عند تعيين `config.output_attentions=True`) -- مجموعة من `torch.Tensor` (واحدة لكل طبقة) بأبعاد `(batch_size, num_heads, sequence_length, sequence_length)`.

  أوزان الانتباه بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.
- **router_logits** (`tuple(torch.Tensor)`، *اختياري*، يُعاد عند تمرير `output_router_probs=True` و`config.add_router_probs=True` أو عند `config.output_router_probs=True`) -- مجموعة من `torch.Tensor` (واحدة لكل طبقة) بأبعاد `(batch_size, sequence_length, num_experts)`.

  قيمات التوجيه الخام (بعد تطبيق دالة softmax) التي تحسبها وحدات التوجيه في نماذج مزيج الخبراء (MoE)، وتُستخدم هذه القيم لحساب الخسارة المساعدة في نماذج مزيج الخبراء.

## LagunaForCausalLM[[transformers.LagunaForCausalLM]]

#### transformers.LagunaForCausalLM[[transformers.LagunaForCausalLM]]

```python
transformers.LagunaForCausalLM(config: LagunaConfig)
```

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

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

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

نموذج لاجونا لنمذجة اللغة السببية.

يرث هذا النموذج من [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.LagunaForCausalLM.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, output_router_logits: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

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)

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

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

labels (`torch.LongTensor` من الشكل `(batch_size, sequence_length)`، *اختياري*) : تسميات لحساب خسارة نمذجة اللغة المقنّعة. يجب أن تكون الفهارس إما ضمن `[0, ..., config.vocab_size]` أو -100 (انظر `input_ids` docstring). يتم تجاهل الرموز التي تكون فهارسها مضبوطة على `-100` (مقنّعة)، ولا تُحسب الخسارة إلا للرموز التي تسمياتها ضمن `[0, ..., config.vocab_size]`.

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

output_router_logits (`bool`، *اختياري*) : ما إذا كان يجب إرجاع قيم logits لجميع الموجّهات (routers) أم لا. تُفيد هذه القيم في حساب خسارة الموجّه (router loss)، ولا ينبغي إرجاعها أثناء الاستدلال.

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

**يعيد:** `MoeCausalLMOutputWithPast` أو `tuple(torch.Tensor)`

`MoeCausalLMOutputWithPast` أو مجموعة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتماداً على الإعداد ([LagunaConfig](/docs/transformers/main/ar/model_doc/laguna#transformers.LagunaConfig)) والمدخلات.

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

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

- **loss** (`torch.Tensor` من الشكل `(1,)`، *اختياري*، يُعاد عند توفير `labels`) -- خسارة نمذجة اللغة (لتوقع الرمز التالي).
- **logits** (`torch.Tensor` من الشكل `(batch_size, sequence_length, config.vocab_size)`) -- درجات التنبؤ لرأس نمذجة اللغة (درجات لكل رمز في المفردات قبل SoftMax).
- **aux_loss** (`torch.Tensor`، *اختياري*، يُعاد عند تمرير `output_router_logits=True` أو عند تعيين `config.output_router_logits=True`، وفي حال تدريب النموذج لموجّهه باستخدام خسارة توازن الأحمال) -- خسارة مساعدة لتوازن الأحمال الخاصة بالوحدات المتناثرة. تُعيد النماذج التي توازن خبرائها باستخدام انحياز الموجّه بدلاً من ذلك (DeepSeek-V3 والهندسات المشتقة منه) قيمة `None` هنا مع الاستمرار في إرجاع `router_logits`.
- **router_logits** (`tuple(torch.Tensor)`، *اختياري*، يُعاد عند تمرير `output_router_logits=True` أو عند تعيين `config.output_router_logits=True`) -- مجموعة من `torch.Tensor` (واحدة لكل طبقة متناثرة) بأبعاد `(batch_size * sequence_length, num_experts)`.

  قيمات التوجيه الخام (logits) التي يحسبها موجّهات MoE. يمكن استخدامها لحساب خسارة موازنة الحمل أو لفحص كيفية توزيع الرموز على الخبراء.
- **past_key_values** (`Cache`، *اختياري*، يُعاد عند تمرير `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`) لتسريع فك الترميز التسلسلي.
- **hidden_states** (`tuple(torch.Tensor)`، *اختياري*، يُعاد عند تمرير `output_hidden_states=True` أو عند تعيين `config.output_hidden_states=True`) -- مجموعة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل طبقة) بأبعاد `(batch_size, sequence_length, hidden_size)`.

  حالات النموذج المخفية عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي الاختيارية.
- **attentions** (`tuple(torch.Tensor)`، *اختياري*، يُعاد عند تمرير `output_attentions=True` أو عند تعيين `config.output_attentions=True`) -- مجموعة من `torch.Tensor` (واحدة لكل طبقة) بأبعاد `(batch_size, num_heads, sequence_length, sequence_length)`.

  أوزان الانتباه بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.

مثال:

```python
```