Callbacks#
O framework Ultralytics suporta callbacks, que servem como pontos de entrada em estágios estratégicos 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 na seção de Referência da documentação.
Watch: How to use Ultralytics Callbacks | Predict, Train, Validate and Export Callbacks | Ultralytics YOLO🚀
Exemplos#
Retornando informações adicionais com a predição#
Neste exemplo, demonstramos como retornar o quadro 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
# Ensure that image is a list
image = image if isinstance(image, list) else [image]
# Combine the prediction results with the corresponding frames
predictor.results = zip(predictor.results, image)
# Create a YOLO model instance
model = YOLO("yolo26n.pt")
# Add the custom callback to the model
model.add_callback("on_predict_batch_end", on_predict_batch_end)
# Iterate through the results and frames
for result, frame in model.predict(): # or model.track()
passAceda às métricas do Model utilizando o callback on_model_save#
Este exemplo mostra como recuperar detalhes de treino, como a pontuação best_fitness, total_loss e outras métricas após um ponto de controle ser guardado 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 suportados. Para mais detalhes, 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 de dados e da configuração do modelo. |
on_pretrain_routine_end | Acionado no final da rotina de pré-treinamento, após a conclusão do carregamento de dados e da configuração do modelo. |
on_train_start | Acionado quando o treino começa, antes do início da primeira época. |
on_train_epoch_start | Acionado no início de cada época de treino, antes de a iteração de lote começar. |
on_train_batch_start | Acionado no início de cada lote de treinamento, antes da passagem direta (forward pass). |
optimizer_step | Acionado durante o passo do otimizador. Reservado para integrações personalizadas; não chamado pelo loop de treinamento padrão. |
on_before_zero_grad | Acionado antes que os gradientes sejam zerados. Reservado para integrações personalizadas; não chamado pelo loop de treinamento padrão. |
on_train_batch_end | Acionado no final de cada lote de treinamento, após a passagem reversa (backward pass). O passo do otimizador pode ser adiado devido ao acúmulo de gradiente. |
on_train_epoch_end | Acionado no final de cada época de treinamento, após todos os lotes serem processados, mas antes da validação. As métricas de validação e a aptidão podem ainda não estar disponíveis. |
on_model_save | Acionado quando o checkpoint do modelo é salvo, após a validação. |
on_fit_epoch_end | Acionado no final de cada época de ajuste (treino + val), após a validação e qualquer salvamento de checkpoint. As métricas de validação estão disponíveis e a aptidão está disponível para a chamada de treinamento por época. Este callback também é chamado durante a avaliação final do melhor modelo, onde não ocorre salvamento de checkpoint e a aptidão pode não estar presente. |
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 quando o processo de treinamento está sendo encerrado. |
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 final 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 final do pós-processamento de predição. |
on_predict_batch_end | Acionado no final 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. |
FAQ#
Os callbacks do Ultralytics são pontos de entrada especializados que são acionados durante estágios-chave de operações do modelo, tais como treino, validação, exportação e predição. Estes callbacks permitem funcionalidade personalizada 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 propriedades detalhadas destes objetos, consulta a seção de Referência.Para usar um callback, define uma função e adiciona-a ao modelo usando o método
model.add_callback(). Aqui está um exemplo de retorno de informação adicional 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 tua rotina de treino do Ultralytics injetando lógica em estágios específicos do processo de treino. O Ultralytics YOLO fornece uma variedade de callbacks de treino, tais como
on_train_start,on_train_endeon_train_batch_end, que te permitem adicionar métricas personalizadas, processamento ou registo.Veja como congelar estatísticas de BatchNorm ao congelar camadas com callbacks:
from ultralytics import YOLO # Add a callback to put the frozen layers in eval mode to prevent BN values from changing def put_in_eval_mode(trainer): n_layers = trainer.args.freeze if not isinstance(n_layers, int): return for i, (name, module) in enumerate(trainer.model.named_modules()): if name.endswith("bn") and int(name.split(".")[1]) < n_layers: module.eval() module.track_running_stats = False model = YOLO("yolo26n.pt") model.add_callback("on_train_epoch_start", put_in_eval_mode) model.train(data="coco.yaml", epochs=10)Para mais detalhes sobre como usar eficazmente os callbacks de treino, consulta o Guia de Treino.
Usar callbacks durante a validação no Ultralytics YOLO melhora a avaliação do modelo ao permitir processamento personalizado, registo ou cálculo de métricas. Callbacks como
on_val_start,on_val_batch_endeon_val_endfornecem pontos de entrada para injetar lógica personalizada, garantindo processos de validação detalhados e abrangentes.Por exemplo, para plotar todos os lotes de validação em vez de apenas os 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 mais conhecimentos sobre a incorporação de callbacks no teu processo de validação, consulta o Guia de Validação.
Para anexar um callback personalizado para o modo de predição no Ultralytics YOLO, define uma função de callback e regista-a com o processo de predição. Os callbacks de predição comuns incluem
on_predict_start,on_predict_batch_endeon_predict_end. Estes permitem a modificação de saídas de predição e a integração de funcionalidades adicionais, como registo de dados ou transformação de resultados.Aqui está um exemplo onde um callback personalizado salva predições com base na presença ou não de um objeto de uma classe específica:
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 um uso mais abrangente, consulta o Guia de Predição, que inclui instruções detalhadas e opções de personalização adicionais.
O YOLO da Ultralytics suporta várias implementações práticas de callbacks para aprimorar e personalizar diferentes fases, como treinamento, validação e predição. Alguns exemplos práticos incluem:
- Registo de Métricas Personalizadas: Regista métricas adicionais em diferentes estágios, como no final das épocas de treino ou validação.
- Aumento de Dados: Implementa transformações de dados personalizadas ou aumentos durante a predição ou lotes de treino.
- Resultados intermediários: Salve resultados intermediários, como predições ou quadros, para análise ou visualização posterior.
Exemplo: Combinar quadros 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 de callbacks para mais opções e exemplos.