コールバック#
Ultralytics フレームワークはコールバックをサポートしており、train、val、export、および predict モードの重要な段階のエントリポイントとして機能します。各コールバックは、操作の種類に応じて Trainer、Validator、または Predictor オブジェクトを受け取ります。これらのオブジェクトのすべてのプロパティについては、ドキュメントの参照セクションで詳しく説明されています。
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()
passon_model_save コールバックを使用して Model メトリクスにアクセスする#
この例は、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 | 最初のエポックが始まる前の、トレーニング開始時にトリガーされます。 |
on_train_epoch_start | バッチ反復が始まる前の、各トレーニングエポックの開始時にトリガーされます。 |
on_train_batch_start | 各学習バッチの開始時、順伝播（forward pass）の前にトリガーされます。 |
optimizer_step | オプティマイザのステップ中にトリガーされます。カスタム統合用に予約されており、デフォルトの学習ループからは呼び出されません。 |
on_before_zero_grad | 勾配のゼロ化の前にトリガーされます。カスタム統合用に予約されており、デフォルトの学習ループからは呼び出されません。 |
on_train_batch_end | 各学習バッチの終了時、逆伝播（backward pass）の後にトリガーされます。勾配累積のため、オプティマイザのステップが遅延される場合があります。 |
on_train_epoch_end | 各学習エポックの終了時、全バッチの処理完了後で、検証（validation）の前にトリガーされます。検証メトリクスやフィットネススコアはまだ利用できない場合があります。 |
on_model_save | 検証後、モデルのチェックポイントが保存されるときにトリガーされます。 |
on_fit_epoch_end | 各フィットエポック（学習＋検証）の終了時、検証およびチェックポイント保存の後にトリガーされます。検証メトリクスは利用可能であり、エポックごとの学習呼び出し時にフィットネスも利用可能です。このコールバックは最終的なベストモデル評価中にも呼び出されますが、その際チェックポイント保存は行われず、フィットネスが存在しない可能性があります。 |
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 | エクスポートプロセスが終了するときにトリガーされます。 |
よくある質問 (FAQ)#
Ultralytics コールバックは、トレーニング、検証、エクスポート、予測などのモデル操作の主要な段階でトリガーされる特殊なエントリポイントです。これらのコールバックにより、プロセスの特定ポイントでカスタム機能が可能になり、ワークフローの拡張と修正が行えます。各コールバックは、操作の種類に応じて
Trainer、Validator、またはPredictorオブジェクトを受け取ります。これらのオブジェクトの詳細なプロパティについては、参照セクションをご参照ください。コールバックを使用するには、関数を定義し、
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その他のオプションと例については、コールバックソースコードをご覧ください。