# Colaborador de dados

Data collators são objetos que formam um lote usando uma lista de elementos do dataset como entrada. Esses elementos são do mesmo tipo que os elementos de `train_dataset` ou `eval_dataset`.

Para poder montar lotes, os coletores de dados podem aplicar algum processamento (como preenchimento). Alguns deles (como [DataCollatorForLanguageModeling](/docs/transformers/main/pt/main_classes/data_collator#transformers.DataCollatorForLanguageModeling)) também aplicam alguma ampliação aleatória de dados (como mascaramento aleatório) no lote formado.

Exemplos de uso podem ser encontrados nos [notebooks de exemplo](https://github.com/huggingface/notebooks/tree/main/examples).

## Colador de dados padrão[[transformers.default_data_collator]]

#### transformers.default_data_collator[[transformers.default_data_collator]]

```python
transformers.default_data_collator(features: list, return_tensors = 'pt')
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/data/data_collator.py#L71)

Um collator de dados muito simples que simplesmente agrupa lotes de objetos semelhantes a dicionários e realiza um tratamento especial para chaves potenciais nomeadas:

- `label`: trata de um único valor (int ou float) por objeto
- `label_ids`: trata uma lista de valores por objeto

Não realiza nenhum pré-processamento adicional: os nomes das propriedades do objeto de entrada serão usados como as entradas correspondentes para o modelo. Veja glue e ner como exemplo de como isso é útil.

## DefaultDataCollator[[transformers.DefaultDataCollator]]

#### transformers.DefaultDataCollator[[transformers.DefaultDataCollator]]

```python
transformers.DefaultDataCollator(return_tensors: str = 'pt')
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/data/data_collator.py#L95)

**Parâmetros:**

return_tensors (`str`, *opcional*, padrão `"pt"`) : O tipo de Tensor a ser retornado. Os valores permitidos são "np" ou "pt".

Um collator de dados muito simples que simplesmente agrupa lotes de objetos semelhantes a dicionários e realiza um tratamento especial para chaves potenciais nomeadas:

- `label`: trata de um único valor (int ou float) por objeto
- `label_ids`: trata uma lista de valores por objeto

Não realiza nenhum pré-processamento adicional: os nomes das propriedades do objeto de entrada serão usados como as entradas correspondentes para o modelo. Veja glue e ner como exemplo de como isso é útil.

Este é um objeto (assim como outros data collators), em vez de uma função pura como default_data_collator. Isso pode ser útil se você precisar definir um valor para return_tensors na inicialização.

## DataCollatorWithPadding[[transformers.DataCollatorWithPadding]]

#### transformers.DataCollatorWithPadding[[transformers.DataCollatorWithPadding]]

```python
transformers.DataCollatorWithPadding(tokenizer: PreTrainedTokenizerBase, padding: bool | str | transformers.utils.generic.PaddingStrategy = True, max_length: int | None = None, pad_to_multiple_of: int | None = None, return_tensors: str = 'pt')
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/data/data_collator.py#L191)

**Parâmetros:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/main/pt/main_classes/tokenizer#transformers.PythonBackend) ou [PreTrainedTokenizerFast](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend)) : O tokenizer usado para codificar os dados.

padding (`bool`, `str` ou [PaddingStrategy](/docs/transformers/main/pt/internal/file_utils#transformers.utils.PaddingStrategy), *opcional*, padrão `True`) : Selecione uma estratégia para aplicar padding às sequências retornadas (de acordo com o lado de padding e o índice de padding do modelo) entre:  - `True` ou `'longest'` (padrão): Aplica padding até a sequência mais longa do lote (ou não aplica padding se apenas uma sequência for fornecida). - `'max_length'`: Aplica padding até um comprimento máximo especificado com o argumento `max_length` ou até o comprimento máximo aceitável de entrada para o modelo, caso esse argumento não seja fornecido. - `False` ou `'do_not_pad'`: Sem padding (ou seja, pode gerar um lote com sequências de comprimentos diferentes).

max_length (`int`, *opcional*) : Comprimento máximo da lista retornada e, opcionalmente, o comprimento do padding (veja acima).

pad_to_multiple_of (`int`, *opcional*) : Se definido, a sequência será preenchida até um múltiplo do valor fornecido. Isso é especialmente útil para habilitar o uso de Tensor Cores em hardware NVIDIA com capacidade de computação >= 7.0 (Volta).

return_tensors (`str`, *opcional*, padrão `"pt"`) : O tipo de Tensor a ser retornado. Os valores permitidos são "np" ou "pt".

Data collator que irá aplicar padding dinamicamente às entradas recebidas.

## DataCollatorForTokenClassification[[transformers.DataCollatorForTokenClassification]]

#### transformers.DataCollatorForTokenClassification[[transformers.DataCollatorForTokenClassification]]

```python
transformers.DataCollatorForTokenClassification(tokenizer: PreTrainedTokenizerBase, padding: bool | str | transformers.utils.generic.PaddingStrategy = True, max_length: int | None = None, pad_to_multiple_of: int | None = None, label_pad_token_id: int = -100, return_tensors: str = 'pt')
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/data/data_collator.py#L243)

**Parâmetros:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/main/pt/main_classes/tokenizer#transformers.PythonBackend) ou [PreTrainedTokenizerFast](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend)) : O tokenizer usado para codificar os dados.

padding (`bool`, `str` ou [PaddingStrategy](/docs/transformers/main/pt/internal/file_utils#transformers.utils.PaddingStrategy), *opcional*, padrão `True`) : Selecione uma estratégia para aplicar padding às sequências retornadas (de acordo com o lado de padding e o índice de padding do modelo) entre:  - `True` ou `'longest'` (padrão): Aplica padding até a sequência mais longa do lote (ou não aplica padding se apenas uma sequência for fornecida). - `'max_length'`: Aplica padding até um comprimento máximo especificado com o argumento `max_length` ou até o comprimento máximo aceitável de entrada para o modelo, caso esse argumento não seja fornecido. - `False` ou `'do_not_pad'`: Sem padding (ou seja, pode gerar um lote com sequências de comprimentos diferentes).

max_length (`int`, *opcional*) : Comprimento máximo da lista retornada e, opcionalmente, o comprimento do padding (veja acima).

pad_to_multiple_of (`int`, *opcional*) : Se definido, a sequência será preenchida até um múltiplo do valor fornecido. Isso é especialmente útil para habilitar o uso de Tensor Cores em hardware NVIDIA com capacidade de computação >= 7.0 (Volta).

label_pad_token_id (`int`, *opcional*, padrão -100) : O id a ser usado ao aplicar padding nos rótulos (-100 será automaticamente ignorado pelas funções de perda do PyTorch).

return_tensors (`str`, *opcional*, padrão `"pt"`) : O tipo de Tensor a ser retornado. Os valores permitidos são "np" ou "pt".

Data collator que irá preencher dinamicamente os inputs recebidos, bem como os labels.

## DataCollatorForSeq2Seq[[transformers.DataCollatorForSeq2Seq]]

#### transformers.DataCollatorForSeq2Seq[[transformers.DataCollatorForSeq2Seq]]

```python
transformers.DataCollatorForSeq2Seq(tokenizer: PreTrainedTokenizerBase, model: typing.Any | None = None, padding: bool | str | transformers.utils.generic.PaddingStrategy = True, max_length: int | None = None, pad_to_multiple_of: int | None = None, label_pad_token_id: int = -100, return_tensors: str = 'pt')
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/data/data_collator.py#L489)

**Parâmetros:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/main/pt/main_classes/tokenizer#transformers.PythonBackend) ou [PreTrainedTokenizerFast](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend)) : O tokenizer usado para codificar os dados.

model ([PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel), *opcional*) : O modelo que está sendo treinado. Se definido e tiver o *prepare_decoder_input_ids_from_labels*, use-o para preparar o *decoder_input_ids*. Isso é útil ao usar *label_smoothing* para evitar o cálculo da perda duas vezes.

padding (`bool`, `str` ou [PaddingStrategy](/docs/transformers/main/pt/internal/file_utils#transformers.utils.PaddingStrategy), *opcional*, padrão `True`) : Selecione uma estratégia para aplicar padding às sequências retornadas (de acordo com o lado de padding e o índice de padding do modelo) entre:  - `True` ou `'longest'` (padrão): Aplica padding até a sequência mais longa do lote (ou não aplica padding se apenas uma sequência for fornecida). - `'max_length'`: Aplica padding até um comprimento máximo especificado com o argumento `max_length` ou até o comprimento máximo de entrada aceitável para o modelo, caso esse argumento não seja fornecido. - `False` ou `'do_not_pad'`: Sem padding (ou seja, pode gerar um lote com sequências de comprimentos diferentes).

max_length (`int`, *opcional*) : Comprimento máximo da lista retornada e, opcionalmente, o comprimento do padding (veja acima).

pad_to_multiple_of (`int`, *opcional*) : Se definido, a sequência será preenchida até um múltiplo do valor fornecido. Isso é especialmente útil para habilitar o uso de Tensor Cores em hardware NVIDIA com capacidade de computação >= 7.0 (Volta).

label_pad_token_id (`int`, *opcional*, padrão -100) : O id a ser usado ao aplicar padding nos rótulos (-100 será automaticamente ignorado pelas funções de perda do PyTorch).

return_tensors (`str`, *opcional*, padrão `"pt"`) : O tipo de Tensor a ser retornado. Os valores permitidos são "np" ou "pt".

Data collator que irá preencher dinamicamente os inputs recebidos, bem como os labels.

## DataCollatorForLanguageModeling[[transformers.DataCollatorForLanguageModeling]]

#### transformers.DataCollatorForLanguageModeling[[transformers.DataCollatorForLanguageModeling]]

```python
transformers.DataCollatorForLanguageModeling(tokenizer: PreTrainedTokenizerBase, mlm: bool = True, whole_word_mask: bool = False, mlm_probability: float | None = 0.15, mask_replace_prob: float = 0.8, random_replace_prob: float = 0.1, pad_to_multiple_of: int | None = None, return_tensors: str = 'pt', seed: int | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/data/data_collator.py#L621)

**Parâmetros:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/main/pt/main_classes/tokenizer#transformers.PythonBackend) ou [PreTrainedTokenizerFast](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend)) : O tokenizer usado para codificar os dados.

mlm (`bool`, *opcional*, padrão `True`) : Indica se deve ou não usar modelagem de linguagem mascarada. Se definido como `False`, os rótulos são os mesmos das entradas, com os tokens de preenchimento ignorados (definindo-os como -100). Caso contrário, os rótulos são -100 para tokens não mascarados e o valor a prever para o token mascarado.

whole_word_mask (`bool`, *opcional*, padrão `False`) : Se deve mascarar palavras inteiras em vez de tokens individuais.

mlm_probability (`float`, *opcional*, padrão 0.15) : A probabilidade com a qual mascarar (aleatoriamente) tokens na entrada, quando `mlm` está definido como `True`.

mask_replace_prob (`float`, *opcional*, padrão 0.8) : A probabilidade com a qual os tokens mascarados são substituídos pelo token de máscara do tokenizer (por exemplo, `[MASK]`). O padrão é 0,8, o que significa que 80% dos tokens mascarados serão substituídos por `[MASK]`. Funciona apenas quando `mlm` está definido como `True`.

random_replace_prob (`float`, *opcional*, padrão 0.1) : A probabilidade com a qual os tokens mascarados são substituídos por tokens aleatórios do vocabulário do tokenizer. O padrão é 0.1, o que significa que 10% dos tokens mascarados serão substituídos por tokens aleatórios. Os tokens mascarados restantes (1 - mask_replace_prob - random_replace_prob) permanecem inalterados. Funciona apenas quando `mlm` está definido como `True`.

pad_to_multiple_of (`int`, *opcional*) : Se definido, a sequência será preenchida até um múltiplo do valor fornecido.

return_tensors (`str`) : O tipo de Tensor a ser retornado. Os valores permitidos são "np" ou "pt".

seed (`int`, *opcional*) : A semente a ser usada para o gerador de números aleatórios para mascaramento. Se não for fornecida, o RNG global será utilizado.

Collator de dados usado para modelagem de linguagem. As entradas são dinamicamente preenchidas até o comprimento máximo de um lote, caso não tenham todas o mesmo comprimento.

Para o melhor desempenho, este data collator deve ser usado com um conjunto de dados cujos itens são dicionários ou BatchEncoding, com a chave `"special_tokens_mask"`, conforme retornado por um [PreTrainedTokenizer](/docs/transformers/main/pt/main_classes/tokenizer#transformers.PythonBackend) ou um [PreTrainedTokenizerFast](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend) com o argumento `return_special_tokens_mask=True`.

1. Comportamento padrão:
   - `mask_replace_prob=0.8`, `random_replace_prob=0.1`.
   - Espera-se que 80% dos tokens mascarados sejam substituídos por `[MASK]`, 10% por tokens aleatórios e 10% permaneçam inalterados.

2. Todos os tokens mascarados substituídos por `[MASK]`:
   - `mask_replace_prob=1.0`, `random_replace_prob=0.0`.
   - Espera-se que todos os tokens mascarados sejam substituídos por `[MASK]`. Nenhum token permanece inalterado ou é substituído por tokens aleatórios.

3. Na substituição de `[MASK]`, apenas tokens aleatórios:
   - `mask_replace_prob=0.0`, `random_replace_prob=1.0`.
   - Espera-se que todos os tokens mascarados sejam substituídos por tokens aleatórios. Sem substituições por `[MASK]` ou tokens inalterados.

4. Substituição equilibrada:
   - `mask_replace_prob=0.5`, `random_replace_prob=0.4`.
   - Espera-se que 50% dos tokens mascarados sejam substituídos por `[MASK]`, 40% por tokens aleatórios e 10% permaneçam inalterados.

Observação: a soma de `mask_replace_prob` e `random_replace_prob` não deve exceder 1. Se a soma for menor que 1, a proporção restante consistirá em tokens mascarados mantidos inalterados.

#### numpy_mask_tokens[[transformers.DataCollatorForLanguageModeling.numpy_mask_tokens]]

```python
numpy_mask_tokens(inputs: Any, special_tokens_mask: typing.Any | None = None, offset_mapping: typing.Any | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/data/data_collator.py#L892)

Prepare os tokens mascarados de entrada/rótulos para modelagem de linguagem mascarada.

#### torch_mask_tokens[[transformers.DataCollatorForLanguageModeling.torch_mask_tokens]]

```python
torch_mask_tokens(inputs: Any, special_tokens_mask: typing.Any | None = None, offset_mapping: typing.Any | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/data/data_collator.py#L798)

Prepare os tokens mascarados de entrada/rótulos para modelagem de linguagem mascarada.

## DataCollatorForPermutationLanguageModeling[[transformers.DataCollatorForPermutationLanguageModeling]]

#### transformers.DataCollatorForPermutationLanguageModeling[[transformers.DataCollatorForPermutationLanguageModeling]]

```python
transformers.DataCollatorForPermutationLanguageModeling(tokenizer: PreTrainedTokenizerBase, plm_probability: float = 0.16666666666666666, max_span_length: int = 5, return_tensors: str = 'pt')
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/data/data_collator.py#L1030)

Data collator usado para modelagem de linguagem por permutação.

- agrupa lotes de tensores, respeitando o pad_token do seu tokenizador
- pré-processa lotes para modelagem de linguagem por permutação com procedimentos específicos do XLNet

#### numpy_mask_tokens[[transformers.DataCollatorForPermutationLanguageModeling.numpy_mask_tokens]]

```python
numpy_mask_tokens(inputs: Any)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/data/data_collator.py#L1156)

Os tokens mascarados a serem previstos para uma sequência específica são determinados pelo seguinte algoritmo:

0. Comece do início da sequência definindo `cur_len = 0` (número de tokens processados até o momento).
1. Amostrar um `span_length` do intervalo `[1, max_span_length]` (comprimento do trecho de tokens a ser mascarado)
2. Reserve um contexto de comprimento `context_length = span_length / plm_probability` para envolver o trecho a ser mascarado
3. Amostrar um ponto de partida `start_index` do intervalo `[cur_len, cur_len + context_length - span_length]` e mascarar os tokens `start_index:start_index + span_length`
4. Defina `cur_len = cur_len + context_length`. Se `cur_len < max_len` (ou seja, ainda há tokens restantes na sequência a serem processados), repita a partir da Etapa 1.

#### torch_mask_tokens[[transformers.DataCollatorForPermutationLanguageModeling.torch_mask_tokens]]

```python
torch_mask_tokens(inputs: Any)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/data/data_collator.py#L1057)

Os tokens mascarados a serem previstos para uma sequência específica são determinados pelo seguinte algoritmo:

0. Comece do início da sequência definindo `cur_len = 0` (número de tokens processados até o momento).
1. Amostrar um `span_length` do intervalo `[1, max_span_length]` (comprimento do trecho de tokens a ser mascarado)
2. Reserve um contexto de comprimento `context_length = span_length / plm_probability` para envolver o trecho a ser mascarado
3. Amostrar um ponto de partida `start_index` do intervalo `[cur_len, cur_len + context_length - span_length]` e mascarar os tokens `start_index:start_index + span_length`
4. Defina `cur_len = cur_len + context_length`. Se `cur_len < max_len` (ou seja, ainda há tokens restantes na sequência a serem processados), repita a partir da Etapa 1.

## DataCollatorWithFlattening[[transformers.DataCollatorWithFlattening]]

#### transformers.DataCollatorWithFlattening[[transformers.DataCollatorWithFlattening]]

```python
transformers.DataCollatorWithFlattening(*args, return_position_ids = True, separator_id = -100, return_flash_attn_kwargs = False, return_seq_idx = False, position_ids_start = 0, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/data/data_collator.py#L1255)

**Parâmetros:**

return_position_ids (`bool`, *opcional*, padrão `True`) : Se deve retornar `position_ids`, que reiniciam em `position_ids_start` para cada sequência achatada.

separator_id (`int`, *opcional*, padrão -100) : O valor usado para separar sequências dentro das `labels` concatenadas.

return_flash_attn_kwargs (`bool`, *opcional*, padrão `False`) : Se deve retornar os kwargs de fronteira de sequência usados pelo FlashAttention (`cu_seq_lens_q`, `cu_seq_lens_k`, `max_length_q` e `max_length_k`).

return_seq_idx (`bool`, *opcional*, padrão `False`) : Se deve retornar `seq_idx`, que indica a sequência à qual cada token pertence.

position_ids_start (`int`, *opcional*, padrão 0) : O id de posição atribuído ao primeiro token de cada sequência.

Data collator usado para a abordagem sem padding. Faz o seguinte:

- concatena todo o mini lote em uma única sequência longa de forma [1, total_tokens]
- usa `separator_id` para separar sequências dentro das `labels` concatenadas, o valor padrão é -100
- nenhum padding será adicionado, retorna `input_ids`, `labels` e `position_ids` por padrão
- retorna opcionalmente os kwargs contidos em FlashAttentionKwargs
- opcionalmente retorna seq_idx indicando a qual sequência cada token pertence

O uso de `DataCollatorWithFlattening` aplaina o mini lote inteiro em uma única sequência longa. Certifique-se de que o cálculo de atenção seja capaz de lidar com isso!

Nem todo modelo numera as posições a partir de 0 ao calcular os position ids por conta própria. Arquiteturas semelhantes à RoBERTa (entre elas `roberta`, `xlm_roberta`, `camembert`, `mpnet` e `esm` com embeddings de posição absolutos) começam em `padding_idx + 1`, que geralmente é 2. Passar a esses modelos o `position_ids` padrão baseado em 0 desloca silenciosamente os embeddings de posição e degrada suas saídas, portanto, defina `position_ids_start` de forma adequada para esses modelos.

## DataCollatorForMultipleChoice[[transformers.DataCollatorForMultipleChoice]]

#### transformers.DataCollatorForMultipleChoice[[transformers.DataCollatorForMultipleChoice]]

```python
transformers.DataCollatorForMultipleChoice(tokenizer: PreTrainedTokenizerBase, padding: bool | str | transformers.utils.generic.PaddingStrategy = True, max_length: int | None = None, pad_to_multiple_of: int | None = None, return_tensors: str = 'pt')
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/data/data_collator.py#L422)

**Parâmetros:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/main/pt/main_classes/tokenizer#transformers.PythonBackend) ou [PreTrainedTokenizerFast](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend)) : O tokenizer usado para codificar os dados.

padding (`bool`, `str` ou [PaddingStrategy](/docs/transformers/main/pt/internal/file_utils#transformers.utils.PaddingStrategy), *opcional*, padrão `True`) : Selecione uma estratégia para aplicar padding às sequências retornadas de acordo com o lado de padding e o índice de padding do modelo, entre:  - `True` ou `'longest'`: Aplica padding até a sequência mais longa do lote (ou não aplica padding se apenas uma sequência for fornecida). - `'max_length'`: Aplica padding até um comprimento máximo especificado com o argumento `max_length` ou até o comprimento máximo aceitável de entrada para o modelo, caso esse argumento não seja fornecido. - `False` ou `'do_not_pad'` (padrão): Sem padding (ou seja, pode gerar um lote com sequências de comprimentos diferentes).

max_length (`int`, *opcional*) : Comprimento máximo da lista retornada e, opcionalmente, o comprimento do padding (veja acima).

pad_to_multiple_of (`int`, *opcional*) : Preenche a sequência até um múltiplo do valor fornecido. Isso é especialmente útil para habilitar o uso de Tensor Cores em hardware NVIDIA com capacidade de computação >= 7.5 (Volta).

return_tensors (`str`, *opcional*, padrão `"pt"`) : O tipo de Tensor a ser retornado. Os valores permitidos são "np" ou "pt".

Data collator que faz o padding dinâmico de um lote de exemplos aninhados para múltipla escolha, de modo que todas as escolhas de todos os exemplos tenham o mesmo comprimento.