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 nas páginas de referência BaseTrainer, BaseValidator e BasePredictor.
Watch: How to use Ultralytics Callbacks | Predict, Train, Validate and Export Callbacks | Ultralytics YOLO🚀
Exemplos#
Retornando informações adicionais com a previsã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()
passRegisto de Hooks de Encaminhamento do PyTorch Antes do Treino#
model.train() constroi um modelo de treino a partir da configuracao do modelo e transfere os pesos carregados para ele. Os hooks do PyTorch registados diretamente em model.model antes desta chamada sao o estado de tempo de execucao, pelo que o modelo de treino reconstruido nao os herda. Regista os hooks de treino em on_pretrain_routine_end, apos a configuracao do modelo estar concluida:
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 com o treino de dispositivo unico e DistributedDataParallel. Nao enlaces um hook definido localmente a trainer.ema.ema, porque os pontos de controlo do treino serializam o modelo EMA e outro processo pode nao conseguir importar a retorno de chamada ao carregar o ponto de controlo. Se a mesma pre-processamento tiver de ser executada durante a validacao do treino, implementa-a como um componente de modelo importavel em vez de um hook de tempo de execucao.
O model.val() autonomo copia o modelo carregado para cada chamada. A previsao cria e armazena em cache uma copia na sua primeira chamada, por isso regista os hooks em model.model antes da primeira chamada de model.predict() ou model.track(); os hooks adicionados posteriormente nao alcancam o preditor em cache. Regista novamente os hooks de tempo de execucao apos carregar um ponto de controlo num novo processo.
Acesse as métricas do modelo usando o callback on_model_save#
Este exemplo mostra como recuperar detalhes de treinamento, como a pontuação best_fitness, total_loss e outras métricas após um ponto de verificação ser salvo 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, consulte o código-fonte dos callbacks.
Callbacks de 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 o carregamento de dados e a configuração do modelo estarem completos. |
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 de lotes. |
on_train_batch_start | Acionado no início de cada lote de treinamento, antes da passagem para a frente. |
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 os gradientes serem 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 para trás. A etapa do otimizador pode ser adiada 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 ponto de verificação 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 ponto de verificação. 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 nenhum salvamento de ponto de verificação ocorre 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 limpo. |
Callbacks de 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 de preditor#
| Callback | Descrição |
|---|---|
on_predict_start | Acionado quando o processo de previsão começa. |
on_predict_batch_start | Acionado no início de cada lote de previsão. |
on_predict_postprocess_end | Acionado no final do pós-processamento de previsão. |
on_predict_batch_end | Acionado no final de cada lote de previsão. |
on_predict_end | Acionado quando o processo de previsão termina. |
Callbacks de 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 da Ultralytics são pontos de entrada especializados que são disparados durante estágios-chave de operações de modelos, como treinamento, validação, exportação e predição. Esses callbacks habilitam funcionalidade personalizada em pontos específicos do processo, permitindo melhorias e modificações no fluxo de trabalho. Cada callback aceita um objeto
Trainer,ValidatorouPredictor, dependendo do tipo de operação. Para propriedades detalhadas desses objetos, consulte as páginas de referênciaBaseTrainer,BaseValidatoreBasePredictor.Para usar um callback, defina uma função e adicione-a ao modelo usando o método
model.add_callback(). Aqui está um exemplo de retorno de informações adicionais durante a previsã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(): passPersonalize a tua rotina de treinamento do Ultralytics injetando lógica em estágios específicos do processo de treinamento. O YOLO do Ultralytics fornece uma variedade de callbacks de treinamento, como
on_train_start,on_train_endeon_train_batch_end, que permitem adicionar métricas personalizadas, processamento ou registro.Eis como congelar as estatísticas do 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 treinamento, consulte o Guia de Treinamento.
O uso de callbacks durante a validação no YOLO do Ultralytics melhora a avaliação do modelo ao habilitar o processamento personalizado, registro 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 insights sobre como incorporar callbacks no teu processo de validação, consulte o Guia de Validação.
Para anexar um callback personalizado para o modo de previsão no YOLO do Ultralytics, defina uma função de callback e registre-a no processo de previsão. Callbacks de previsão comuns incluem
on_predict_start,on_predict_batch_endeon_predict_end. Eles permitem a modificação de saídas de previsão e a integração de funcionalidades adicionais, como registro de dados ou transformação de resultados.Aqui está um exemplo em que um callback personalizado salva previsões com base na presença 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, consulte o Guia de Previsão, que inclui instruções detalhadas e opções adicionais de personalização.
O YOLO do Ultralytics suporta várias implementações práticas de callbacks para aprimorar e personalizar diferentes fases, como treinamento, validação e previsão. Alguns exemplos práticos incluem:
- Registrando Métricas Personalizadas: Registre métricas adicionais em diferentes estágios, como no final de épocas de treinamento ou validação.
- Aumento de Dados: Implemente transformações ou aumentos de dados personalizados durante lotes de previsão ou treinamento.
- Resultados Intermediários: Salve resultados intermediários, como previsões ou quadros, para análises ou visualizações posteriores.
Exemplo: Combinando quadros com resultados de previsão durante a previsã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(): passExplore o código-fonte dos callbacks para mais opções e exemplos.