Callbacks
A estrutura Ultralytics suporta callbacks, que servem como pontos de entrada em estágios estratégicos durante o train, val, export, e predict modos. Cada callback aceita um Trainer, Validator, ou Predictor objeto, dependendo do tipo de operação. Todas as propriedades desses objetos são detalhadas no Seção de Referência da documentação.
Assista: Como usar Callbacks Ultralytics | Callbacks de Previsão, Treino, Validação e Exportação | Ultralytics YOLO 🚀
Exemplos
Retornando Informações Adicionais com a Predição
Neste exemplo, demonstramos como retornar o frame original juntamente 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("yolo11n.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()
pass
Aceda às métricas do modelo usando o on_model_save callback
Este exemplo mostra como recuperar detalhes de treinamento, como a melhor pontuação de fitness, a perda total e outras métricas depois que um checkpoint é salvo usando o on_model_save callback.
from ultralytics import YOLO
# Load a YOLO model
model = YOLO("yolo11n.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é-treino. |
on_pretrain_routine_end |
Acionado no final da rotina de pré-treino. |
on_train_start |
Disparado quando o treinamento começa. |
on_train_epoch_start |
Disparado no início de cada época de treinamento. |
on_train_batch_start |
Disparado no início de cada lote de treinamento. |
optimizer_step |
Disparado durante a etapa do otimizador. |
on_before_zero_grad |
Disparado antes que os gradientes sejam zerados. |
on_train_batch_end |
Acionado no final de cada lote de treino. |
on_train_epoch_end |
Acionado no final de cada época de treino. |
on_fit_epoch_end |
Acionado no final de cada época de ajuste. |
on_model_save |
Disparado quando o modelo é salvo. |
on_train_end |
Disparado quando o processo de treinamento termina. |
on_params_update |
Disparado quando os parâmetros do modelo são atualizados. |
teardown |
Disparado quando o processo de treinamento está sendo limpo. |
Callbacks do Validator
| Callback | Descrição |
|---|---|
on_val_start |
Disparado quando a validação começa. |
on_val_batch_start |
Disparado 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 |
Disparado quando a validação termina. |
Callbacks do Predictor
| Callback | Descrição |
|---|---|
on_predict_start |
Disparado 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 da previsão. |
on_predict_batch_end |
Acionado no final de cada lote de previsão. |
on_predict_end |
Disparado quando o processo de previsão termina. |
Callbacks do Exporter
| Callback | Descrição |
|---|---|
on_export_start |
Disparado quando o processo de exportação começa. |
on_export_end |
Disparado quando o processo de exportação termina. |
FAQ
O que são os callbacks Ultralytics e como posso usá-los?
Os callbacks da Ultralytics são pontos de entrada especializados que são acionados durante os estágios principais das operações do modelo, como treinamento, validação, exportação e previsão. Esses callbacks habilitam funcionalidades personalizadas em pontos específicos do processo, permitindo aprimoramentos e modificações no fluxo de trabalho. Cada callback aceita um Trainer, Validator, ou Predictor objeto, 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 model.add_callback() método. Aqui está um exemplo de como retornar 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("yolo11n.pt")
model.add_callback("on_predict_batch_end", on_predict_batch_end)
for result, frame in model.predict():
pass
Como posso personalizar a rotina de treinamento da Ultralytics usando callbacks?
Personalize sua rotina de treinamento 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 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("yolo11n.pt")
model.add_callback("on_train_epoch_start", put_in_eval_mode)
model.train(data="coco.yaml", epochs=10)
Para obter mais detalhes sobre como usar callbacks de treinamento de forma eficaz, consulte 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 aprimora 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 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("yolo11n.pt")
model.add_callback("on_val_batch_end", plot_samples)
model.val(data="coco.yaml")
Para obter mais informações sobre como incorporar callbacks ao seu processo de validação, consulte 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 previsão no Ultralytics YOLO, defina uma função de callback e registre-a no processo de previsão. Os callbacks de previsão comuns incluem on_predict_start, on_predict_batch_end, e on_predict_end. Estes 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 de um callback personalizado que salva as previsões com base na presença de um objeto de uma classe específica:
from ultralytics import YOLO
model = YOLO("yolo11n.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:
pass
Para 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?
Ultralytics YOLO 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:
- Registo de Métricas Personalizadas: Registe métricas adicionais em diferentes estágios, como no final do treino ou épocas de validação.
- Aumento de Dados: Implemente transformações ou aumentos de dados personalizados durante lotes de previsão ou treinamento.
- Resultados Intermediários: Guarde resultados intermediários, como previsões ou frames, para análise ou visualização posterior.
Exemplo: Combinando frames 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("yolo11n.pt")
model.add_callback("on_predict_batch_end", on_predict_batch_end)
for result, frame in model.predict():
pass
Explore o código fonte de callback para mais opções e exemplos.
