# Callbacks

[TrainerCallback](/docs/transformers/v5.23.0/fr/main_classes/callback#transformers.TrainerCallback) s’interfère avec des événements d’entraînement spécifiques (début d’époque, évaluation, fin d’entraînement) afin de modifier l’état de l’entraînement ou le flux de contrôle. Utilisez des callbacks pour journaliser des métriques vers des traceurs d’expériences comme Trackio, personnaliser le moment où les sauvegardes et les évaluations ont lieu, ou ajouter d’autres comportements personnalisés. Empilez plusieurs callbacks pour combiner les fonctionnalités.

Les callbacks ne peuvent pas modifier la boucle d’entraînement elle-même, comme le passage avant. Pour changer ce que [Trainer](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.Trainer) calcule, il faut plutôt [sous-classe](./trainer_customize) ses méthodes.

Le diagramme ci-dessous montre tous les événements auxquels un rappel peut s'attacher.

```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
```

## Créer un rappel

Sous-classez [TrainerCallback](/docs/transformers/v5.23.0/fr/main_classes/callback#transformers.TrainerCallback) et écrasez une ou plusieurs méthodes d'événement de la figure ci-dessus. L'exemple ci-dessous illustre trois hooks :

- `on_epoch_begin` affiche l'époque en cours depuis [TrainerState](/docs/transformers/v5.23.0/fr/main_classes/callback#transformers.TrainerState) (une valeur dynamique) et le taux d'apprentissage depuis [TrainingArguments](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.TrainingArguments) (une valeur statique).
- `on_step_end` lit le taux d’apprentissage actuel depuis lr_scheduler (transmis via `**kwargs`) et définit `should_evaluate` sur [TrainerControl](/docs/transformers/v5.23.0/fr/main_classes/callback#transformers.TrainerControl) (voir [TrainerControl](/docs/transformers/v5.23.0/fr/main_classes/callback#transformers.TrainerControl) pour la liste complète des objets de contrôle) afin de déclencher une évaluation lorsqu’il passe sous le seuil.
- `on_train_end` affiche la meilleure métrique et l'étape à laquelle elle a été atteinte.

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

Enregistrez le rappel avec [Trainer](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.Trainer) dans l’argument `callbacks`. Vous pouvez également passer plusieurs rappels sous forme de liste.

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

## Callbacks intégrés

Transformers intègre plusieurs callbacks intégrés qui sont actifs par défaut. Des [callbacks intégrés supplémentaires](./main_classes/callback) permettent d'effectuer un suivi sur des plateformes telles que [Trackio](https://huggingface.co/docs/trackio/en/index).

### DefaultFlowCallback

[DefaultFlowCallback](/docs/transformers/v5.23.0/fr/main_classes/callback#transformers.DefaultFlowCallback) gère l’horaire par défaut de la journalisation, de l’évaluation et de la sauvegarde des points de contrôle, en fonction des valeurs de `logging_strategy`, `eval_strategy` et `save_strategy` dans [TrainingArguments](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.TrainingArguments). À l’étape ou à l’époque appropriée, il définit les drapeaux `control` correspondants (`should_log`, `should_evaluate`, `should_save`). Il définit également `should_training_stop` lorsque `global_step` atteint `max_steps`.

L’écriture en surcharge de ce rappel est le principal moyen de personnaliser *le moment* où la journalisation, l’évaluation ou l’enregistrement sont effectués.

### ProgressCallback et PrinterCallback

[Trainer](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.Trainer) choisit automatiquement entre ces deux callbacks en fonction du champ [disable_tqdm](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.TrainingArguments.disable_tqdm) dans [TrainingArguments](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.TrainingArguments).

- [ProgressCallback](/docs/transformers/v5.23.0/fr/main_classes/callback#transformers.ProgressCallback) est utilisé par défaut. Il affiche une barre de progression tqdm pendant l’entraînement et une barre distincte pendant l’évaluation ou la prédiction, et imprime les dernières métriques à chaque événement `on_log`. Lors d’un entraînement distribué, il ne s’exécute que sur le processus principal afin d’éviter les sorties dupliquées.
- [PrinterCallback](/docs/transformers/v5.23.0/fr/main_classes/callback#transformers.PrinterCallback) est utilisé lorsque `disable_tqdm=True`. Il affiche le dictionnaire de journalisation sur la sortie standard à chaque événement `on_log`, sans barre de progression.

Vous pouvez également les remplacer manuellement à l'aide de [remove_callback()](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.Trainer.remove_callback) et [add_callback()](/docs/transformers/v5.23.0/fr/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/fr/main_classes/callback#transformers.EarlyStoppingCallback) arrête l'entraînement lorsqu'une métrique d'évaluation cesse de s'améliorer. Après chaque évaluation, il vérifie si la métrique s'est améliorée de plus de `early_stopping_threshold`. Si la métrique ne s'est pas améliorée pendant `early_stopping_patience` évaluations consécutives, l'entraînement est arrêté.

[EarlyStoppingCallback](/docs/transformers/v5.23.0/fr/main_classes/callback#transformers.EarlyStoppingCallback) nécessite deux [TrainingArguments](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.TrainingArguments) :

- `metric_for_best_model`, la métrique d'évaluation à surveiller
- `eval_strategy`, si l'évaluation doit être effectuée à chaque `"steps"` ou à chaque `"epoch"`

```py
from transformers import EarlyStoppingCallback

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

## Étapes suivantes

- Voir tous les [callbacks intégrés](./main_classes/callback) disponibles pour la journalisation vers les traceurs d'expériences.
- Le guide [Sous-classement des méthodes de Trainer](./trainer_customize) explique comment surcharger les méthodes de [Trainer](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.Trainer) lorsque vous devez modifier les calculs effectués par la boucle d’entraînement.

