# 数据整理器

数据整理器（data collator）将单个数据集样本组装成供模型使用的批次。它还可以动态地将样本填充到*每个批次*中最长的序列长度，这比填充到全局最大长度更高效。

```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 collator）（参见所有可用的 [数据整理器](./main_classes/data_collator)）。使用以下内容创建自定义数据整理器：

- 当您需要基于标准分词器的填充以及额外字段时，请使用 [DataCollatorWithPadding](#datacollatorwithpadding)。
- 当您需要自定义填充逻辑、每个样本包含多组配对输入，或者分词器无法自行生成的批次结构时，请使用 [DataCollatorMixin](#datacollatormixin)。

## DataCollatorWithPadding

对于添加额外字段等简单用例，请子类化 [DataCollatorWithPadding](/docs/transformers/v5.23.0/zh/main_classes/data_collator#transformers.DataCollatorWithPadding) 并扩展其 `__call__` 方法。下面的示例添加了一个 `"score"` 字段。

1. 首先移除自定义字段，因为 [pad()](/docs/transformers/v5.23.0/zh/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/v5.23.0/zh/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. 由于 collator 处理的是原始 token ID 列表，请使用 [torch.ones_like](https://docs.pytorch.org/docs/stable/generated/torch.ones_like.html) 而不是 tokenizer 来生成 `attention_mask`。
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)。

