# コールバック

[TrainerCallback](/docs/transformers/main/ja/main_classes/callback#transformers.TrainerCallback) は、特定のトレーニングイベント（エポック開始、評価、トレーニング終了）にフックし、トレーニング状態の変更や制御フローの操作を行います。コールバックを使用して、Trackio などの実験トラッカーへのメトリクスの記録、保存や評価の実行タイミングのカスタマイズ、その他のカスタム動作の追加を行うことができます。複数のコールバックをスタックすることで、機能を組み合わせることができます。

Callbackは、フォワードパスのようなトレーニングループ自体を変更することはできません。[Trainer](/docs/transformers/main/ja/main_classes/trainer#transformers.Trainer)が計算する内容を変更するには、代わりにそのメソッドを[サブクラス化](./trainer_customize)してください。

以下の図は、コールバックがフックできるすべてのイベントを示しています。

```md
on_train_begin
  └─ for each epoch:
      on_epoch_begin
      └─ for each step:
          on_step_begin
          ├─ for each gradient accumulation substep:
          │   on_substep_end
          on_pre_optimizer_step   ← after gradient clipping, before optimizer.step()
          on_optimizer_step       ← after optimizer.step()
          on_step_end
          └─ (conditionally):
              on_log
              on_evaluate
              on_save
      on_epoch_end
on_train_end
on_predict / on_prediction_step
on_push_begin
```

## コールバックの作成

[TrainerCallback](/docs/transformers/main/ja/main_classes/callback#transformers.TrainerCallback) をサブクラス化し、上記の図にあるイベントメソッドのうち1つ以上をオーバーライドします。以下の例では、3つのフックを示しています。

- `on_epoch_begin` は、[TrainerState](/docs/transformers/main/ja/main_classes/callback#transformers.TrainerState)（ライブ値）から現在のエポックを、[TrainingArguments](/docs/transformers/main/ja/main_classes/trainer#transformers.TrainingArguments)（静的値）から学習率を出力します。
- `on_step_end` は、lr_scheduler（`**kwargs` を介して渡される）から現在の学習率を読み取り、閾値を下回ったときに評価をトリガーするために、[TrainerControl](/docs/transformers/main/ja/main_classes/callback#transformers.TrainerControl) の `should_evaluate` を設定します（制御オブジェクトの完全なリストについては [TrainerControl](/docs/transformers/main/ja/main_classes/callback#transformers.TrainerControl) を参照してください）。
- `on_train_end` は、最良のメトリックとその発生したステップを出力します。

```python
from transformers import TrainerCallback

class EpochLoggerCallback(TrainerCallback):
    def __init__(self, lr_eval_threshold=1e-5):
        self.lr_eval_threshold = lr_eval_threshold

    def on_epoch_begin(self, args, state, control, **kwargs):
        print(f"Starting epoch {int(state.epoch) + 1}/{state.num_train_epochs} "
              f"(lr={args.learning_rate})")

    def on_step_end(self, args, state, control, **kwargs):
        lr_scheduler = kwargs.get("lr_scheduler")
        if lr_scheduler is not None:
            current_lr = lr_scheduler.get_last_lr()[0]
            if current_lr < self.lr_eval_threshold:
                control.should_evaluate = True

    def on_train_end(self, args, state, control, **kwargs):
        print(f"Training complete! Best metric: {state.best_metric} at step {state.best_global_step}")
```

`callbacks` 引数で、[Trainer](/docs/transformers/main/ja/main_classes/trainer#transformers.Trainer) にコールバックを登録します。リストとして複数のコールバックを渡すこともできます。

```python
trainer = Trainer(
    callbacks=[EpochLoggerCallback(lr_eval_threshold=1e-5)],
    ...,
)
```

## 組み込みコールバック

Transformers には、デフォルトで有効になる組み込みのコールバックがいくつか含まれています。追加の [統合コールバック](./main_classes/callback) は、[Trackio](https://huggingface.co/docs/trackio/en/index) などのプラットフォームにログを出力します。

### DefaultFlowCallback

[DefaultFlowCallback](/docs/transformers/main/ja/main_classes/callback#transformers.DefaultFlowCallback) は、[TrainingArguments](/docs/transformers/main/ja/main_classes/trainer#transformers.TrainingArguments) 内の `logging_strategy`、`eval_strategy`、`save_strategy` の値に基づいて、デフォルトのログ記録、評価、チェックポイントのスケジュールを管理します。適切なステップまたはエポックに達すると、対応する `control` フラグ（`should_log`、`should_evaluate`、`should_save`）を設定します。また、`global_step` が `max_steps` に達した時点で `should_training_stop` を設定します。

このコールバックをオーバーライドすることは、ログ出力、評価、または保存の*タイミング*をカスタマイズする主な方法です。

### ProgressCallback と PrinterCallback

[Trainer](/docs/transformers/main/ja/main_classes/trainer#transformers.Trainer) は、[TrainingArguments](/docs/transformers/main/ja/main_classes/trainer#transformers.TrainingArguments) の [disable_tqdm](/docs/transformers/main/ja/main_classes/trainer#transformers.TrainingArguments.disable_tqdm) フィールドに基づいて、これらの2つのコールバックのいずれかを自動的に選択します。

- [ProgressCallback](/docs/transformers/main/ja/main_classes/callback#transformers.ProgressCallback)はデフォルトで使用されます。トレーニング中はtqdmのプログレスバーを表示し、評価または予測時には別のバーを表示し、各`on_log`イベントで最新のメトリクスを出力します。分散学習時には、重複した出力を避けるため、メインプロセスでのみ実行されます。
- [PrinterCallback](/docs/transformers/main/ja/main_classes/callback#transformers.PrinterCallback) は、`disable_tqdm=True` の場合に使用されます。進捗バーを表示せず、`on_log` イベントのたびにログ辞書を標準出力に出力します。

[remove_callback()](/docs/transformers/main/ja/main_classes/trainer#transformers.Trainer.remove_callback) と [add_callback()](/docs/transformers/main/ja/main_classes/trainer#transformers.Trainer.add_callback) を使用して、手動で交換することもできます。

```py
from transformers import PrinterCallback

trainer = Trainer(...)
trainer.remove_callback(ProgressCallback)
trainer.add_callback(PrinterCallback)
```

### EarlyStoppingCallback

[EarlyStoppingCallback](/docs/transformers/main/ja/main_classes/callback#transformers.EarlyStoppingCallback)は、評価指標の改善が止まった時点でトレーニングを停止します。各評価の後に、指標が`early_stopping_threshold`以上改善したかどうかを確認します。`early_stopping_patience`回連続で指標が改善しなかった場合、トレーニングが停止します。

[EarlyStoppingCallback](/docs/transformers/main/ja/main_classes/callback#transformers.EarlyStoppingCallback)には、[TrainingArguments](/docs/transformers/main/ja/main_classes/trainer#transformers.TrainingArguments)が2つ必要です:

- 監視する評価指標である`metric_for_best_model`
- `eval_strategy`、`"steps"` で評価するか `"epoch"` で評価するか

```py
from transformers import EarlyStoppingCallback

trainer = Trainer(
    ...,
    callbacks=[EarlyStoppingCallback(early_stopping_patience=3, early_stopping_threshold=0.001)],
)
```

## 次のステップ

- 実験トラッカーへのログ出力に対応するすべての[統合コールバック](./main_classes/callback)を確認できます。
- [Trainer メソッドのサブクラス化](./trainer_customize)ガイドでは、トレーニングループが計算する内容を変更する必要がある場合に [Trainer](/docs/transformers/main/ja/main_classes/trainer#transformers.Trainer) のメソッドをオーバーライドする方法について説明しています。