コールバック#
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 フォワードフックの登録#
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 コールバックを使用してモデルのメトリクスにアクセスする#
この例では、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 | トレーニングが開始されるとき、最初のエポックが始まる前にトリガーされます。 |
on_train_epoch_start | 各トレーニングエポックの開始時、バッチ反復が始まる前にトリガーされます。 |
on_train_batch_start | 各トレーニングバッチの開始時、順方向パスの前にトリガーされます。 |
optimizer_step | オプティマイザのステップ中にトリガーされます。カスタム統合用に予約されており、デフォルトのトレーニングループからは呼び出されません。 |
on_before_zero_grad | 勾配がゼロにリセットされる前にトリガーされます。カスタム統合用に予約されており、デフォルトのトレーニングループからは呼び出されません。 |
on_train_batch_end | 各トレーニングバッチの終了時、逆方向パスの後にトリガーされます。勾配の累積により、オプティマイザのステップが延期される場合があります。 |
on_train_epoch_end | すべてのバッチが処理された後、検証の前に、各トレーニングエポックの終了時にトリガーされます。検証メトリクスとフィットネスはまだ利用できない場合があります。 |
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 | 予測の後処理の終了時にトリガーされます。 |
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などのさまざまなトレーニングコールバックを提供しており、カスタムメトリクス、処理、またはロギングを追加できます。コールバックでレイヤーを凍結する際に 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などのコールバックは、カスタムロジックを挿入するエントリーポイントを提供し、詳細で包括的な検証プロセスを保証します。たとえば、最初の3つだけでなく、すべての検証バッチをプロットするには次のようにします。
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 は、トレーニング、検証、予測などのさまざまなフェーズを強化およびカスタマイズするための、コールバックのさまざまな実践的実装をサポートしています。いくつかの実践的な例には次のようなものがあります。
- カスタムメトリクスのロギング: トレーニングや検証のエポックの終了時などのさまざまな段階で、追加のメトリクスをログに記録します。
- データ拡張: 予測またはトレーニングバッチ中に、カスタムのデータ変換または拡張を実装します。
- 中間結果: ささらなる分析や可視化のために、予測やフレームなどの中間結果を保存します。
例:
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その他のオプションや例については、コールバックのソースコードをご参照ください。