# Утилиты для Trainer

На этой странице перечислены все вспомогательные функции, используемые в [Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer).

Большинство из них полезны только в том случае, если вы изучаете код класса Trainer в библиотеке.

## Утилиты[[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)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_utils.py#L210)

**Параметры:**

predictions (`np.ndarray`) : Прогнозы модели.

label_ids (`np.ndarray`) : Целевые значения для сопоставления.

inputs (`np.ndarray`, *необязательный*) : Входные данные, передаваемые в модель.

losses (`np.ndarray`, *необязательный*) : Значения потерь, вычисленные во время оценки.

Вывод оценки (всегда содержит метки), используемый для вычисления метрик.

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

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

[Источник](https://github.com/huggingface/transformers/blob/main/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)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_utils.py#L154)

Вспомогательная функция для воспроизводимого поведения при распределённом обучении. См. https://pytorch.org/docs/stable/notes/randomness.html для pytorch

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

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

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_utils.py#L180)

**Параметры:**

seed (`int`) : Значение seed, которое нужно установить.

deterministic (`bool`, *необязательный*, по умолчанию `False`) : Использовать ли детерминированные алгоритмы, если они доступны. Может замедлить обучение.

Вспомогательная функция для воспроизводимого поведения: устанавливает seed в `random`, `numpy`, `torch` (если установлено).

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

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

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_pt_utils.py#L309)

**Параметры:**

local_rank (`int`) : Ранг локального процесса.

Декоратор, заставляющий все процессы в распределённом обучении ждать, пока каждый local_master выполнит определённое действие.

## Внутреннее устройство колбэков[[transformers.trainer_callback.CallbackHandler]]

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

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

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/trainer_callback.py#L429)

Внутренний класс, который просто вызывает список обратных вызовов по порядку.

## Парсер аргументов 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)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L111)

**Параметры:**

dataclass_types (`DataClassType` или `Iterable[DataClassType]`, *необязательно*) : Тип dataclass или список типов dataclass, для которых мы будем «заполнять» экземпляры распарсенными аргументами.

kwargs (`dict[str, Any]`, *необязательный*) : Передаётся в `argparse.ArgumentParser()` стандартным способом.

Этот подкласс `argparse.ArgumentParser` использует аннотации типов в dataclasses для генерации аргументов.

Класс спроектирован для удобной работы с нативным argparse. В частности, после инициализации вы можете добавить в парсер дополнительные аргументы (не поддерживаемые dataclass), и после разбора получите их в виде дополнительного namespace. Необязательно: для создания подгрупп аргументов используйте атрибут `_argument_group_name` в 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)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L272)

**Параметры:**

args : Список строк для разбора. Значение по умолчанию берется из sys.argv (аналогично argparse.ArgumentParser).

return_remaining_strings : Если true, также возвращает список оставшихся строковых аргументов.

look_for_args_file : Если значение равно true, будет выполняться поиск файла «.args» с тем же базовым именем, что и сценарий точки входа для данного процесса, и его возможное содержимое будет добавлено к аргументам командной строки.

args_filename : Если значение не None, будет использоваться этот файл вместо файла «.args», указанного в предыдущем аргументе.

args_file_flag : Если значение не None, будет выполняться поиск файла в аргументах командной строки, указанных с этим флагом. Флаг можно указать несколько раз, а приоритет определяется порядком (действует последний).

**Возвращает:** `Tuple consisting of`

- экземпляры dataclass в том же порядке, в котором они были переданы в инициализатор.
- при необходимости, дополнительное пространство имён для дополнительных (не основанных на dataclass) аргументов, добавляемых в парсер после инициализации.
- Потенциальный список оставшихся строковых аргументов. (аналогично argparse.ArgumentParser.parse_known_args)

Разобрать аргументы командной строки в экземпляры указанных типов dataclass.

Это опирается на `ArgumentParser.parse_known_args` из argparse. См. документацию: docs.python.org/3/library/argparse.html#argparse.ArgumentParser.parse_args

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

```python
parse_dict(args: dict, allow_extra_keys: bool = False)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L358)

**Параметры:**

args (`dict`) : словарь, содержащий значения конфигурации

allow_extra_keys (`bool`, *необязательный*, по умолчанию `False`) : По умолчанию False. Если False, будет выброшено исключение, если словарь содержит ключи, которые не были распознаны.

**Возвращает:** `Tuple consisting of`

- экземпляры dataclass в том же порядке, в котором они были переданы в инициализатор.

Альтернативный вспомогательный метод, который вообще не использует `argparse`, а вместо этого работает со словарём и заполняет типы dataclass.

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

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

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L386)

**Параметры:**

json_file (`str` или `os.PathLike`) : Имя файла json для разбора

allow_extra_keys (`bool`, *необязательный*, по умолчанию `False`) : По умолчанию False. Если False, будет выброшено исключение, если файл json содержит ключи, которые не были распознаны.

**Возвращает:** `Tuple consisting of`

- экземпляры dataclass в том же порядке, в котором они были переданы в инициализатор.

Альтернативный вспомогательный метод, который вообще не использует `argparse`, а вместо этого загружает json-файл и заполняет типы dataclass.

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

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

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/hf_argparser.py#L408)

**Параметры:**

yaml_file (`str` или `os.PathLike`) : Имя файла yaml для разбора

allow_extra_keys (`bool`, *необязательный*, по умолчанию `False`) : По умолчанию False. Если False, будет выброшено исключение, если файл json содержит ключи, которые не были распознаны.

**Возвращает:** `Tuple consisting of`

- экземпляры dataclass в том же порядке, в котором они были переданы в инициализатор.

Альтернативный вспомогательный метод, который вообще не использует `argparse`, а вместо этого загружает файл yaml и заполняет типы dataclass.

## Утилиты отладки[[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)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/debug_utils.py#L27)

**Параметры:**

model (`nn.Module`) : модель для отладки.

max_frames_to_save (`int`, *необязательный*, по умолчанию 21) : Сколько кадров назад записывать

trace_batch_nums(`list[int]`, *необязательный*, по умолчанию `[]`) : номера батчей для трассировки (отключает обнаружение ходов)

abort_after_batch_num  (`int``, *необязательный*) : Прерывать ли выполнение после завершения определённого номера батча

Этот класс отладки помогает обнаружить и понять, где в модели значения начинают становиться очень большими или очень маленькими, а что ещё важнее — где появляются элементы весов и активаций, равные `nan` или `inf`.

Существуют 2 рабочих режима:

1. Обнаружение переполнения/недополнения (по умолчанию)
2. Отслеживание абсолютных минимальных/максимальных значений конкретной партии без обнаружения

Режим 1: обнаружение переполнения/недополнения

Для активации обнаружения переполнения/недополнения инициализируйте объект с моделью:

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

затем запустите обучение в обычном режиме, и если `nan` или `inf` обнаруживается хотя бы в одном из элементов весов, входных или выходных данных, этот модуль выбросит исключение и выведет `max_frames_to_save` кадров, приведших к этому событию, при этом каждый кадр сообщает

1. полное имя модуля с указанием имени класса, для которого был выполнен `forward`
2. абсолютные минимальное и максимальное значения всех элементов весов каждого модуля, а также входных и выходных данных

Например, ниже приведены заголовок и последние кадры отчёта о детекции для запуска `google/mt5-small` в fp16

смешанная точность:

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

Здесь видно, что `T5DenseGatedGeluDense.forward` привела к выходным активациям, максимальное абсолютное значение которых составило около 62,7K, что очень близко к верхнему пределу fp16 в 64K. На следующем кадре мы видим `Dropout`, который заново нормализует веса после обнуления некоторых элементов, что выталкивает максимальное абсолютное значение за пределы 64K, и возникает переполнение.

Как видно, именно предыдущие кадры следует рассматривать, когда значения начинают становиться очень большими для чисел fp16.

Отслеживание выполняется в прямом хуке, который вызывается сразу после завершения `forward`.

По умолчанию выводятся последние 21 кадр. Вы можете изменить это значение по умолчанию в соответствии со своими потребностями. Например:

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

Чтобы убедиться, что эта функция отладки настроена правильно и вы планируете использовать её в обучении, которое может занять несколько часов, сначала запустите её с обычным трассированием для одной из нескольких партий, как описано в следующем разделе.

Режим 2. Отслеживание конкретных абсолютных минимальных/максимальных значений батча без обнаружения

Второй режим работы — это трассировка по батчам с отключённой функцией обнаружения переполнения/недополнения.

Допустим, вы хотите отслеживать абсолютные минимальные и максимальные значения для всех компонентов каждого вызова `forward`

заданной партии, и выполнять это только для партий 1 и 3. Затем вы создаёте экземпляр этого класса как

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

Теперь полные батчи 1 и 3 будут отслеживаться в том же формате, что описан выше. Нумерация батчей начинается с нуля.

Это полезно, если вы знаете, что программа начинает работать некорректно после определённого номера батча, — в этом случае можно сразу перейти к нужному участку.

Ранняя остановка:

Вы также можете указать номер батча, после которого следует остановить обучение, с помощью :

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

Эта функция в основном полезна в режиме трассировки, но вы можете использовать её в любом режиме.

**Производительность**:

Поскольку этот модуль измеряет абсолютные `min`/``max` каждого веса модели при каждом прямом проходе, он замедляет обучение. Поэтому не забудьте отключить его, как только необходимость в отладке будет устранена.