# Beam

## نظرة عامة

[Beam](https://reflection.ai/blog/introducing-beam) هو أول نموذج مفتوح الأوزان من Reflection، وهو نموذج لغة من نوع مزيج الخبراء المتناثر (MoE) بإجمالي 501 مليار معامل و23 مليار معامل نشط لكل رمز، مصمم لأعمال البرمجة والاستدلال ومهام الوكلاء. تم تدريبه مسبقًا على 23.8 تريليون رمز، ثم خضع لتدريب لاحق باستخدام التعلم المعزز غير المتزامن على نطاق واسع. نموذج Beam نصي فقط، وهو يستدل قبل كل إجابة. إعداد مستوى الجهد الاستدلالي في قالب المحادثة يتحكم في مقدار هذا الاستدلال.

يحتوي Beam على 52 طبقة مُفكِّكة (decoder) ويجمع بين الميزات التالية:

- **انتباه هجين منزلق وكامل.** تستخدم كل طبقة سادسة والطبقة الأخيرة الانتباه الكامل، بينما تركز الطبقات الأخرى على أحدث `sliding_window` (512) رمز. يحدد `layer_types` النمط.
- **تطبيق RoPE على الطبقات المنزلقة، وتطبيق NoPE على الطبقات الكاملة.** يُفهرس `rope_parameters` حسب نوع الطبقة، ويُشير `None` إلى نوع طبقة لا يحتوي على ترميز موضعي. أما طبقات الانتباه الكاملة فتقوم بتوسيع الاستعلامات بدلاً من ذلك (softmax قابل للتوسع): حيث يُضرب الاستعلام الموجود في الموضع `n` (بدءاً من 1) في `(1 + n / 2048) ** 0.1`، مما يحافظ على انتباه غير مسطّح مع نمو السياق.
- **انتباه مُبوَّب.** انتباه الاستعلامات المُجمَّعة مع 48 رأس استعلام و8 رؤوس مفتاح/قيمة، وتطبيع RMSNorm على كل رأس استعلام ومفتاح. بوابة سيجمويد محسوبة من مدخل الانتباه، مع انحياز متعلَّم لكل رأس، تُقيّم مخرجات الانتباه عنصرًا بعنصر قبل الإسقاط النهائي.
- **MoE المتناثر.** تستخدم الطبقات الثلاث الأولى شبكة عصبية متعددة الطبقات (MLP) كثيفة من نوع SwiGLU، بينما تُوجّه الطبقات الأربع والخمسون المتبقية كل رمز إلى 8 من بين 256 خبيرًا، دون وجود خبير مشترك (حيث يحدد `mlp_layer_types` النمط). يقوم الموجّه بتقييم الخبراء باستخدام دالة sigmoid، ويوازن الحمل باستخدام انحياز متعلّم لكل خبير بدلاً من خسارة مساعدة، ويقيّد كل رمز بأفضل `topk_group` من مجموعات الخبراء `n_group`. تُطبَّع أوزان التوجيه، ويُضرب ناتج MoE في `routed_scaling_factor`.
- **معايير متوسطة مع بقايا مُقيَّمة حسب العمق.** يُغلَّف كل كتلة انتباه وكتلة MLP بمعايير RMSNorm قبلها وبعدها. تُعاد مقياسية عمليات الجمع الباقية بحيث، بعد `k` مساهمة (مع احتساب التضمينات كأول مساهمة)، يكون تدفق البقايا هو مجموعها مقسومًا على `sqrt(k)`.
- **تقييد اللوجيت النهائي.** يتم تقييد اللوجيتات باستخدام `30 * tanh(logits / 30)` (`final_logit_softcapping`).

تُحسب عملية توسيع RMSNorm، ودالة التنشيط SwiGLU، وRoPE، وتوسيع الاستعلامات، والتوجيه، والقصّ الناعم (softcapping) بدقة FP32 لمطابقة الأرقام التي تم تدريب Beam وتقديم الخدمة بها. وتُحفظ أوزان الموجّه (router) والانحياز الخاص بالخبراء بدقة FP32 عند التحميل، وتكون قيم `logits` المُعادَة دائمًا بدقة FP32.

يمكنك العثور على جميع نقاط التفتيش الأصلية الخاصة بـ Beam تحت منظمة [Reflection](https://huggingface.co/reflection).

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

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

يُنسّق قالب المحادثة الخاص بـ Beam المحادثات بتنسيق Harmony الخاص بـ Beam، ويحلّل [قالب الاستجابة](../chat_response_parsing) النص المولَّد إلى رسالة تحتوي على حقول `thinking` و`content` و`tool_calls`. تولّد الأمثلة أدناه ردًّا باستخدام [Pipeline](/docs/transformers/main/ar/main_classes/pipelines#transformers.Pipeline) أو فئة [AutoModelForCausalLM](/docs/transformers/main/ar/model_doc/auto#transformers.AutoModelForCausalLM).

حجم نقطة التفتيش BF16 يبلغ حوالي 1 تيرابايت، لذا تقسم الأمثلة هذا الملف عبر 8 أجهزة، مع وضع خبراء التوجيه الكاملين على كل جهاز باستخدام [توازي الخبراء](../expert_parallelism). شغّلها باستخدام `torchrun --nproc-per-node 8 <script.py>`.

```python
from transformers import DistributedConfig, pipeline

pipe = pipeline(
    task="text-generation",
    model="reflection/Beam-1.0-501B-A23B",
    model_kwargs={"distributed_config": DistributedConfig(tp_size=8, ep_size=8)},
)

messages = [{"role": "user", "content": "Explain in one sentence why the sky is usually blue."}]
output = pipe(messages, max_new_tokens=2048)
reply = output[0]["generated_text"][-1]
print(reply["thinking"])
print(reply["content"])
```

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

model_id = "reflection/Beam-1.0-501B-A23B"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, distributed_config=DistributedConfig(tp_size=8, ep_size=8))

messages = [{"role": "user", "content": "Explain in one sentence why the sky is usually blue."}]
inputs = tokenizer.apply_chat_template(
    messages, add_generation_prompt=True, return_tensors="pt", return_dict=True, reasoning_effort="low"
).to(model.device)

outputs = model.generate(**inputs, max_new_tokens=2048)
generated = tokenizer.decode(outputs[0, inputs["input_ids"].shape[1] :])
message = tokenizer.parse_response(generated, prefix=inputs["input_ids"][0])
print(message["thinking"])
print(message["content"])
```

يُفضَّل استخدام هذا بدلاً من `device_map="auto"`، الذي يضع طبقات كاملة على كل جهاز، ويشغّلها جهازاً تلو الآخر، وقد يستنفد الذاكرة أثناء التحميل.

ولّد عينات باستخدام قيم Beam الموصى بها `temperature=0.7` و`top_p=0.99`، والتي تُعيّنها [GenerationConfig](/docs/transformers/main/ar/main_classes/text_generation#transformers.GenerationConfig) في نقطة الحفظ كقيم افتراضية. مرّر `do_sample=False` لفك الترميز الطمعي.

### جهد الاستدلال

مرّر `reasoning_effort` إلى [apply_chat_template()](/docs/transformers/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.apply_chat_template) للتحكم في مقدار تفكير Beam. يقبل هذا المعامل قيمة عددية صحيحة أو أحد التسميات أدناه. لم يتم تدريب Beam بمستويات جهد أقل من 8، لذلك لا تُحترم القيم الأصغر.

| التسمية | `minimal` | `low` | `medium` | `high` | `xhigh` | `max` |
|---|---|---|---|---|---|---|
| الجهد | 8 | 32 | 64 | 128 | 256 | 512 |

عندما لا يتم تعيين `reasoning_effort`، يستخدم القالب `max`. إذا نفدت `max_new_tokens` أثناء الاستدلال، فإن الرسالة المُحلَّلة تحتوي على `thinking` دون `content`.

### المحادثات متعددة الأدوار

أضِف الرسالة المُحلَّلة إلى السجل كما هي. تتدهور مخرجات Beam في غياب استدلالها السابق، الذي يقرأه قالب المحادثة من `thinking` (يُقبل أيضًا `reasoning_content` و`reasoning`). افتراضيًا، يُعرض دور المساعد الذي لا يحتوي على استدلال مع كتلة استدلال فارغة. مرِّر `allow_missing_thinking=False` لرمي خطأ بدلاً من ذلك عند `add_generation_prompt=True`، وهو ما يُنصح به عند تقديم Beam.

```python
messages.append(message)
messages.append({"role": "user", "content": "And why are sunsets red?"})
inputs = tokenizer.apply_chat_template(
    messages, add_generation_prompt=True, return_tensors="pt", return_dict=True
).to(model.device)
```

### استدعاء الأدوات

مرّر `tools` إلى كلٍّ من [apply_chat_template()](/docs/transformers/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.apply_chat_template) و[parse_response()](/docs/transformers/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.parse_response). عند استخدام `tools`، تُحوَّل الحُجج المُحلَّلة إلى الأنواع المحددة في مخطط كل أداة؛ وبدون ذلك، تكون كل حُجّة نصًا.

```python
def get_weather(city: str):
    """
    Get the current weather in a city.

    Args:
        city: The city name.
    """
    return "Sunny, 22 C"

messages = [{"role": "user", "content": "What's the weather like in Paris right now?"}]
inputs = tokenizer.apply_chat_template(
    messages, tools=[get_weather], add_generation_prompt=True, return_tensors="pt", return_dict=True
).to(model.device)
outputs = model.generate(**inputs, max_new_tokens=2048)
generated = tokenizer.decode(outputs[0, inputs["input_ids"].shape[1] :])
message = tokenizer.parse_response(generated, prefix=inputs["input_ids"][0], tools=[get_weather])
print(message["tool_calls"])
# [{'type': 'function', 'function': {'name': 'get_weather', 'arguments': {'city': 'Paris'}}}]

messages.append(message)
for call in message["tool_calls"]:
    result = get_weather(**call["function"]["arguments"])
    messages.append({"role": "tool", "name": call["function"]["name"], "content": result})
```

ثم أعد التوليد من `messages` للحصول على الإجابة النهائية. نداءات الأدوات المُحلَّلة لا تحتوي على `id`، ويتطابق التنسيق بين النتائج والنداءات حسب الموضع، لذا أعد نتائج الأدوات بنفس ترتيب النداءات. يتوقف التوليد بعد إجابة نهائية (`<|return|>`) أو نداء أداة (`<|call|>`)؛ ويذكر `generation_config.json` كلاهما.

للبث، تُعيد [get_response_parser()](/docs/transformers/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.get_response_parser) محلّلًا يمكنك `feed()` إليه مقاطع النص كما يتم توليدها. راجع [تحليل الاستجابة](../chat_response_parsing) لمزيد من التفاصيل.

## ملاحظات

- **حُجج القالب.** إلى جانب `reasoning_effort`، يقبل قالب المحادثة `model_identity` (يحل محل السطر الأول من رسالة النظام)، و`builtin_tools`، و`allow_missing_thinking`. يجب أن يُسمّي `builtin_tools` أدوات `search` و`browse` فقط، وذلك فقط مع التعريفات التي تم تدريب Beam عليها. الأدوات الأخرى تحتاج فقط إلى `tools`. تُعرض رسائل `system` و`developer` فقط في بداية المحادثة.
- **التدريب.** يحدد قالب المحادثة مخرجات المساعد لـ`apply_chat_template(..., return_dict=True, return_assistant_tokens_mask=True)`، لذلك يدرب `SFTConfig(assistant_only_loss=True)` في TRL على رموز المساعد فقط. تغطي القناع استدلال كل دور من أدوار المساعد، وإجابته، واستدعاءات أدواته.
- **لا توجد خسارة مساعدة.** يقوم الموجِّه بتوازن عبء الخبراء من خلال انحيازه، لذا لا يحسب `BeamForCausalLM` أي خسارة لتوازن العبء. لا يزال `output_router_logits=True` يعيد قيم اللوجيتس الخاصة بالموجِّه.

## BeamConfig[[transformers.BeamConfig]]

#### transformers.BeamConfig[[transformers.BeamConfig]]

```python
transformers.BeamConfig(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 = 151936, hidden_size: int = 5120, intermediate_size: int = 20480, num_hidden_layers: int = 52, num_attention_heads: int = 48, num_key_value_heads: int = 8, hidden_act: str = 'silu', max_position_embeddings: int = 8192, 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, attention_bias: bool = False, sliding_window: int | None = 512, attention_dropout: float | int = 0.0, moe_intermediate_size: int = 2560, num_experts_per_tok: int = 8, num_experts: int = 256, norm_topk_prob: bool = True, output_router_logits: bool = False, pad_token_id: int | None = None, bos_token_id: int | None = None, eos_token_id: int | list[int] | None = None, head_dim: int = 128, layer_types: list[str] | None = None, mlp_layer_types: list[str] | None = None, n_group: int | None = 8, topk_group: int | None = 4, routed_scaling_factor: int | float = 2.5, final_logit_softcapping: int | float | None = 30.0)
```

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

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

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

hidden_size (`int`، *اختياري*، القيمة الافتراضية هي `5120`) : بعد التمثيلات المخفية.

intermediate_size (`int`, *اختياري*, القيمة الافتراضية `20480`) : أبعاد تمثيلات MLP.

num_hidden_layers (`int`، *اختياري*، القيمة الافتراضية `52`) : عدد الطبقات المخفية في مفكك Transformer.

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

num_key_value_heads (`int`، *اختياري*، القيمة الافتراضية `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`، *اختياري*، الافتراضي هو `8192`) : أقصى طول تسلسل قد يُستخدم به هذا النموذج.

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

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

use_cache (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب على النموذج إرجاع قيم المفاتيح/القيم الأخيرة للانتباه (لا تستخدمها جميع النماذج). لا ينطبق إلا إذا كان `config.is_decoder=True` أو عندما يكون النموذج نموذجًا توليديًا يعتمد على المُفكِّك فقط.

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

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

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

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

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

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

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

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

norm_topk_prob (`bool`، *اختياري*، الافتراضي `True`) : ما إذا كان سيتم تطبيع أوزان الخبراء الموجَّهين.

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

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

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

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

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

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

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

n_group (`int`, *اختياري*, القيمة الافتراضية 8) : عدد مجموعات الخبراء الموجَّهين.

topk_group (`int`، *اختياري*، الافتراضي `4`) : عدد المجموعات المختارة لكل رمز (لكل رمز، مع ضمان أن الخبراء المختارين يكونون ضمن `topk_group` مجموعات فقط).

routed_scaling_factor (`Union[int, float]`، *اختياري*، القيمة الافتراضية `2.5`) : معامل التوسُّع أو الخبراء الموجَّهين.

final_logit_softcapping (`Union[int, float]`, *اختياري*, الافتراضي هو `30.0`) : قيمة التقييد الناعم المطبقة على قيم logits النهائية قبل حساب توزيع الاحتمالات. تُضبط قيم logits بواسطة `tanh(logit / cap) * cap`.

هذه فئة التهيئة لحفظ إعدادات BeamModel. تُستخدم لإنشاء نموذج Beam بناءً على الحجج المحددة، مع تحديد بنية النموذج. إنشاء إعدادات بقيم افتراضية سيُنتج إعدادات مشابهة لتلك الخاصة بـ [reflection/Beam-1.0-501B-A23B](https://huggingface.co/reflection/Beam-1.0-501B-A23B)

ترث كائنات الإعداد من [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) لمزيد من المعلومات.

```python
>>> from transformers import BeamConfig

>>> # Initializing a Beam configuration
>>> configuration = BeamConfig()
```

## BeamModel[[transformers.BeamModel]]

#### transformers.BeamModel[[transformers.BeamModel]]

```python
transformers.BeamModel(config: BeamConfig)
```

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

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

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

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

يرث هذا النموذج من [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.BeamModel.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/beam/modeling_beam.py#L515)

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

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`)، وتتضمن عناصر مختلفة اعتمادًا على التهيئة ([BeamConfig](/docs/transformers/main/ar/model_doc/beam#transformers.BeamConfig)) والمدخلات.

تتجاوز طريقة [BeamModel](/docs/transformers/main/ar/model_doc/beam#transformers.BeamModel) الخاصة بالتقديم (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)، وتُستخدم هذه القيم لحساب الخسارة المساعدة في نماذج مزيج الخبراء.

## BeamForCausalLM[[transformers.BeamForCausalLM]]

#### transformers.BeamForCausalLM[[transformers.BeamForCausalLM]]

```python
transformers.BeamForCausalLM(config: BeamConfig)
```

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

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

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

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

يرث هذا النموذج من [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.BeamForCausalLM.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, 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/beam/modeling_beam.py#L602)

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

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

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`)، وتتضمن عناصر مختلفة اعتمادًا على التهيئة ([BeamConfig](/docs/transformers/main/ar/model_doc/beam#transformers.BeamConfig)) والمدخلات.

تتجاوز طريقة [BeamForCausalLM](/docs/transformers/main/ar/model_doc/beam#transformers.BeamForCausalLM) الخاصة بـ 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
```