# MuseGlimmerAssistant

[MuseGlimmerAssistant](https://research.meta.ai/blog/introducing-muse-glimmer-open-agentic-model) هو مُصيغ [DFlash](https://huggingface.co/papers/2602.06036) الخاص بـ [MuseGlimmer](./muse_glimmer). إنه ليس نموذج لغة قائمًا بذاته. يتكوّن من 5 طبقات نافذة منزلقة ولا يحتوي على تمثيلات خاصة به. يستعير تمثيلات الإدخال والإخراج من النموذج الرئيسي، ويقرأ الحالات المخفية للنموذج الرئيسي عند `target_layer_ids` (الطبقات 1 و13 و25 و37 و49 افتراضيًا) كسياق.

بدلاً من صياغة رمز واحد في كل مرة، يقوم المُصاغ بإزالة الضوضاء عن كتلة كاملة من الرموز المقنّعة بحجم `block_size` في تمريرة أمامية واحدة، على غرار نافذة الانتشار. ثم يتحقق النموذج الرئيسي من الكتلة في خطوة واحدة. وتُفيد شركة Meta بأن فك الترميز أسرع بمقدار 3.1 أضعاف على بطاقة RTX 5090، وأسرع بمقدار 1.5 إلى 1.8 أضعاف على شرائح Apple M-series.

مرّر المُسوّدة إلى [generate()](/docs/transformers/main/ar/main_classes/text_generation#transformers.GenerationMixin.generate) كـ `assistant_model` و اضبط `speculation_type="dflash"`. يجب تحميل المُسوّدة بنفس نوع البيانات (dtype) وعلى نفس الجهاز (device) مثل النموذج الرئيسي.

```python
from transformers import AutoProcessor, MuseGlimmerAssistantModel, MuseGlimmerForConditionalGeneration

processor = AutoProcessor.from_pretrained("meta-models/Muse-Glimmer-30B")
model = MuseGlimmerForConditionalGeneration.from_pretrained(
    "meta-models/Muse-Glimmer-30B",
    device_map="auto",
)
drafter = MuseGlimmerAssistantModel.from_pretrained(
    "meta-models/Muse-Glimmer-30B-assistant",
    device_map="auto",
)

messages = [
    {
        "role": "user",
        "content": [{"type": "text", "text": "Write a bash one-liner that counts lines of Python in a repo."}],
    },
]
inputs = processor.apply_chat_template(
    messages,
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
).to(model.device)
input_len = inputs["input_ids"].shape[-1]

outputs = model.generate(
    **inputs,
    assistant_model=drafter,
    speculation_type="dflash",
    max_new_tokens=256,
)
response = processor.decode(outputs[0][input_len:], skip_special_tokens=False)
print(response)
```

## ملاحظات

- يحتاج المُعدّ إلى حالات الإخفاء للنموذج الرئيسي، لذا يفرض `generate` قيمة `output_hidden_states=True` لنموذج الهدف عندما تكون `speculation_type="dflash"`.
- اطّلع على منشور المدونة [Meta تعود مع Muse Glimmer: محلي، ووكيلي، ومتعدد الوسائط، ومفتوح المصدر!](https://huggingface.co/blog/muse-glimmer) لمزيد من التفاصيل وأمثلة على الاستخدام.

## MuseGlimmerAssistantConfig[[transformers.MuseGlimmerAssistantConfig]]

#### transformers.MuseGlimmerAssistantConfig[[transformers.MuseGlimmerAssistantConfig]]

```python
transformers.MuseGlimmerAssistantConfig(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, hidden_size: int = 6656, intermediate_size: int = 19968, num_hidden_layers: int = 5, num_attention_heads: int = 32, num_key_value_heads: int = 8, head_dim: int = 128, rms_norm_eps: float = 1e-05, rope_parameters: dict | None = None, max_position_embeddings: int = 131072, sliding_window: int = 2048, layer_types: list[str] | None = None, attention_dropout: float | int = 0, hidden_act: str = 'silu', bos_token_id: int | None = 200000, eos_token_id: int | None = 200001, pad_token_id: int | None = 200018, block_size: int = 16, mask_token_id: int = 201818, target_layer_ids: list[int] | None = None)
```

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

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

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

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

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

num_attention_heads (`int`، *اختياري*، القيمة الافتراضية `32`) : عدد رؤوس الانتباه في كل طبقة انتباه داخل مُفكِّك 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`.

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

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

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

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

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

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

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

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

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

eos_token_id (`int`، *اختياري*، القيمة الافتراضية `200001`) : معرّف الرمز المستخدم لنهاية البث في المفردات.

pad_token_id (`int`، *اختياري*، القيمة الافتراضية `200018`) : معرّف الرمز المستخدم للتعبئة في المفردات.

block_size (`int`, *اختياري*) : حجم كتلة مدخلات الضوضاء التي سيتم إزالة الضوضاء منها.

mask_token_id (`int`، *اختياري*) : معرّفات الرموز القناعية المستخدمة كمدخلات ضجيجية للنموذج.

target_layer_ids (`list[int]`، *اختياري*) : معرّفات طبقات تبدأ من الصفر، حيث تُدمج حالاتها المخفية كسياق للنموذج.

هذه فئة الإعدادات المخزنة لإعدادات نموذج MuseGlimmerAssistantModel. تُستخدم لاستحداث نموذج Muse Glimmer Assistant وفقًا للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيُنتج إعدادات مشابهة لتلك الخاصة بـ [meta-models/Muse-Glimmer-30B-assistant](https://huggingface.co/meta-models/Muse-Glimmer-30B-assistant)

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

مثال:

```python
>>> from transformers import MuseGlimmerAssistantConfig, MuseGlimmerAssistantModel

>>> # Initializing a Muse Glimmer Assistant config similar to `meta-models/Muse-Glimmer-30B-assistant`.
>>> configuration = MuseGlimmerAssistantConfig(text_config)

>>> # Initializing a model from the `meta-models/Muse-Glimmer-30B-assistant` configuration.
>>> model = MuseGlimmerAssistantModel(configuration)

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

## MuseGlimmerAssistantPreTrainedModel[[transformers.MuseGlimmerAssistantPreTrainedModel]]

#### transformers.MuseGlimmerAssistantPreTrainedModel[[transformers.MuseGlimmerAssistantPreTrainedModel]]

```python
transformers.MuseGlimmerAssistantPreTrainedModel(config: PreTrainedConfig, *inputs, **kwargs)
```

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

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

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

## MuseGlimmerAssistantModel[[transformers.MuseGlimmerAssistantModel]]

#### transformers.MuseGlimmerAssistantModel[[transformers.MuseGlimmerAssistantModel]]

```python
transformers.MuseGlimmerAssistantModel(config: MuseGlimmerAssistantConfig)
```

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

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

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

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

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

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

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

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

noise_embeds (`torch.Tensor` من الشكل `[batch_size, config.block_size, dim]`) : تمثيل الإدخال للرمز المرساة الأخير المولّد ورموز الأقنعة التي سيتم إزالة الضوضاء عنها.

context_hidden_states (`torch.Tensor` من الشكل `[batch_size, number_of_previous_accepted_tokens, dim * len(config.target_layer_ids)]`) : حالات المخفية للسياق من معرّفات الطبقات المحددة في النموذج المستهدف، مدمجة في البُعد الأخير.

attention_mask (`torch.Tensor` من الشكل `[batch_size, number_of_previous_accepted_tokens + config.block_size]`) : يشبه attention_mask المعتاد، لكن لاحظ أن طوله `number_of_previous_accepted_tokens + config.block_size`، لأن آلية الانتباه ستقوم أولاً بدمج `context_hidden_states` مع حالات الخفاء المشتقة من `noise_embeds`، بحيث لا تكون حالات k/v بنفس طول q_states، حتى قبل استدعاء `cache.update()`. وبالتالي، يجب أن تمتد بُعد kv_seq_len في قناع الانتباه عبر المواضع الإضافية.

position_ids (`torch.Tensor` من الشكل `[batch_size, number_of_previous_accepted_tokens + config.block_size]`) : يشبه `position_ids` المعتادة، لكن لاحظ أن طوله `number_of_previous_accepted_tokens + config.block_size`، لأن آلية الانتباه ستقوم أولاً بدمج `context_hidden_states` مع حالات الخفاء المشتقة من `noise_embeds`، بحيث لا تكون حالات k/v بنفس طول q_states، حتى قبل استدعاء `cache.update()`. وبالتالي، يجب أن تغطي `position_ids` والتضمينات الموضعية المشتقة منها `position_embeddings` جميع المواضع الإضافية.

past_key_values (`~cache_utils.DFlashCache`، *اختياري*) : حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكون هذا عادةً من `past_key_values` التي يعيدها النموذج في مرحلة سابقة من فك الترميز، عندما يكون `use_cache=True` أو `config.use_cache=True`. يُسمح فقط بتمرير كائن [Cache](/docs/transformers/main/ar/internal/generation_utils#transformers.Cache) كمدخل، راجد دليل [kv cache guide](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)`.

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

**يعيد:** [BaseModelOutputWithPast](/docs/transformers/main/ar/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) أو `tuple(torch.Tensor)`

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

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

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

- **last_hidden_state** (`torch.Tensor` من الشكل `(batch_size, sequence_length, hidden_size)`) -- تسلسل من حالات الإخفاء (hidden-states) عند مخرج الطبقة الأخيرة من النموذج.

  إذا تم استخدام `past_key_values`، فإن الحالة المخفية الأخيرة فقط من التسلسلات ذات الشكل `(batch_size, 1, hidden_size)` هي التي تُخرج.
- **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 على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.