# mLUKE

## نظرة عامة

قُدم نموذج mLUKE في [mLUKE: The Power of Entity Representations in Multilingual Pretrained Language Models](https://huggingface.co/papers/2110.08151) من قِبل Ryokan Ri وIkuya Yamada وYoshimasa Tsuruoka. وهو امتداد متعدد اللغات لنموذج [LUKE model](https://huggingface.co/papers/2010.01057) تم تدريبه بناءً على XLM-RoBERTa.

يستند إلى XLM-RoBERTa ويضيف تمثيلات الكيانات، مما يساعد على تحسين الأداء في مهام لاحقة متنوعة تتضمن الاستدلال على الكيانات مثل التعرف على الكيانات المسمّاة، والإجابة الاستخراجية على الأسئلة، وتصنيف العلاقات، وإكمال المعرفة بأسلوب الفراغات.

المستخلص من الورقة البحثية هو كالتالي:

*أظهرت دراسات حديثة أنه يمكن تحسين نماذج اللغة متعددة اللغات المُسبقة التدريب بشكل فعّال باستخدام معلومات المحاذاة عبر اللغات المستمدة من كيانات ويكيبيديا. ومع ذلك، فإن الأساليب الحالية تستغل معلومات الكيانات في مرحلة التدريب المسبق فقط، ولا تستخدم الكيانات صراحةً في المهام اللاحقة. في هذه الدراسة، نستكشف فعالية الاستفادة من تمثيلات الكيانات في المهام اللاحقة عبر اللغات. قمنا بتدريب نموذج لغة متعدد اللغات يغطي 24 لغة باستخدام تمثيلات الكيانات، وأظهرنا أن النموذج يتفوق باستمرار على النماذج المُسبقة التدريب القائمة على الكلمات في مهام النقل عبر اللغات المختلفة. كما قمنا بتحليل النموذج، وكانت الرؤيا الأساسية أن دمج تمثيلات الكيانات في المدخلات يتيح لنا استخراج ميزات أكثر استقلالية عن اللغة. كما قيّمنا النموذج باستخدام مهمة تلميح متعددة اللغات من نوع "ملء الفراغ" مع مجموعة بيانات mLAMA. وأظهرنا أن التلميح القائم على الكيانات يستدعي المعرفة الواقعية الصحيحة باحتمال أكبر مقارنةً باستخدام تمثيلات الكلمات فقط.*

تمت مساهمة هذا النموذج من قِبل [ryo0634](https://huggingface.co/ryo0634). يمكن العثور على الكود الأصلي [هنا](https://github.com/studio-ousia/luke).

## نصائح للاستخدام

يمكن إدخال أوزان mLUKE مباشرةً في نموذج LUKE، على النحو التالي:

```python
from transformers import LukeModel

model = LukeModel.from_pretrained("studio-ousia/mluke-base", device_map="auto")
```

لاحظ أن mLUKE يحتوي على مُجزِّئ خاص به، [MLukeTokenizer](/docs/transformers/main/ar/model_doc/mluke#transformers.MLukeTokenizer). يمكنك تهيئته على النحو التالي:

```python
from transformers import MLukeTokenizer

tokenizer = MLukeTokenizer.from_pretrained("studio-ousia/mluke-base")
```

بما أن بنية mLUKE مكافئة لبنية LUKE، يمكن الرجوع إلى [صفحة توثيق LUKE](luke) لجميع النصائح وأمثلة الأكواد والدفاتر.

## MLukeTokenizer[[transformers.MLukeTokenizer]]

#### transformers.MLukeTokenizer[[transformers.MLukeTokenizer]]

```python
transformers.MLukeTokenizer(bos_token = '<s>', eos_token = '</s>', sep_token = '</s>', cls_token = '<s>', unk_token = '<unk>', pad_token = '<pad>', mask_token = '<mask>', task = None, max_entity_length = 32, max_mention_length = 30, entity_1_token = '<ent>', entity_2_token = '<ent2>', entity_unk_token = '[UNK]', entity_pad_token = '[PAD]', entity_mask_token = '[MASK]', entity_mask2_token = '[MASK2]', vocab: str | dict | list | None = None, entity_vocab: str | dict | list | None = None, **kwargs)
```

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

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

vocab_file (`str`) : مسار ملف المفردات.

entity_vocab_file (`str`) : مسار ملف مفردات الكيانات.

bos_token (`str`، *اختياري*، القيمة الافتراضية `"<s>"`) : رمز بداية التسلسل الذي تم استخدامه أثناء التدريب المسبق. يمكن استخدامه كرمز مصنف التسلسل. عند بناء تسلسل باستخدام الرموز الخاصة، هذا ليس الرمز المستخدم لبداية التسلسل. الرمز المستخدم هو `cls_token`.

eos_token (`str`، *اختياري*، القيمة الافتراضية `"</s>"`) : رمز نهاية التسلسل. عند بناء تسلسل باستخدام الرموز الخاصة، هذا ليس الرمز المستخدم لنهاية التسلسل. الرمز المستخدم هو `sep_token`.

sep_token (`str`، *اختياري*، الافتراضي هو `"</s>"`) : رمز الفاصل، الذي يُستخدم عند بناء تسلسل من عدة تسلسلات، مثل تسلسلين لتصنيف التسلسلات، أو نص وسؤال للإجابة على الأسئلة. كما يُستخدم كآخر رمز في تسلسل مبني برموز خاصة.

cls_token (`str`، *اختياري*، القيمة الافتراضية `"<s>"`) : رمز التصنيف الذي يُستخدم عند إجراء تصنيف التسلسل (تصنيف التسلسل بأكمله بدلاً من تصنيف كل رمز على حدة). وهو الرمز الأول في التسلسل عند بناؤه باستخدام الرموز الخاصة.

unk_token (`str`، *اختياري*، القيمة الافتراضية `"<unk>"`) : رمز المجهول. الرمز غير الموجود في قاموس الكلمات لا يمكن تحويله إلى معرّف، لذا يُعيَّن هذا الرمز بدلاً منه.

pad_token (`str`، *اختياري*، القيمة الافتراضية هي `"<pad>"`) : الرمز المستخدم للتعبئة، على سبيل المثال عند تجميع تسلسلات ذات أطوال مختلفة.

mask_token (`str`، *اختياري*، القيمة الافتراضية `"<mask>"`) : الرمز المستخدم لإخفاء القيم. هذا هو الرمز المستخدم عند تدريب هذا النموذج باستخدام نمذجة اللغة المقنّعة. وهو الرمز الذي سيحاول النموذج التنبؤ به.

task (`str`، *اختياري*) : المهمة التي تريد إعداد التسلسلات من أجلها. أحد `"entity_classification"` أو `"entity_pair_classification"` أو `"entity_span_classification"`. إذا حددت هذا الحجة، يتم إنشاء تسلسل الكيانات تلقائيًا بناءً على نطاق الكيان أو نطاقات الكيانات المحددة.

max_entity_length (`int`، *اختياري*، القيمة الافتراضية 32) : الحد الأقصى لطول `entity_ids`.

max_mention_length (`int`، *اختياري*، القيمة الافتراضية 30) : الحد الأقصى لعدد الرموز داخل نطاق الكيان.

entity_1_token (`str`، *اختياري*، القيمة الافتراضية `<ent>`) : الرمز الخاص المستخدم لتمثيل نطاق الكيان في تسلسل رموز الكلمات. يُستخدم هذا الرمز فقط عندما تكون قيمة `task` هي `"entity_classification"` أو `"entity_pair_classification"`.

entity_2_token (`str`، *اختياري*، القيمة الافتراضية `<ent2>`) : الرمز الخاص المستخدم لتمثيل نطاق الكيان في تسلسل رموز الكلمات. يُستخدم هذا الرمز فقط عندما تكون قيمة `task` هي `"entity_pair_classification"`.

additional_special_tokens (`list[str]`، *اختياري*، القيمة الافتراضية هي `["<s>NOTUSED", "</s>NOTUSED"]`) : رموز خاصة إضافية يستخدمها مُجزِّئ النص.

sp_model_kwargs (`dict`، *اختياري*) : سيتم تمريرها إلى طريقة `SentencePieceProcessor.__init__()`. يمكن استخدام [غلاف Python لـ SentencePiece](https://github.com/google/sentencepiece/tree/master/python)، من بين أمور أخرى، لضبط:  - `enable_sampling`: تفعيل تنسيق تحت الكلمة. - `nbest_size`: معاملات العينة للوحدة الأحادية. غير صالح لـ BPE-Dropout.  - `nbest_size = {0,1}`: لا يتم إجراء أي عينة. - `nbest_size > 1`: يأخذ عينات من نتائج nbest_size. - `nbest_size < 0`: بافتراض أن nbest_size لا نهائي، ويأخذ عينات من جميع الفرضيات (الشبكة) باستخدام خوارزمية التصفية الأمامية والعينة الخلفية.  - `alpha`: معامل التنعيم لعينة الوحدة الأحادية، واحتمالية dropout لعمليات الدمج في BPE-dropout.

sp_model (`SentencePieceProcessor`) : معالج *SentencePiece* المستخدم لكل عملية تحويل (النص، الرموز، والمعرّفات).

مُعدَّل من [XLMRobertaTokenizer](/docs/transformers/main/ar/model_doc/xlm-roberta#transformers.XLMRobertaTokenizer) و [LukeTokenizer](/docs/transformers/main/ar/model_doc/luke#transformers.LukeTokenizer). مبني على [SentencePiece](https://github.com/google/sentencepiece).

يرث هذا المُجزِّئ من [PreTrainedTokenizer](/docs/transformers/main/ar/main_classes/tokenizer#transformers.PythonBackend) التي تحتوي على معظم الطرق الرئيسية. ينبغي للمستخدمين الرجوع إلى هذه الفئة الأصلية لمزيد من المعلومات حول تلك الطرق.

#### __call__[[transformers.MLukeTokenizer.__call__]]

```python
__call__(text: str | list[str], text_pair: str | list[str] | None = None, entity_spans: list[tuple[int, int]] | list[list[tuple[int, int]]] | None = None, entity_spans_pair: list[tuple[int, int]] | list[list[tuple[int, int]]] | None = None, entities: list[str] | list[list[str]] | None = None, entities_pair: list[str] | list[list[str]] | None = None, add_special_tokens: bool = True, padding: bool | str | transformers.utils.generic.PaddingStrategy = False, truncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy | None = None, max_length: int | None = None, max_entity_length: int | None = None, stride: int = 0, is_split_into_words: bool | None = False, pad_to_multiple_of: int | None = None, padding_side: str | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, return_token_type_ids: bool | None = None, return_attention_mask: bool | None = None, return_overflowing_tokens: bool = False, return_special_tokens_mask: bool = False, return_offsets_mapping: bool = False, return_length: bool = False, verbose: bool = True, **kwargs)
```

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

**يعيد:** [BatchEncoding](/docs/transformers/main/ar/main_classes/tokenizer#transformers.BatchEncoding)

[BatchEncoding](/docs/transformers/main/ar/main_classes/tokenizer#transformers.BatchEncoding) يحتوي على الحقول التالية:

- **input_ids** -- قائمة معرّفات الرموز المراد تغذيتها إلى النموذج.

  [ما هي معرّفات الإدخال؟](../glossary#input-ids)

- **token_type_ids** -- قائمة معرّفات أنواع الرموز التي تُمرَّر إلى النموذج (عندما يكون `return_token_type_ids=True` أو إذا كان *"token_type_ids"* ضمن `self.model_input_names`).

  [ما هي معرّفات أنواع الرموز؟](../glossary#token-type-ids)

- **attention_mask** -- قائمة بالفهارس تحدد الرموز التي يجب على النموذج الانتباه إليها (عندما يكون `return_attention_mask=True` أو إذا كان *"attention_mask"* ضمن `self.model_input_names`).

  [ما هي أقنعة الانتباه؟](../glossary#attention-mask)

- **entity_ids** -- قائمة بمعرّفات الكيانات التي سيتم تقديمها إلى النموذج.

  [ما هي معرّفات الإدخال؟](../glossary#input-ids)

- **entity_position_ids** -- قائمة بمواقع الكيانات في تسلسل الإدخال الذي سيُمرَّر إلى النموذج.

- **entity_token_type_ids** -- قائمة معرّفات أنواع الرموز الكيانية التي تُمرَّر إلى النموذج (عندما يكون `return_token_type_ids=True` أو إذا كان *"entity_token_type_ids"* ضمن `self.model_input_names`).

  [ما هي معرّفات أنواع الرموز؟](../glossary#token-type-ids)

- **entity_attention_mask** -- قائمة بالفهارس تحدد الكيانات التي يجب أن يوليها النموذج انتباهه (عندما يكون `return_attention_mask=True` أو إذا كان *"entity_attention_mask"* ضمن `self.model_input_names`).

  [ما هي أقنعة الانتباه؟](../glossary#attention-mask)

- **entity_start_positions** -- قائمة بمواقع بداية الكيانات في تسلسل رموز الكلمات (عند `task="entity_span_classification"`).
- **entity_end_positions** -- قائمة بمواقع نهاية الكيانات في تسلسل الرموز اللفظية (عند `task="entity_span_classification"`).
- **overflowing_tokens** -- قائمة تسلسلات الرموز الزائدة (عند تحديد `max_length` و`return_overflowing_tokens=True`).
- **num_truncated_tokens** -- عدد الرموز التي تم اقتطاعها (عند تحديد `max_length` و`return_overflowing_tokens=True`).
- **special_tokens_mask** -- قائمة من الأصفار والواحدات، حيث تشير 1 إلى الرموز الخاصة المضافة وتُشير 0 إلى رموز التسلسل العادية (عندما تكون `add_special_tokens=True` و`return_special_tokens_mask=True`).
- **length** -- طول المدخلات (عندما يكون `return_length=True`)

add_special_tokens (`bool`، *اختياري*، القيمة الافتراضية `True`): ما إذا كان سيتم إضافة الرموز الخاصة عند ترميز التسلسلات أم لا. سيستخدم هذا الدالة الأساسية `PretrainedTokenizerBase.build_inputs_with_special_tokens`، التي تحدد الرموز التي تُضاف تلقائياً إلى معرّفات الإدخال. يكون هذا مفيداً إذا كنت ترغب في إضافة رموز `bos` أو `eos` تلقائياً. padding (`bool`، `str` أو [PaddingStrategy](/docs/transformers/main/ar/internal/file_utils#transformers.utils.PaddingStrategy)، *اختياري*، القيمة الافتراضية `False`): يُفعّل التحكم في الحشو. يقبل القيم التالية:

- `True` أو `'longest'`: يتم ملء التسلسلات حتى أطول تسلسل في الدفعة (أو لا يتم أي ملء إذا تم تقديم تسلسل واحد فقط).
- `'max_length'`: يُكمل النص حتى الطول الأقصى المحدد عبر الحجة `max_length` أو حتى الطول الأقصى المقبول لإدخال النموذج إذا لم تُقدَّم تلك الحجة.
- `False` أو `'do_not_pad'` (الافتراضي): لا يوجد حشو (أي، يمكن إخراج دفعة تحتوي على تسلسلات بطول مختلف).
truncation (`bool` أو `str` أو [TruncationStrategy](/docs/transformers/main/ar/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy)، *اختياري*، القيمة الافتراضية `False`): يُفعّل التحكم في القص. يقبل القيم التالية:

- `True` أو `'longest_first'`: يُقصّ النص إلى الحد الأقصى للطول المحدد عبر الحجة `max_length` أو إلى الحد الأقصى المقبول لطول الإدخال للنموذج إذا لم تُقدَّم تلك الحجة. يتم هذا القص رمزًا تلو الآخر، حيث يُزال رمز من أطول تسلسل في الزوج إذا كان قد قُدِّم زوج من التسلسلات (أو دفعة من الأزواج).
- `'only_first'`: يُقصّ النص إلى الحد الأقصى للطول المحدد عبر الحجة `max_length` أو إلى الحد الأقصى المقبول لطول الإدخال للنموذج إذا لم تُقدَّم تلك الحجة. لن يُقصّ هذا الخيار سوى التسلسل الأول من الزوج إذا قُدِّم زوج من التسلسلات (أو دفعة من الأزواج).
- `'only_second'`: يُقصّ النص إلى الحد الأقصى للطول المحدد عبر الحجة `max_length` أو إلى الحد الأقصى لطول الإدخال المقبول للنموذج إذا لم تُقدَّم تلك الحجة. لن يتم قصّ النص الثاني من الزوج إلا إذا قُدِّم زوج من النصوص (أو دفعة من الأزواج).
- `False` أو `'do_not_truncate'` (الافتراضي): لا يوجد اقتطاع (أي، يمكن إخراج دفعة بأطوال تسلسلات أكبر من الحد الأقصى المقبول لحجم الإدخال في النموذج).
max_length (`int`، *اختياري*): يتحكم في الحد الأقصى للطول الذي يستخدمه أحد معاملات القص/الحشو.

If left unset or set to `None`, this will use the predefined model maximum length if a maximum length is required by one of the truncation/padding parameters. If the model has no specific maximum input length (like XLNet) truncation/padding to a maximum length will be deactivated. stride (`int`, *optional*, defaults to 0): If set to a number along with `max_length`, the overflowing tokens returned when `return_overflowing_tokens=True` will contain some tokens from the end of the truncated sequence returned to provide some overlap between truncated and overflowing sequences. The value of this argument defines the number of overlapping tokens. is_split_into_words (`bool`, *optional*, defaults to `False`): Whether or not the input is already pre-tokenized (e.g., split into words). If set to `True`, the tokenizer assumes the input is already split into words (for instance, by splitting it on whitespace) which it will tokenize. This is useful for NER or token classification. pad_to_multiple_of (`int`, *optional*): If set will pad the sequence to a multiple of the provided value. Requires `padding` to be activated. This is especially useful to enable the use of Tensor Cores on NVIDIA hardware with compute capability `>= 7.5` (Volta). padding_side (`str`, *optional*): The side on which the model should have padding applied. Should be selected between ['right', 'left']. Default value is picked from the class attribute of the same name. return_tensors (`str` or [TensorType](/docs/transformers/main/ar/internal/file_utils#transformers.TensorType), *optional*): If set, will return tensors instead of list of python integers. Acceptable values are:

- `'pt'`: إرجاع كائنات `torch.Tensor` من PyTorch.
- `'np'`: إرجاع كائنات `np.ndarray` من نوع Numpy.

return_token_type_ids (`bool`، *اختياري*): ما إذا كان يجب إرجاع معرّفات أنواع الرموز. إذا تُركت القيمة الافتراضية، فسيتم إرجاع معرّفات أنواع الرموز وفقًا للقيمة الافتراضية الخاصة بمجزّئ الرموز المحدد، كما تحددها خاصية `return_outputs`.

[ما هي معرّفات أنواع الرموز؟](../glossary#token-type-ids) return_attention_mask (`bool`, *اختياري*): ما إذا كان يجب إرجاع قناع الانتباه. إذا تُركت القيمة الافتراضية، فسيتم إرجاع قناع الانتباه وفقًا للقيمة الافتراضية الخاصة بمجزّئ الرموز المحدد، كما تحددها خاصية `return_outputs`.

[ما هي أقنعة الانتباه؟](../glossary#attention-mask) return_overflowing_tokens (`bool`، *اختياري*، القيمة الافتراضية `False`): ما إذا كان سيتم إرجاع تسلسلات الرموز المتجاوزة أم لا. إذا تم تقديم زوج من تسلسلات معرّفات الإدخال (أو دفعة من الأزواج) مع `truncation_strategy = longest_first` أو `True`، فسيتم رفع خطأ بدلاً من إرجاع الرموز المتجاوزة. return_special_tokens_mask (`bool`، *اختياري*، القيمة الافتراضية `False`): ما إذا كان سيتم إرجاع معلومات قناع الرموز الخاصة أم لا. return_offsets_mapping (`bool`، *اختياري*، القيمة الافتراضية `False`): ما إذا كان سيتم إرجاع `(char_start, char_end)` لكل رمز.

يتوفر هذا فقط على مُرمّزيات سريعة ترث من [PreTrainedTokenizerFast](/docs/transformers/main/ar/main_classes/tokenizer#transformers.TokenizersBackend)، فإذا كنت تستخدم مُرمّزي Python، فسيُطلق هذا الدالة `NotImplementedError`. return_length (`bool`، *اختياري*، الافتراضي `False`): ما إذا كان يجب إرجاع أطوال المدخلات المُرمّزة أم لا. verbose (`bool`، *اختياري*، الافتراضي `True`): ما إذا كان يجب طباعة مزيد من المعلومات والتحذيرات أم لا. **kwargs: تُمرَّر إلى الدالة `self.tokenize()`

#### save_vocabulary[[transformers.MLukeTokenizer.save_vocabulary]]

```python
save_vocabulary(save_directory: str, filename_prefix: str | None = None)
```

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

احفظ ملف قاموس الكيانات فقط. يتم حفظ tokenizer.json بواسطة TokenizersBackend الأب.