# LayoutXLM ## نظرة عامة قُدِّم نموذج LayoutXLM في [LayoutXLM: Multimodal Pre-training for Multilingual Visually-rich Document Understanding](https://huggingface.co/papers/2104.08836) بواسطة Yiheng Xu وTengchao Lv وLei Cui وGuoxin Wang وYijuan Lu وDinei Florencio وCha Zhang وFuru Wei. وهو امتداد متعدد اللغات لنموذج [LayoutLMv2](https://huggingface.co/papers/2012.14740) تم تدريبه على 53 لغة. المستخلص من الورقة البحثية هو كالتالي: *حقّق التدريب المسبق متعدد الوسائط باستخدام النص والتخطيط والصورة أداءً متقدماً (SOTA) مؤخراً في مهام فهم المستندات الغنية بصرياً، مما يُظهر الإمكانات الكبيرة للتعلم المشترك عبر الوسائط المختلفة. في هذه الورقة، نعرض LayoutXLM، وهو نموذج مُدرَّب مسبقاً متعدد الوسائط لفهم المستندات متعددة اللغات، ويهدف إلى تجاوز الحواجز اللغوية في فهم المستندات الغنية بصرياً. لتقييم LayoutXLM بدقة، نقدم أيضاً مجموعة بيانات مرجعية متعددة اللغات لفهم النماذج (النماذج الورقية) تُسمى XFUN، والتي تتضمن عينات لفهم النماذج في 7 لغات (الصينية، اليابانية، الإسبانية، الفرنسية، الإيطالية، الألمانية، البرتغالية)، وقد تم تمييز أزواج المفاتيح والقيم يدوياً لكل لغة. تُظهر نتائج التجارب أن نموذج LayoutXLM تفوّق بشكل كبير على النماذج المُدرَّبة مسبقاً متعددة اللغات المتقدمة (SOTA) الموجودة على مجموعة بيانات XFUN.* تمت مساهمة هذا النموذج من قِبل [nielsr](https://huggingface.co/nielsr). يمكن العثور على الكود الأصلي [هنا](https://github.com/microsoft/unilm). ## نصائح وأمثلة للاستخدام يمكن إدخال أوزان LayoutXLM مباشرةً في نموذج LayoutLMv2، على النحو التالي: ```python from transformers import LayoutLMv2Model model = LayoutLMv2Model.from_pretrained("microsoft/layoutxlm-base", device_map="auto") ``` لاحظ أن LayoutXLM يحتوي على مُجزِّئ خاص به، مبني على [LayoutXLMTokenizer](/docs/transformers/main/ar/model_doc/layoutxlm#transformers.LayoutXLMTokenizer)/[LayoutXLMTokenizerFast](/docs/transformers/main/ar/model_doc/layoutxlm#transformers.LayoutXLMTokenizer). يمكنك تهيئته على النحو التالي: ```python from transformers import LayoutXLMTokenizer tokenizer = LayoutXLMTokenizer.from_pretrained("microsoft/layoutxlm-base") ``` بشكل مشابه لـ LayoutLMv2، يمكنك استخدام [LayoutXLMProcessor](/docs/transformers/main/ar/model_doc/layoutxlm#transformers.LayoutXLMProcessor) (الذي يطبق داخليًا [LayoutLMv2ImageProcessor](/docs/transformers/main/ar/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) و [LayoutXLMTokenizer](/docs/transformers/main/ar/model_doc/layoutxlm#transformers.LayoutXLMTokenizer)/[LayoutXLMTokenizerFast](/docs/transformers/main/ar/model_doc/layoutxlm#transformers.LayoutXLMTokenizer) بالتتابع) لتحضير جميع البيانات للنموذج. بما أن بنية LayoutXLM مكافئة لبنية LayoutLMv2، يمكن الرجوع إلى [صفحة توثيق LayoutLMv2](layoutlmv2) لجميع النصائح وأمثلة الأكواد والدفاتر. ## LayoutXLMConfig[[transformers.LayoutXLMConfig]] #### transformers.LayoutXLMConfig[[transformers.LayoutXLMConfig]] ```python transformers.LayoutXLMConfig(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 = 30522, hidden_size: int = 768, num_hidden_layers: int = 12, num_attention_heads: int = 12, intermediate_size: int = 3072, hidden_act: str = 'gelu', hidden_dropout_prob: float | int = 0.1, attention_probs_dropout_prob: float | int = 0.1, max_position_embeddings: int = 512, type_vocab_size: int = 2, initializer_range: float = 0.02, layer_norm_eps: float = 1e-12, pad_token_id: int | None = 0, max_2d_position_embeddings: int = 1024, max_rel_pos: int = 128, rel_pos_bins: int = 32, fast_qkv: bool = True, max_rel_2d_pos: int = 256, rel_2d_pos_bins: int = 64, convert_sync_batchnorm: bool = True, image_feature_pool_shape: list[int] | tuple[int, ...] = (7, 7, 256), coordinate_size: int = 128, shape_size: int = 128, has_relative_attention_bias: bool = True, has_spatial_attention_bias: bool = True, has_visual_segment_embedding: bool = False, detectron2_config_args: dict | None = None) ``` [المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/layoutxlm/configuration_layoutxlm.py#L35) **المعاملات:** vocab_size (`int`، *اختياري*، القيمة الافتراضية `30522`) : حجم مفردات النموذج. يحدد عدد الرموز المختلفة التي يمكن تمثيلها بواسطة `input_ids`. hidden_size (`int`، *اختياري*، القيمة الافتراضية `768`) : بُعد التمثيلات المخفية. num_hidden_layers (`int`، *اختياري*، القيمة الافتراضية `12`) : عدد الطبقات المخفية في مُفكِّك Transformer. num_attention_heads (`int`، *اختياري*، القيمة الافتراضية `12`) : عدد رؤوس الانتباه في كل طبقة انتباه داخل مُفكِّك Transformer. intermediate_size (`int`، *اختياري*، القيمة الافتراضية `3072`) : بُعد تمثيلات MLP. hidden_act (`str`، *اختياري*، القيمة الافتراضية `gelu`) : دالة التنشيط غير الخطية (دالة أو نص) في المُفكِّك. على سبيل المثال، `"gelu"`، `"relu"`، `"silu"`، وما إلى ذلك. hidden_dropout_prob (`Union[float, int]`، *اختياري*، القيمة الافتراضية `0.1`) : احتمال الإسقاط (dropout) لجميع الطبقات المتصلة بالكامل في التضمينات (embeddings) والمُشفِّر (encoder) والمُجمِّع (pooler). attention_probs_dropout_prob (`Union[float, int]`، *اختياري*، القيمة الافتراضية `0.1`) : نسبة الإسقاط (dropout) لاحتمالات الانتباه. max_position_embeddings (`int`، *اختياري*، القيمة الافتراضية `512`) : أقصى طول تسلسل قد يُستخدم مع هذا النموذج. type_vocab_size (`int`، *اختياري*، القيمة الافتراضية `2`) : حجم مفردات `token_type_ids`. initializer_range (`float`، *اختياري*، القيمة الافتراضية `0.02`) : الانحراف المعياري لـ truncated_normal_initializer المستخدم في تهيئة جميع مصفوفات الأوزان. layer_norm_eps (`float`، *اختياري*، القيمة الافتراضية `1e-12`) : قيمة الإيبسلون المستخدمة في طبقات تطبيع الطبقة. pad_token_id (`int`، *اختياري*، القيمة الافتراضية `0`) : معرّف الرمز المستخدم للتعبئة في المفردات. max_2d_position_embeddings (`int`، *اختياري*، القيمة الافتراضية 1024) : القيمة القصوى التي قد يُستخدم معها تضمين الموقع ثنائي الأبعاد. يُنصح عادةً بإعداد هذه القيمة إلى رقم كبير احتياطًا (مثل 1024). max_rel_pos (`int`، *اختياري*، القيمة الافتراضية 128) : الحد الأقصى لعدد المواضع النسبية المستخدمة في آلية الانتباه الذاتي. rel_pos_bins (`int`، *اختياري*، القيمة الافتراضية 32) : عدد دلاء الموضع النسبي المستخدمة في آلية الانتباه الذاتي. fast_qkv (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم استخدام مصفوفة واحدة للاستعلامات والمفاتيح والقيم في طبقات الانتباه الذاتي. max_rel_2d_pos (`int`، *اختياري*، القيمة الافتراضية 256) : الحد الأقصى لعدد المواضع النسبية ثنائية الأبعاد في آلية الانتباه الذاتي. rel_2d_pos_bins (`int`، *اختياري*، القيمة الافتراضية 64) : عدد خلايا المواقع النسبية ثنائية الأبعاد في آلية الانتباه الذاتي. convert_sync_batchnorm (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم تحويل طبقات تطبيع الدفعة (batch normalization) إلى طبقات تطبيع دفعة متزامنة (synchronized batch normalization) أم لا. image_feature_pool_shape (`list[int]`، *اختياري*، القيمة الافتراضية `[7, 7, 256]`) : شكل خريطة الميزات المُجمَّعة بمتوسط التجميع. coordinate_size (`int`، *اختياري*، القيمة الافتراضية 128) : بُعد تضمينات الإحداثيات. shape_size (`int`، *اختياري*، القيمة الافتراضية 128) : بُعد تضمينات العرض والارتفاع. has_relative_attention_bias (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم استخدام انحياز انتباه نسبي في آلية الانتباه الذاتي أم لا. has_spatial_attention_bias (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم استخدام انحياز انتباه مكاني في آلية الانتباه الذاتي أم لا. has_visual_segment_embedding (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان يجب إضافة تضمينات المقاطع البصرية أم لا. detectron2_config_args (`dict`، *اختياري*) : قاموس يحتوي على حُجج التهيئة للعمود الفقري البصري في Detectron2. راجع [هذا الملف](https://github.com/microsoft/unilm/blob/master/layoutlmft/layoutlmft/models/layoutxlm/detectron2_config.py) للتفاصيل المتعلقة بالقيم الافتراضية. هذه فئة الإعدادات المخزنة لإعدادات نموذج LayoutxlmModel. تُستخدم لاستحداث نموذج Layoutxlm وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ [microsoft/layoutxlm-base](https://huggingface.co/microsoft/layoutxlm-base) ترث كائنات الإعداد من [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) لمزيد من المعلومات. مثال: ```python >>> from transformers import LayoutXLMConfig, LayoutXLMModel >>> # Initializing a LayoutXLM microsoft/layoutxlm-base style configuration >>> configuration = LayoutXLMConfig() >>> # Initializing a model (with random weights) from the microsoft/layoutxlm-base style configuration >>> model = LayoutXLMModel(configuration) >>> # Accessing the model configuration >>> configuration = model.config ``` ## LayoutXLMTokenizer[[transformers.LayoutXLMTokenizer]] #### transformers.LayoutXLMTokenizer[[transformers.LayoutXLMTokenizer]] ```python transformers.LayoutXLMTokenizer(vocab: str | list | None = None, bos_token = '', eos_token = '', sep_token = '', cls_token = '', unk_token = '', pad_token = '', mask_token = '', cls_token_box = [0, 0, 0, 0], sep_token_box = [1000, 1000, 1000, 1000], pad_token_box = [0, 0, 0, 0], pad_token_label = -100, only_label_first_subword = True, add_prefix_space = True, **kwargs) ``` [المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/layoutxlm/tokenization_layoutxlm.py#L140) **المعاملات:** vocab (`str` أو `dict` أو `list`، *اختياري*) : مفردات مُجزِّئ الرموز (tokenizer) كمسار، أو قاموس، أو قائمة من أزواج `(token, score)`. bos_token (`str`، *اختياري*، القيمة الافتراضية `""`) : رمز بداية التسلسل الذي تم استخدامه أثناء التدريب المسبق. يمكن استخدامه كرمز مصنف التسلسل. عند بناء تسلسل باستخدام الرموز الخاصة، هذا ليس الرمز المستخدم لبداية التسلسل. الرمز المستخدم هو `cls_token`. eos_token (`str`، *اختياري*، القيمة الافتراضية `""`) : رمز نهاية التسلسل. عند بناء تسلسل باستخدام الرموز الخاصة، هذا ليس الرمز المستخدم لنهاية التسلسل. الرمز المستخدم هو `sep_token`. sep_token (`str`، *اختياري*، الافتراضي هو `""`) : رمز الفاصل، الذي يُستخدم عند بناء تسلسل من عدة تسلسلات، مثل تسلسلين لتصنيف التسلسلات، أو نص وسؤال للإجابة على الأسئلة. كما يُستخدم كآخر رمز في تسلسل مبني برموز خاصة. cls_token (`str`، *اختياري*، القيمة الافتراضية `""`) : رمز التصنيف الذي يُستخدم عند إجراء تصنيف التسلسل (تصنيف التسلسل بأكمله بدلاً من تصنيف كل رمز على حدة). وهو الرمز الأول في التسلسل عند بناؤه باستخدام الرموز الخاصة. unk_token (`str`، *اختياري*، القيمة الافتراضية `""`) : رمز المجهول. الرمز غير الموجود في قاموس الكلمات لا يمكن تحويله إلى معرّف، لذا يُعيَّن هذا الرمز بدلاً منه. pad_token (`str`، *اختياري*، القيمة الافتراضية هي `""`) : الرمز المستخدم للتعبئة، على سبيل المثال عند تجميع تسلسلات ذات أطوال مختلفة. mask_token (`str`، *اختياري*، القيمة الافتراضية `""`) : الرمز المستخدم لإخفاء القيم. هذا هو الرمز المستخدم عند تدريب هذا النموذج باستخدام نمذجة اللغة المقنّعة. وهو الرمز الذي سيحاول النموذج التنبؤ به. cls_token_box (`list[int]`، *اختياري*، القيمة الافتراضية `[0, 0, 0, 0]`) : الصندوق المحيط (bounding box) الذي سيُستخدم للرمز الخاص [CLS]. sep_token_box (`list[int]`، *اختياري*، القيمة الافتراضية `[1000, 1000, 1000, 1000]`) : صندوق الحدود (bounding box) الذي سيُستخدم للرمز الخاص [SEP]. pad_token_box (`list[int]`، *اختياري*، القيمة الافتراضية `[0, 0, 0, 0]`) : الصندوق المحيط (bounding box) الذي سيُستخدم للرمز الخاص [PAD]. pad_token_label (`int`، *اختياري*، القيمة الافتراضية -100) : التسمية المستخدمة لرموز الحشو. القيمة الافتراضية هي -100، وهي `ignore_index` في CrossEntropyLoss الخاصة بـ PyTorch. only_label_first_subword (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب وضع التسمية على أول جزء من الكلمة فقط، في حال تم توفير تسميات الكلمات. add_prefix_space (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إضافة مسافة أولية إلى المدخلات أم لا. additional_special_tokens (`list[str]`، *اختياري*، القيمة الافتراضية هي `["NOTUSED", "NOTUSED"]`) : رموز خاصة إضافية يستخدمها مُجزِّئ النص. أنشئ مُرمِّز LayoutXLM "سريع" (مدعوم بمكتبة *tokenizers* من HuggingFace). مُعدَّل من [RobertaTokenizer](/docs/transformers/main/ar/model_doc/led#transformers.RobertaTokenizer) و[XLNetTokenizer](/docs/transformers/main/ar/model_doc/xlnet#transformers.XLNetTokenizer). مبني على [BPE](https://huggingface.co/docs/tokenizers/python/latest/components.html?highlight=BPE#models). يرث هذا المُجزِّئ من [TokenizersBackend](/docs/transformers/main/ar/main_classes/tokenizer#transformers.TokenizersBackend) التي تحتوي على معظم الدوال الرئيسية. ينبغي على المستخدمين الرجوع إلى هذه الفئة الأصلية لمزيد من المعلومات حول تلك الدوال. #### __call__[[transformers.LayoutXLMTokenizer.__call__]] ```python __call__(text: str | list[str] | list[list[str]], text_pair: list[str] | list[list[str]] | None = None, boxes: list[list[int]] | list[list[list[int]]] | None = None, word_labels: list[int] | list[list[int]] | 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, stride: int = 0, 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/layoutxlm/tokenization_layoutxlm.py#L413) **المعاملات:** text (`str`، `list[str]`، `list[list[str]]`) : التسلسل أو الدفعة من التسلسلات المراد ترميزها. يمكن أن يكون كل تسلسل نصًا، أو قائمة من النصوص (كلمات مثال واحد أو أسئلة دفعة من الأمثلة)، أو قائمة من قوائم النصوص (دفعة من الكلمات). text_pair (`list[str]`، `list[list[str]]`) : التسلسل أو الدفعة من التسلسلات المراد ترميزها. يجب أن يكون كل تسلسل قائمة من النصوص (نص مُقسَّم مسبقًا). boxes (`list[list[int]]`، `list[list[list[int]]]`) : صناديق حدود على مستوى الكلمة. يجب أن تكون كل صناديق الحدود مُعايرة على مقياس من 0 إلى 1000. word_labels (`list[int]`، `list[list[int]]`، *اختياري*) : تسميات عددية صحيحة على مستوى الكلمة (لمهام تصنيف الرموز مثل FUNSD وCORD). add_special_tokens (`bool`، *اختياري*، الافتراضي `True`) : ما إذا كان سيتم ترميز التسلسلات باستخدام الرموز الخاصة الخاصة بنموذجها أم لا. 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`, *اختياري*) : يتحكم في الحد الأقصى للطول الذي سيستخدمه أحد معاملات القص/الحشو. إذا تُرك غير مضبوط أو ضُبط على `None`، فسيتم استخدام الحد الأقصى للطول المحدد مسبقًا للنموذج إذا كان أحد معاملات القص/الحشو يتطلب حدًا أقصى للطول. إذا لم يكن للنموذج حد أقصى محدد لطول الإدخال (مثل XLNet)، فسيتم تعطيل القص/الحشو إلى حد أقصى للطول. stride (`int`، *اختياري*، القيمة الافتراضية 0) : إذا تم تعيينه إلى رقم مع `max_length`، فإن الرموز الزائدة المُعاد عند `return_overflowing_tokens=True` ستحتوي على بعض الرموز من نهاية التسلسل المُقتطع المُعاد، لتوفير بعض التداخل بين التسلسلات المُقتطعة والتسلسلات الزائدة. تحدد قيمة هذا الحجة عدد الرموز المتداخلة. pad_to_multiple_of (`int`, *اختياري*) : إذا تم تعيينه، سيتم توسيط التسلسل إلى مضاعف للقيمة المُقدَّمة. وهذا مفيد بشكل خاص لتمكين استخدام نوى التينسور (Tensor Cores) على أجهزة NVIDIA التي تتمتع بقابلية معالجة `>= 7.5` (Volta). return_tensors (`str` أو [TensorType](/docs/transformers/main/ar/internal/file_utils#transformers.TensorType)، *اختياري*) : إذا تم تعيينه، فسيُرجع تينسورات بدلاً من قائمة من الأعداد الصحيحة بلغة بايثون. القيم المقبولة هي: - `'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)` لكل رمز. هذه الخاصية متاحة فقط في مُرمّزيات fast التي ترث من [PreTrainedTokenizerFast](/docs/transformers/main/ar/main_classes/tokenizer#transformers.TokenizersBackend)، وإذا كنت تستخدم مُرمّزي Python، فسيُطلق هذا الدالة `NotImplementedError`. return_length (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان يجب إرجاع أطوال المدخلات المُرمّزة أم لا. verbose (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب طباعة مزيد من المعلومات والتنبيهات أم لا. - ****kwargs** : تُمرَّر إلى طريقة `self.tokenize()` **يعيد:** [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) - **bbox** -- قائمة صناديق الإحاطة التي سيتم تقديمها إلى النموذج. - **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) - **labels** -- قائمة بالوسوم التي سيتم تقديمها إلى النموذج. (عند تحديد `word_labels`). - **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`). الطريقة الرئيسية لتجزئة (tokenization) وتجهيز تسلسل واحد أو عدة تسلسلات، أو زوج واحد أو عدة أزواج من التسلسلات، مع صناديق حدود (bounding boxes) مُطبَّعة على مستوى الكلمة، وعلامات اختيارية. #### build_inputs_with_special_tokens[[transformers.LayoutXLMTokenizer.build_inputs_with_special_tokens]] ```python build_inputs_with_special_tokens(token_ids_0: list, token_ids_1: list[int] | None = None) ``` [المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/layoutxlm/tokenization_layoutxlm.py#L892) **المعاملات:** token_ids_0 (`list[int]`) : قائمة بالمعرّفات التي ستُضاف إليها الرموز الخاصة. token_ids_1 (`list[int]`، *اختياري*) : قائمة ثانية اختيارية من المعرّفات لأزواج التسلسلات. **يعيد:** `list[int]` قائمة [معرفات الإدخال](../glossary#input-ids) مع الرموز الخاصة المناسبة. إنشاء مدخلات النموذج من تسلسل أو زوج من التسلسلات لمهام تصنيف التسلسل من خلال الربط وإضافة الرموز الخاصة. يتبع تسلسل XLM-RoBERTa التنسيق التالي: - تسلسل واحد: ` X ` - زوج من التسلسلات: ` A B ` #### get_special_tokens_mask[[transformers.LayoutXLMTokenizer.get_special_tokens_mask]] ```python get_special_tokens_mask(token_ids_0: list[int], token_ids_1: list[int] | None = None, already_has_special_tokens: bool = False) ``` [المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/tokenization_utils_base.py#L1338) **المعاملات:** token_ids_0 : قائمة معرّفات (IDs) للتسلسل (الذي قد يكون منسّقًا بالفعل). token_ids_1 : غير مستخدم عندما يكون `already_has_special_tokens=True`. يجب أن يكون None في هذه الحالة. already_has_special_tokens : ما إذا كانت التسلسلة منسّقة مسبقًا باستخدام الرموز الخاصة. **يعيد:** قائمة من الأعداد الصحيحة في المدى [0, 1] 1 لرمز خاص، 0 لرمز التسلسل. استرجاع معرّفات التسلسلات من قائمة الرموز التي لم تُضف إليها أي رموز خاصة. للمُرمِّزات السريعة، تستدعي مُجمِّعات البيانات هذه الدالة مع `already_has_special_tokens=True` لبناء قناع فوق تسلسل منسّق مسبقًا. في هذه الحالة، نحسب القناع عن طريق التحقق من العضوية في `all_special_ids`. #### create_token_type_ids_from_sequences[[transformers.LayoutXLMTokenizer.create_token_type_ids_from_sequences]] ```python create_token_type_ids_from_sequences(token_ids_0: list, token_ids_1: list[int] | None = None) ``` [المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/layoutxlm/tokenization_layoutxlm.py#L918) **المعاملات:** token_ids_0 (`list[int]`) : قائمة من المعرّفات. token_ids_1 (`list[int]`، *اختياري*) : قائمة ثانية اختيارية من المعرّفات لأزواج التسلسلات. **يعيد:** `list[int]` قائمة من الأصفار. أنشئ قناعًا من التسلسلين المُمرَّرين لاستخدامه في مهمة تصنيف أزواج التسلسلات. لا يستخدم XLM-RoBERTa معرّفات أنواع الرموز، لذلك يُعاد قائمة من الأصفار. #### save_vocabulary[[transformers.LayoutXLMTokenizer.save_vocabulary]] ```python save_vocabulary(save_directory: str, filename_prefix: str | None = None) ``` [المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/tokenization_utils_tokenizers.py#L546) ## LayoutXLMProcessor[[transformers.LayoutXLMProcessor]] #### transformers.LayoutXLMProcessor[[transformers.LayoutXLMProcessor]] ```python transformers.LayoutXLMProcessor(image_processor = None, tokenizer = None, **kwargs) ``` [المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/layoutxlm/processing_layoutxlm.py#L24) **المعاملات:** image_processor (`LayoutLMv2ImageProcessor`) : مُعالج الصور هو مدخل مطلوب. tokenizer (`LayoutXLMTokenizer`) : المُجزِّئ (tokenizer) هو مدخل مطلوب. ينشئ LayoutXLMProcessor الذي يجمع معالج الصور ومعالج الرموز في معالج واحد. يوفر [LayoutXLMProcessor](/docs/transformers/main/ar/model_doc/layoutxlm#transformers.LayoutXLMProcessor) جميع وظائف [LayoutLMv2ImageProcessor](/docs/transformers/main/ar/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) و[LayoutXLMTokenizer](/docs/transformers/main/ar/model_doc/layoutxlm#transformers.LayoutXLMTokenizer). راجع [~LayoutLMv2ImageProcessor](/docs/transformers/main/ar/model_doc/layoutlmv2#transformers.LayoutLMv2ImageProcessor) و[~LayoutXLMTokenizer](/docs/transformers/main/ar/model_doc/layoutxlm#transformers.LayoutXLMTokenizer) لمزيد من المعلومات. #### __call__[[transformers.LayoutXLMProcessor.__call__]] ```python __call__(images, text: str | list[str] | list[list[str]] = None, text_pair: list[str] | list[list[str]] | None = None, boxes: list[list[int]] | list[list[list[int]]] | None = None, word_labels: list[int] | list[list[int]] | None = None, add_special_tokens: bool = True, padding: bool | str | transformers.utils.generic.PaddingStrategy = False, truncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy = None, max_length: int | None = None, stride: int = 0, pad_to_multiple_of: int | 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, return_tensors: str | transformers.utils.generic.TensorType | None = None, **kwargs) ``` [المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/layoutxlm/processing_layoutxlm.py#L28) **المعاملات:** images (``) : Image to preprocess. Expects a single or batch of images with pixel values ranging from 0 to 255. If passing in images with pixel values between 0 and 1, set `do_rescale=False`. text (`Union[str, list[str], list[list[str]]]`، *اختياري*) : التسلسل أو الدفعة من التسلسلات المراد ترميزها. يمكن أن يكون كل تسلسل نصًا أو قائمة من النصوص (نص مُجزَّأ مسبقًا). إذا مررت مدخلات مُجزَّأة مسبقًا، فاضبط `is_split_into_words=True` لتجنب الغموض مع المدخلات المُجمَّعة في دفعات. text_pair (`str, list[str] or list[int]`, *اختياري*) : تسلسل ثانٍ اختياري ليتم ترميزه. يمكن أن يكون هذا نصًا، أو قائمة من النصوص (نص مُرمَّز باستخدام طريقة `tokenize`)، أو قائمة من الأعداد الصحيحة (معرّفات رموز مُرمَّزة باستخدام طريقة `convert_tokens_to_ids`). boxes (`list[list[int]] or list[list[list[int]]]`، *اختياري*) : صناديق حدود على مستوى الكلمات. يجب أن تكون كل صناديق الحدود مُعايرة على مقياس من 0 إلى 1000. word_labels (`list[int] or list[list[int]]`، *اختياري*) : تسميات عددية صحيحة على مستوى الكلمة (لمهام تصنيف الرموز مثل FUNSD وCORD). 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 or [TruncationStrategy](/docs/transformers/main/ar/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *optional*) : يُفعّل التحكم في القص. يقبل القيم التالية: - `True` أو `'longest_first'`: يُقصّ إلى الحد الأقصى للطول المحدد بالحجة `max_length` أو إلى الحد الأقصى لطول الإدخال المقبول للنموذج إذا لم تُقدَّم تلك الحجة. سيؤدي هذا إلى القص رمزًا تلو الآخر، مع إزالة رمز من أطول تسلسل في الزوج إذا قُدِّم زوج من التسلسلات (أو دفعة من الأزواج). - `'only_first'`: يُقصّ إلى الحد الأقصى للطول المحدد بالحجة `max_length` أو إلى الحد الأقصى لطول الإدخال المقبول للنموذج إذا لم تُقدَّم تلك الحجة. سيؤدي هذا إلى قصّ التسلسل الأول من الزوج فقط إذا قُدِّم زوج من التسلسلات (أو دفعة من الأزواج). - `'only_second'`: يُقصّ إلى الحد الأقصى للطول المحدد بالحجة `max_length` أو إلى الحد الأقصى لطول الإدخال المقبول للنموذج إذا لم تُقدَّم تلك الحجة. سيؤدي هذا إلى قصّ التسلسل الثاني من الزوج فقط إذا قُدِّم زوج من التسلسلات (أو دفعة من الأزواج). - `False` أو `'do_not_truncate'` (الافتراضي): لا يوجد قص (أي، يمكن إخراج دفعة بأطوال تسلسلات أكبر من الحد الأقصى المقبول لحجم الإدخال للنموذج). max_length (`int`, *اختياري*) : يتحكم في الحد الأقصى للطول الذي سيستخدمه أحد معاملات القص/الحشو. إذا تُرك غير مضبوط أو ضُبط على `None`، فسيتم استخدام الحد الأقصى للطول المحدد مسبقًا للنموذج إذا كان أحد معاملات القص/الحشو يتطلب حدًا أقصى للطول. إذا لم يكن للنموذج حد أقصى محدد لطول الإدخال (مثل XLNet)، فسيتم تعطيل القص/الحشو إلى حد أقصى للطول. stride (`int`، *اختياري*، القيمة الافتراضية `0`) : إذا تم تعيينه إلى رقم مع `max_length`، فإن الرموز الزائدة المُعاد عند `return_overflowing_tokens=True` ستحتوي على بعض الرموز من نهاية التسلسل المُقتطع المُعاد، لتوفير بعض التداخل بين التسلسلات المُقتطعة والتسلسلات الزائدة. تحدد قيمة هذا الحجة عدد الرموز المتداخلة. pad_to_multiple_of (`int`, *اختياري*) : إذا تم ضبطه، سيتم ملء التسلسل حتى يصبح مضاعفًا للقيمة المُقدَّمة. يتطلب تفعيل `padding`. وهذا مفيد بشكل خاص لتمكين استخدام Tensor Cores على أجهزة NVIDIA التي تتمتع بقابلية معالجة `>= 7.5` (Volta). 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)` لكل رمز. هذه الخاصية متاحة فقط في مُرمّزيات fast التي ترث من [PreTrainedTokenizerFast](/docs/transformers/main/ar/main_classes/tokenizer#transformers.TokenizersBackend)، وإذا كنت تستخدم مُرمّزي Python، فسيُطلق هذا الدالة `NotImplementedError`. return_length (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان يجب إرجاع أطوال المدخلات المُرمّزة أم لا. verbose (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب طباعة مزيد من المعلومات والتنبيهات أم لا. return_tensors (`Union[str, ~utils.generic.TensorType]`، *اختياري*) : إذا تم تعيينه، فسيُرجع تينسورات (Tensors) لإطار عمل معين. القيم المقبولة هي: - `'pt'`: يُرجع كائنات `torch.Tensor` من PyTorch. - `'np'`: يُرجع كائنات `np.ndarray` من NumPy. **يعيد:** `~tokenization_utils_base.BatchEncoding` - **data** (`dict`، *اختياري*) -- قاموس من القوائم/المصفوفات/الموترات الذي يُعاد عن طريق طرق `__call__`/`encode_plus`/`batch_encode_plus` ('input_ids'، 'attention_mask'، إلخ). - **encoding** (`tokenizers.Encoding` أو `Sequence[tokenizers.Encoding]`، *اختياري*) -- إذا كان مُجزِّئ الرموز مُجزِّئًا سريعًا يُخرج معلومات إضافية مثل التحويل من فضاء الكلمات/الأحرف إلى فضاء الرموز، فإنّ كائن `tokenizers.Encoding` أو قائمة من الكائنات (للدفّات) تحتفظ بهذه المعلومات. - **tensor_type** (`Union[None, str, TensorType]`، *اختياري*) -- يمكنك تحديد tensor_type هنا لتحويل قوائم الأعداد الصحيحة إلى تينسورات PyTorch/Numpy عند التهيئة. - **prepend_batch_axis** (`bool`, *اختياري*، القيمة الافتراضية `False`) -- ما إذا كان يجب إضافة محور الدفعة عند التحويل إلى المصفوفات (انظر `tensor_type` أعلاه). يُرجى ملاحظة أن لهذا المعامل تأثير إذا تم تعيين المعامل `tensor_type`، *وإلا فلا يكون له أي تأثير*. - **n_sequences** (`int`, *اختياري*) -- عدد تسلسلات الإدخال التي يمثلها كل ترميز (`None` للمجهول، و`1` لتسلسل واحد، و`2` لزوج من التسلسلات).