コールバック#
Ultralytics フレームワークはコールバックをサポートしており、train、val、export、predict モードの戦略的な段階でエントリーポイントとして機能します。各コールバックは、操作の種類に応じて Trainer、Validator、または Predictor オブジェクトを受け取ります。これらのオブジェクトのすべてのプロパティについては、BaseTrainer、BaseValidator、BasePredictor のリファレンスページで詳しく説明しています。
視聴: Ultralytics コールバックの使い方 | Predict、Train、Validate、Export のコールバック | Ultralytics YOLO26 🚀
例#
予測時に追加情報を返す#
この例では、各結果オブジェクトとともに元のフレームを返す方法を示します。
from ultralytics import YOLO
def on_predict_batch_end(predictor):
"""Combine prediction results with corresponding frames."""
_, image, _ = predictor.batch
# image がリストであることを確認します
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 Hook を登録する#
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 にフックを登録してください。後から追加したフックは、キャッシュ済みの予測器には反映されません。新しいプロセスでチェックポイントを読み込んだ後は、ランタイムフックを再度登録してください。
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 | すべてのバッチの処理後、各トレーニングエポックの終了時に呼び出されますが、検証の前です。検証メトリクスと fitness はまだ利用できない場合があります。 |
on_model_save | 検証後、モデルのチェックポイントが保存されるときに呼び出されます。 |
on_fit_epoch_end | 検証とチェックポイントの保存後、各 fit エポック（train + val）の終了時に呼び出されます。検証メトリクスを利用でき、エポックごとのトレーニング呼び出しでは fitness も利用できます。このコールバックは最良モデルの最終評価中にも呼び出されますが、その際はチェックポイントの保存は行われず、fitness が存在しない場合があります。 |
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 | エクスポートプロセスの終了時に呼び出されます。 |
よくある質問#
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など、さまざまなトレーニングコールバックが用意されており、カスタムメトリクス、処理、ログ記録を追加できます。各トレーニングエポックの終了時に、オプティマイザーの各パラメーターグループの学習率を記録する方法は次のとおりです。
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 の統計情報を固定するためのコールバックは必要ありません。エポックの開始時に、トレーナーが固定されたレイヤーの BatchNorm レイヤーを自動的に eval モードに設定します。トレーニングコールバックを効果的に使用する方法について詳しくは、トレーニングガイドを参照してください。
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その他のオプションや例については、コールバックのソースコードを確認してください。