Callbacks
A estrutura do 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 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
# 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()
passAcesse 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 um checkpoint 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 do Trainer
| 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 treinamento começa, antes do início da primeira epoch. |
on_train_epoch_start | Acionado no início de cada epoch de treinamento, antes do início da iteração do batch. |
on_train_batch_start | Acionado no início de cada batch de treinamento, antes do 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 batch de treinamento, após o backward pass. O passo do otimizador pode ser adiado devido à acumulação de gradientes. |
on_train_epoch_end | Acionado no final de cada epoch de treinamento, após todos os batches 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 epoch 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 epoch. Este callback também é chamado durante a avaliação final do melhor modelo, onde nenhum salvamento de checkpoint 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 finalizado. |
Callbacks do Validator
| Callback | Descrição |
|---|---|
on_val_start | Acionado quando a validação começa. |
on_val_batch_start | Acionado no início de cada batch de validação. |
on_val_batch_end | Acionado no final de cada batch de validação. |
on_val_end | Acionado quando a validação termina. |
Callbacks do Predictor
| 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 batch de predição. |
on_predict_postprocess_end | Acionado no final do pós-processamento da predição. |
on_predict_batch_end | Acionado no final de cada batch de predição. |
on_predict_end | Acionado quando o processo de predição termina. |
Callbacks do Exporter
| 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
O que são callbacks do Ultralytics e como posso usá-los?
Callbacks do Ultralytics são pontos de entrada especializados que são acionados durante estágios importantes de operações do modelo, como treinamento, validação, exportação e predição. Esses callbacks permitem funcionalidades personalizadas em pontos específicos do processo, possibilitando melhorias e modificações no fluxo de trabalho. Cada callback aceita um objeto Trainer, Validator ou Predictor, dependendo do tipo de operação. Para propriedades detalhadas desses objetos, consulte a Seção de referência.
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 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():
passComo posso personalizar a rotina de treinamento do Ultralytics usando callbacks?
Personalize sua rotina de treinamento no Ultralytics injetando lógica em estágios específicos do processo de treinamento. O Ultralytics YOLO fornece uma variedade de callbacks de treinamento, como on_train_start, on_train_end e on_train_batch_end, que permitem adicionar métricas, processamento ou registro personalizados.
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 o uso eficaz de callbacks de treinamento, veja o Guia de Treinamento.
Por que devo usar callbacks durante a validação no Ultralytics YOLO?
Usar callbacks durante a validação no Ultralytics YOLO melhora a avaliação do modelo, permitindo processamento personalizado, registro ou cálculo de métricas. Callbacks como on_val_start, on_val_batch_end e on_val_end fornecem pontos de entrada para injetar lógica personalizada, garantindo processos de validação detalhados e abrangentes.
Por exemplo, para plotar todos os batches 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 ao seu processo de validação, veja o Guia de Validação.
Como anexo um callback personalizado para o modo de predição no Ultralytics YOLO?
Para anexar um callback personalizado para o modo de predição no Ultralytics YOLO, defina uma função de callback e registre-a no processo de predição. Callbacks de predição comuns incluem on_predict_start, on_predict_batch_end e on_predict_end. Eles permitem a modificação das saídas de predição e a integração de funcionalidades adicionais, como registro de dados ou transformação de resultados.
Aqui está um exemplo onde um callback personalizado salva as prediçõ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 = model("pedestrians.mp4", stream=True, save=True)
for results in results:
passPara um uso mais abrangente, consulte o Guia de Predição, que inclui instruções detalhadas e opções de personalização adicionais.
Quais são alguns exemplos práticos de uso de callbacks no Ultralytics YOLO?
O Ultralytics YOLO suporta várias implementações práticas de callbacks para melhorar e personalizar diferentes fases, como treinamento, validação e predição. Alguns exemplos práticos incluem:
- Registro de Métricas Personalizadas: Registre métricas adicionais em diferentes estágios, como ao final de epochs de treinamento ou validação.
- Data Augmentation: Implemente transformações ou aumentos de dados personalizados durante batches de predição ou treinamento.
- Resultados Intermediários: Salve resultados intermediários, como predições ou frames, para análise posterior ou visualização.
Exemplo: Combinando 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():
passExplore o código-fonte dos callbacks para mais opções e exemplos.