Ultralytics YOLO27:

콜백#

Ultralytics 프레임워크는 train, val, export, predict 모드 중 전략적 단계에서 진입점 역할을 하는 콜백을 지원합니다. 각 콜백은 작업 유형에 따라 Trainer, Validator, 또는 Predictor 객체를 허용합니다. 이러한 객체의 모든 속성은 BaseTrainer, BaseValidator, 및 BasePredictor 참조 페이지에 자세히 설명되어 있습니다.



Watch: How to use Ultralytics Callbacks | Predict, Train, Validate and Export Callbacks | Ultralytics YOLO🚀

예시#

예측 시 추가 정보 반환하기#

이 예제에서는 각 결과 객체와 함께 원본 프레임을 반환하는 방법을 보여줍니다.

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()
    pass

학습 전 PyTorch Forward 훅 등록하기#

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에 부착하지 마십시오. 학습 검증 중에 동일한 전처리가 실행되어야 하는 경우, 런타임 훅 대신 가져올 수 있는 모델 구성 요소로 구현하십시오.

독립형 model.val()은(는) 각 호출마다 로드된 모델을 복사합니다. 예측은 첫 번째 호출 시 복사본을 생성하고 캐시하므로, 첫 번째 model.predict() 또는 model.track() 호출 전에 model.model에 훅을 등록하십시오. 이후에 추가된 훅은 캐시된 예측기에 도달하지 않습니다. 새로운 프로세스에서 체크포인트를 로드한 후 런타임 훅을 다시 등록하십시오.

on_model_save 콜백을 사용하여 모델 지표(Metrics)에 액세스하기#

이 예제는 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)

모든 콜백#

아래는 지원되는 모든 콜백입니다. 자세한 내용은 콜백 소스 코드를 참조하십시오.

트레이너 콜백#

콜백설명
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) 후에 트리거됩니다. 기울기 누적으로 인해 옵티마이저 단계가 연기될 수 있습니다.
on_train_epoch_end모든 배치가 처리된 후 검증 전, 각 학습 에폭의 끝 부분에서 트리거됩니다. 검증 지표와 적합도(Fitness)는 아직 사용하지 못할 수 있습니다.
on_model_save모델 체크포인트가 저장될 때, 검증 후에 트리거됩니다.
on_fit_epoch_end검증 및 체크포인트 저장 후, 각 적합 에폭(학습 + 검증)의 끝 부분에서 트리거됩니다. 검증 지표를 사용할 수 있으며, 에폭별 학습 호출에 대한 적합도를 사용할 수 있습니다. 이 콜백은 체크포인트가 저장되지 않고 적합도가 존재하지 않을 수 있는 최종 최적 모델 평가 중에도 호출됩니다.
on_train_end최적 모델의 최종 평가 후, 학습 프로세스가 종료될 때 트리거됩니다.
on_params_update모델 파라미터가 업데이트될 때 트리거됩니다. 사용자 정의 통합을 위해 예약되어 있으며, 기본 학습 루프에서는 호출되지 않습니다.
teardown학습 프로세스가 정리될 때 트리거됩니다.

검증기 콜백#

콜백설명
on_val_start검증이 시작될 때 트리거됩니다.
on_val_batch_start각 검증 배치의 시작 부분에서 트리거됩니다.
on_val_batch_end각 검증 배치의 끝 부분에서 트리거됩니다.
on_val_end검증이 끝날 때 트리거됩니다.

예측기 콜백#

콜백설명
on_predict_start예측 프로세스가 시작될 때 트리거됩니다.
on_predict_batch_start각 예측 배치의 시작 부분에서 트리거됩니다.
on_predict_postprocess_end예측 후처리(Post-processing)의 끝 부분에서 트리거됩니다.
on_predict_batch_end각 예측 배치의 끝 부분에서 트리거됩니다.
on_predict_end예측 프로세스가 끝날 때 트리거됩니다.

내보내기 콜백#

콜백설명
on_export_start내보내기 프로세스가 시작될 때 트리거됩니다.
on_export_end내보내기 프로세스가 끝날 때 트리거됩니다.

FAQ#

  • 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와 같은 다양한 학습 콜백을 제공하여 사용자 정의 지표, 처리 또는 로깅을 추가할 수 있습니다.

    콜백으로 레이어를 고정(Freeze)할 때 BatchNorm 통계를 고정하는 방법은 다음과 같습니다.

    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)

    학습 콜백을 효과적으로 사용하는 방법에 대한 자세한 내용은 학습 가이드를 참조하십시오.

  • Ultralytics YOLO의 검증 중 콜백 사용은 사용자 정의 처리, 로깅 또는 지표 계산을 가능하게 하여 모델 평가를 향상시킵니다. on_val_start, on_val_batch_end, on_val_end와 같은 콜백은 사용자 정의 로직을 주입할 수 있는 진입점을 제공하여 상세하고 포괄적인 검증 프로세스를 보장합니다.

    예를 들어, 처음 세 개 대신 모든 검증 배치를 플롯(Plot)하려면 다음과 같이 합니다.

    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)의 끝 등 다양한 단계에서 추가 지표를 기록합니다.
    • 데이터 증강(Data Augmentation): 예측 또는 학습 배치 동안 사용자 정의 데이터 변환 또는 증강을 구현합니다.
    • 중간 결과: 추가 분석이나 시각화를 위해 예측 또는 프레임과 같은 중간 결과를 저장합니다.

    예제: 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

    더 많은 옵션과 예제를 보려면 콜백 소스 코드를 살펴보십시오.

기여자
GLglenn-jocher16RIRizwanMunawar3RAraimbekovm2A A Aswanth Raj1Y-Y-T-G1

댓글