Transformers documentation

منسّق البيانات

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

منسّق البيانات

مجمِّعات البيانات هي كائنات تُشكِّل دفعةً (batch) باستخدام قائمة من عناصر مجموعة البيانات كمدخلات. تكون هذه العناصر من نفس نوع عناصر train_dataset أو eval_dataset.

لتمكين من بناء الدفعات، قد تطبّق مجمّعات البيانات بعض المعالجات (مثل الحشو). وتطبّق بعض هذه المجمّعات (مثل DataCollatorForLanguageModeling) أيضاً بعض المعالجات العشوائية للبيانات (مثل الإخفاء العشوائي) على الدفعة المُشكَّلة.

يمكن العثور على أمثلة للاستخدام في دفاتر الأمثلة.

مجمّع البيانات الافتراضي

transformers.default_data_collator

< >

( features: listreturn_tensors = 'pt' )

مجمِّع بيانات بسيط للغاية يجمع دفعات من كائنات تشبه القواميس ويؤدي معالجة خاصة للمفاتيح المحتملة المسماة:

  • label: يتعامل مع قيمة واحدة (int أو float) لكل كائن
  • label_ids: يتعامل مع قائمة من القيم لكل كائن

لا يقوم بأي معالجة مسبقة إضافية: سيتم استخدام أسماء خصائص كائن الإدخال كمدخلات مقابلة للنموذج. راجع glue وner كمثال على كيفية فائدته.

DefaultDataCollator

فئة transformers.DefaultDataCollator

< >

( return_tensors: str = 'pt' )

المعاملات

  • return_tensors (str، اختياري، القيمة الافتراضية "pt") — نوع Tensor المُعاد. القيم المسموح بها هي “np” أو “pt”.

مجمِّع بيانات بسيط للغاية يجمع دفعات من كائنات تشبه القواميس ويؤدي معالجة خاصة للمفاتيح المحتملة المسماة:

  • label: يتعامل مع قيمة واحدة (int أو float) لكل كائن
  • label_ids: يتعامل مع قائمة من القيم لكل كائن

لا يقوم بأي معالجة مسبقة إضافية: سيتم استخدام أسماء خصائص كائن الإدخال كمدخلات مقابلة للنموذج. راجع glue وner كمثال على كيفية فائدته.

هذا كائن (مثل مُجمِّعات البيانات الأخرى) وليس دالةً خالصةً مثل default_data_collator. وقد يكون ذلك مفيداً إذا كنت بحاجة إلى تعيين قيمة return_tensors عند التهيئة.

DataCollatorWithPadding

فئة transformers.DataCollatorWithPadding

< >

( tokenizer: PreTrainedTokenizerBasepadding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonepad_to_multiple_of: int | None = Nonereturn_tensors: str = 'pt' )

المعاملات

  • tokenizer (PreTrainedTokenizer أو PreTrainedTokenizerFast) — المُرمِّز المستخدم لتشفير البيانات.
  • padding (bool, str أو PaddingStrategy, اختياري, الافتراضي هو True) — اختر استراتيجية لحشو التسلسلات المُعادَة (وفقًا لجانب الحشو وفهرس الحشو الخاص بالنموذج) من بين الخيارات التالية: True أو 'longest' (الافتراضي): حشو حتى أطول تسلسل في الدفعة (أو بدون حشو إذا تم تقديم تسلسل واحد فقط). 'max_length': حشو حتى الحد الأقصى للطول المحدد بواسطة الحجة max_length أو حتى الحد الأقصى المقبول لطول الإدخال للنموذج إذا لم يتم تقديم تلك الحجة. False أو 'do_not_pad': بدون حشو (أي، يمكن إخراج دفعة تحتوي على تسلسلات بطول مختلف).
    • True أو 'longest' (الافتراضي): يتم ملء التسلسلات حتى أطول تسلسل في الدفعة (أو لا يتم أي ملء إذا تم تقديم تسلسل واحد فقط).
    • 'max_length': يتم ملء النص حتى الطول الأقصى المحدد عبر الحجة max_length أو حتى الطول الأقصى المقبول لإدخال النموذج إذا لم تُقدَّم تلك الحجة.
    • False أو 'do_not_pad': لا يُستخدم الحشو (أي، يمكن إخراج دفعة تحتوي على تسلسلات بطول مختلف).
  • max_length (int، اختياري) — الحد الأقصى لطول القائمة المُعادَة وطول الحشو بشكل اختياري (انظر أعلاه).
  • pad_to_multiple_of (int, اختياري) — إذا تم تعيينه، سيتم توسيط التسلسل إلى مضاعف للقيمة المُقدَّمة.

    يُعدّ هذا مفيداً بشكل خاص لتفعيل استخدام نوى التينسور (Tensor Cores) على أجهزة NVIDIA التي تتمتع بقابلية معالجة >= 7.0 (Volta).

  • return_tensors (str، اختياري، القيمة الافتراضية "pt") — نوع Tensor المُعاد. القيم المسموح بها هي “np” أو “pt”.

مجمّع بيانات يقوم بتوسيط المدخلات المستلمة ديناميكيًا.

DataCollatorForTokenClassification

فئة transformers.DataCollatorForTokenClassification

< >

( tokenizer: PreTrainedTokenizerBasepadding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonepad_to_multiple_of: int | None = Nonelabel_pad_token_id: int = -100return_tensors: str = 'pt' )

المعاملات

  • tokenizer (PreTrainedTokenizer أو PreTrainedTokenizerFast) — المُرمِّز المستخدم لتشفير البيانات.
  • padding (bool, str أو PaddingStrategy, اختياري, الافتراضي هو True) — اختر استراتيجية لحشو التسلسلات المُعادَة (وفقًا لجانب الحشو وفهرس الحشو الخاص بالنموذج) من بين الخيارات التالية: True أو 'longest' (الافتراضي): حشو حتى أطول تسلسل في الدفعة (أو بدون حشو إذا تم تقديم تسلسل واحد فقط). 'max_length': حشو حتى الحد الأقصى للطول المحدد بواسطة الحجة max_length أو حتى الحد الأقصى المقبول لطول الإدخال للنموذج إذا لم يتم تقديم تلك الحجة. False أو 'do_not_pad': بدون حشو (أي، يمكن إخراج دفعة تحتوي على تسلسلات بطول مختلف).
    • True أو 'longest' (الافتراضي): يتم ملء التسلسلات حتى أطول تسلسل في الدفعة (أو لا يتم أي ملء إذا تم تقديم تسلسل واحد فقط).
    • 'max_length': يتم ملء النص حتى الطول الأقصى المحدد عبر الحجة max_length أو حتى الطول الأقصى المقبول لإدخال النموذج إذا لم تُقدَّم تلك الحجة.
    • False أو 'do_not_pad': لا يُستخدم الحشو (أي، يمكن إخراج دفعة تحتوي على تسلسلات بطول مختلف).
  • max_length (int، اختياري) — الحد الأقصى لطول القائمة المُعادَة وطول الحشو بشكل اختياري (انظر أعلاه).
  • pad_to_multiple_of (int, اختياري) — إذا تم تعيينه، سيتم توسيط التسلسل إلى مضاعف للقيمة المُقدَّمة.

    يُعدّ هذا مفيداً بشكل خاص لتفعيل استخدام نوى التينسور (Tensor Cores) على أجهزة NVIDIA التي تتمتع بقابلية معالجة >= 7.0 (Volta).

  • label_pad_token_id (int، اختياري، القيمة الافتراضية -100) — المعرّف المستخدم عند ملء التسميات (سيتم تجاهل -100 تلقائيًا بواسطة دوال الخسارة في PyTorch).
  • return_tensors (str، اختياري، القيمة الافتراضية "pt") — نوع Tensor المُعاد. القيم المسموح بها هي “np” أو “pt”.

مجمّع بيانات يقوم بتوسيط المدخلات المستلمة ديناميكياً، وكذلك التسميات.

DataCollatorForSeq2Seq

فئة transformers.DataCollatorForSeq2Seq

< >

( tokenizer: PreTrainedTokenizerBasemodel: typing.Any | None = Nonepadding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonepad_to_multiple_of: int | None = Nonelabel_pad_token_id: int = -100return_tensors: str = 'pt' )

المعاملات

  • tokenizer (PreTrainedTokenizer أو PreTrainedTokenizerFast) — المُرمِّز المستخدم لتشفير البيانات.
  • model (PreTrainedModel, اختياري) — النموذج الذي يتم تدريبه. إذا تم تعيينه وكان يحتوي على prepare_decoder_input_ids_from_labels, ، فاستخدمه لتحضير decoder_input_ids

    يُعدّ هذا مفيداً عند استخدام label_smoothing لتجنّب حساب الخسارة مرتين.

  • padding (bool, str أو PaddingStrategy, اختياري, الافتراضي هو True) — اختر استراتيجية لحشو التسلسلات المُعادَة (وفقًا لجانب الحشو وفهرس الحشو الخاص بالنموذج) من بين الخيارات التالية: True أو 'longest' (الافتراضي): حشو حتى أطول تسلسل في الدفعة (أو بدون حشو إذا تم تقديم تسلسل واحد فقط). 'max_length': حشو حتى الحد الأقصى للطول المحدد بواسطة الحجة max_length أو حتى الحد الأقصى المقبول لطول الإدخال للنموذج إذا لم يتم تقديم تلك الحجة. False أو 'do_not_pad': بدون حشو (أي، يمكن إخراج دفعة تحتوي على تسلسلات بطول مختلف).
    • True أو 'longest' (الافتراضي): يتم ملء التسلسلات حتى أطول تسلسل في الدفعة (أو لا يتم أي ملء إذا تم تقديم تسلسل واحد فقط).
    • 'max_length': يتم ملء النص حتى الطول الأقصى المحدد عبر الحجة max_length أو حتى الطول الأقصى المقبول لإدخال النموذج إذا لم تُقدَّم تلك الحجة.
    • False أو 'do_not_pad': لا يُستخدم الحشو (أي، يمكن إخراج دفعة تحتوي على تسلسلات بطول مختلف).
  • max_length (int، اختياري) — الحد الأقصى لطول القائمة المُعادَة وطول الحشو بشكل اختياري (انظر أعلاه).
  • pad_to_multiple_of (int, اختياري) — إذا تم تعيينه، سيتم توسيط التسلسل إلى مضاعف للقيمة المُقدَّمة.

    يُعدّ هذا مفيداً بشكل خاص لتفعيل استخدام نوى التينسور (Tensor Cores) على أجهزة NVIDIA التي تتمتع بقابلية معالجة >= 7.0 (Volta).

  • label_pad_token_id (int، اختياري، القيمة الافتراضية -100) — المعرّف المستخدم عند ملء التسميات (سيتم تجاهل -100 تلقائيًا بواسطة دوال الخسارة في PyTorch).
  • return_tensors (str، اختياري، القيمة الافتراضية "pt") — نوع Tensor المُعاد. القيم المسموح بها هي “np” أو “pt”.

مجمّع بيانات يقوم بتوسيط المدخلات المستلمة ديناميكياً، وكذلك التسميات.

DataCollatorForLanguageModeling

فئة transformers.DataCollatorForLanguageModeling

< >

( tokenizer: PreTrainedTokenizerBasemlm: bool = Truewhole_word_mask: bool = Falsemlm_probability: float | None = 0.15mask_replace_prob: float = 0.8random_replace_prob: float = 0.1pad_to_multiple_of: int | None = Nonereturn_tensors: str = 'pt'seed: int | None = None )

المعاملات

  • tokenizer (PreTrainedTokenizer أو PreTrainedTokenizerFast) — المُرمِّز المستخدم لتشفير البيانات.
  • mlm (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم استخدام نمذجة اللغة المقنّعة أم لا. إذا تم ضبطه على False، تكون التسميات هي نفسها المدخلات مع تجاهل رموز الحشو (عن طريق ضبطها على -100). وإلا، تكون التسميات -100 للرموز غير المقنّعة والقيمة المتوقعة للرمز المقنّع.
  • whole_word_mask (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم إخفاء الكلمات الكاملة بدلاً من الرموز الفردية.
  • mlm_probability (float، اختياري، القيمة الافتراضية 0.15) — الاحتمال الذي يتم بموجبه إخفاء الرموز (عشوائياً) في المدخلات، عند ضبط mlm على True.
  • mask_replace_prob (float, اختياري، القيمة الافتراضية 0.8) — احتمال استبدال الرموز المقنّعة برمz القناع الخاص بمعالج الرموز (مثل [MASK]). القيمة الافتراضية هي 0.8، مما يعني أن 80% من الرموز المقنّعة ستُستبدل بـ [MASK]. يعمل فقط عند ضبط mlm على True.
  • random_replace_prob (float, اختياري، القيمة الافتراضية 0.1) — احتمال استبدال الرموز المقنّعة برموز عشوائية من مفردات مُجزّئ الرموز. القيمة الافتراضية هي 0.1، مما يعني أن 10% من الرموز المقنّعة ستُستبدل برموز عشوائية. تبقى الرموز المقنّعة المتبقية (1 - mask_replace_prob - random_replace_prob) دون تغيير. يعمل هذا الخيار فقط عند ضبط mlm على True.
  • pad_to_multiple_of (int، اختياري) — إذا تم تعيينه، سيتم توسيط التسلسل إلى مضاعف للقيمة المُقدَّمة.
  • return_tensors (str) — نوع Tensor المُعاد. القيم المسموح بها هي “np” أو “pt”.
  • seed (int، اختياري) — البذرة المستخدمة لمولّد الأرقام العشوائية للتعتيم. إذا لم تُقدَّم، فسيتم استخدام مولّد الأرقام العشوائية العام.

مُجمِّع البيانات المستخدم لنمذجة اللغة. يتم توسيد المدخلات ديناميكيًا حتى الطول الأقصى للدفعة إذا لم تكن جميعها بنفس الطول.

للحصول على أفضل أداء، يجب استخدام مِجمِّع البيانات هذا مع مجموعة بيانات تحتوي على عناصر تكون قواميس أو BatchEncoding، مع المفتاح "special_tokens_mask"، كما تُعاد بواسطة PreTrainedTokenizer أو PreTrainedTokenizerFast مع الحجة return_special_tokens_mask=True.

<Example Options and Expectations>
  1. السلوك الافتراضي:

    • mask_replace_prob=0.8, random_replace_prob=0.1.
    • توقع أن يتم استبدال 80% من الرموز المقنّعة بـ[MASK]، واستبدال 10% برموز عشوائية، وإبقاء 10% دون تغيير.
  2. جميع الرموز المقنّعة التي استُبدلت بـ [MASK]:

    • mask_replace_prob=1.0, random_replace_prob=0.0.
    • توقع أن يتم استبدال جميع الرموز المقنّعة بـ [MASK]. لا تُترك أي رموز دون تغيير ولا تُستبدل برموز عشوائية.
  3. لا يوجد استبدال بـ [MASK]، بل رموز عشوائية فقط:

    • mask_replace_prob=0.0, random_replace_prob=1.0.
    • توقع أن يتم استبدال جميع الرموز المقنّعة برموز عشوائية. لا توجد عمليات استبدال بـ[MASK] أو رموز لم تتغير.
  4. استبدال متوازن:

    • mask_replace_prob=0.5, random_replace_prob=0.4.
    • توقع أن يتم استبدال 50% من الرموز المقنّعة بـ [MASK]، واستبدال 40% برموز عشوائية، وإبقاء 10% دون تغيير.

ملاحظة: يجب ألا يتجاوز مجموع mask_replace_prob وrandom_replace_prob القيمة 1. إذا كان مجموعهما أقل من 1، فإن النسبة المتبقية ستتكون من رموز مقنّعة تُترك دون تغيير.

numpy_mask_tokens

< >

( inputs: Anyspecial_tokens_mask: typing.Any | None = Noneoffset_mapping: typing.Any | None = None )

جهّز مدخلات/تسميات الرموز المقنّعة لنمذجة اللغة المقنّعة.

torch_mask_tokens

< >

( inputs: Anyspecial_tokens_mask: typing.Any | None = Noneoffset_mapping: typing.Any | None = None )

جهّز مدخلات/تسميات الرموز المقنّعة لنمذجة اللغة المقنّعة.

DataCollatorForPermutationLanguageModeling

فئة transformers.DataCollatorForPermutationLanguageModeling

< >

( tokenizer: PreTrainedTokenizerBaseplm_probability: float = 0.16666666666666666max_span_length: int = 5return_tensors: str = 'pt' )

مجمّع البيانات المستخدم لنمذجة اللغة بالتبديل.

  • يجمع دفعات من الموترات (tensors) مع مراعاة رمز الحشو (pad_token) الخاص بمجزّئها (tokenizer).
  • يعالج الدفعات مسبقاً لنمذجة اللغة بالتبديل باستخدام إجراءات خاصة بـ XLNet

numpy_mask_tokens

< >

( inputs: Any )

تُحدَّد الرموز المقنَّعة التي يجب التنبؤ بها لسلسلة معينة من خلال الخوارزمية التالية:

  1. ابدأ من بداية التسلسل عن طريق تعيين cur_len = 0 (عدد الرموز التي تم معالجتها حتى الآن).
  2. اختر span_length عشوائياً من الفترة [1, max_span_length] (طول المقطع من الرموز التي سيتم إخفاؤها)
  3. احجز سياقاً بطول context_length = span_length / plm_probability لمحيط الجزء الذي سيتم إخفاؤه
  4. اختر نقطة بداية start_index من الفترة [cur_len, cur_len + context_length - span_length] وأقنِع الرموز start_index:start_index + span_length
  5. اضبط cur_len = cur_len + context_length. إذا كان cur_len < max_len (أي أنه لا تزال هناك رموز متبقية في التسلسل لم تتم معالجتها)، كرر من الخطوة 1.

torch_mask_tokens

< >

( inputs: Any )

تُحدَّد الرموز المقنَّعة التي يجب التنبؤ بها لسلسلة معينة من خلال الخوارزمية التالية:

  1. ابدأ من بداية التسلسل عن طريق تعيين cur_len = 0 (عدد الرموز التي تم معالجتها حتى الآن).
  2. اختر span_length عشوائياً من الفترة [1, max_span_length] (طول المقطع من الرموز التي سيتم إخفاؤها)
  3. احجز سياقاً بطول context_length = span_length / plm_probability لمحيط الجزء الذي سيتم إخفاؤه
  4. اختر نقطة بداية start_index من الفترة [cur_len, cur_len + context_length - span_length] وأقنِع الرموز start_index:start_index + span_length
  5. اضبط cur_len = cur_len + context_length. إذا كان cur_len < max_len (أي أنه لا تزال هناك رموز متبقية في التسلسل لم تتم معالجتها)، كرر من الخطوة 1.

DataCollatorWithFlattening

فئة transformers.DataCollatorWithFlattening

< >

( *argsreturn_position_ids = Trueseparator_id = -100return_flash_attn_kwargs = Falsereturn_seq_idx = Falseposition_ids_start = 0**kwargs )

المعاملات

  • return_position_ids (bool، اختياري، القيمة الافتراضية True) — ما إذا كان يجب إرجاع position_ids، والتي تُعاد من position_ids_start لكل تسلسل مُسطّح.
  • separator_id (int، اختياري، القيمة الافتراضية -100) — القيمة المستخدمة لفصل التسلسلات داخل labels المدمجة.
  • return_flash_attn_kwargs (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب إرجاع معاملات حدود التسلسل (kwargs) المستخدمة في FlashAttention (cu_seq_lens_q، cu_seq_lens_k، max_length_q وmax_length_k).
  • return_seq_idx (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب إرجاع seq_idx، الذي يحدد التسلسل الذي ينتمي إليه كل رمز.
  • position_ids_start (int، اختياري، القيمة الافتراضية 0) — معرّف الموضع المُعطى للرمز الأول في كل تسلسل.

مُجمِّع البيانات المستخدم في نهج خالٍ من الحشو. يقوم بما يلي:

  • يجمع الدفعة الفرعية بأكملها في تسلسل طويل واحد من الشكل [1, total_tokens]
  • يستخدم separator_id لفصل التسلسلات داخل labels المدمجة، والقيمة الافتراضية هي -100
  • لن يتم إضافة أي حشو، وتُرجع input_ids وlabels وposition_ids افتراضيًا
  • تُرجع اختياريًا معاملات kwargs الموجودة في FlashAttentionKwargs
  • يعيد اختياريًا seq_idx الذي يحدد التسلسل الذي ينتمي إليه كل رمز

سيؤدي استخدام DataCollatorWithFlattening إلى تسطيح الدفعة الفرعية بأكملها في تسلسل طويل واحد. تأكد من أن حساب الانتباه لديك قادر على التعامل مع ذلك!

لا يبدأ كل نموذج ترقيم الموضع من 0 عند حساب معرّفات الموضع بنفسه. تبدأ البنى المعمارية المشابهة لـ RoBERTa (من بينها roberta وxlm_roberta وcamembert وmpnet وesm مع تضمينات الموضع المطلقة) من padding_idx + 1، وهو عادةً 2. تمرير معرّفات الموضع الافتراضية القائمة على 0 إلى هذه النماذج من خلال position_ids يُسبّب إزاحة تضمينات الموضع بصمت وتدهور مخرجاتها، لذا اضبط position_ids_start بشكل مناسب لتلك النماذج.

DataCollatorForMultipleChoice

فئة transformers.DataCollatorForMultipleChoice

< >

( tokenizer: PreTrainedTokenizerBasepadding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonepad_to_multiple_of: int | None = Nonereturn_tensors: str = 'pt' )

المعاملات

  • tokenizer (PreTrainedTokenizer أو PreTrainedTokenizerFast) — المُرمِّز المستخدم لتشفير البيانات.
  • padding (bool, str أو PaddingStrategy, اختياري, الافتراضي هو True) — اختر استراتيجية لحشو التسلسلات المُعادَة وفقًا لجانب الحشو وفهرس الحشو الخاص بالنموذج، من بين الخيارات التالية: True أو 'longest': الحشو حتى أطول تسلسل في الدفعة (أو بدون حشو إذا تم تقديم تسلسل واحد فقط). 'max_length': الحشو حتى الحد الأقصى للطول المحدد بواسطة الحجة max_length أو حتى الحد الأقصى المقبول لطول الإدخال للنموذج إذا لم تُقدَّم تلك الحجة. False أو 'do_not_pad' (الافتراضي): بدون حشو (أي، يمكن إخراج دفعة تحتوي على تسلسلات بطول مختلف).
    • True أو 'longest': يتم ملء التسلسلات حتى أطول تسلسل في الدفعة (أو لا يتم أي ملء إذا تم تقديم تسلسل واحد فقط).
    • 'max_length': يتم ملء النص حتى الطول الأقصى المحدد عبر الحجة max_length أو حتى الطول الأقصى المقبول لإدخال النموذج إذا لم تُقدَّم تلك الحجة.
    • False أو 'do_not_pad' (الافتراضي): لا يوجد حشو (أي، يمكن إخراج دفعة تحتوي على تسلسلات بطول مختلف).
  • max_length (int، اختياري) — الحد الأقصى لطول القائمة المُعادَة وطول الحشو بشكل اختياري (انظر أعلاه).
  • pad_to_multiple_of (int, اختياري) — توسيط التسلسل إلى مضاعف للقيمة المُقدَّمة. هذا مفيد بشكل خاص لتفعيل استخدام نوى الموترات (Tensor Cores) على أجهزة NVIDIA التي تتمتع بقابلية معالجة >= 7.5 (Volta).

    يُعدّ هذا مفيدًا بشكل خاص لتفعيل استخدام نوى التينسور (Tensor Cores) على أجهزة NVIDIA التي تتمتع بقابلية معالجة >= 7.5 (Volta).

  • return_tensors (str، اختياري، القيمة الافتراضية "pt") — نوع Tensor المُعاد. القيم المسموح بها هي “np” أو “pt”.

مجمِّع بيانات يقوم بتوسيط ديناميكي لدفعة من الأمثلة المتداخلة لاختيارات متعددة، بحيث تكون جميع الخيارات لجميع الأمثلة بنفس الطول.

Update on GitHub