# 콜백

[TrainerCallback](/docs/transformers/v5.23.0/ko/main_classes/callback#transformers.TrainerCallback)은 epoch 시작, 평가, 학습 종료와 같은 특정 학습 이벤트에 연결되어 학습 상태나 제어 흐름을 수정합니다. Trackio와 같은 실험 트래커에 메트릭을 기록하거나, 저장 및 평가가 수행되는 시점을 사용자 정의하거나, 기타 사용자 정의 동작을 추가하는 데 콜백을 사용하세요. 여러 콜백을 스택하여 기능을 조합할 수 있습니다.

Callbacks는 forward pass와 같이 학습 루프 자체를 수정할 수 없습니다. [Trainer](/docs/transformers/v5.23.0/ko/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/v5.23.0/ko/main_classes/callback#transformers.TrainerCallback)를 서브클래스로 상속하고, 위 다이어그램의 이벤트 메서드 중 하나 이상을 오버라이드합니다. 아래 예시는 세 가지 훅을 보여줍니다:

- `on_epoch_begin`은 [TrainerState](/docs/transformers/v5.23.0/ko/main_classes/callback#transformers.TrainerState)(실시간 값)에서 현재 epoch를, [TrainingArguments](/docs/transformers/v5.23.0/ko/main_classes/trainer#transformers.TrainingArguments)(정적 값)에서 학습률을 출력합니다.
- `on_step_end`는 lr_scheduler(`**kwargs`를 통해 전달됨)에서 현재 학습률을 읽어 [TrainerControl](/docs/transformers/v5.23.0/ko/main_classes/callback#transformers.TrainerControl)의 `should_evaluate`를 설정하여 임계값 이하로 떨어질 때 평가를 트리거합니다([TrainerControl](/docs/transformers/v5.23.0/ko/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/v5.23.0/ko/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/v5.23.0/ko/main_classes/callback#transformers.DefaultFlowCallback)은 [TrainingArguments](/docs/transformers/v5.23.0/ko/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/v5.23.0/ko/main_classes/trainer#transformers.Trainer)는 [TrainingArguments](/docs/transformers/v5.23.0/ko/main_classes/trainer#transformers.TrainingArguments)의 [disable_tqdm](/docs/transformers/v5.23.0/ko/main_classes/trainer#transformers.TrainingArguments.disable_tqdm) 필드를 기준으로 이 두 callback 중 하나를 자동으로 선택합니다.

- [ProgressCallback](/docs/transformers/v5.23.0/ko/main_classes/callback#transformers.ProgressCallback)은 기본적으로 사용됩니다. 학습 중에는 tqdm 진행 표시줄을 표시하고, 평가 또는 예측 중에는 별도의 표시줄을 표시하며, 각 `on_log` 이벤트마다 최신 메트릭을 출력합니다. 분산 학습 중에는 중복 출력을 방지하기 위해 메인 프로세스에서만 실행됩니다.
- `disable_tqdm=True`일 때 [PrinterCallback](/docs/transformers/v5.23.0/ko/main_classes/callback#transformers.PrinterCallback)이 사용됩니다. 진행 표시줄 없이 모든 `on_log` 이벤트마다 로그 사전(stdout)을 출력합니다.

[remove_callback()](/docs/transformers/v5.23.0/ko/main_classes/trainer#transformers.Trainer.remove_callback)와 [add_callback()](/docs/transformers/v5.23.0/ko/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/v5.23.0/ko/main_classes/callback#transformers.EarlyStoppingCallback)은 평가 지표가 더 이상 개선되지 않을 때 학습을 중단합니다. 각 평가 후, 해당 지표가 `early_stopping_threshold`보다 더 개선되었는지 확인합니다. 지표가 `early_stopping_patience`회 연속 평가에서 개선되지 않으면 학습이 중단됩니다.

[EarlyStoppingCallback](/docs/transformers/v5.23.0/ko/main_classes/callback#transformers.EarlyStoppingCallback)에는 두 개의 [TrainingArguments](/docs/transformers/v5.23.0/ko/main_classes/trainer#transformers.TrainingArguments)가 필요합니다:

- `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/v5.23.0/ko/main_classes/trainer#transformers.Trainer) 메서드를 오버라이드하는 방법을 다룹니다.

