Transformers documentation

콜백

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

콜백

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

Callback은 forward pass와 같이 학습 루프 자체를 수정할 수 없습니다. Trainer가 계산하는 내용을 변경하려면, 해당 메서드를 서브클래스로 구현해야 합니다.

아래 다이어그램은 콜백이 연결할 수 있는 모든 이벤트를 보여 줍니다.

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를 서브클래스로 상속하고, 위 다이어그램의 이벤트 메서드 중 하나 이상을 오버라이드합니다. 아래 예시는 세 가지 훅을 보여줍니다:

  • on_epoch_begin은 TrainerState(실시간 값)에서 현재 epoch를, TrainingArguments(정적 값)에서 학습률을 출력합니다.
  • on_step_end는 lr_scheduler(**kwargs를 통해 전달됨)에서 현재 학습률을 읽어 TrainerControl의 should_evaluate를 설정하여 임계값 이하로 떨어질 때 평가를 트리거합니다(TrainerControl에서 제어 객체의 전체 목록을 참조).
  • on_train_end는 최적의 지표와 해당 단계가 발생한 위치를 출력합니다.
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에 콜백을 등록합니다. 여러 콜백을 리스트로 전달할 수도 있습니다.

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

내장 콜백

Transformers에는 기본적으로 활성화되는 여러 내장 콜백이 포함되어 있습니다. 추가적인 통합 콜백은 Trackio와 같은 플랫폼에 로깅합니다.

DefaultFlowCallback

DefaultFlowCallback은 TrainingArguments의 logging_strategy, eval_strategy, save_strategy 값에 따라 기본 로깅, 평가, 체크포인트 일정을 관리합니다. 적절한 스텝 또는 에포크에 도달하면 해당 control 플래그(should_log, should_evaluate, should_save)를 설정합니다. 또한 global_step이 max_steps에 도달하면 should_training_stop도 설정합니다.

이 콜백을 오버라이드하는 것이 로깅, 평가 또는 저장이 언제 수행될지를 커스터마이즈하는 주요 방법입니다.

ProgressCallback과 PrinterCallback

Trainer는 TrainingArguments의 disable_tqdm 필드를 기준으로 이 두 callback 중 하나를 자동으로 선택합니다.

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

remove_callback()와 add_callback()를 사용하여 수동으로 교체할 수도 있습니다.

from transformers import PrinterCallback

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

EarlyStoppingCallback

EarlyStoppingCallback은 평가 지표가 더 이상 개선되지 않을 때 학습을 중단합니다. 각 평가 후, 해당 지표가 early_stopping_threshold보다 더 개선되었는지 확인합니다. 지표가 early_stopping_patience회 연속 평가에서 개선되지 않으면 학습이 중단됩니다.

EarlyStoppingCallback에는 두 개의 TrainingArguments가 필요합니다:

  • metric_for_best_model, 모니터링할 평가 지표
  • eval_strategy, "steps" 또는 "epoch" 기준으로 평가할지 여부
from transformers import EarlyStoppingCallback

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

다음 단계

  • 실험 트래커에 기록하기 위한 모든 사용 가능한 통합 콜백을 확인하세요.
  • Trainer 메서드 서브클래스화 가이드에서는 학습 루프가 계산하는 내용을 변경해야 할 때 Trainer 메서드를 오버라이드하는 방법을 다룹니다.
Update on GitHub