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

يجمع مُجمِّع البيانات (Data Collator) عينات مجموعة البيانات الفردية في دفعة (batch) للنموذج. كما يمكنه أيضًا ملء العينات ديناميكيًا حتى أطول تسلسل في *كل دفعة*، وهو ما يكون أكثر كفاءة من الملء حتى الحد الأقصى الطولي العام.

```md
Dataset[0] → {"input_ids": [101, 2003], "labels": 1}
Dataset[1] → {"input_ids": [101, 2003, 1996], "labels": 0}
Dataset[2] → {"input_ids": [101, 7592], "labels": 1}
         ↓  collator
{
  "input_ids": tensor([[101, 2003,    0],   # padded to longest
                        [101, 2003, 1996],
                        [101, 7592,    0]]),
  "labels":    tensor([1, 0, 1])
}
```

توفر مكتبة Transformers أدوات لجمع البيانات (data collators) لمهام مختلفة (انظر جميع [أدوات جمع البيانات](./main_classes/data_collator) المتاحة). أنشئ أداة جمع بيانات مخصصة باستخدام:

- [DataCollatorWithPadding](#datacollatorwithpadding) عندما تحتاج إلى تعبئة قياسية مبنية على مُجزِّئ النصوص بالإضافة إلى حقول إضافية.
- [DataCollatorMixin](#datacollatormixin) عندما تحتاج إلى منطق توسيد مخصص، أو مدخلات متعددة متزاوجة لكل عينة، أو بنية دفعة لا يستطيع مُرمّز الرموز إنتاجها بمفرده.

## DataCollatorWithPadding

في حالات الاستخدام البسيطة مثل إضافة حقل إضافي، قم بإنشاء فئة فرعية من [DataCollatorWithPadding](/docs/transformers/main/ar/main_classes/data_collator#transformers.DataCollatorWithPadding) ووسّع طريقة `__call__` الخاصة بها. يضيف المثال أدناه حقل `"score"`.

1. أزل الحقل المخصص أولاً لأن [pad()](/docs/transformers/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.pad) لا يتعرف عليه.
2. استدعِ الفئة الأصلية للتعامل مع `input_ids` و`attention_mask`.
3. أعد إضافة الحقل `"score"` إلى الدفعة.

```py
import torch
from dataclasses import dataclass
from transformers import DataCollatorWithPadding, PreTrainedTokenizerBase

@dataclass
class DataCollatorWithScore(DataCollatorWithPadding):
    tokenizer: PreTrainedTokenizerBase

    def __call__(self, features):
        scores = [f.pop("score") for f in features]

        batch = super().__call__(features)
        batch["score"] = torch.tensor(scores, dtype=torch.float)

        return batch
```

مرّر مُجمِّع البيانات المخصص إلى [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) تمامًا كما تفعل مع أي مُجمِّع بيانات آخر.

```py
trainer = Trainer(
    ...,
    data_collator=DataCollatorWithScore(tokenizer=tokenizer),
)
```

## DataCollatorMixin

ارث من `DataCollatorMixin` للحصول على تحكم كامل في تجميع الدُفعات، ونفّذ منهج `__call__` الخاص بك. ابنِ منطق حشو مخصص، أو تعامل مع أنواع مدخلات متعددة، أو أنشئ هياكل دفعات جديدة كليًا. يستخدم المثال أدناه [DataCollatorForPreference](https://github.com/huggingface/trl/blob/cfbdd3bea4448cde878c0da0de49551f553c61fe/trl/trainer/reward_trainer.py#L126) `DataCollatorMixin` لأن كل عينة تدريب تحتوي على ردّ مُختار وردّ مرفوض، ويحتاج النموذج إلى رؤية كلاهما.

1. افصل `chosen_ids` عن `rejected_ids` لأن `pad` يتوقع قوائم مسطحة.
2. ادمج الزوج المدخل في قائمة واحدة.
3. أنشئ `attention_mask` باستخدام [torch.ones_like](https://docs.pytorch.org/docs/stable/generated/torch.ones_like.html) بدلاً من المُرمِّز (tokenizer)، لأن المُجمِّع (collator) يعمل مع قوائم معرّفات الرموز الخام.
4. أضف الحشو إلى `input_ids` و`attention_mask`.

```py
import torch
from dataclasses import dataclass
from transformers.data.data_collator import DataCollatorMixin
from trl.trainer.utils import pad

@dataclass
class DataCollatorForPreference(DataCollatorMixin):
    pad_token_id: int
    pad_to_multiple_of: int | None = None

    def __call__(self, examples: list[dict]) -> dict:
        chosen_input_ids   = [torch.tensor(ex["chosen_ids"])   for ex in examples]
        rejected_input_ids = [torch.tensor(ex["rejected_ids"]) for ex in examples]

        input_ids      = chosen_input_ids + rejected_input_ids
        attention_mask = [torch.ones_like(ids) for ids in input_ids]

        output = {
            "input_ids": pad(
                input_ids,
                padding_value=self.pad_token_id,
                padding_side="right",
                pad_to_multiple_of=self.pad_to_multiple_of,
            ),
            "attention_mask": pad(
                attention_mask,
                padding_value=0,
                padding_side="right",
                pad_to_multiple_of=self.pad_to_multiple_of,
            ),
        }

        ...

        return output
```

## الخطوات التالية

- اطّلع على جميع [مجمّعات البيانات](./main_classes/data_collator) المتاحة للمهام الشائعة مثل تصنيف الرموز.