# Utilidades para Trainer

Esta página enumera todas las funciones de utilidad utilizadas por [Trainer](/docs/transformers/v5.23.0/es/main_classes/trainer#transformers.Trainer).

La mayoría de esos parámetros solo son útiles si estás estudiando el código del Trainer en la biblioteca.

## Utilidades[[transformers.EvalPrediction]]

#### transformers.EvalPrediction[[transformers.EvalPrediction]]

```python
transformers.EvalPrediction(predictions: numpy.ndarray | tuple[numpy.ndarray], label_ids: numpy.ndarray | tuple[numpy.ndarray], inputs: numpy.ndarray | tuple[numpy.ndarray] | None = None, losses: numpy.ndarray | tuple[numpy.ndarray] | None = None)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/trainer_utils.py#L210)

**Parámetros:**

predictions (`np.ndarray`) : Predicciones del modelo.

label_ids (`np.ndarray`) : Objetivos que deben coincidir.

inputs (`np.ndarray`, *opcional*) : Datos de entrada pasados al modelo.

losses (`np.ndarray`, *opcional*) : Valores de pérdida calculados durante la evaluación.

Salida de evaluación (siempre contiene etiquetas), para usar en el cálculo de métricas.

#### transformers.IntervalStrategy[[transformers.IntervalStrategy]]

```python
transformers.IntervalStrategy(value, names = None, module = None, qualname = None, type = None, start = 1, boundary = None)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/trainer_utils.py#L389)

#### transformers.enable_full_determinism[[transformers.enable_full_determinism]]

```python
transformers.enable_full_determinism(seed: int, warn_only: bool = False)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/trainer_utils.py#L154)

Función auxiliar para un comportamiento reproducible durante el entrenamiento distribuido. Consulte https://pytorch.org/docs/stable/notes/randomness.html para pytorch

#### transformers.set_seed[[transformers.set_seed]]

```python
transformers.set_seed(seed: int, deterministic: bool = False)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/trainer_utils.py#L180)

**Parámetros:**

seed (`int`) : La semilla a establecer.

deterministic (`bool`, *opcional*, valor predeterminado `False`) : Indica si se deben utilizar algoritmos deterministas cuando estén disponibles. Puede ralentizar el entrenamiento.

Función auxiliar para un comportamiento reproducible que establece la semilla en `random`, `numpy` y `torch` (si está instalado).

#### transformers.torch_distributed_zero_first[[transformers.torch_distributed_zero_first]]

```python
transformers.torch_distributed_zero_first(local_rank: int)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/trainer_pt_utils.py#L309)

**Parámetros:**

local_rank (`int`) : El rango del proceso local.

Decorador para hacer que todos los procesos en el entrenamiento distribuido esperen a que cada local_master realice algo.

## Interno de los callbacks[[transformers.trainer_callback.CallbackHandler]]

#### transformers.trainer_callback.CallbackHandler[[transformers.trainer_callback.CallbackHandler]]

```python
transformers.trainer_callback.CallbackHandler(callbacks, model, processing_class, optimizer, lr_scheduler)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/trainer_callback.py#L429)

Clase interna que simplemente llama a la lista de callbacks en orden.

## Analizador de argumentos del Trainer[[transformers.HfArgumentParser]]

#### transformers.HfArgumentParser[[transformers.HfArgumentParser]]

```python
transformers.HfArgumentParser(dataclass_types: typing.Union[transformers.hf_argparser.DataClassType, collections.abc.Iterable[transformers.hf_argparser.DataClassType], NoneType] = None, **kwargs)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/hf_argparser.py#L111)

**Parámetros:**

dataclass_types (`DataClassType` o `Iterable[DataClassType]`, *opcional*) : Tipo de dataclass, o lista de tipos de dataclass para los que "llenaremos" instancias con los argumentos analizados.

kwargs (`dict[str, Any]`, *opcional*) : Se pasa a `argparse.ArgumentParser()` de la forma habitual.

Esta subclase de `argparse.ArgumentParser` utiliza las anotaciones de tipo en dataclasses para generar argumentos.

La clase está diseñada para funcionar bien con el argparse nativo. En particular, puedes añadir más argumentos (no respaldados por dataclass) al parser después de la inicialización y obtendrás la salida tras el análisis como un espacio de nombres adicional. Opcional: para crear grupos de argumentos secundarios, utiliza el atributo `_argument_group_name` en el dataclass.

#### parse_args_into_dataclasses[[transformers.HfArgumentParser.parse_args_into_dataclasses]]

```python
parse_args_into_dataclasses(args = None, return_remaining_strings = False, look_for_args_file = True, args_filename = None, args_file_flag = None)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/hf_argparser.py#L272)

**Parámetros:**

args : Lista de cadenas para analizar. El valor predeterminado se toma de sys.argv. (igual que argparse.ArgumentParser)

return_remaining_strings : Si es true, también devuelve una lista de las cadenas de argumentos restantes.

look_for_args_file : Si es true, buscará un archivo ".args" con el mismo nombre base que el script de punto de entrada de este proceso y agregará su contenido potencial a los argumentos de la línea de comandos.

args_filename : Si no es None, se usará este archivo en lugar del archivo ".args" especificado en el argumento anterior.

args_file_flag : Si no es None, buscará un archivo en los argumentos de línea de comandos especificados con esta bandera. La bandera puede especificarse varias veces y la precedencia se determina por el orden (prevalece la última).

**Devuelve:** `Tuple consisting of`

- las instancias de dataclass en el mismo orden en que se pasaron al inicializador.
- si aplica, un espacio de nombres adicional para más argumentos (no respaldados por dataclass) que se agregan al parser después de la inicialización.
- La lista potencial de cadenas de argumentos restantes. (igual que argparse.ArgumentParser.parse_known_args)

Analiza los argumentos de la línea de comandos en instancias de los tipos de dataclass especificados.

Esto se basa en `ArgumentParser.parse_known_args` de argparse. Consulta la documentación en: docs.python.org/3/library/argparse.html#argparse.ArgumentParser.parse_args

#### parse_dict[[transformers.HfArgumentParser.parse_dict]]

```python
parse_dict(args: dict[str, typing.Any], allow_extra_keys: bool = False)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/hf_argparser.py#L358)

**Parámetros:**

args (`dict`) : diccionario que contiene los valores de configuración

allow_extra_keys (`bool`, *opcional*, valor predeterminado `False`) : El valor predeterminado es False. Si es False, se lanzará una excepción si el diccionario contiene claves que no se analizan.

**Devuelve:** `Tuple consisting of`

- las instancias de dataclass en el mismo orden en que se pasaron al inicializador.

Método auxiliar alternativo que no utiliza `argparse` en absoluto, sino que emplea un diccionario y rellena los tipos de dataclass.

#### parse_json_file[[transformers.HfArgumentParser.parse_json_file]]

```python
parse_json_file(json_file: str | os.PathLike, allow_extra_keys: bool = False)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/hf_argparser.py#L386)

**Parámetros:**

json_file (`str` o `os.PathLike`) : Nombre del archivo json a analizar

allow_extra_keys (`bool`, *opcional*, valor predeterminado `False`) : El valor predeterminado es False. Si es False, se lanzará una excepción si el archivo json contiene claves que no se analizan.

**Devuelve:** `Tuple consisting of`

- las instancias de dataclass en el mismo orden en que se pasaron al inicializador.

Método auxiliar alternativo que no utiliza `argparse` en absoluto, sino que carga un archivo json y rellena los tipos de dataclass.

#### parse_yaml_file[[transformers.HfArgumentParser.parse_yaml_file]]

```python
parse_yaml_file(yaml_file: str | os.PathLike, allow_extra_keys: bool = False)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/hf_argparser.py#L408)

**Parámetros:**

yaml_file (`str` o `os.PathLike`) : Nombre del archivo yaml a analizar

allow_extra_keys (`bool`, *opcional*, valor predeterminado `False`) : El valor predeterminado es False. Si es False, se lanzará una excepción si el archivo json contiene claves que no se analizan.

**Devuelve:** `Tuple consisting of`

- las instancias de dataclass en el mismo orden en que se pasaron al inicializador.

Método auxiliar alternativo que no utiliza `argparse` en absoluto, sino que carga un archivo yaml y rellena los tipos de dataclass.

## Utilidades de depuración[[transformers.debug_utils.DebugUnderflowOverflow]]

#### transformers.debug_utils.DebugUnderflowOverflow[[transformers.debug_utils.DebugUnderflowOverflow]]

```python
transformers.debug_utils.DebugUnderflowOverflow(model, max_frames_to_save = 21, trace_batch_nums = None, abort_after_batch_num = None)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/debug_utils.py#L27)

**Parámetros:**

model (`nn.Module`) : El modelo que se va a depurar.

max_frames_to_save (`int`, *opcional*, valor predeterminado 21) : Cuántos fotogramas hacia atrás registrar

trace_batch_nums(`list[int]`, *opcional*, valor predeterminado `[]`) : Números de lote que se deben trazar (desactiva la detección de turnos)

abort_after_batch_num  (`int``, *opcional*) : Si se debe abortar después de que se haya completado un número determinado de lotes

Esta clase de depuración ayuda a detectar y comprender en qué punto del modelo los valores comienzan a ser muy grandes o muy pequeños, y, lo que es más importante, a identificar elementos de pesos y activaciones con valores `nan` o `inf`.

Hay 2 modos de funcionamiento:

1. Detección de desbordamiento/subdesbordamiento (predeterminado)
2. Trazado de valores absolutos mínimos/máximos de lotes específicos sin detección

Modo 1: Detección de desbordamiento

Para activar la detección de desbordamiento/underflow, inicialice el objeto con el modelo:

```python
debug_overflow = DebugUnderflowOverflow(model)
```

luego, ejecute el entrenamiento de forma normal y si se detecta `nan` o `inf` en al menos uno de los elementos de peso, entrada o salida, este módulo lanzará una excepción e imprimirá `max_frames_to_save` fotogramas que condujeron a este evento, donde cada fotograma informa

1. el nombre de módulo totalmente cualificado más el nombre de la clase cuyo `forward` se ejecutó
2. el valor mínimo y máximo absoluto de todos los elementos para los pesos de cada módulo, así como las entradas y salidas

Por ejemplo, aquí se muestra la cabecera y los últimos fotogramas del informe de detección para `google/mt5-small` ejecutado en fp16

precisión mixta:

```
Detected inf/nan during batch_number=0
Last 21 forward frames:
abs min  abs max  metadata
[...]
                  encoder.block.2.layer.1.DenseReluDense.wi_0 Linear
2.17e-07 4.50e+00 weight
1.79e-06 4.65e+00 input[0]
2.68e-06 3.70e+01 output
                  encoder.block.2.layer.1.DenseReluDense.wi_1 Linear
8.08e-07 2.66e+01 weight
1.79e-06 4.65e+00 input[0]
1.27e-04 2.37e+02 output
                  encoder.block.2.layer.1.DenseReluDense.wo Linear
1.01e-06 6.44e+00 weight
0.00e+00 9.74e+03 input[0]
3.18e-04 6.27e+04 output
                  encoder.block.2.layer.1.DenseReluDense T5DenseGatedGeluDense
1.79e-06 4.65e+00 input[0]
3.18e-04 6.27e+04 output
                  encoder.block.2.layer.1.dropout Dropout
3.18e-04 6.27e+04 input[0]
0.00e+00      inf output
```

Aquí se puede ver que `T5DenseGatedGeluDense.forward` produjo activaciones de salida cuyo valor máximo absoluto fue de aproximadamente 62,7K, muy cerca del límite superior de 64K de fp16. En el siguiente fotograma aparece `Dropout`, que renormaliza los pesos después de poner a cero algunos de los elementos, lo que eleva el valor máximo absoluto a más de 64K y provoca un desbordamiento.

Como puede ver, son los fotogramas anteriores en los que debemos fijarnos cuando los números comienzan a ser muy grandes para números fp16.

El seguimiento se realiza en un hook de forward, que se invoca inmediatamente después de que `forward` haya finalizado.

Por defecto, se imprimen los últimos 21 fotogramas. Puedes cambiar el valor predeterminado para ajustarlo a tus necesidades. Por ejemplo:

```python
debug_overflow = DebugUnderflowOverflow(model, max_frames_to_save=100)
```

Para validar que has configurado correctamente esta función de depuración y que tienes la intención de usarla en un entrenamiento que puede tardar horas en completarse, primero ejecútala con el trazado normal habilitado para uno de unos pocos lotes, como se explica en la siguiente sección.

Modo 2. Trazado de valores absolutos mín/máx específicos del lote sin detección

El segundo modo de trabajo es el trazado por lote con la función de detección de desbordamiento/underflow desactivada.

Supongamos que quieres observar los valores absolutos mínimo y máximo de todos los ingredientes de cada llamada a `forward` de un

dado un lote, y solo hacer eso para los lotes 1 y 3. Luego, instancias esta clase como

```python
debug_overflow = DebugUnderflowOverflow(model, trace_batch_nums=[1, 3])
```

Y ahora los lotes completos 1 y 3 se trazarán utilizando el mismo formato explicado anteriormente. Los lotes tienen índice base 0.

Esto resulta útil si sabes que el programa empieza a comportarse de forma incorrecta después de un número de lote determinado, ya que puedes avanzar rápidamente hasta esa zona.

Detención temprana:

También puede especificar el número de lote después del cual se detendrá el entrenamiento, con:

```python
debug_overflow = DebugUnderflowOverflow(model, trace_batch_nums=[1, 3], abort_after_batch_num=3)
```

Esta función es principalmente útil en el modo de trazado, pero puedes usarla en cualquier modo.

**Rendimiento**:

Como este módulo mide el `min`/``max` absoluto de cada peso del modelo en cada paso de propagación hacia adelante, ralentizará el entrenamiento. Por lo tanto, recuerda desactivarlo una vez que se hayan cumplido las necesidades de depuración.

