# Обработчики событий

Callbacks — это объекты, которые позволяют настраивать поведение цикла обучения в PyTorch [Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer). Они могут анализировать состояние цикла обучения (например, для отчета о прогрессе, записи логов в TensorBoard или другие ML-платформы) и принимать решения (например, о досрочной остановке).

Объекты [TrainerControl](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerControl), возвращаемые callback'ами, являются единственным исключением: сами callback'ы представляют собой код, работающий в режиме «только чтение», и не могут вносить никаких изменений в цикл обучения. Если для кастомизации необходимо модифицировать цикл обучения, следует создать подкласс [Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer) и переопределить нужные методы (примеры см. в разделе [trainer](trainer)).

По умолчанию `TrainingArguments.report_to` установлен в значение `"none"`.

Основной класс, реализующий обратные вызовы, — это [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback). Он получает [TrainingArguments](/docs/transformers/main/ru/main_classes/trainer#transformers.TrainingArguments), использованные для создания экземпляра [Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer), может обращаться к внутреннему состоянию этого Trainer через [TrainerState](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerState) и выполнять определённые действия в цикле обучения с помощью [TrainerControl](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerControl).

## Доступные обратные вызовы[[transformers.integrations.CometCallback]]

Вот список доступных в библиотеке [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback):

#### transformers.integrations.CometCallback[[transformers.integrations.CometCallback]]

```python
transformers.integrations.CometCallback()
```

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

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), который отправляет логи в [Comet ML](https://www.comet.com/site/).

#### настройка[[transformers.integrations.CometCallback.setup]]

```python
setup(args, state, model)
```

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

Настройте необязательную интеграцию с Comet.

Окружение:
- **COMET_MODE** (`str`, *необязательный*, по умолчанию `get_or_create`): управляет тем, следует ли создать новый эксперимент Comet и вести в него журнал или добавить записи в существующий эксперимент. Допустимые значения:
  * `get_or_create`: автоматически определяет поведение в зависимости от того, задан ли `COMET_EXPERIMENT_KEY` и существует ли уже Experiment с этим ключом.
  * `create`: Всегда создавать новый эксперимент Comet.
  * `get`: всегда пытайтесь добавлять данные в существующий эксперимент Comet. Требуется, чтобы переменная `COMET_EXPERIMENT_KEY` была установлена.
- **COMET_START_ONLINE** (`bool`, *необязательный*): Указывает, следует ли создать онлайн- или офлайн-эксперимент.
- **COMET_PROJECT_NAME** (`str`, *необязательный*): имя проекта Comet для экспериментов.
- **COMET_LOG_ASSETS** (`str`, *необязательный*, по умолчанию `TRUE`): определяет, следует ли отправлять в Comet данные о ходе обучения (чекпоинты и т. д.). Может принимать значение `TRUE` или `FALSE`.

Список настраиваемых параметров окружения см. [здесь](https://www.comet.com/docs/v2/guides/experiment-management/configure-sdk/#explore-comet-configuration-options).

#### transformers.DefaultFlowCallback[[transformers.DefaultFlowCallback]]

```python
transformers.DefaultFlowCallback()
```

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

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), который обрабатывает стандартный поток цикла обучения для ведения журналов, оценки и создания контрольных точек.

#### transformers.PrinterCallback[[transformers.PrinterCallback]]

```python
transformers.PrinterCallback()
```

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

Голый [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), который просто выводит логи.

#### transformers.ProgressCallback[[transformers.ProgressCallback]]

```python
transformers.ProgressCallback(max_str_len: int = 100)
```

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

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), отображающий ход обучения или оценки. Параметр `max_str_len` можно изменить, чтобы управлять длиной обрезки строк при ведении журнала.

#### transformers.EarlyStoppingCallback[[transformers.EarlyStoppingCallback]]

```python
transformers.EarlyStoppingCallback(early_stopping_patience: int = 1, early_stopping_threshold: float | None = 0.0)
```

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

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

early_stopping_patience (`int`) : Используется вместе с `metric_for_best_model` для остановки обучения, если указанная метрика ухудшается в течение `early_stopping_patience` вызовов оценки.

early_stopping_threshold(`float`, *необязательный*) : Используйте вместе с TrainingArguments `metric_for_best_model` и `early_stopping_patience`, чтобы указать, насколько должна улучшиться заданная метрика для выполнения условий раннего завершения. `

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), реализующий раннюю остановку.

Этот callback использует функциональность аргумента *load_best_model_at_end* в [TrainingArguments](/docs/transformers/main/ru/main_classes/trainer#transformers.TrainingArguments) для установки best_metric в [TrainerState](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerState). Обратите внимание, что если аргумент *save_steps* в [TrainingArguments](/docs/transformers/main/ru/main_classes/trainer#transformers.TrainingArguments) отличается от *eval_steps*, ранняя остановка не произойдёт до следующего шага сохранения.

#### transformers.integrations.TensorBoardCallback[[transformers.integrations.TensorBoardCallback]]

```python
transformers.integrations.TensorBoardCallback(tb_writer = None)
```

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

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

tb_writer (`SummaryWriter`, *необязательный*) : Записываемый объект. Если не задан, будет создан автоматически.

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), который отправляет логи в [TensorBoard](https://www.tensorflow.org/tensorboard).

Окружение:
- **TENSORBOARD_LOGGING_DIR** (`str`, *необязательный*, по умолчанию `None`): каталог для записи результатов. Значение по умолчанию: os.path.join(args.output_dir, default_logdir())

#### transformers.integrations.TrackioCallback[[transformers.integrations.TrackioCallback]]

```python
transformers.integrations.TrackioCallback()
```

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

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), который записывает метрики в Trackio.

#### настройка[[transformers.integrations.TrackioCallback.setup]]

```python
setup(args, state, model, **kwargs)
```

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

Настройте необязательную интеграцию с Trackio.

Чтобы настроить конфигурацию, вы также можете задать `project`, `trackio_space_id`, `trackio_bucket_id`, `trackio_static_space_id` и `hub_private_repo` в [TrainingArguments](/docs/transformers/main/ru/main_classes/trainer#transformers.TrainingArguments).

#### transformers.integrations.WandbCallback[[transformers.integrations.WandbCallback]]

```python
transformers.integrations.WandbCallback()
```

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

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), который записывает метрики, медиафайлы и контрольные точки модели в [Weight and Biases](https://www.wandb.com/).

#### настройка[[transformers.integrations.WandbCallback.setup]]

```python
setup(args, state, model, **kwargs)
```

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

Настройте необязательную интеграцию с Weights & Biases (*wandb*).

Можно создать подкласс и переопределить этот метод, чтобы настроить процесс при необходимости. Подробнее — [здесь](https://docs.wandb.ai/guides/integrations/huggingface). Также можно переопределить следующие переменные окружения:

Окружение:
- **WANDB_LOG_MODEL** (`str`, *необязательный*, по умолчанию `"false"`): определяет, следует ли записывать в журнал модель и контрольные точки во время обучения. Допустимые значения: `"end"`, `"checkpoint"` или `"false"`. Если установлено значение `"end"`, модель будет загружена по завершении обучения. Если установлено значение `"checkpoint"`, контрольная точка будет загружаться каждые `args.save_steps` . Если установлено значение `"false"`, модель не будет загружена. Используйте вместе с `load_best_model_at_end()` для загрузки лучшей модели.
- **WANDB_WATCH** (`str`, *необязательный*, по умолчанию `"false"`): может принимать значения `"gradients"`, `"all"`, `"parameters"` или `"false"`. Установите значение `"all"`, чтобы записывать градиенты и параметры.
- **WANDB_PROJECT** (`str`, *необязательный*, по умолчанию `"huggingface"`): задайте это значение как произвольную строку, чтобы сохранять результаты в другом проекте.

#### transformers.integrations.MLflowCallback[[transformers.integrations.MLflowCallback]]

```python
transformers.integrations.MLflowCallback()
```

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

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), который отправляет логи в [MLflow](https://www.mlflow.org/). Интеграцию можно отключить, установив переменную окружения `DISABLE_MLFLOW_INTEGRATION = TRUE`.

#### настройка[[transformers.integrations.MLflowCallback.setup]]

```python
setup(args, state, model)
```

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

Настройте необязательную интеграцию с MLflow.

Окружение:
- **HF_MLFLOW_LOG_ARTIFACTS** (`str`, *необязательный*): Использовать ли механизм `.log_artifact()` MLflow для записи артефактов. Это имеет смысл только при записи на удалённый сервер, например s3 или GCS. Если установлено значение `True` или *1*, каждая сохранённая контрольная точка из `output_dir` в [TrainingArguments](/docs/transformers/main/ru/main_classes/trainer#transformers.TrainingArguments) будет копироваться в локальное или удалённое хранилище артефактов при каждом сохранении. Использование без удалённого хранилища просто скопирует файлы в ваше расположение для артефактов.
- **MLFLOW_TRACKING_URI** (`str`, *необязательный*): определяет, сохранять ли результаты экспериментов в конкретном пути или на удалённом сервере. По умолчанию не задан, что означает полный пропуск установки URI отслеживания.
- **MLFLOW_EXPERIMENT_NAME** (`str`, *необязательный*, по умолчанию `None`): определяет, следует ли использовать experiment_name MLflow, в рамках которого будет запущен run. По умолчанию `None`, что указывает на эксперимент `Default` в MLflow. В противном случае это имя эксперимента, чувствительное к регистру, которое будет активировано. Если эксперимент с таким именем не существует, создаётся новый эксперимент с этим именем.
- **MLFLOW_TAGS** (`str`, *необязательный*): строковое представление словаря пар ключ/значение, которые будут добавлены в запуск MLflow в качестве тегов. Пример: `os.environ['MLFLOW_TAGS']='{"release.candidate": "RC1", "release.version": "2.2.0"}'`.
- **MLFLOW_NESTED_RUN** (`str`, *необязательный*): Использовать ли вложенные запуски MLflow. Если установлено значение `True` или *1*, будет создан вложенный запуск внутри текущего.
- **MLFLOW_RUN_ID** (`str`, *необязательный*): Позволяет повторно подключиться к существующему запуску, что может быть полезно при возобновлении обучения из контрольной точки. Если переменная окружения `MLFLOW_RUN_ID` задана, `start_run` пытается возобновить запуск с указанным идентификатором, а остальные параметры игнорируются.
- **MLFLOW_FLATTEN_PARAMS** (`str`, *необязательный*, по умолчанию `False`): Указывает, следует ли выровнять словарь параметров перед записью в журнал.
- **MLFLOW_MAX_LOG_PARAMS** (`int`, *необязательный*): задаёт максимальное количество параметров, которые нужно записывать в журнал запуска.

#### transformers.integrations.AzureMLCallback[[transformers.integrations.AzureMLCallback]]

```python
transformers.integrations.AzureMLCallback(azureml_run = None)
```

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

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), который отправляет логи в [AzureML](https://pypi.org/project/azureml-sdk/).

#### transformers.integrations.CodeCarbonCallback[[transformers.integrations.CodeCarbonCallback]]

```python
transformers.integrations.CodeCarbonCallback()
```

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

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), отслеживающий выбросы CO2 в процессе обучения.

#### transformers.integrations.ClearMLCallback[[transformers.integrations.ClearMLCallback]]

```python
transformers.integrations.ClearMLCallback()
```

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

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), который отправляет логи в [ClearML](https://clear.ml/).

Окружение:
- **CLEARML_PROJECT** (`str`, *необязательный*, по умолчанию `HuggingFace Transformers`): имя проекта ClearML.
- **CLEARML_TASK** (`str`, *необязательный*, по умолчанию `Trainer`): имя задачи ClearML.
- **CLEARML_LOG_MODEL** (`bool`, *необязательный*, по умолчанию `False`): указывает, следует ли регистрировать модели в качестве артефактов во время обучения.

#### transformers.integrations.DagsHubCallback[[transformers.integrations.DagsHubCallback]]

```python
transformers.integrations.DagsHubCallback()
```

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

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), который выполняет логирование в [DagsHub](https://dagshub.com/). Наследует `MLflowCallback`

#### настройка[[transformers.integrations.DagsHubCallback.setup]]

```python
setup(*args, **kwargs)
```

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

Настройте интеграцию с логированием DagsHub.

Окружение:
- **HF_DAGSHUB_LOG_ARTIFACTS** (`str`, *необязательный*): Определяет, следует ли сохранять артефакты данных и модели для эксперимента. По умолчанию `False`.

#### transformers.integrations.FlyteCallback[[transformers.integrations.FlyteCallback]]

```python
transformers.integrations.FlyteCallback(save_log_history: bool = True, sync_checkpoints: bool = True)
```

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

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

save_log_history (`bool`, *необязательный*, по умолчанию `True`) : Если установлено значение True, журналы обучения сохраняются в виде Flyte Deck.

sync_checkpoints (`bool`, *необязательный*, по умолчанию `True`) : Если установлено значение True, контрольные точки синхронизируются с Flyte и могут использоваться для возобновления обучения в случае прерывания.

Колбэк [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), который отправляет логи в [Flyte](https://flyte.org/). Примечание: этот колбэк работает только внутри задачи Flyte.

Пример:

```python
# Note: This example skips over some setup steps for brevity.
from flytekit import current_context, task

@task
def train_hf_transformer():
    cp = current_context().checkpoint
    trainer = Trainer(..., callbacks=[FlyteCallback()])
    output = trainer.train(resume_from_checkpoint=cp.restore())
```

#### transformers.integrations.KubeflowCallback[[transformers.integrations.KubeflowCallback]]

```python
transformers.integrations.KubeflowCallback()
```

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

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), который сообщает о ходе обучения в [Kubeflow Trainer](https://github.com/kubeflow/trainer).

Этот callback автоматически регистрируется при обучении внутри Kubeflow TrainJob, если включён feature gate `TrainJobRuntimeStatus`. Контроллер Kubeflow вставляет необходимые переменные окружения в pod обучения.

**Переменные окружения (инжектируются контроллером):**

- `KUBEFLOW_TRAINER_SERVER_URL`: HTTPS-адрес для обновления статуса
- `KUBEFLOW_TRAINER_SERVER_CA_CERT`: Путь к сертификату CA для проверки TLS
- `KUBEFLOW_TRAINER_SERVER_TOKEN`: путь к токену учётной записи службы для аутентификации

**Сообщенная информация:**

- Процент выполнения (0–100%)
- Ожидаемое оставшееся время (в секундах)
- Метрики обучения (loss, learning_rate и т. д.)

**Возможности:**

- Автоматическое ограничение частоты (не более 1 обновления за 5 секунд) для предотвращения перегрузки контроллера
- Кэширование токенов (5 минут) для минимизации ввода-вывода файлов
- Только ранг 0 сообщает о ходе обучения в распределённом режиме
- Тихие сбои — сетевые проблемы не прерывают обучение

Можно отключить, установив переменную окружения `DISABLE_KUBEFLOW_INTEGRATION=TRUE`.

#### transformers.integrations.DVCLiveCallback[[transformers.integrations.DVCLiveCallback]]

```python
transformers.integrations.DVCLiveCallback(live: typing.Any | None = None, log_model: typing.Union[typing.Literal['all'], bool, NoneType] = None, **kwargs)
```

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

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

live (`dvclive.Live`, *необязательный*, по умолчанию `None`) : Необязательный экземпляр Live. Если значение равно None, будет создан новый экземпляр с использованием **kwargs.

log_model (Union[Literal["all"], bool], *необязательный*, по умолчанию `None`) : Использовать ли `dvclive.Live.log_artifact()` для записи контрольных точек, создаваемых [Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer). Если установлено значение `True`, итоговая контрольная точка записывается в конце обучения. Если установлено значение `"all"`, при каждой контрольной точке записывается весь `output_dir` из [TrainingArguments](/docs/transformers/main/ru/main_classes/trainer#transformers.TrainingArguments).

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), который отправляет логи в [DVCLive](https://www.dvc.org/doc/dvclive).

Используйте перечисленные ниже переменные окружения в `setup` для настройки интеграции. Чтобы настроить этот callback способами, выходящими за рамки этих переменных окружения, см. [здесь](https://dvc.org/doc/dvclive/ml-frameworks/huggingface).

#### настройка[[transformers.integrations.DVCLiveCallback.setup]]

```python
setup(args, state, model)
```

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

Настройте необязательную интеграцию DVCLive. Чтобы настроить этот callback в деталях, выходящих за рамки перечисленных ниже переменных окружения, см. [здесь](https://dvc.org/doc/dvclive/ml-frameworks/huggingface).

Окружение:
- **HF_DVCLIVE_LOG_MODEL** (`str`, *необязательный*): определяет, следует ли использовать `dvclive.Live.log_artifact()` для записи контрольных точек, создаваемых [Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer). Если значение установлено в `True` или *1*, итоговая контрольная точка записывается в конце обучения. Если значение установлено в `all`, при каждой контрольной точке записывается весь `output_dir` из [TrainingArguments](/docs/transformers/main/ru/main_classes/trainer#transformers.TrainingArguments).

#### transformers.integrations.SwanLabCallback[[transformers.integrations.SwanLabCallback]]

```python
transformers.integrations.SwanLabCallback()
```

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

Класс [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback), который записывает метрики, медиафайлы и контрольные точки модели в [SwanLab](https://swanlab.cn/).

#### настройка[[transformers.integrations.SwanLabCallback.setup]]

```python
setup(args, state, model, **kwargs)
```

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

Настройте необязательную интеграцию SwanLab (*swanlab*).

Можно создать подкласс и переопределить этот метод, чтобы настроить процесс при необходимости. Подробнее — [здесь](https://docs.swanlab.cn/guide_cloud/integration/integration-huggingface-transformers.html).

Вы также можете переопределить следующие переменные окружения. Дополнительную информацию о переменных окружения можно найти [здесь](https://docs.swanlab.cn/en/api/environment-variable.html#environment-variables)

Окружение:
- **SWANLAB_API_KEY** (`str`, *необязательный*, по умолчанию `None`): ключ облачного API. При входе в систему в первую очередь проверяется наличие этой переменной окружения. Если она не задана, система проверяет, выполнен ли уже вход. Если нет, запускается процесс входа.

  - Если в интерфейс входа передаётся строка, эта переменная окружения игнорируется.
  - Если пользователь уже вошёл в систему, эта переменная окружения имеет приоритет над локально сохранёнными данными для входа.

- **SWANLAB_PROJECT** (`str`, *необязательный*, по умолчанию `None`): задайте это значение как произвольную строку, чтобы сохранять результаты в другом проекте. Если значение не указано, используется имя текущей рабочей директории.

- **SWANLAB_LOG_DIR** (`str`, *необязательный*, по умолчанию `swanlog`): эта переменная окружения задаёт путь к хранилищу файлов журнала при работе в локальном режиме. По умолчанию журналы сохраняются в папке swanlog в рабочей директории.

- **SWANLAB_MODE** (`Literal["local", "cloud", "disabled"]`, *необязательный*, по умолчанию `cloud`): режим разбора SwanLab, который включает в себя колбэки, зарегистрированные оператором. В настоящее время доступны три режима: local, cloud и disabled. Примечание: регистр символов имеет значение. Дополнительную информацию можно найти [здесь](https://docs.swanlab.cn/en/api/py-init.html#swanlab-init)

- **SWANLAB_LOG_MODEL** (`str`, *необязательный*, по умолчанию `None`): SwanLab в настоящее время не поддерживает функциональность режима сохранения. Эта функция будет доступна в одном из будущих выпусков

- **SWANLAB_WEB_HOST** (`str`, *необязательный*, по умолчанию `None`): веб-адрес облачной среды SwanLab для частной версии (она бесплатна)

- **SWANLAB_API_HOST** (`str`, *необязательный*, по умолчанию `None`): адрес API облачной среды SwanLab для приватной версии (она бесплатна)

- **SWANLAB_RUN_ID** (`str`, *необязательный*, по умолчанию `None`): ID эксперимента для возобновления предыдущего запуска. Используйте вместе с `SWANLAB_RESUME`, чтобы продолжить существующий эксперимент.

- **SWANLAB_RESUME** (`str`, *необязательный*, по умолчанию `None`): режим возобновления (`"must"`, `"allow"`, `"never"`). По умолчанию `"allow"`, если используется `resume_from_checkpoint`.

## TrainerCallback[[transformers.TrainerCallback]]

#### transformers.TrainerCallback[[transformers.TrainerCallback]]

```python
transformers.TrainerCallback()
```

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

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

args ([TrainingArguments](/docs/transformers/main/ru/main_classes/trainer#transformers.TrainingArguments)) : аргументы обучения, используемые для создания экземпляра [Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer).

state ([TrainerState](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerState)) : текущее состояние [Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer).

control ([TrainerControl](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerControl)) : объект, который возвращается в [Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer) и может использоваться для принятия некоторых решений.

model ([PreTrainedModel](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel) или `torch.nn.Module`) : обучаемая модель.

processing_class ([`PreTrainedTokenizer` или `BaseImageProcessor` или `ProcessorMixin` или `FeatureExtractionMixin`]) : Класс обработки, используемый для кодирования данных. Может быть токенизатором, процессором, процессором изображений или экстрактором признаков.

optimizer (`torch.optim.Optimizer`) : оптимизатор, используемый для шагов обучения.

lr_scheduler (`torch.optim.lr_scheduler.LambdaLR`) : планировщик, используемый для установки скорости обучения.

train_dataloader (`torch.utils.data.DataLoader`, *необязательный*) : Текущий dataloader, используемый для обучения.

eval_dataloader (`torch.utils.data.DataLoader`, *необязательный*) : Текущий dataloader, используемый для оценки.

metrics (`dict[str, float]`) : Метрики, вычисленные на последнем этапе оценки. Они доступны только в событии `on_evaluate`.

logs  (`dict[str, float]`) : Значения для записи в журнал.  Доступны только в событии `on_log`.

Класс для объектов, которые в определённые моменты проверяют состояние цикла обучения и принимают решения. На каждом из таких событий доступны следующие аргументы:

Объект `control` — единственный, который может быть изменён колбэком, при этом событие, вносящее изменения, должно вернуть изменённую версию.

Аргументы `args`, `state` и `control` являются позиционными для всех событий, все остальные сгруппированы в `kwargs`. Вы можете распаковать в сигнатуре события те из них, которые вам нужны. Пример — код простого [PrinterCallback](/docs/transformers/main/ru/main_classes/callback#transformers.PrinterCallback).

Пример:

```python
class PrinterCallback(TrainerCallback):
    def on_log(self, args, state, control, logs=None, **kwargs):
        _ = logs.pop("total_flos", None)
        if state.is_local_process_zero:
            print(logs)
```

#### on_epoch_begin[[transformers.TrainerCallback.on_epoch_begin]]

```python
on_epoch_begin(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

Событие, вызываемое в начале эпохи.

#### on_epoch_end[[transformers.TrainerCallback.on_epoch_end]]

```python
on_epoch_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

Событие, вызываемое в конце эпохи.

#### on_evaluate[[transformers.TrainerCallback.on_evaluate]]

```python
on_evaluate(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

Событие, вызываемое после фазы оценки.

#### on_init_end[[transformers.TrainerCallback.on_init_end]]

```python
on_init_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

Событие, вызываемое в конце инициализации [Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer).

#### on_log[[transformers.TrainerCallback.on_log]]

```python
on_log(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

Событие, вызываемое после записи последних логов.

#### on_optimizer_step[[transformers.TrainerCallback.on_optimizer_step]]

```python
on_optimizer_step(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

Событие, вызываемое после шага оптимизатора, но до обнуления градиентов. Полезно для мониторинга градиентов.

#### on_pre_optimizer_step[[transformers.TrainerCallback.on_pre_optimizer_step]]

```python
on_pre_optimizer_step(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

Событие, вызываемое перед шагом оптимизатора, но после обрезки градиентов. Полезно для мониторинга градиентов.

#### on_predict[[transformers.TrainerCallback.on_predict]]

```python
on_predict(args: TrainingArguments, state: TrainerState, control: TrainerControl, metrics, **kwargs)
```

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

Событие, вызываемое после успешного предсказания.

#### on_prediction_step[[transformers.TrainerCallback.on_prediction_step]]

```python
on_prediction_step(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

Событие, вызываемое после шага предсказания.

#### on_push_begin[[transformers.TrainerCallback.on_push_begin]]

```python
on_push_begin(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

Event called before pushing the model to the hub, at the beginning of Trainer.push_to_hub and Trainer._push_from_checkpoint.

#### on_save[[transformers.TrainerCallback.on_save]]

```python
on_save(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

Событие, вызываемое после сохранения контрольной точки.

#### on_step_begin[[transformers.TrainerCallback.on_step_begin]]

```python
on_step_begin(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

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

#### on_step_end[[transformers.TrainerCallback.on_step_end]]

```python
on_step_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

Событие, вызываемое в конце шага обучения. При использовании накопления градиентов один шаг обучения может охватывать несколько входных данных.

#### on_substep_end[[transformers.TrainerCallback.on_substep_end]]

```python
on_substep_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

Событие, вызываемое в конце подшага во время накопления градиентов.

#### on_train_begin[[transformers.TrainerCallback.on_train_begin]]

```python
on_train_begin(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

Событие, вызываемое в начале обучения.

#### on_train_end[[transformers.TrainerCallback.on_train_end]]

```python
on_train_end(args: TrainingArguments, state: TrainerState, control: TrainerControl, **kwargs)
```

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

Событие, вызываемое в конце обучения.

Ниже приведен пример регистрации пользовательского обратного вызова с [Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer) PyTorch:

```python
class MyCallback(TrainerCallback):
    "A callback that prints a message at the beginning of training"

    def on_train_begin(self, args, state, control, **kwargs):
        print("Starting training")

trainer = Trainer(
    model,
    args,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
    callbacks=[MyCallback],  # We can either pass the callback class this way or an instance of it (MyCallback())
)
```

Ещё один способ зарегистрировать колбэк — вызвать `trainer.add_callback()` следующим образом:

```python
trainer = Trainer(...)
trainer.add_callback(MyCallback)
# Alternatively, we can pass an instance of the callback class
trainer.add_callback(MyCallback())
```

## TrainerState[[transformers.TrainerState]]

#### transformers.TrainerState[[transformers.TrainerState]]

```python
transformers.TrainerState(epoch: float = 0, global_step: int = 0, max_steps: int = 0, logging_steps: int = 500, eval_steps: int = 500, save_steps: int = 500, train_batch_size: int | None = None, num_train_epochs: int = 0, num_input_tokens_seen: int = 0, total_flos: float = 0, log_history: list = None, best_metric: float | None = None, best_global_step: int | None = None, best_model_checkpoint: str | None = None, is_local_process_zero: bool = True, is_world_process_zero: bool = True, is_hyper_param_search: bool = False, trial_name: str | None = None, trial_params: dict[str, str | float | int | bool] | None = None, stateful_callbacks: list['TrainerCallback'] | None = None)
```

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

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

epoch (`float`, *optional*) : Устанавливается только во время обучения и указывает текущую эпоху (дробная часть показывает процент завершённости текущей эпохи).

global_step (`int`, *optional*, по умолчанию 0) : Во время обучения представляет собой количество завершённых шагов обновления.

max_steps (`int`, *необязательный*, по умолчанию 0) : Количество шагов обновления, выполняемых в ходе текущей тренировки.

logging_steps (`int`, *optional*, по умолчанию 500) : Выводить лог каждые X шагов обновления

eval_steps (`int`, *optional*) : Запускать оценку каждые X шагов.

save_steps (`int`, *optional*, по умолчанию 500) : Сохранять контрольную точку каждые X шагов обновления.

train_batch_size (`int`, *необязательный*) : Размер батча для загрузчика данных обучения. Требуется только при использовании `auto_find_batch_size`.

num_input_tokens_seen (`int`, *optional*, по умолчанию 0) : При отслеживании входных токенов — количество токенов, обработанных во время обучения (число входных токенов, а не число токенов предсказания).

total_flos (`float`, *optional*, по умолчанию 0) : Общее количество операций с плавающей точкой, выполненных моделью с начала обучения (хранится в формате float, чтобы избежать переполнения).

log_history (`list[dict[str, float]]`, *необязательный*) : Список логов, выполненных с начала обучения.

best_metric (`float`, *необязательный*) : при отслеживании лучшей модели — значение лучшей метрики, полученной на данный момент.

best_global_step (`int`, *optional*) : при отслеживании лучшей модели — шаг, на котором было достигнуто лучшее значение метрики. Используется для установки `best_model_checkpoint`.

best_model_checkpoint (`str`, *необязательный*) : при отслеживании лучшей модели — значение имени контрольной точки для лучшей модели, найденной на данный момент.

is_local_process_zero (`bool`, *необязательный*, по умолчанию `True`) : Является ли этот процесс локальным (например, на одной машине при распределённом обучении на нескольких машинах) основным процессом.

is_world_process_zero (`bool`, *необязательный*, по умолчанию `True`) : Является ли этот процесс глобальным основным процессом (при распределённом обучении на нескольких машинах значение `True` будет только для одного процесса).

is_hyper_param_search (`bool`, *необязательный*, по умолчанию `False`) : Указывает, выполняется ли в данный момент поиск гиперпараметров с помощью Trainer.hyperparameter_search. Это влияет на способ записи данных в TensorBoard.

stateful_callbacks (`list[StatefulTrainerCallback]`, *необязательный*) : Колбэки, привязанные к `Trainer`, состояние которых должно сохраняться или восстанавливаться. Соответствующие колбэки должны реализовывать функции `state` и `from_state`.

Класс, содержащий внутреннее состояние [Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer), которое сохраняется вместе с моделью и оптимизатором при создании контрольных точек и передаётся в [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback).

Во всех классах этого раздела один шаг понимается как один шаг обновления. При использовании накопления градиентов один шаг обновления может требовать нескольких проходов вперёд и назад: если вы используете `gradient_accumulation_steps=n`, то для одного шага обновления необходимо обработать *n* батчей.

#### compute_steps[[transformers.TrainerState.compute_steps]]

```python
compute_steps(args, max_steps)
```

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

Вычисляет и сохраняет абсолютное значение для шагов логирования, оценки и сохранения на основе того, было ли это значение долей или нет.

#### init_training_references[[transformers.TrainerState.init_training_references]]

```python
init_training_references(trainer, max_steps, num_train_epochs, trial)
```

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

Сохраняет начальные опорные данные для обучения в `self`

#### load_from_json[[transformers.TrainerState.load_from_json]]

```python
load_from_json(json_path: str)
```

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

Создайте экземпляр на основе содержимого `json_path`.

#### save_to_json[[transformers.TrainerState.save_to_json]]

```python
save_to_json(json_path: str)
```

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

Сохраните содержимое этого экземпляра в формате JSON внутри `json_path`.

## TrainerControl[[transformers.TrainerControl]]

#### transformers.TrainerControl[[transformers.TrainerControl]]

```python
transformers.TrainerControl(should_training_stop: bool = False, should_epoch_stop: bool = False, should_save: bool = False, should_evaluate: bool = False, should_log: bool = False)
```

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

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

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

should_epoch_stop (`bool`, *необязательный*, по умолчанию `False`) : Указывает, следует ли прервать текущую эпоху. Если `True`, то в начале следующей эпохи значение этой переменной будет сброшено в `False`.

should_save (`bool`, *необязательный*, по умолчанию `False`) : Указывает, следует ли сохранять модель на этом шаге. Если `True`, то в начале следующего шага значение этой переменной будет сброшено в `False`.

should_evaluate (`bool`, *необязательный*, по умолчанию `False`) : Указывает, следует ли выполнять оценку модели на этом шаге. Если `True`, то в начале следующего шага значение этой переменной будет сброшено в `False`.

should_log (`bool`, *необязательный*, по умолчанию `False`) : Указывает, следует ли выводить логи на этом шаге. Если `True`, то в начале следующего шага значение этой переменной будет сброшено в `False`.

Класс, управляющий потоком выполнения [Trainer](/docs/transformers/main/ru/main_classes/trainer#transformers.Trainer). Этот класс используется [TrainerCallback](/docs/transformers/main/ru/main_classes/callback#transformers.TrainerCallback) для активации определённых переключателей в цикле обучения.