Callbacks#
O framework Ultralytics oferece suporte a callbacks, que servem como pontos de entrada em etapas estratégicas durante os modos train, val, export e predict. Cada callback aceita um objeto Trainer, Validator ou Predictor, dependendo do tipo de operação. Todas as propriedades desses objetos estão detalhadas nas páginas de referência BaseTrainer, BaseValidator e BasePredictor.
Assista: Como usar callbacks do Ultralytics | Callbacks de predição, treinamento, validação e exportação | Ultralytics YOLO26 🚀
Exemplos#
Retornar informações adicionais com a predição#
Neste exemplo, mostramos como retornar o frame original junto com cada objeto de resultado:
from ultralytics import YOLO
def on_predict_batch_end(predictor):
"""Combine prediction results with corresponding frames."""
_, image, _ = predictor.batch
# Garante que image seja uma lista
image = image if isinstance(image, list) else [image]
# Combina os resultados da predição com os frames correspondentes
predictor.results = zip(predictor.results, image)
# Cria uma instância do modelo YOLO
model = YOLO("yolo26n.pt")
# Adiciona o callback personalizado ao modelo
model.add_callback("on_predict_batch_end", on_predict_batch_end)
# Itera pelos resultados e frames
for result, frame in model.predict(): # ou model.track()
passRegistrar hooks de encaminhamento do PyTorch antes do treinamento#
model.train() cria um modelo de treinamento a partir da configuração do modelo e transfere para ele os pesos carregados. Os hooks do PyTorch registrados diretamente em model.model antes dessa chamada são estado de execução, portanto, o modelo de treinamento recriado não os herda. Registra os hooks de treinamento em on_pretrain_routine_end, depois que a configuração do modelo estiver concluída:
from ultralytics import YOLO
from ultralytics.utils.torch_utils import unwrap_model
def preprocess_input(module, inputs):
"""Center each input channel before the first model layer."""
images = inputs[0]
return (images - images.mean(dim=(-2, -1), keepdim=True),)
def register_forward_pre_hook(trainer):
"""Attach preprocessing to the active training model."""
train_model = unwrap_model(trainer.model)
train_model.model[0].register_forward_pre_hook(preprocess_input)
model = YOLO("yolo26n.pt")
model.add_callback("on_pretrain_routine_end", register_forward_pre_hook)
model.train(data="coco8.yaml", epochs=1)unwrap_model() lida tanto com o treinamento em um único dispositivo quanto com o treinamento DistributedDataParallel. Não vincules um hook definido localmente a trainer.ema.ema, pois os checkpoints de treinamento serializam o modelo EMA e outro processo talvez não consiga importar o callback ao carregar o checkpoint. Se o mesmo pré-processamento precisar ser executado durante a validação do treinamento, implementa-o como um componente de modelo importável, em vez de um hook de execução. A recuperação de NaN recria o EMA a partir do modelo de treinamento; assim, um hook registrado dessa forma é copiado para o EMA e para os checkpoints salvos após uma recuperação. Define a função do hook em um módulo importável se os checkpoints precisarem ser carregados em outro processo.
O model.val() independente copia o modelo carregado a cada chamada. A predição cria e armazena em cache uma cópia na primeira chamada; por isso, regista os hooks em model.model antes da primeira chamada a model.predict() ou model.track(). Os hooks adicionados depois disso não chegam ao preditor em cache. Regista novamente os hooks de execução após carregar um checkpoint em um novo processo.
Acessar as métricas do modelo usando o callback on_model_save#
Este exemplo mostra como recuperar detalhes do treinamento, como a pontuação best_fitness, total_loss e outras métricas, após salvar um checkpoint usando o callback on_model_save.
from ultralytics import YOLO
# Load a YOLO model
model = YOLO("yolo26n.pt")
def print_checkpoint_metrics(trainer):
"""Print trainer metrics and loss details after each checkpoint is saved."""
print(
f"Model details\n"
f"Best fitness: {trainer.best_fitness}, "
f"Loss names: {trainer.loss_names}, " # List of loss names
f"Metrics: {trainer.metrics}, "
f"Total loss: {trainer.tloss}" # Total loss value
)
if __name__ == "__main__":
# Add on_model_save callback.
model.add_callback("on_model_save", print_checkpoint_metrics)
# Run model training on custom dataset.
results = model.train(data="coco8.yaml", epochs=3)Todos os callbacks#
Abaixo estão todos os callbacks compatíveis. Para saber mais, consulta o código-fonte dos callbacks.
Callbacks do treinador#
| Callback | Descrição |
|---|---|
on_pretrain_routine_start | Acionado no início da rotina de pré-treinamento, antes do carregamento dos dados e da configuração do modelo. |
on_pretrain_routine_end | Acionado no fim da rotina de pré-treinamento, depois que o carregamento dos dados e a configuração do modelo forem concluídos. |
on_train_start | Acionado quando o treinamento começa, antes do início da primeira época. |
on_train_epoch_start | Acionado no início de cada época de treinamento, antes do início da iteração dos lotes. |
on_train_batch_start | Acionado no início de cada lote de treinamento, antes da passagem direta. |
optimizer_step | Acionado durante a etapa do otimizador. Reservado para integrações personalizadas; não é chamado pelo loop de treinamento padrão. |
on_before_zero_grad | Acionado antes de zerar os gradientes. Reservado para integrações personalizadas; não é chamado pelo loop de treinamento padrão. |
on_train_batch_end | Acionado no fim de cada lote de treinamento, após a passagem reversa. A etapa do otimizador pode ser adiada devido ao acúmulo de gradientes. |
on_train_epoch_end | Acionado no fim de cada época de treinamento, após o processamento de todos os lotes, mas antes da validação. Talvez as métricas de validação e o fitness ainda não estejam disponíveis. |
on_model_save | Acionado quando o checkpoint do modelo é salvo, após a validação. |
on_fit_epoch_end | Acionado no fim de cada época de ajuste (treinamento + validação), após a validação e qualquer salvamento de checkpoint. As métricas de validação estão disponíveis, e o fitness está disponível para a chamada de treinamento por época. Esse callback também é chamado durante a avaliação final do melhor modelo, quando nenhum checkpoint é salvo e o fitness talvez não esteja disponível. |
on_train_end | Acionado quando o processo de treinamento termina, após a avaliação final do melhor modelo. |
on_params_update | Acionado quando os parâmetros do modelo são atualizados. Reservado para integrações personalizadas; não é chamado pelo loop de treinamento padrão. |
teardown | Acionado durante a limpeza do processo de treinamento. |
Callbacks do validador#
| Callback | Descrição |
|---|---|
on_val_start | Acionado quando a validação começa. |
on_val_batch_start | Acionado no início de cada lote de validação. |
on_val_batch_end | Acionado no fim de cada lote de validação. |
on_val_end | Acionado quando a validação termina. |
Callbacks do preditor#
| Callback | Descrição |
|---|---|
on_predict_start | Acionado quando o processo de predição começa. |
on_predict_batch_start | Acionado no início de cada lote de predição. |
on_predict_postprocess_end | Acionado no fim do pós-processamento da predição. |
on_predict_batch_end | Acionado no fim de cada lote de predição. |
on_predict_end | Acionado quando o processo de predição termina. |
Callbacks do exportador#
| Callback | Descrição |
|---|---|
on_export_start | Acionado quando o processo de exportação começa. |
on_export_end | Acionado quando o processo de exportação termina. |
Perguntas frequentes#
Os callbacks do Ultralytics são pontos de entrada especializados, acionados durante etapas importantes das operações do modelo, como treinamento, validação, exportação e predição. Esses callbacks permitem adicionar funcionalidades personalizadas em pontos específicos do processo, possibilitando melhorias e modificações no fluxo de trabalho. Cada callback aceita um objeto
Trainer,ValidatorouPredictor, dependendo do tipo de operação. Para ver as propriedades detalhadas desses objetos, consulta as páginas de referênciaBaseTrainer,BaseValidatoreBasePredictor.Para usar um callback, define uma função e adiciona-a ao modelo usando o método
model.add_callback(). Veja um exemplo de como retornar informações adicionais durante a predição:from ultralytics import YOLO def on_predict_batch_end(predictor): """Handle prediction batch end by combining results with corresponding frames; modifies predictor results.""" _, image, _ = predictor.batch image = image if isinstance(image, list) else [image] predictor.results = zip(predictor.results, image) model = YOLO("yolo26n.pt") model.add_callback("on_predict_batch_end", on_predict_batch_end) for result, frame in model.predict(): passPersonaliza a rotina de treinamento do Ultralytics inserindo lógica em etapas específicas do processo de treinamento. O Ultralytics YOLO oferece vários callbacks de treinamento, como
on_train_start,on_train_endeon_train_batch_end, que permitem adicionar métricas, processamento ou registro em log personalizados.Veja como registrar a taxa de aprendizado de cada grupo de parâmetros do otimizador no fim de cada época de treinamento:
from ultralytics import YOLO def log_learning_rates(trainer): """Print the current learning rates after each training epoch.""" print(f"Epoch {trainer.epoch + 1}: {trainer.lr}") model = YOLO("yolo26n.pt") model.add_callback("on_train_epoch_end", log_learning_rates) model.train(data="coco8.yaml", epochs=3)DicaNão precisas de um callback para congelar as estatísticas de BatchNorm ao usar
freeze: o treinador coloca automaticamente as camadas BatchNorm das camadas congeladas no modo de avaliação no início de cada época.Para saber mais sobre como usar callbacks de treinamento de forma eficaz, consulta o Guia de treinamento.
O uso de callbacks durante a validação no Ultralytics YOLO melhora a avaliação do modelo, permitindo processamento personalizado, registro em log ou cálculo de métricas. Callbacks como
on_val_start,on_val_batch_endeon_val_endoferecem pontos de entrada para inserir lógica personalizada e garantir processos de validação detalhados e abrangentes.Por exemplo, para gerar gráficos de todos os lotes de validação, em vez de apenas dos três primeiros:
import inspect from ultralytics import YOLO def plot_samples(validator): frame = inspect.currentframe().f_back.f_back v = frame.f_locals validator.plot_val_samples(v["batch"], v["batch_i"]) validator.plot_predictions(v["batch"], v["preds"], v["batch_i"]) model = YOLO("yolo26n.pt") model.add_callback("on_val_batch_end", plot_samples) model.val(data="coco.yaml")Para saber mais sobre como incorporar callbacks ao processo de validação, consulta o Guia de validação.
Para vincular um callback personalizado ao modo de predição no Ultralytics YOLO, define uma função de callback e regista-a no processo de predição. Entre os callbacks de predição comuns estão
on_predict_start,on_predict_batch_endeon_predict_end. Eles permitem modificar as saídas da predição e integrar funcionalidades adicionais, como registro de dados ou transformação de resultados.Veja um exemplo em que um callback personalizado salva predições com base na presença de um objeto de uma determinada classe:
from ultralytics import YOLO model = YOLO("yolo26n.pt") class_id = 2 def save_on_object(predictor): r = predictor.results[0] if class_id in r.boxes.cls: predictor.args.save = True else: predictor.args.save = False model.add_callback("on_predict_postprocess_end", save_on_object) results_stream = model("pedestrians.mp4", stream=True, save=True) for result in results_stream: passPara ver exemplos de uso mais abrangentes, consulta o Guia de predição, que inclui instruções detalhadas e opções adicionais de personalização.
O Ultralytics YOLO oferece suporte a várias implementações práticas de callbacks para aprimorar e personalizar diferentes etapas, como treinamento, validação e predição. Alguns exemplos práticos:
- Registro de métricas personalizadas: Registra métricas adicionais em diferentes etapas, como no fim das épocas de treinamento ou validação.
- Aumento de dados: Implementa transformações ou aumentos de dados personalizados durante a predição ou os lotes de treinamento.
- Resultados intermediários: Salva resultados intermediários, como predições ou frames, para análise ou visualização posterior.
Exemplo: combinar frames com resultados de predição durante a predição usando
on_predict_batch_end:from ultralytics import YOLO def on_predict_batch_end(predictor): """Combine prediction results with frames.""" _, image, _ = predictor.batch image = image if isinstance(image, list) else [image] predictor.results = zip(predictor.results, image) model = YOLO("yolo26n.pt") model.add_callback("on_predict_batch_end", on_predict_batch_end) for result, frame in model.predict(): passExplora o código-fonte dos callbacks para ver mais opções e exemplos.