콜백#
Ultralytics 프레임워크는 콜백을 지원하며, 콜백은 train, val, export, predict 모드 중 전략적으로 중요한 단계에서 진입점 역할을 합니다. 각 콜백은 작업 유형에 따라 Trainer, Validator 또는 Predictor 객체를 받습니다. 이러한 객체의 모든 속성은 BaseTrainer, BaseValidator, BasePredictor 참조 페이지에 자세히 설명되어 있습니다.
시청: Ultralytics 콜백 사용 방법 | 예측, 학습, 검증 및 내보내기 콜백 | Ultralytics YOLO26 🚀
예제#
예측 결과에 추가 정보 반환#
이 예제에서는 각 결과 객체와 함께 원본 프레임을 반환하는 방법을 보여줍니다.
from ultralytics import YOLO
def on_predict_batch_end(predictor):
"""Combine prediction results with corresponding frames."""
_, image, _ = predictor.batch
# 이미지가 리스트인지 확인합니다
image = image if isinstance(image, list) else [image]
# 예측 결과를 해당 프레임과 결합합니다
predictor.results = zip(predictor.results, image)
# YOLO 모델 인스턴스를 생성합니다
model = YOLO("yolo26n.pt")
# 사용자 지정 콜백을 모델에 추가합니다
model.add_callback("on_predict_batch_end", on_predict_batch_end)
# 결과와 프레임을 순회합니다
for result, frame in model.predict(): # 또는 model.track()
pass학습 전에 PyTorch Forward Hooks 등록하기#
model.train()은 모델 구성에서 학습 모델을 생성하고 로드된 가중치를 모델에 전달합니다. 이 호출 전에 model.model에 직접 등록한 PyTorch 훅은 런타임 상태이므로, 다시 생성된 학습 모델은 해당 훅을 상속하지 않습니다. 모델 설정이 완료된 후 on_pretrain_routine_end에서 학습 훅을 등록합니다.
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()은 단일 장치 학습과 DistributedDataParallel 학습을 모두 처리합니다. 학습 체크포인트는 EMA 모델을 직렬화하며, 체크포인트를 로드할 때 다른 프로세스에서 콜백을 가져오지 못할 수 있으므로 로컬에서 정의한 훅을 trainer.ema.ema에 연결하지 마세요. 학습 검증 중에도 동일한 전처리를 실행해야 한다면 런타임 훅 대신 가져올 수 있는 모델 컴포넌트로 구현하세요. NaN 복구 시 학습 모델에서 EMA를 다시 생성하므로, 이 방식으로 등록한 훅은 EMA와 복구 후 저장되는 체크포인트에 복사됩니다. 체크포인트를 다른 프로세스에서 로드해야 한다면 가져올 수 있는 모듈에 훅 함수를 정의하세요.
독립 실행형 model.val()은 호출할 때마다 로드된 모델을 복사합니다. 예측은 첫 호출에서 복사본을 생성하고 캐시하므로, 첫 번째 model.predict() 또는 model.track() 호출 전에 model.model에 훅을 등록하세요. 이후에 추가한 훅은 캐시된 predictor에 적용되지 않습니다. 새 프로세스에서 체크포인트를 로드한 후에는 런타임 훅을 다시 등록하세요.
on_model_save 콜백을 사용하여 모델 메트릭에 액세스하기#
이 예제에서는 on_model_save 콜백을 사용해 체크포인트 저장 후 best_fitness 점수, total_loss 및 기타 메트릭과 같은 학습 세부 정보를 가져오는 방법을 보여줍니다.
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)모든 콜백#
아래는 지원되는 모든 콜백입니다. 자세한 내용은 콜백 소스 코드를 참조하세요.
Trainer 콜백#
| 콜백 | 설명 |
|---|---|
on_pretrain_routine_start | 데이터 로딩 및 모델 설정 전에 사전 학습 루틴이 시작될 때 트리거됩니다. |
on_pretrain_routine_end | 데이터 로딩 및 모델 설정이 완료된 후 사전 학습 루틴이 끝날 때 트리거됩니다. |
on_train_start | 첫 번째 epoch가 시작되기 전에 학습이 시작될 때 트리거됩니다. |
on_train_epoch_start | 배치 순회가 시작되기 전에 각 학습 epoch이 시작될 때 트리거됩니다. |
on_train_batch_start | Forward pass 전에 각 학습 배치가 시작될 때 트리거됩니다. |
optimizer_step | optimizer 단계 중에 트리거됩니다. 사용자 지정 통합을 위해 예약되어 있으며 기본 학습 루프에서는 호출되지 않습니다. |
on_before_zero_grad | gradient를 0으로 설정하기 전에 트리거됩니다. 사용자 지정 통합을 위해 예약되어 있으며 기본 학습 루프에서는 호출되지 않습니다. |
on_train_batch_end | Backward pass 후 각 학습 배치가 끝날 때 트리거됩니다. gradient accumulation으로 인해 optimizer 단계가 연기될 수 있습니다. |
on_train_epoch_end | 모든 배치가 처리된 후, 검증 전에 각 학습 epoch가 끝날 때 트리거됩니다. 검증 메트릭과 fitness는 아직 제공되지 않을 수 있습니다. |
on_model_save | 검증 후 모델 체크포인트가 저장될 때 트리거됩니다. |
on_fit_epoch_end | 검증 및 체크포인트 저장이 완료된 후, 각 fit epoch(학습 + 검증)가 끝날 때 트리거됩니다. 검증 메트릭을 사용할 수 있으며, epoch별 학습 호출에서는 fitness도 사용할 수 있습니다. 이 콜백은 체크포인트 저장이 발생하지 않고 fitness가 없을 수 있는 최종 최고 모델 평가 중에도 호출됩니다. |
on_train_end | 최고 모델의 최종 평가 후 학습 프로세스가 종료될 때 트리거됩니다. |
on_params_update | 모델 파라미터가 업데이트될 때 트리거됩니다. 사용자 지정 통합을 위해 예약되어 있으며 기본 학습 루프에서는 호출되지 않습니다. |
teardown | 학습 프로세스 정리가 진행될 때 트리거됩니다. |
Validator 콜백#
| 콜백 | 설명 |
|---|---|
on_val_start | 검증이 시작될 때 트리거됩니다. |
on_val_batch_start | 각 검증 배치가 시작될 때 트리거됩니다. |
on_val_batch_end | 각 검증 배치가 끝날 때 트리거됩니다. |
on_val_end | 검증이 끝날 때 트리거됩니다. |
Predictor 콜백#
| 콜백 | 설명 |
|---|---|
on_predict_start | 예측 프로세스가 시작될 때 트리거됩니다. |
on_predict_batch_start | 각 예측 배치가 시작될 때 트리거됩니다. |
on_predict_postprocess_end | 예측 후처리가 끝날 때 트리거됩니다. |
on_predict_batch_end | 각 예측 배치가 끝날 때 트리거됩니다. |
on_predict_end | 예측 프로세스가 끝날 때 트리거됩니다. |
Exporter 콜백#
| 콜백 | 설명 |
|---|---|
on_export_start | 내보내기 프로세스가 시작될 때 트리거됩니다. |
on_export_end | 내보내기 프로세스가 끝날 때 트리거됩니다. |
자주 묻는 질문#
Ultralytics 콜백은 학습, 검증, 내보내기, 예측과 같은 모델 작업의 주요 단계에서 트리거되는 특수 진입점입니다. 이러한 콜백을 사용하면 프로세스의 특정 시점에 사용자 지정 기능을 추가하여 워크플로를 개선하고 수정할 수 있습니다. 각 콜백은 작업 유형에 따라
Trainer,Validator또는Predictor객체를 받습니다. 이러한 객체의 속성에 관한 자세한 내용은BaseTrainer,BaseValidator,BasePredictor참조 페이지를 확인하세요.콜백을 사용하려면 함수를 정의하고
model.add_callback()메서드를 사용해 모델에 추가합니다. 다음은 예측 중에 추가 정보를 반환하는 예제입니다.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(): pass학습 프로세스의 특정 단계에 로직을 삽입하여 Ultralytics 학습 루틴을 사용자 지정할 수 있습니다. Ultralytics YOLO는
on_train_start,on_train_end,on_train_batch_end와 같은 다양한 학습 콜백을 제공하여 사용자 지정 메트릭, 처리 또는 로깅을 추가할 수 있도록 합니다.각 학습 epoch가 끝날 때 모든 optimizer 파라미터 그룹의 learning rate를 기록하는 방법은 다음과 같습니다.
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)팁freeze을 사용할 때 BatchNorm 통계를 고정하기 위해 콜백을 사용할 필요는 없습니다. trainer가 매 epoch 시작 시 고정된 레이어의 BatchNorm 레이어를 자동으로 eval 모드로 설정합니다.학습 콜백을 효과적으로 사용하는 방법에 관한 자세한 내용은 학습 가이드를 참조하세요.
Ultralytics YOLO에서 검증 중 콜백을 사용하면 사용자 지정 처리, 로깅 또는 메트릭 계산을 통해 모델 평가를 개선할 수 있습니다.
on_val_start,on_val_batch_end,on_val_end와 같은 콜백은 사용자 지정 로직을 삽입할 진입점을 제공하여 상세하고 포괄적인 검증 프로세스를 지원합니다.예를 들어, 처음 세 개만이 아니라 모든 검증 배치를 시각화하려면 다음과 같이 합니다.
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")검증 프로세스에 콜백을 적용하는 방법에 관한 자세한 내용은 검증 가이드를 참조하세요.
Ultralytics YOLO의 예측 모드에 사용자 지정 콜백을 연결하려면 콜백 함수를 정의하고 예측 프로세스에 등록하세요. 일반적인 예측 콜백에는
on_predict_start,on_predict_batch_end,on_predict_end가 있습니다. 이러한 콜백을 사용하면 예측 출력을 수정하고 데이터 로깅이나 결과 변환과 같은 기능을 통합할 수 있습니다.특정 클래스의 객체가 있는지에 따라 예측 결과를 저장하는 사용자 지정 콜백의 예제입니다.
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: pass더 자세한 사용 방법은 상세한 지침과 추가 사용자 지정 옵션을 포함하는 예측 가이드를 참조하세요.
Ultralytics YOLO는 학습, 검증, 예측과 같은 여러 단계를 개선하고 사용자 지정할 수 있도록 다양한 실용적인 콜백 구현을 지원합니다. 실용적인 예제는 다음과 같습니다.
- 사용자 지정 메트릭 로깅: 학습 또는 검증 epoch가 끝나는 시점 등 여러 단계에서 추가 메트릭을 기록합니다.
- 데이터 증강: 예측 또는 학습 배치 중에 사용자 지정 데이터 변환이나 증강을 구현합니다.
- 중간 결과: 추가 분석 또는 시각화를 위해 예측이나 프레임과 같은 중간 결과를 저장합니다.
예:
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(): pass더 많은 옵션과 예제를 보려면 콜백 소스 코드를 확인하세요.