Transformers documentation
منسّق البيانات
منسّق البيانات
مجمِّعات البيانات هي كائنات تُشكِّل دفعةً (batch) باستخدام قائمة من عناصر مجموعة البيانات كمدخلات. تكون هذه العناصر من نفس نوع عناصر train_dataset أو eval_dataset.
لتمكين من بناء الدفعات، قد تطبّق مجمّعات البيانات بعض المعالجات (مثل الحشو). وتطبّق بعض هذه المجمّعات (مثل DataCollatorForLanguageModeling) أيضاً بعض المعالجات العشوائية للبيانات (مثل الإخفاء العشوائي) على الدفعة المُشكَّلة.
يمكن العثور على أمثلة للاستخدام في دفاتر الأمثلة.
مجمّع البيانات الافتراضي
مجمِّع بيانات بسيط للغاية يجمع دفعات من كائنات تشبه القواميس ويؤدي معالجة خاصة للمفاتيح المحتملة المسماة:
label: يتعامل مع قيمة واحدة (int أو float) لكل كائنlabel_ids: يتعامل مع قائمة من القيم لكل كائن
لا يقوم بأي معالجة مسبقة إضافية: سيتم استخدام أسماء خصائص كائن الإدخال كمدخلات مقابلة للنموذج. راجع glue وner كمثال على كيفية فائدته.
DefaultDataCollator
فئة transformers.DefaultDataCollator
< source >( return_tensors: str = 'pt' )
مجمِّع بيانات بسيط للغاية يجمع دفعات من كائنات تشبه القواميس ويؤدي معالجة خاصة للمفاتيح المحتملة المسماة:
label: يتعامل مع قيمة واحدة (int أو float) لكل كائنlabel_ids: يتعامل مع قائمة من القيم لكل كائن
لا يقوم بأي معالجة مسبقة إضافية: سيتم استخدام أسماء خصائص كائن الإدخال كمدخلات مقابلة للنموذج. راجع glue وner كمثال على كيفية فائدته.
هذا كائن (مثل مُجمِّعات البيانات الأخرى) وليس دالةً خالصةً مثل default_data_collator. وقد يكون ذلك مفيداً إذا كنت بحاجة إلى تعيين قيمة return_tensors عند التهيئة.
DataCollatorWithPadding
فئة transformers.DataCollatorWithPadding
< source >( 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
< source >( 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
< source >( 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
< source >( 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، مع المفتاح
<Example Options and Expectations>"special_tokens_mask"، كما تُعاد بواسطة PreTrainedTokenizer أو PreTrainedTokenizerFast مع الحجةreturn_special_tokens_mask=True.
السلوك الافتراضي:
mask_replace_prob=0.8,random_replace_prob=0.1.- توقع أن يتم استبدال 80% من الرموز المقنّعة بـ
[MASK]، واستبدال 10% برموز عشوائية، وإبقاء 10% دون تغيير.جميع الرموز المقنّعة التي استُبدلت بـ
[MASK]:
mask_replace_prob=1.0,random_replace_prob=0.0.- توقع أن يتم استبدال جميع الرموز المقنّعة بـ
[MASK]. لا تُترك أي رموز دون تغيير ولا تُستبدل برموز عشوائية.لا يوجد استبدال بـ
[MASK]، بل رموز عشوائية فقط:
mask_replace_prob=0.0,random_replace_prob=1.0.- توقع أن يتم استبدال جميع الرموز المقنّعة برموز عشوائية. لا توجد عمليات استبدال بـ
[MASK]أو رموز لم تتغير.استبدال متوازن:
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
< source >( inputs: Anyspecial_tokens_mask: typing.Any | None = Noneoffset_mapping: typing.Any | None = None )
جهّز مدخلات/تسميات الرموز المقنّعة لنمذجة اللغة المقنّعة.
torch_mask_tokens
< source >( inputs: Anyspecial_tokens_mask: typing.Any | None = Noneoffset_mapping: typing.Any | None = None )
جهّز مدخلات/تسميات الرموز المقنّعة لنمذجة اللغة المقنّعة.
DataCollatorForPermutationLanguageModeling
فئة transformers.DataCollatorForPermutationLanguageModeling
< source >( tokenizer: PreTrainedTokenizerBaseplm_probability: float = 0.16666666666666666max_span_length: int = 5return_tensors: str = 'pt' )
مجمّع البيانات المستخدم لنمذجة اللغة بالتبديل.
- يجمع دفعات من الموترات (tensors) مع مراعاة رمز الحشو (pad_token) الخاص بمجزّئها (tokenizer).
- يعالج الدفعات مسبقاً لنمذجة اللغة بالتبديل باستخدام إجراءات خاصة بـ XLNet
تُحدَّد الرموز المقنَّعة التي يجب التنبؤ بها لسلسلة معينة من خلال الخوارزمية التالية:
- ابدأ من بداية التسلسل عن طريق تعيين
cur_len = 0(عدد الرموز التي تم معالجتها حتى الآن). - اختر
span_lengthعشوائياً من الفترة[1, max_span_length](طول المقطع من الرموز التي سيتم إخفاؤها) - احجز سياقاً بطول
context_length = span_length / plm_probabilityلمحيط الجزء الذي سيتم إخفاؤه - اختر نقطة بداية
start_indexمن الفترة[cur_len, cur_len + context_length - span_length]وأقنِع الرموزstart_index:start_index + span_length - اضبط
cur_len = cur_len + context_length. إذا كانcur_len < max_len(أي أنه لا تزال هناك رموز متبقية في التسلسل لم تتم معالجتها)، كرر من الخطوة 1.
تُحدَّد الرموز المقنَّعة التي يجب التنبؤ بها لسلسلة معينة من خلال الخوارزمية التالية:
- ابدأ من بداية التسلسل عن طريق تعيين
cur_len = 0(عدد الرموز التي تم معالجتها حتى الآن). - اختر
span_lengthعشوائياً من الفترة[1, max_span_length](طول المقطع من الرموز التي سيتم إخفاؤها) - احجز سياقاً بطول
context_length = span_length / plm_probabilityلمحيط الجزء الذي سيتم إخفاؤه - اختر نقطة بداية
start_indexمن الفترة[cur_len, cur_len + context_length - span_length]وأقنِع الرموزstart_index:start_index + span_length - اضبط
cur_len = cur_len + context_length. إذا كانcur_len < max_len(أي أنه لا تزال هناك رموز متبقية في التسلسل لم تتم معالجتها)، كرر من الخطوة 1.
DataCollatorWithFlattening
فئة transformers.DataCollatorWithFlattening
< source >( *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
< source >( 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”.
مجمِّع بيانات يقوم بتوسيط ديناميكي لدفعة من الأمثلة المتداخلة لاختيارات متعددة، بحيث تكون جميع الخيارات لجميع الأمثلة بنفس الطول.