# Colaborador de datos

Los collators de datos son objetos que forman un lote a partir de una lista de elementos del conjunto de datos como entrada. Estos elementos son del mismo tipo que los elementos de `train_dataset` o `eval_dataset`.

Para poder construir lotes, los collators de datos pueden aplicar algún procesamiento (como relleno). Algunos de ellos (como [DataCollatorForLanguageModeling](/docs/transformers/main/es/main_classes/data_collator#transformers.DataCollatorForLanguageModeling)) también aplican alguna aumentación de datos aleatoria (como enmascarado aleatorio) en el lote formado.

Se pueden encontrar ejemplos de uso en los [cuadernos de ejemplo](https://github.com/huggingface/notebooks/tree/main/examples).

## Colador de datos predeterminado[[transformers.default_data_collator]]

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

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

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

Collator de datos muy simple que simplemente agrupa lotes de objetos tipo diccionario y realiza un tratamiento especial para posibles claves con los nombres:

- `label`: maneja un único valor (int o float) por objeto
- `label_ids`: maneja una lista de valores por objeto

No realiza ningún preprocesamiento adicional: los nombres de las propiedades del objeto de entrada se utilizarán como entradas correspondientes para el modelo. Consulte glue y ner como ejemplo de cómo es útil.

## DefaultDataCollator[[transformers.DefaultDataCollator]]

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

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

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

**Parámetros:**

return_tensors (`str`, *opcional*, valor predeterminado `"pt"`) : El tipo de Tensor a devolver. Los valores permitidos son "np" o "pt".

Collator de datos muy simple que simplemente agrupa lotes de objetos tipo diccionario y realiza un tratamiento especial para posibles claves con los nombres:

- `label`: maneja un único valor (int o float) por objeto
- `label_ids`: maneja una lista de valores por objeto

No realiza ningún preprocesamiento adicional: los nombres de las propiedades del objeto de entrada se utilizarán como las entradas correspondientes del modelo. Consulte glue y ner como ejemplo de cómo es útil.

Este es un objeto (al igual que otros data collators) en lugar de una función pura como default_data_collator. Esto puede ser útil si necesitas establecer un valor de return_tensors durante la inicialización.

## 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')
```

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

**Parámetros:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/main/es/main_classes/tokenizer#transformers.PythonBackend) o [PreTrainedTokenizerFast](/docs/transformers/main/es/main_classes/tokenizer#transformers.TokenizersBackend)) : El tokenizador utilizado para codificar los datos.

padding (`bool`, `str` o [PaddingStrategy](/docs/transformers/main/es/internal/file_utils#transformers.utils.PaddingStrategy), *opcional*, valor predeterminado `True`) : Selecciona una estrategia para rellenar las secuencias devueltas (según el lado de relleno y el índice de relleno del modelo) entre:  - `True` o `'longest'` (predeterminado): Rellena hasta la secuencia más larga del lote (o no rellena si solo se proporciona una secuencia). - `'max_length'`: Rellena hasta una longitud máxima especificada con el argumento `max_length` o hasta la longitud de entrada máxima aceptable para el modelo si no se proporciona ese argumento. - `False` o `'do_not_pad'`: Sin relleno (es decir, puede devolver un lote con secuencias de longitudes diferentes).

max_length (`int`, *opcional*) : Longitud máxima de la lista devuelta y, opcionalmente, longitud de relleno (ver arriba).

pad_to_multiple_of (`int`, *opcional*) : Si se establece, rellenará la secuencia hasta un múltiplo del valor proporcionado. Esto resulta especialmente útil para habilitar el uso de Tensor Cores en hardware de NVIDIA con capacidad de cómputo >= 7.0 (Volta).

return_tensors (`str`, *opcional*, valor predeterminado `"pt"`) : El tipo de Tensor a devolver. Los valores permitidos son "np" o "pt".

Colador de datos que rellenará dinámicamente las entradas recibidas.

## 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')
```

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

**Parámetros:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/main/es/main_classes/tokenizer#transformers.PythonBackend) o [PreTrainedTokenizerFast](/docs/transformers/main/es/main_classes/tokenizer#transformers.TokenizersBackend)) : El tokenizador utilizado para codificar los datos.

padding (`bool`, `str` o [PaddingStrategy](/docs/transformers/main/es/internal/file_utils#transformers.utils.PaddingStrategy), *opcional*, valor predeterminado `True`) : Selecciona una estrategia para rellenar las secuencias devueltas (según el lado de relleno y el índice de relleno del modelo) entre:  - `True` o `'longest'` (predeterminado): Rellena hasta la secuencia más larga del lote (o no aplica relleno si solo se proporciona una secuencia). - `'max_length'`: Rellena hasta una longitud máxima especificada con el argumento `max_length` o hasta la longitud de entrada máxima aceptable para el modelo si no se proporciona dicho argumento. - `False` o `'do_not_pad'`: Sin relleno (es decir, puede devolver un lote con secuencias de longitudes diferentes).

max_length (`int`, *opcional*) : Longitud máxima de la lista devuelta y, opcionalmente, longitud de relleno (ver arriba).

pad_to_multiple_of (`int`, *opcional*) : Si se establece, rellenará la secuencia hasta un múltiplo del valor proporcionado. Esto resulta especialmente útil para habilitar el uso de Tensor Cores en hardware de NVIDIA con capacidad de cálculo >= 7.0 (Volta).

label_pad_token_id (`int`, *opcional*, valor predeterminado -100) : El identificador que se utilizará al rellenar las etiquetas (-100 se ignorará automáticamente en las funciones de pérdida de PyTorch).

return_tensors (`str`, *opcional*, valor predeterminado `"pt"`) : El tipo de Tensor a devolver. Los valores permitidos son "np" o "pt".

Colador de datos que rellenará dinámicamente las entradas recibidas, así como las etiquetas.

## 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')
```

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

**Parámetros:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/main/es/main_classes/tokenizer#transformers.PythonBackend) o [PreTrainedTokenizerFast](/docs/transformers/main/es/main_classes/tokenizer#transformers.TokenizersBackend)) : El tokenizador utilizado para codificar los datos.

model ([PreTrainedModel](/docs/transformers/main/es/main_classes/model#transformers.PreTrainedModel), *opcional*) : El modelo que se está entrenando. Si se establece y tiene *prepare_decoder_input_ids_from_labels*, úsalo para preparar *decoder_input_ids*. Esto es útil al usar *label_smoothing* para evitar calcular la pérdida dos veces.

padding (`bool`, `str` o [PaddingStrategy](/docs/transformers/main/es/internal/file_utils#transformers.utils.PaddingStrategy), *opcional*, valor predeterminado `True`) : Selecciona una estrategia para rellenar las secuencias devueltas (según el lado de relleno y el índice de relleno del modelo) entre:  - `True` o `'longest'` (predeterminado): Rellena hasta la secuencia más larga del lote (o no rellena si solo se proporciona una secuencia). - `'max_length'`: Rellena hasta una longitud máxima especificada con el argumento `max_length` o hasta la longitud de entrada máxima aceptable para el modelo si no se proporciona ese argumento. - `False` o `'do_not_pad'`: Sin relleno (es decir, puede devolver un lote con secuencias de longitudes diferentes).

max_length (`int`, *opcional*) : Longitud máxima de la lista devuelta y, opcionalmente, longitud de relleno (ver arriba).

pad_to_multiple_of (`int`, *opcional*) : Si se establece, rellenará la secuencia hasta un múltiplo del valor proporcionado. Esto resulta especialmente útil para habilitar el uso de Tensor Cores en hardware de NVIDIA con capacidad de cálculo >= 7.0 (Volta).

label_pad_token_id (`int`, *opcional*, valor predeterminado: -100) : El identificador que se utilizará al rellenar las etiquetas (-100 se ignorará automáticamente por las funciones de pérdida de PyTorch).

return_tensors (`str`, *opcional*, valor predeterminado `"pt"`) : El tipo de Tensor a devolver. Los valores permitidos son "np" o "pt".

Colador de datos que rellenará dinámicamente las entradas recibidas, así como las etiquetas.

## 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)
```

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

**Parámetros:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/main/es/main_classes/tokenizer#transformers.PythonBackend) o [PreTrainedTokenizerFast](/docs/transformers/main/es/main_classes/tokenizer#transformers.TokenizersBackend)) : El tokenizador utilizado para codificar los datos.

mlm (`bool`, *opcional*, valor predeterminado `True`) : Indica si se debe usar modelado de lenguaje enmascarado. Si se establece en `False`, las etiquetas son las mismas que las entradas, ignorando los tokens de relleno (estableciéndolos en -100). En caso contrario, las etiquetas son -100 para los tokens no enmascarados y el valor a predecir para el token enmascarado.

whole_word_mask (`bool`, *opcional*, valor predeterminado `False`) : Indica si se deben enmascarar palabras completas en lugar de tokens individuales.

mlm_probability (`float`, *opcional*, valor predeterminado 0.15) : La probabilidad con la que se enmascaran (aleatoriamente) los tokens de la entrada, cuando `mlm` se establece en `True`.

mask_replace_prob (`float`, *opcional*, valor predeterminado 0.8) : La probabilidad con la que los tokens enmascarados se reemplazan por el token de máscara del tokenizador (p. ej., `[MASK]`). El valor predeterminado es 0.8, lo que significa que el 80 % de los tokens enmascarados se reemplazarán con `[MASK]`. Solo funciona cuando `mlm` está establecido en `True`.

random_replace_prob (`float`, *opcional*, valor predeterminado 0.1) : La probabilidad con la que los tokens enmascarados se reemplazan por tokens aleatorios del vocabulario del tokenizador. El valor predeterminado es 0.1, lo que significa que el 10% de los tokens enmascarados se reemplazará con tokens aleatorios. Los tokens enmascarados restantes (1 - mask_replace_prob - random_replace_prob) se dejan sin cambios. Solo funciona cuando `mlm` está establecido en `True`.

pad_to_multiple_of (`int`, *opcional*) : Si se establece, rellenará la secuencia hasta un múltiplo del valor proporcionado.

return_tensors (`str`) : El tipo de Tensor a devolver. Los valores permitidos son "np" o "pt".

seed (`int`, *opcional*) : La semilla a utilizar para el generador de números aleatorios para el enmascaramiento. Si no se proporciona, se utilizará el RNG global.

Colador de datos utilizado para el modelado de lenguaje. Las entradas se rellenan dinámicamente hasta la longitud máxima de un lote si no todas tienen la misma longitud.

Para obtener el mejor rendimiento, este data collator debe usarse con un conjunto de datos cuyos elementos sean diccionarios o BatchEncoding, con la clave `"special_tokens_mask"`, tal como se devuelve por un [PreTrainedTokenizer](/docs/transformers/main/es/main_classes/tokenizer#transformers.PythonBackend) o un [PreTrainedTokenizerFast](/docs/transformers/main/es/main_classes/tokenizer#transformers.TokenizersBackend) con el argumento `return_special_tokens_mask=True`.

1. Comportamiento predeterminado:
   - `mask_replace_prob=0.8`, `random_replace_prob=0.1`.
   - Esperamos que el 80% de los tokens enmascarados se reemplacen por `[MASK]`, el 10% se reemplace por tokens aleatorios y el 10% permanezca sin cambios.

2. Todos los tokens enmascarados reemplazados por `[MASK]`:
   - `mask_replace_prob=1.0`, `random_replace_prob=0.0`.
   - Se espera que todos los tokens enmascarados se reemplacen con `[MASK]`. No se dejan tokens sin cambios ni se reemplazan con tokens aleatorios.

3. Sin reemplazo de `[MASK]`, solo tokens aleatorios:
   - `mask_replace_prob=0.0`, `random_replace_prob=1.0`.
   - Esperar que todos los tokens enmascarados se reemplacen con tokens aleatorios. Sin reemplazos de `[MASK]` ni tokens sin cambios.

4. Sustitución equilibrada:
   - `mask_replace_prob=0.5`, `random_replace_prob=0.4`.
   - Esperamos que el 50% de los tokens enmascarados se reemplacen con `[MASK]`, el 40% se reemplace con tokens aleatorios y el 10% permanezca sin cambios.

Nota: La suma de `mask_replace_prob` y `random_replace_prob` no debe superar 1. Si su suma es menor que 1, la proporción restante consistirá en tokens enmascarados que se mantendrán sin cambios.

#### 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)
```

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

Prepara las entradas/etiquetas de tokens enmascarados para el modelado de lenguaje enmascarado.

#### 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)
```

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

Prepara las entradas/etiquetas de tokens enmascarados para el modelado de lenguaje enmascarado.

## 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')
```

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

Colador de datos utilizado para el modelado de lenguaje por permutación.

- agrupa lotes de tensores, respetando el pad_token de su tokenizador
- preprocesa lotes para el modelado de lenguaje por permutación con procedimientos específicos de XLNet

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

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

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

Los tokens enmascarados que se deben predecir para una secuencia en particular se determinan mediante el siguiente algoritmo:

0. Comience desde el inicio de la secuencia estableciendo `cur_len = 0` (número de tokens procesados hasta el momento).
1. Muestreea un `span_length` del intervalo `[1, max_span_length]` (longitud del tramo de tokens que se van a enmascarar)
2. Reserve un contexto de longitud `context_length = span_length / plm_probability` para rodear el span que se va a enmascarar
3. Muestree un punto de inicio `start_index` del intervalo `[cur_len, cur_len + context_length - span_length]` y enmascare los tokens `start_index:start_index + span_length`
4. Establezca `cur_len = cur_len + context_length`. Si `cur_len < max_len` (es decir, quedan tokens en la secuencia por procesar), repita desde el Paso 1.

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

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

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

Los tokens enmascarados que se deben predecir para una secuencia en particular se determinan mediante el siguiente algoritmo:

0. Comience desde el inicio de la secuencia estableciendo `cur_len = 0` (número de tokens procesados hasta el momento).
1. Muestreea un `span_length` del intervalo `[1, max_span_length]` (longitud del tramo de tokens que se van a enmascarar)
2. Reserve un contexto de longitud `context_length = span_length / plm_probability` para rodear el span que se va a enmascarar
3. Muestree un punto de inicio `start_index` del intervalo `[cur_len, cur_len + context_length - span_length]` y enmascare los tokens `start_index:start_index + span_length`
4. Establezca `cur_len = cur_len + context_length`. Si `cur_len < max_len` (es decir, quedan tokens en la secuencia por procesar), repita desde el Paso 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)
```

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

**Parámetros:**

return_position_ids (`bool`, *opcional*, valor predeterminado `True`) : Si se deben devolver `position_ids`, que se reinician en `position_ids_start` para cada secuencia aplanada.

separator_id (`int`, *opcional*, valor predeterminado -100) : El valor utilizado para separar las secuencias dentro de las `labels` concatenadas.

return_flash_attn_kwargs (`bool`, *opcional*, valor predeterminado `False`) : Indica si se deben devolver los kwargs de límites de secuencia utilizados por FlashAttention (`cu_seq_lens_q`, `cu_seq_lens_k`, `max_length_q` y `max_length_k`).

return_seq_idx (`bool`, *opcional*, valor predeterminado `False`) : Indica si se debe devolver `seq_idx`, que especifica la secuencia a la que pertenece cada token.

position_ids_start (`int`, *opcional*, valor predeterminado 0): El identificador de posición asignado al primer token de cada secuencia.

Colador de datos utilizado para el enfoque sin relleno. Realiza lo siguiente:

- concatena todo el mini lote en una única secuencia larga de forma [1, total_tokens]
- usa `separator_id` para separar las secuencias dentro de `labels` concatenadas, el valor predeterminado es -100
- no se añadirá padding, devuelve `input_ids`, `labels` y `position_ids` de forma predeterminada
- opcionalmente devuelve los kwargs contenidos en FlashAttentionKwargs
- opcionalmente devuelve seq_idx que indica a qué secuencia pertenece cada token

El uso de `DataCollatorWithFlattening` aplanará el mini lote completo en una única secuencia larga. ¡Asegúrate de que tu cálculo de atención pueda manejarlo!

No todos los modelos numeran las posiciones a partir de 0 cuando calculan los `position_ids` por sí mismos. Las arquitecturas similares a RoBERTa (entre ellas `roberta`, `xlm_roberta`, `camembert`, `mpnet` y `esm` con embeddings de posición absolutos) comienzan en `padding_idx + 1`, que suele ser 2. Si se les pasa a estos modelos el valor predeterminado de `position_ids` basado en 0, los embeddings de posición se desplazan silenciosamente y se degradan sus salidas, por lo que hay que establecer `position_ids_start` en consecuencia para esos 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')
```

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

**Parámetros:**

tokenizer ([PreTrainedTokenizer](/docs/transformers/main/es/main_classes/tokenizer#transformers.PythonBackend) o [PreTrainedTokenizerFast](/docs/transformers/main/es/main_classes/tokenizer#transformers.TokenizersBackend)) : El tokenizador utilizado para codificar los datos.

padding (`bool`, `str` o [PaddingStrategy](/docs/transformers/main/es/internal/file_utils#transformers.utils.PaddingStrategy), *opcional*, valor predeterminado `True`) : Selecciona una estrategia para rellenar las secuencias devueltas según el lado de relleno y el índice de relleno del modelo, entre:  - `True` o `'longest'`: Rellena hasta la secuencia más larga del lote (o no aplica relleno si solo se proporciona una secuencia). - `'max_length'`: Rellena hasta una longitud máxima especificada con el argumento `max_length` o hasta la longitud de entrada máxima aceptable para el modelo si no se proporciona dicho argumento. - `False` o `'do_not_pad'` (predeterminado): Sin relleno (es decir, puede devolver un lote con secuencias de longitudes diferentes).

max_length (`int`, *opcional*) : Longitud máxima de la lista devuelta y, opcionalmente, longitud de relleno (ver arriba).

pad_to_multiple_of (`int`, *opcional*) : Rellena la secuencia hasta un múltiplo del valor proporcionado. Esto resulta especialmente útil para habilitar el uso de Tensor Cores en hardware de NVIDIA con capacidad de cálculo >= 7.5 (Volta).

return_tensors (`str`, *opcional*, valor predeterminado `"pt"`) : El tipo de Tensor a devolver. Los valores permitidos son "np" o "pt".

Colador de datos que rellena dinámicamente un lote de ejemplos anidados para opciones múltiples, de modo que todas las opciones de todos los ejemplos tengan la misma longitud.