Callback

TrainerCallback melekat pada peristiwa pelatihan tertentu (awal epoch, evaluasi, akhir pelatihan) untuk mengubah status pelatihan atau alur kendali. Gunakan callback untuk mencatat metrik ke pelacak eksperimen seperti Trackio, menyesuaikan kapan penyimpanan dan evaluasi dilakukan, atau menambahkan perilaku kustom lainnya. Tumpuk beberapa callback untuk menggabungkan fitur.

Callback tidak dapat memodifikasi loop pelatihan itu sendiri, seperti forward pass. Untuk mengubah apa yang dihitung oleh Trainer, subclass metode-metodenya.

Diagram di bawah ini menunjukkan setiap event yang dapat di-hook oleh callback.

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

Membuat callback

Subclass TrainerCallback dan override satu atau beberapa metode event dari diagram di atas. Contoh di bawah ini mendemonstrasikan tiga hook:

• on_epoch_begin mencetak epoch saat ini dari TrainerState (nilai yang berubah-ubah) dan learning rate dari TrainingArguments (nilai statis).
• on_step_end membaca learning rate saat ini dari lr_scheduler (diteruskan melalui **kwargs) dan mengatur should_evaluate pada TrainerControl (lihat TrainerControl untuk daftar lengkap objek kontrol) untuk memicu evaluasi ketika nilainya turun di bawah ambang batas.
• on_train_end mencetak metrik terbaik dan langkah tempat metrik tersebut tercapai.

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}")

Daftarkan callback dengan Trainer pada argumen callbacks. Anda juga dapat meneruskan beberapa callback sebagai daftar.

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

Callback bawaan

Transformers mencakup beberapa callback bawaan yang aktif secara default. Callback terintegrasi tambahan mencatat ke platform seperti Trackio.

DefaultFlowCallback

DefaultFlowCallback mengelola jadwal logging, evaluasi, dan checkpoint default berdasarkan nilai logging_strategy, eval_strategy, dan save_strategy di TrainingArguments. Pada langkah atau epoch yang tepat, callback ini mengatur flag control yang sesuai (should_log, should_evaluate, should_save). Ia juga mengatur should_training_stop ketika global_step mencapai max_steps.

Menimpa callback ini adalah cara utama untuk menyesuaikan kapan pencatatan, evaluasi, atau penyimpanan dilakukan.

ProgressCallback dan PrinterCallback

Trainer secara otomatis memilih antara dua callback ini berdasarkan field disable_tqdm di TrainingArguments.

• ProgressCallback digunakan secara default. Callback ini menampilkan progress bar tqdm selama pelatihan dan bar terpisah selama evaluasi atau prediksi, serta mencetak metrik terbaru pada setiap event on_log. Selama pelatihan terdistribusi, callback ini hanya berjalan pada proses utama untuk menghindari output duplikat.
• PrinterCallback digunakan ketika disable_tqdm=True. Callback ini mencetak log dictionary ke stdout pada setiap event on_log tanpa progress bar.

Anda juga dapat menggantinya secara manual dengan remove_callback() dan add_callback().

from transformers import PrinterCallback

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

EarlyStoppingCallback

EarlyStoppingCallback menghentikan pelatihan ketika metrik evaluasi berhenti membaik. Setelah setiap evaluasi, callback ini memeriksa apakah metrik membaik lebih dari early_stopping_threshold. Jika metrik tidak membaik selama early_stopping_patience evaluasi berturut-turut, pelatihan dihentikan.

EarlyStoppingCallback membutuhkan dua TrainingArguments:

• metric_for_best_model, metrik evaluasi yang dipantau
• eval_strategy, apakah mengevaluasi pada "steps" atau "epoch"

from transformers import EarlyStoppingCallback

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

Langkah selanjutnya

• Lihat semua callback terintegrasi yang tersedia untuk pencatatan ke pelacak eksperimen.
• Panduan Subclassing Trainer methods membahas cara menimpa metode Trainer ketika Anda perlu mengubah apa yang dihitung oleh loop pelatihan.